Global Lua Modules/Arguments

Arguments invocation argument extractor for Scribunto modules. It is intended for use by other Lua modules, and should not be called from an invocation (#invoke) directly.

This module supports the following features:

Trimming and blank argument removal.
Argument inheritance between child and parent frames.
Argument extraction for external modules and console input.
Options to customise argument extraction behaviour.

Installation

Lua installation

Module:

Create Module:Arguments on your wiki with the following code:

return require('Dev:Arguments')

Documentation

Package items

arguments.getArgs(frame, options) (function)

Main argument extraction utility. Arguments are memoized once fetched for optimal performance, as with the frame.args metatable in Scribunto core.

The default argument lookup behaviour uses the child frame arguments first, then the parent frame arguments. There are numerous frame options to change this behaviour.

The default value tidying behaviour trims parameter values if they are defined strings and treats blank strings as nil. This can be customised in the getArgs options.

Parameters:

frame Scribunto frame object or Lua arguments table, passed from an invocation or Lua logic such as frame:getParent(). If this parameter does not have an args field and a getParent method, frame is assumed to be a Lua arguments table, such as the arguments from a named arguments call. (frame|table)
options Extraction/processing options. (table; optional)
- options.trim Whether to trim the blank arguments present in the arguments table. Accepts false only. Default: true. (boolean; optional)
- options.removeBlanks Whether to remove blank arguments from the arguments table. Does not shift sequential arguments removed by the processing stage. Accepts false only. Default: true. (boolean; optional)
- options.valueFunc Custom value tidying function for use if the trim and removeBlanks options don't cover the developer's argument processing use case. (function; optional)
- options.frameOnly Only read arguments from child frame (the frame parameter - usually invocation frame). (boolean; optional)
- options.parentOnly Only read arguments from frame parent (the frame parameter - usually template frame). (boolean; optional)
- options.parentFirst Argument lookup in the frame parent first, prioritised over the invocation frame arguments. (boolean; optional)
- options.wrappers Individual value or array of values, listing wrapper title name(s) or article ID(s) to permit parent argument lookup from. (table; optional)
- options.wrapper Alias of options.wrappers - contains title name or article ID to permit parent argument lookup from. (string|number; optional)
- options.readOnly Whether to restrict write permissions to the arguments table. When set to a truthy value, an error will be thrown on any write attempt. (boolean; optional)
- options.noOverwrite Whether to restrict overwrite attempts on existing argument keys in the arguments table. When set to a truthy value, an error will be thrown on any write attempt that would result in an existing argument being overwritten. (boolean; optional)
- options.translate Map of parameter name aliases to their canonical argument parameter names. (table; optional)
- options.backtranslate Map of canonical parameter names to their argument parameter aliases. Supersedes options.translate if both options are in use. (table; optional)

Errors:

'bad value assigned to option "valueFunc" (function expected, got $type)' (line 317; optional)
'could not write to argument table key "$key"; the table is read-only' (line 407; optional)
'could not write to argument table key "$key"; overwriting existing arguments is not permitted' (line 409; optional)

Returns: Arguments extracted from invocation. The argument data is embedded as a metatable in the exported table and cannot be accessed with the # operator or table library methods. However, the exported table can be written to if the options.readOnly flag parameter is not truthy. (table)

Note: Reference tags in the form of <ref> will generate phantom references when calling the pairs iterator on the arguments table, IF the <ref> tag does not appear in the dependent module's wikitext output.

Usage:

local getArgs = require('Module:Arguments').getArgs
function p.main(frame)
    local args = getArgs(frame, {
        wrapper = 'Template:<TEMPLATE>'
    })
    -- Use the args table here.
    -- A common paradigm is <code><nowiki>return p._main(args)</nowiki></code>.
    -- This allows other Lua modules to access the
    -- main logic in a performant manner without a
    -- frame object.
end

Notes

The args table from the arguments.getArgs function is a metatable for performance reasons. Thus, the table will not permit Lua table methods such as #args, next(args), and table library functions.
This module will eventually be adapted as a library in MediaWiki core, called as require('getArgs'). The core library will remove options.parentOnly.

Global Lua Modules/Arguments

Contents

Installation

Documentation

Package items

Notes

See also

Fan Feed