Xenharmonic Wiki

Module:Module introspection: Difference between revisions

← Older edit
Ganaram inukshuk (talk | contribs)
autopatrolled, emailconfirmed
6,211 edits
introspection should now ignore strings, on the offchance that strings contain code
ArrowHead294 (talk | contribs)
15,213 edits
mNo edit summary
 
(89 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 mos = require("Module:MOS")
local iutils  = require("Module:Introspection utils")
--[[
local yesno  = require("Module:Yesno")
local rat = require("Module:Rational")
 
]]--
local p = {}
local p = {}
-- TODO: add additional functions:
-- - Determine whether a main function exists, as _main or a function of the
--  same name as the module with an underscore.
-- - Determine whether a wrapper exists, as main or a function of the same name
--  as the module, without an underscore.
-- - If the wrapper exists without _main, the wrapper is assumed to be the main
--  function.
-- - If both wrapper and _main exists, _main is the main function.
-- - If neither function exists, then the module is a metamodule, a module that
--  generally provides functionality to other modules.
-- 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(code_unstripped)
function p.make_dependency_table(module_deps)
if not code_unstripped then return "" end
 
local lines = {}
local in_multiline = false
local end_pattern
 
for line in code_unstripped:gmatch("([^\n]*)\n") do
local processed = line
if in_multiline then
-- Check for end of multi-line comment first
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
local start_eq = processed:match("%-%-%[(=*)%[")
if start_eq then
in_multiline = true
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
table.insert(lines, processed)
end
 
return table.concat(lines, "\n")
end
 
-- Helper function
-- Blanks strings while preserving line numbers
function p.strip_strings(code)
-- Blank double-quoted strings
code = code:gsub('"(.-)"', function(s)
return string.rep(" ", #s + 2)  -- +2 for the quotes
end)
 
-- Blank single-quoted strings
code = code:gsub("'(.-)'", function(s)
return string.rep(" ", #s + 2)
end)
 
-- Blank long bracketed strings [[...]]
code = code:gsub("%[%[(.-)%]%]", function(s)
-- Preserve line breaks
local blanks = s:gsub(".", " ")
local newlines = s:gsub("[^\n]", " ")
return blanks .. "]" .. "]"
end)
 
return code
end
 
 
-- Helper function
-- Find dependencies for a module, given a preprocessed module's code, then use
-- that information to find every function call for each dependency.
function p.find_dependencies(code)
local deps = {} -- Dependencies used
-- STEP 1
-- For each require line, get the dependency name (dep), the variable used
-- for that dependency (var), and, if applicable, the function used from
-- that dependency.
-- A require line looks like: local var = require("Module:Dependency").func,
-- where ".func" is optional.
for var, dep, func in code:gmatch([[local%s+([%w_]+)%s*=%s*require%(%s*["']([^"']+)["']%s*%)%.?([%w_%.]*)]]) do
if func == "" then func = nil end -- If func was blank, replace with nil instead
deps[var] = {
["dep"] = dep,
["funcs"] = { },
["direct_func"] = func -- For detecting whether one function out of a package was used
}
end
-- STEP 2
-- For each dependency found, find all function calls that involve that
-- dependency, as var.func(), or var(), without duplicates. If at least one
-- function call was found, then that module is used.
for var, info in pairs(deps) do
local seen  = {}  -- For detecting whether a function call was already found
local funcs = {}  -- For tracking all found function calls
if info["direct_func"] then
-- SPECIAL CASE 1: only one function imported from a package
if code:match(var .. "%s*%(") then
funcs = { info["direct_func"] }
end
else
-- EXPECTED CASE: multiple functions from package used
for func in code:gmatch(var .. "%.([%w_%.]+)%s*%(") do
if not seen[func] then
seen[func] = true
table.insert(funcs, func)
end
end
-- SPECIAL CASE 2: module returns a function and is callable
if #funcs == 0 and code:match(var .. "%s*%(") then
funcs = { var }
end
end
info["funcs"] = funcs
end
 
return deps
end


-- Helper function
-- Table headers
-- Given the output of the above function, create a mediawiki table
function p.make_dependency_table(deps)
local lines = {}
local lines = {}
table.insert(lines, '{| class="wikitable sortable"')
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")


-- Table header
-- Table rows (assuming they're all alphabetized)
table.insert(lines, '{| class="wikitable sortable left-1 left-2"')
for _, info in ipairs(module_deps) do
table.insert(lines, '! Variable')
table.insert(lines, '! Module')
table.insert(lines, '! Functions used')
 
for var, info in pairs(deps) do
local funcs_text
local funcs_text
if #info.funcs == 0 then
if #info.funcs == 0 then
funcs_text = "''dependency not used''"
funcs_text = "''dependency not used''"
else
else
funcs_text = table.concat(info.funcs, '<br />')
local func_lines = {}
for _, func in ipairs(info.funcs) do
table.insert(func_lines, string.format("<code>%s</code>", func))
end
funcs_text = table.concat(func_lines, "<br />")
end
end


table.insert(lines, '|-')
table.insert(lines, "|-")
table.insert(lines, '| ' .. var)
table.insert(lines, "| " .. info.var)
table.insert(lines, '| ' .. info.dep)
table.insert(lines, "| [[" .. info.dep .. "]]")
table.insert(lines, '| ' .. funcs_text)
table.insert(lines, "| " .. funcs_text)
end
end


-- Table footer
-- Table footer
table.insert(lines, '|}')
table.insert(lines, "|}")


-- Join all lines into a single string
-- Join all lines into a single string
return table.concat(lines, '\n')
return table.concat(lines, "\n")
end
 
 
-- Helper function
-- Find functions provided by a module, ignoring nested/local functions
function p.find_functions(code)
 
-- Iterate through file and find each function and the line found at
local funcs = {}
if code then
local line_num = 0
for line in code: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
end


Line 212: Line 48:
-- Lists module's own functions; requires module name to produce links to each
-- Lists module's own functions; requires module name to produce links to each
-- function.
-- function.
function p.make_function_table(module_name, module_functions, main_function)
function p.make_function_table(module_name, module_funcs, descriptions, main_function)
-- Collapse table if it's larger than 20 lines
-- Check whether descriptions was passed in
local func_class = "wikitable sortable mw-collapsible"
local has_descriptions = false
if #module_functions > 20 then
if type(descriptions) == "table" then
func_class = func_class .. " mw-collapsed"
for _, _ in pairs(descriptions) do
has_descriptions = true
break
end
end
end
local func_lines = {}
-- Table headers
--table.insert(func_lines, string.format("'''Module:%s''' provides %d function(s):", module_name, #module_functions))
local lines = {}
table.insert(func_lines, "{| class=\"" .. func_class .. "\"")
--table.insert(lines, string.format("'''Module:%s''' provides %d function(s):", module_name, #module_funcs))
table.insert(func_lines, "|+ Functions provided by this module")
table.insert(lines, '{| class="wikitable sortable"')
table.insert(func_lines, "! Function")
table.insert(lines, "|+ style=\"font-size: 105%;\" | " .. string.format("Functions&nbsp;provided&nbsp;(%d)", #module_funcs))
table.insert(func_lines, "! Line")
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


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
-- Helper function: determines whether module has a main function; if it does,
-- it indicates that it's not a library function and provides specific function-
-- ality, usually for a template.


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


-- 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(code)
local module_funcs = iutils.find_functions(code)
local func_lines = p.make_function_table(module_name, module_functions, main_function)
local func_table = p.make_function_table(module_name, module_funcs, descriptions, main_function)


-- Return the tables as strings
-- Return the tables
local summary = string.format("'''Introspection summary:''' Module:%s provides %d functions(s).", module_name, #module_functions)
-- Styling may be improved at a later time
return summary .. "\n" .. table.concat(func_lines, "\n") .. "\n" .. dep_table
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 table.concat(lines, "\n")
end
end


-- Wrapper function for modules
-- Wrapper function for modules
Line 283: 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 290: 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
})
})
end


function p.tester()
    -- Debugger option to show generated WikiText
local sample_code_1 = [[
    local wtext = yesno(frame.args["wtext"] or args["wtext"])
-- Package of functions (used)
 
local util = require("Module:Util")
if wtext == true then
util.trim(" x ")
result = "<syntaxhighlight lang=\"wikitext\">" .. result .. "</syntaxhighlight>"
util.str.pad("y")
end
-- Module returning a single function (used)
local makeMessage = require("Module:Message")
makeMessage("hello")
-- Module returning a table but only one function imported (used)
local trim = require("Module:StringUtils").trim
trim(" world ")
]]
local sample_code_2 = [[
-- Package of functions (used)
local util = require("Module:Util")
util.trim(" x ")
util.str.pad("y")
-- Module returning a single function (used)
local makeMessage = require("Module:Message")
makeMessage("hello")
-- Module returning a table but only one function imported (used)
local trim = require("Module:StringUtils").trim
trim(" world ")
-- UNUSED MODULES
-- Unused package of functions
local mathx = require("Module:MathX")
-- Unused module returning a single function
local sendNotification = require("Module:Notify")
-- Unused single imported function
local pad = require("Module:Util").pad
]]
local title = mw.title.new("Module:Infobox MOS")
local code = title:getContent()
code = p.strip_comments(code) -- Blank-out comments
return p.make_dependency_table(p.find_dependencies(code))
return frame:preprocess(result)
end
end


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