Xenharmonic Wiki

Module:Module introspection: Difference between revisions

← Older edit
Ganaram inukshuk (talk | contribs)
autopatrolled, emailconfirmed
6,211 edits
mNo edit summary
ArrowHead294 (talk | contribs)
15,213 edits
mNo edit summary
 
(102 intermediate revisions by 2 users not shown)
Line 1: Line 1:
-- This module follows [[User:Ganaram inukshuk/Provisional style guide for Lua]]
-- This module follows [[User:Ganaram inukshuk/Provisional style guide for Lua]]
local getArgs = require("Module:Arguments").getArgs
local getArgs = require("Module:Arguments").getArgs
local iutils  = require("Module:Introspection utils")
local yesno  = require("Module:Yesno")
local p = {}
local p = {}
-- Inspects a module for its functions, its dependencies, and the functions used
-- from those dependencies.


-- Helper function
-- Helper function
-- Blanks comments but preserves line numbers
-- Given the output of the above function, create a mediawiki table
function p.strip_comments(content)
function p.make_dependency_table(module_deps)
if not content then return "" end


-- Table headers
local lines = {}
local lines = {}
local in_multiline = false
table.insert(lines, '{| class="wikitable sortable"')
local end_pattern
table.insert(lines, "|+ style=\"font-size: 105%;\" | " .. string.format("Lua modules required (%d)", #module_deps))
table.insert(lines, "|-")
table.insert(lines, "! Variable")
table.insert(lines, "! Module")
table.insert(lines, "! Functions used")


for line in content:gmatch("([^\n]*)\n") do
-- Table rows (assuming they're all alphabetized)
local processed = line
for _, info in ipairs(module_deps) do
local funcs_text
if in_multiline then
if #info.funcs == 0 then
-- Check for end of multi-line comment first
funcs_text = "''dependency not used''"
local s, e = processed:find(end_pattern)
if s then
in_multiline = false
-- Replace only the comment part with spaces
processed = string.rep(" ", e) .. processed:sub(e + 1)
else
-- Entire line is inside comment
processed = processed:gsub(".", " ")
end
else
else
local start_eq = processed:match("%-%-%[(=*)%[")
local func_lines = {}
if start_eq then
for _, func in ipairs(info.funcs) do
in_multiline = true
table.insert(func_lines, string.format("<code>%s</code>", func))
end_pattern = "%]" .. start_eq .. "%]"
-- Blank from the start of comment to the end of line
local s, e = processed:find("%-%-%[" .. start_eq .. "%[")
if s then
processed = string.rep(" ", #processed)
end
else
processed = processed:gsub("%-%-.*", function(s)
return string.rep(" ", #s)
end)
end
end
funcs_text = table.concat(func_lines, "<br />")
end
end
table.insert(lines, processed)
end


return table.concat(lines, "\n")
table.insert(lines, "|-")
end
table.insert(lines, "| " .. info.var)
 
table.insert(lines, "| [[" .. info.dep .. "]]")
-- Helper function
table.insert(lines, "| " .. funcs_text)
-- Find dependencies for a module, given a preprocessed module's code
function p.find_dependencies(preprocessed_module)
local deps = {}
for dep in preprocessed_module:gmatch("require%s*%(%s*['\"]Module:(.-)['\"]%s*%)") do
table.insert(deps, dep)
end
end
return deps
end


-- Helper function
-- Table footer
-- Find functions used by each dependency
table.insert(lines, "|}")
function p.find_dependency_functions(preprocessed_module)


-- Step 1: Find all require statements with optional .function
-- Join all lines into a single string
local results = {}
return table.concat(lines, "\n")
for var, dep, entry in preprocessed_module:gmatch(
"local%s+([%w_]+)%s*=%s*require%s*%(%s*['\"]Module:(.-)['\"]%s*%)%.?([%w_]*)"
) do
local used = {}
 
-- Step 2: Check how it's used
if entry ~= "" then
-- The module returned a single function: var() usage
for _ in preprocessed_module:gmatch(var .. "%s*%(") do
used[entry] = true
end
else
-- The variable is a module table: var.func() usage
for func in preprocessed_module:gmatch(var .. "%.(%w+)%s*%(") do
used[func] = true
end
end
 
-- Step 3: Build result entry
local func_list = {}
for f in pairs(used) do table.insert(func_list, f) end
table.sort(func_list)
 
results[dep] = results[dep] or {}
table.insert(results[dep], {
variable = var,
entry = (entry ~= "" and entry or nil),
functions = func_list
})
end
 
return results
end
end


-- Helper function
-- Helper function
-- Find functions provided by a module, ignoring nested/local functions
-- Lists module's own functions; requires module name to produce links to each
function p.find_functions(preprocessed_content)
-- function.
 
function p.make_function_table(module_name, module_funcs, descriptions, main_function)
-- Iterate through file and find each function and the line found at
local funcs = {}
if preprocessed_content then
local line_num = 0
for line in preprocessed_content:gmatch("([^\n]*)\n?") do -- Make sure gmatch does not skip blank lines
line_num = line_num + 1
 
-- Match functions defined as function p.name(
local name = line:match("function%s+[%w_]+%.([%w_]+)%s*%(")
if name then
table.insert(funcs, {name = name, line = line_num})
end
 
-- Match functions defined as p.name = function(
name = line:match("[%w_]+%.([%w_]+)%s*=%s*function%s*%(")
if name then
table.insert(funcs, {name = name, line = line_num})
end
end
end
 
return funcs
end
 
-- Helper function; builds the table of dependencies
-- All dependencies are included regardless of use
function p.make_dependency_table(deps, dep_functions)
local dep_lines = {}
-- Check whether descriptions was passed in
--.insert(dep_lines, string.format("'''Module:%s''' requires the following dependencies:", module_name))
local has_descriptions = false
table.insert(dep_lines, '{| class="wikitable sortable"')
if type(descriptions) == "table" then
table.insert(dep_lines, '|+ Dependencies and functions used')
for _, _ in pairs(descriptions) do
table.insert(dep_lines, "! Dependency")
has_descriptions = true
table.insert(dep_lines, "! Variable")
break
table.insert(dep_lines, "! Function(s) used")
for _, dep in ipairs(deps) do
local dep_link = string.format("[[Module: %s]]", dep)
local usages = dep_functions[dep]
if usages and #usages > 0 then
for _, usage in ipairs(usages) do
local func_str = table.concat(usage.functions, ", ")
if usage.entry then
func_str = usage.entry .. (func_str ~= "" and (", " .. func_str) or "")
end
table.insert(dep_lines, "|-")
table.insert(dep_lines, "| " .. dep_link)
table.insert(dep_lines, "| " .. usage.variable)
table.insert(dep_lines, "| " .. (func_str ~= "" and func_str or "''dependency not used''"))
end
else
table.insert(dep_lines, "|-")
table.insert(dep_lines, "| " .. dep_link)
table.insert(dep_lines, "| -")
table.insert(dep_lines, "| ''dependency not used''")
end
end
end
end
table.insert(dep_lines, '|}')
return dep_lines
-- Table headers
end
local lines = {}
 
--table.insert(lines, string.format("'''Module:%s''' provides %d function(s):", module_name, #module_funcs))
-- Helper function
table.insert(lines, '{| class="wikitable sortable"')
-- Lists module's own functions; requires module name to produce links to each
table.insert(lines, "|+ style=\"font-size: 105%;\" | " .. string.format("Functions&nbsp;provided&nbsp;(%d)", #module_funcs))
-- function.
table.insert(lines, "|-")
function p.make_function_table(module_name, module_functions)
table.insert(lines, "! Line")
table.insert(lines, "! Function")
table.insert(lines, "! Params")
-- Collapse table if it's larger than 20 lines
-- If there are descriptions, add a column for that
local func_class = "wikitable sortable mw-collapsible"
if has_descriptions then
if #module_functions > 20 then
table.insert(lines, "! Description")
func_class = func_class .. " mw-collapsed"
end
end
local func_lines = {}
--table.insert(func_lines, string.format("'''Module:%s''' provides %d function(s):", module_name, #module_functions))
table.insert(func_lines, "{| class=\"" .. func_class .. "\"")
table.insert(func_lines, "|+ Functions provided by this module")
table.insert(func_lines, "! Function")
table.insert(func_lines, "! Line")


for _, f in ipairs(module_functions) do
-- Table rows
local link = string.format("[[Module:%s#L-%d|%s]]", module_name, f.line, f.name)
for _, info in ipairs(module_funcs) do
-- Find params for that function, or say "none" if none
local params = {}
for _, param in ipairs(info.params) do
table.insert(params, param)
end
local params_string = ""
if #params == 0 then
params_string = "''none''"
else
params_string = string.format("<code>(%s)</code>", table.concat(params, ", "))
end
-- Create link to line for that function
local line_num = string.format("[[Module:%s#L-%d|%d]]", module_name, info.line, info.line)
-- Create text for function
local func = ""
if info.name then
func = string.format("<code>%s</code>", info.name)
else
func = "''none''"
end
-- If the function is the main function, add "main" to that cell
-- If the function is the main function, add "main" to that cell
if f.name == main_function then
if info.name == main_function then
link = link .. " '''(main)'''"
func = func .. " '''(main)'''"
end
end
table.insert(func_lines, "|-")
-- If the function is invokable (it has one param called "frame"), add
table.insert(func_lines, "| " .. link)
-- "invokable" to that cell
table.insert(func_lines, "| " .. f.line)
if #params == 1 and params[1] == "frame" then
func = func .. " '''(invokable)'''"
end
table.insert(lines, "|-")
table.insert(lines, "| " .. line_num)
table.insert(lines, "| " .. func)
table.insert(lines, "| " .. params_string)
if has_descriptions then
table.insert(lines, "| " .. (descriptions[info.name] or ""))
end
end
end
table.insert(func_lines, "|}")
table.insert(lines, "|}")
return func_lines
return table.concat(lines, "\n")
end
end


Line 207: Line 128:
function p._module_introspection(args)
function p._module_introspection(args)
local args = args or {}
local args = args or {}
local module_name  = args["module_name"  ] or "Numlinks"
local module_name  = args["module_name"  ]
local main_function = args["main_function"]
local main_function = args["main_function"]
local descriptions  = args["descriptions" ]
local is_doc = args["is_doc"]
-- Check whether this page is a docpage
-- If so, don't bother
if is_doc then
return "''To see introspection summary, see this module's main page.''"
end
-- Preprocess module and blank-out comments
-- Preprocess module and blank-out comments
local title = mw.title.new('Module:' .. module_name)
--local title = mw.title.new('Module:' .. module_name)
local preprocessed_content = title:getContent()
--local code = title:getContent()
preprocessed_content = p.strip_comments(preprocessed_content) -- Blank-out comments
--code = iutils.preprocess_code(code) -- Blank-out comments
local code = iutils.get_and_preprocess_content("Module", module_name)
-- Get dependencies, their functions used, then build a table
-- Get dependencies and their functions used, then build a table
local deps = p.find_dependencies(preprocessed_content)
local module_deps = iutils.find_dependencies(code)
local dep_functions = p.find_dependency_functions(preprocessed_content)
local dep_table = p.make_dependency_table(module_deps)
local dep_lines = p.make_dependency_table(deps, dep_functions)


-- Get module's functions, then build a table using that information
-- Get module's functions, then build a table using that information
local module_functions = p.find_functions(preprocessed_content)
local module_funcs = iutils.find_functions(code)
local func_lines = p.make_function_table(module_name, module_functions)
local func_table = p.make_function_table(module_name, module_funcs, descriptions, main_function)
 
-- Return the tables
-- Styling may be improved at a later time
local lines = {
'{| class="wikitable mw-collapsible"',
'|-',
'! colspan="2" style="font-size: 105%;" | ' .. string.format("Introspection summary for Module:%s&nbsp;", module_name),
"|-",
'| style="vertical-align: top; border-right: none;" | ',
func_table,
'| style="vertical-align: top; border-left: none;" | ',
dep_table,
"|}"
}
 
-- Check whether descriptions was passed in
local has_descriptions = false
if type(descriptions) == "table" then
for _, _ in pairs(descriptions) do
has_descriptions = true
break
end
end
-- If no descriptions were provided, add text below that points to the code.
if not has_descriptions then
table.insert(lines, "''No function descriptions were provided. The Lua code may have further information.''")
end


-- Return the tables as strings
return table.concat(lines, "\n")
local summary = string.format("'''Introspection summary:''' Module:%s requires %d module(s) and provides %d functions(s).", module_name, #deps, #module_functions)
return summary .. "\n" .. table.concat(dep_lines, "\n") .. "\n" .. table.concat(func_lines, "\n")
end
end


-- Wrapper function for modules
-- Wrapper function for modules
Line 239: Line 193:


-- Strip trailing "/doc" if the template is used on a documentation subpage
-- Strip trailing "/doc" if the template is used on a documentation subpage
module_name = module_name:gsub("/doc$", "")
--module_name = module_name:gsub("/doc$", "")
-- Check whether page is the doc page
-- To ensure proper referencing, do not display introspection on a docpage.
local is_doc = string.find(module_name, "/doc$")
-- Normalize module name so it can be used to find the main function, which
-- Normalize module name so it can be used to find the main function, which
Line 246: Line 204:
local normalized_name = module_name:gsub("[^%w]", "_"):lower()
local normalized_name = module_name:gsub("[^%w]", "_"):lower()
local main_function = args["main_function"] or "_" .. normalized_name
local main_function = args["main_function"] or "_" .. normalized_name
-- Process all function descriptions, if provided as desc_function_name
local func_descriptions = {}
for key, val in pairs(args) do
local func_name = key:match("^desc_([%w_]+)$")
if func_name and val and val ~= "" then
func_descriptions[func_name] = val
end
end


-- Return
-- Return
return p._module_introspection({
local result = p._module_introspection({
["module_name"]   = module_name,
["module_name" ] = module_name,
["main_function"] = main_function,
["main_function"] = main_function,
["descriptions" ] = func_descriptions,
["is_doc"] = is_doc
})
})
    -- Debugger option to show generated WikiText
    local wtext = yesno(frame.args["wtext"] or args["wtext"])
if wtext == true then
result = "<syntaxhighlight lang=\"wikitext\">" .. result .. "</syntaxhighlight>"
end
return frame:preprocess(result)
end
end


return p
return p
Retrieved from "https://en.xen.wiki/w/Module:Module_introspection"