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
 
(127 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
-- Helper function
-- from those dependencies.
-- Given the output of the above function, create a mediawiki table
function p.make_dependency_table(module_deps)


-- List dependencies for a module
-- Table headers
function p.list_dependencies(module_name)
local lines = {}
local module_name = module_name --or "MOS" -- Test arg; comment out when not testing
table.insert(lines, '{| class="wikitable sortable"')
table.insert(lines, "|+ style=\"font-size: 105%;\" | " .. string.format("Lua modules required (%d)", #module_deps))
local title = mw.title.new('Module:' .. module_name)
table.insert(lines, "|-")
local content = title:getContent()
table.insert(lines, "! Variable")
table.insert(lines, "! Module")
table.insert(lines, "! Functions used")


-- Get dependencies for that module
-- Table rows (assuming they're all alphabetized)
-- It's the text from each "require('Module:aaaaa')" line.
for _, info in ipairs(module_deps) do
local deps = {}
local funcs_text
for dep in content:gmatch("require%s*%(%s*['\"]Module:(.-)['\"]%s*%)") do
if #info.funcs == 0 then
table.insert(deps, dep)
funcs_text = "''dependency not used''"
end
return deps
end
 
-- List functions used from each dependency
-- This assumes dependency functions are used in the format of: var.func(),
-- or var() if the module is included as var = require("Module:Dep") if it
-- returns a function or var = require("Module:Dep").func_name if a specific
-- function from that module is used.
-- Optionally accepts a table of its dependencies; if not provided, it will find
-- them itself by calling list_dependencies
function p.list_dependency_functions(module_name, deps)
local module_name = module_name --or "MOS" -- Test arg; comment out when not testing
 
-- Get dependencies
local deps = p.list_dependencies(module_name)
-- Load module
local title = mw.title.new('Module:' .. module_name)
local content = title:getContent()
 
-- Step 1: Find all require statements with optional .function
local results = {}
for var, dep, entry in content: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 content:gmatch(var .. "%s*%(") do
used[entry] = true
end
else
else
-- The variable is a module table: var.func() usage
local func_lines = {}
for func in content:gmatch(var .. "%.(%w+)%s*%(") do
for _, func in ipairs(info.funcs) do
used[func] = true
table.insert(func_lines, string.format("<code>%s</code>", func))
end
end
funcs_text = table.concat(func_lines, "<br />")
end
end


-- Step 3: Build result entry
table.insert(lines, "|-")
local funcList = {}
table.insert(lines, "| " .. info.var)
for f in pairs(used) do table.insert(funcList, f) end
table.insert(lines, "| [[" .. info.dep .. "]]")
table.sort(funcList)
table.insert(lines, "| " .. funcs_text)
end


results[dep] = results[dep] or {}
-- Table footer
table.insert(results[dep], {
table.insert(lines, "|}")
variable = var,
entry = (entry ~= "" and entry or nil),
functions = funcList
})
end


return results
-- Join all lines into a single string
return table.concat(lines, "\n")
end
end


-- List functions provided by a module
-- Helper function
-- Only returned functions are considered, not local functions
-- Lists module's own functions; requires module name to produce links to each
function p.list_functions(module_name)
-- function.
local module_name = module_name --or "MOS" -- Test arg; comment out when not testing
function p.make_function_table(module_name, module_funcs, descriptions, main_function)
-- Load module
-- Check whether descriptions was passed in
local title = mw.title.new('Module:' .. module_name)
local has_descriptions = false
local content = title:getContent()
if type(descriptions) == "table" then
for _, _ in pairs(descriptions) do
has_descriptions = true
break
end
end
-- Iterate through file and find each function and the line found at
-- Table headers
local funcs = {}
local lines = {}
if content then
--table.insert(lines, string.format("'''Module:%s''' provides %d function(s):", module_name, #module_funcs))
local lineNumber = 0
table.insert(lines, '{| class="wikitable sortable"')
for line in content:gmatch("[^\n]+") do
table.insert(lines, "|+ style=\"font-size: 105%;\" | " .. string.format("Functions&nbsp;provided&nbsp;(%d)", #module_funcs))
lineNumber = lineNumber + 1
table.insert(lines, "|-")
table.insert(lines, "! Line")
table.insert(lines, "! Function")
table.insert(lines, "! Params")
-- If there are descriptions, add a column for that
if has_descriptions then
table.insert(lines, "! Description")
end


-- Match functions defined as function p.name(
-- Table rows
local name = line:match("function%s+[%w_]+%.([%w_]+)%s*%(")
for _, info in ipairs(module_funcs) do
if name then
table.insert(funcs, {name = name, line = lineNumber})
-- Find params for that function, or say "none" if none
end
local params = {}
 
for _, param in ipairs(info.params) do
-- Match functions defined as p.name = function(
table.insert(params, param)
name = line:match("[%w_]+%.([%w_]+)%s*=%s*function%s*%(")
end
if name then
local params_string = ""
table.insert(funcs, {name = name, line = lineNumber})
if #params == 0 then
end
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 info.name == main_function then
func = func .. " '''(main)'''"
end
-- If the function is invokable (it has one param called "frame"), add
-- "invokable" to that cell
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
end
 
table.insert(lines, "|}")
return funcs
return table.concat(lines, "\n")
end
end


-- Main function; to be called by wrapper
-- Main function; to be called by wrapper
function p._module_introspection(args)
function p._module_introspection(args)
local module_name = args["module_name"]
local args = args or {}
local module_name   = args["module_name" ]
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
--local title = mw.title.new('Module:' .. module_name)
--local code = title:getContent()
--code = iutils.preprocess_code(code) -- Blank-out comments
local code = iutils.get_and_preprocess_content("Module", module_name)
-- Get dependencies and their functions used, then build a table
local module_deps = iutils.find_dependencies(code)
local dep_table = p.make_dependency_table(module_deps)


    -- Get module functions
-- Get module's functions, then build a table using that information
    local module_functions = p.list_functions(module_name)
local module_funcs = iutils.find_functions(code)
local func_table = p.make_function_table(module_name, module_funcs, descriptions, main_function)


    -- Get dependencies and functions used from each
-- Return the tables
    local dep_functions = p.list_dependency_functions(module_name)
-- 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,
"|}"
}


    -- Build MediaWiki table for dependencies
-- Check whether descriptions was passed in
    local dep_lines = {}
local has_descriptions = false
    table.insert(dep_lines, '{| class="wikitable sortable"')
if type(descriptions) == "table" then
    table.insert(dep_lines, "! Dependency")
for _, _ in pairs(descriptions) do
    table.insert(dep_lines, "! Variable")
has_descriptions = true
    table.insert(dep_lines, "! Function(s) used")
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


    -- Include all dependencies even if no usage is detected
return table.concat(lines, "\n")
    local all_deps = p.list_dependencies(module_name)
    for _, dep in ipairs(all_deps) do
        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)
                table.insert(dep_lines, "| " .. usage.variable)
                table.insert(dep_lines, "| ".. (func_str ~= "" and func_str or "''dependency not used''"))
            end
        else
            -- No functions used from this dependency
            table.insert(dep_lines, "|-")
            table.insert(dep_lines, "| " .. dep)
            table.insert(dep_lines, "| -")
            table.insert(dep_lines, "| ''dependency not used''")
        end
    end
 
    table.insert(dep_lines, '|}')
 
    -- Build MediaWiki table for module's own functions
    local func_lines = {}
    table.insert(func_lines, '{| class="wikitable sortable"')
    table.insert(func_lines, "! Function")
    table.insert(func_lines, "! Line")
 
    for _, f in ipairs(module_functions) do
        local link = string.format("[[Module:%s#%d|%s]]", module_name, f.line, f.name)
        table.insert(func_lines, "|-")
        table.insert(func_lines, "| " .. link)
        table.insert(func_lines, "| " .. f.line)
    end
    table.insert(func_lines, "|}")
 
    -- Return the tables as strings
    return table.concat(dep_lines, "\n"), table.concat(func_lines, "\n")
end
end


-- Wrapper function for modules
-- Wrapper function for modules
function p.module_introspection(frame)
function p.module_introspection(frame)
    -- Extract arguments using getArgs
-- Extract arguments using getArgs
    local args = getArgs(frame)
local args = getArgs(frame) or {}
 
-- Get module name from arguments, or default to current page
local module_name = args["module_name"] or mw.title.getCurrentTitle().text


    -- Get module name from arguments, or default to current page
-- Strip trailing "/doc" if the template is used on a documentation subpage
    local module_name = args["module_name"] or mw.title.getCurrentTitle().text
--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
-- is assumed to be the same name as the module. Module assumes snake_case
-- is used for function names. (If this fails, it can be entered manually.)
local normalized_name = module_name:gsub("[^%w]", "_"):lower()
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


    -- Strip trailing "/doc" if the template is used on a documentation subpage
-- Return
    module_name = module_name:gsub("/doc$", "")
local result = p._module_introspection({
["module_name" ] = module_name,
["main_function"] = main_function,
["descriptions" ] = func_descriptions,
["is_doc"] = is_doc
})


     -- Call the introspection function
     -- Debugger option to show generated WikiText
     local dep_table, func_table = p._module_introspection({["module_name"] = module_name})
     local wtext = yesno(frame.args["wtext"] or args["wtext"])


    -- Return combined tables
if wtext == true then
    return dep_table .. '\n' .. func_table
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"