local assert = require("luassert") local type Node = require("types.Node") local scraper = require("scraper.module_doc") local get_doc_from_page = scraper.get_doc_from_page describe("Scrap documentation", function() it("should return a valid AST for an empty module", function() local ast , nodes = get_doc_from_page("", "empty") local expected : Node = { children = { { children = {}, name = "Signal", token = "enum", } }, name = "Empty", token = "module", } assert.same(expected, ast) assert.same({}, nodes) end) it("should produce Variable and `property::` Signal nodes", function() local ast = get_doc_from_page([[

Object properties

馃敆 value number 路 1 signal

Constraints:

Default value : 0
Negative allowed : true
]], "property_signal") local expected : Node = { children = { { children = { { name = "property::value", token = "identifier", }, }, name = "Signal", token = "enum", }, { name = "value", types = { "number" }, token = "variable", } }, name = "Property_signal", token = "module", } assert.same(expected, ast) end) it("should produce Enum nodes when an Object Property type is a String with constraints", function() local ast = get_doc_from_page([[

Object properties

馃敆 horizontal_fit_policy string 路 1 signal
Default value : "auto"
Valid values:
"auto" : Honor the resize variable and preserve the aspect ratio.
"none" : Do not resize at all.
"fit" : Resize to the widget width.
]], "property_enum") local expected : Node = { children = { { children = { { name = "property::horizontal_fit_policy", token = "identifier", }, }, name = "Signal", token = "enum", }, { children = { { name = "auto", token = "identifier", }, { name = "none", token = "identifier", }, { name = "fit", token = "identifier", }, }, name = "Horizontal_fit_policy", token = "enum", }, { name = "horizontal_fit_policy", types = { "Horizontal_fit_policy" }, token = "variable", }, }, name = "Property_enum", token = "module", } assert.same(expected, ast) end) it("should produce a `string` typed Variable node when a String Property has no constraint", function() local ast = get_doc_from_page([[

Object properties

馃敆 markup string 路 1 signal
string
]], "property_string") local expected : Node = { children = { { children = { { name = "property::markup", token = "identifier", }, }, name = "Signal", token = "enum", }, { name = "markup", types = { "string" }, token = "variable", } }, name = "Property_string", token = "module", } assert.same(expected, ast) end) it("should provide a Function node with the `self` as the first positional parameter", function() local ast = get_doc_from_page([[

Object methods

馃敆 :swap (tag2)

Parameters:

Name Type(s) Description
tag2 tag The second tag
]], "awful.tag") local expected : Node = { children = { { children = {}, name = "Signal", token = "enum", }, { parameters = { { types = { "Tag" }, name = "self", token = "variable", }, { types = { "tag" }, -- This needs to be fixed : tag -> Tag name = "tag2", token = "variable", } }, return_types = {}, name = "swap", token = "function", }, }, name = "Tag", token = "module", } assert.same(expected, ast) end) it("should produce Signal nodes", function() local ast = get_doc_from_page([[

Signals

馃敆 widget::layout_changed 路 Inherited from wibox.widget.base
馃敆 widget::redraw_needed 路 Inherited from wibox.widget.base
]], "signal") local expected : Node = { children = { { children = { { name = "widget::layout_changed", token = "identifier", }, { name = "widget::redraw_needed", token = "identifier", }, }, name = "Signal", token = "enum", }, }, name = "Signal", token = "module", } assert.same(expected, ast) end) it("should produce Function nodes", function() local ast = get_doc_from_page([[

Static module functions

馃敆 awesome.kill (pid, sig) -> boolean
Send a signal to a process.

Parameters:

Name Type(s) Description
pid integer Process identifier. 0 and negative values have special meaning. See man 3 kill.
sig integer Signal number. See awesome.unix_signal for a list of signals.

Returns:

    boolean true if the signal was successfully sent, else false
]], "awesome") -- The module name must be the same as the module name in the doc local expected : Node = { children = { { children = {}, name = "Signal", token = "enum", }, { parameters = { { types = { "integer" }, name = "pid", token = "variable", }, { types = { "integer" }, name = "sig", token = "variable", }, }, return_types = { "boolean" }, name = "kill", token = "function", } }, name = "Awesome", token = "module", } assert.same(expected, ast) end) it("should produce a Record node when a function parameter is a named-parameter-table", function() local ast = get_doc_from_page([[

Static module functions

馃敆 awful.screen.focused {[args]} -> nil or screen

Parameters:

Name Type(s) Description Default value
args Optional table Undefined
client Optional boolean Use the client screen instead of the mouse screen. false
mouse Optional boolean Use the mouse screen true

Returns:

    optional screen The focused screen object, or nil in case no screen is present currently.
]], "awful.screen") assert.same(ast, { children = { { children = {}, name = "Signal", token = "enum", }, { children = { { types = { "boolean" }, name = "client", token = "variable", }, { types = { "boolean" }, name = "mouse", token = "variable", } }, name = "Focused_Args", token = "record", }, { parameters = { { types = { "Focused_Args" }, name = "args", token = "variable", }, }, return_types = { "screen" }, name = "focused", token = "function", }, }, name = "Screen", token = "module", }) end) it("should go back to a table typed parameter when the record is empty", function() local ast = get_doc_from_page([[

Static module functions

馃敆 gears.table.crush (target, source, raw) -> table

Parameters:

Name Type(s) Description Default value
target table The target table. Values from source will be copied into this table. Not applicable
source table The source table. Its values will be copied into target. Not applicable
raw Optional bool If true, values will be assigned with rawset. This will bypass metamethods on target. false

Returns:

    table The target table.
]], "gears.table") local expected : Node = { children = { { children = {}, name = "Signal", token = "enum", }, { parameters = { { types = { "table" }, name = "target", token = "variable", }, { types = { "table" }, name = "source", token = "variable", }, { types = { "bool" }, name = "raw", token = "variable", } }, return_types = { "table" }, name = "crush", token = "function", } }, name = "Table", token = "module", } assert.same(expected, ast) end) it("should go back to a table typed parameter when the record is empty and it's the last parameter", function() local ast = get_doc_from_page([[

Object methods

馃敆 :tags (tags_table) -> table 路 1 signal

Parameters:

Name Type(s) Description
tags_table table A table with tags to set, or nil to get the current tags.

Returns:

    table A table with all tags.
]], "awful.client") local expected : Node = { children = { { children = {}, name = "Signal", token = "enum", }, { parameters = { { types = { "Client" }, name = "self", token = "variable", }, { types = { "table" }, name = "tags_table", token = "variable", }, }, return_types = { "table" }, name = "tags", token = "function", }, }, name = "Client", token = "module", } assert.same(expected, ast) end) it("should return Function nodes with the `other_nodes` list when the function module name doesn't match the module name", function() local ast , other_nodes = get_doc_from_page([[

Static module functions

馃敆 client.instances () -> integer
Get the number of instances.

Returns:

    integer The number of client objects alive.
]], "awful.client") local expected_ast : Node = { children = { { children = {}, name = "Signal", token = "enum", }, }, name = "Client", token = "module", } assert.same(expected_ast, ast) local expected_other_nodes : { Node } = { { parameters = {}, return_types = { "integer" }, name = "client.instances", token = "function", } } assert.same(expected_other_nodes, other_nodes) end) end)