Module:Arguments

This module provides a standardized interface for fetching and normalizing parameters passed to Scribunto Lua modules from frame and parent frame contexts.

Features

Trims leading and trailing whitespace from string parameters by default.
Converts empty string parameters to nil by default.
Merges parameters passed directly to #invoke with parameters passed to the parent template.
Uses lazy evaluation via metatables so parameters are only processed when accessed.

Usage

To use this module in another Lua module, require it and call getArgs:

local Arguments = require('Module:Arguments')

local p = {}

function p.main(frame)
    local args = Arguments.getArgs(frame)
    
    -- Access positional or named parameters directly
    local firstArg = args[1] or 'default value'
    local title = args.title or 'default title'
    
    return firstArg .. ' - ' .. title
end

return p

Functions

getArgs

Arguments.getArgs(frame, options)

Returns a table containing processed arguments from the given frame and/or parent frame.

frame: The Scribunto frame object passed by MediaWiki.
options: (Optional) A table of configuration options altering how parameters are retrieved and sanitized.

Configuration Options

Option	Type	Default	Description
`trim`	boolean	`true`	If `true`, trims leading and trailing whitespace from parameter strings.
`removeBlanks`	boolean	`true`	If `true`, converts empty parameter strings (or whitespace-only strings) to `nil`.
`parentOnly`	boolean	`false`	If `true`, fetches parameters only from the parent template context, ignoring direct `#invoke` parameters.
`frameOnly`	boolean	`false`	If `true`, fetches parameters only from the `#invoke` frame context, ignoring parent template parameters.
`parentFirst`	boolean	`false`	If `true`, parameters set on the parent template override parameters set on the `#invoke` frame when key names conflict.
`valueFunc`	function	`nil`	A custom callback `function(key, value)` to preprocess, modify, or validate individual parameter values.

Examples

Retaining Whitespace and Blank Values

To preserve raw whitespace and empty string arguments:

local args = Arguments.getArgs(frame, {
    trim = false,
    removeBlanks = false
})

Using a Custom Value Function

To automatically convert numeric parameters to Lua numbers:

local args = Arguments.getArgs(frame, {
    valueFunc = function(key, val)
        if key == 'count' or key == 1 then
            return tonumber(val)
        end
        return val
    end
})

Unit Tests

Unit tests are maintained at Module:Arguments/testcases. To execute the suite on a page, insert:

{{#invoke:arguments/testcases|run}}

--[[
Module:Arguments

Provides a standardized wrapper for fetching and normalizing arguments passed to 
Scribunto Lua modules from frame and parent frame contexts. Handles automatic 
whitespace trimming, empty value stripping, parameter precedence, and custom value mapping.
--]]

local Arguments = {}

local function processValue(val, trim, removeBlanks)
    if type(val) ~= 'string' then
        return val
    end
    if trim then
        val = val:match('^%s*(.-)%s*$')
    end
    if removeBlanks and val == '' then
        return nil
    end
    return val
end

function Arguments.getArgs(frame, options)
    options = options or {}
    local trim = options.trim ~= false
    local removeBlanks = options.removeBlanks ~= false
    local valueFunc = options.valueFunc

    local args = {}
    local memo = {}

    local fargs = (not options.parentOnly and type(frame) == 'table' and type(frame.args) == 'table') and frame.args or {}
    local pargs = (not options.frameOnly and type(frame) == 'table' and type(frame.getParent) == 'function' and frame:getParent() and frame:getParent().args) or {}

    local primary = options.parentFirst and pargs or fargs
    local secondary = options.parentFirst and fargs or pargs

    local function fetchValue(key)
        local val = primary[key]
        if val == nil then
            val = secondary[key]
        end
        if val == nil then
            return nil
        end
        if valueFunc then
            return valueFunc(key, val)
        end
        return processValue(val, trim, removeBlanks)
    end

    local mt = {
        __index = function(_, key)
            if memo[key] ~= nil then
                return memo[key]
            end
            local val = fetchValue(key)
            memo[key] = val
            return val
        end,
        __newindex = function(_, key, val)
            memo[key] = val
        end,
        __pairs = function()
            local keys, seen = {}, {}
            for k in pairs(primary) do if not seen[k] then seen[k] = true; table.insert(keys, k) end end
            for k in pairs(secondary) do if not seen[k] then seen[k] = true; table.insert(keys, k) end end
            local i = 0
            return function()
                while i < #keys do
                    i = i + 1
                    local k = keys[i]
                    if args[k] ~= nil then
                        return k, args[k]
                    end
                end
            end
        end
    }

    return setmetatable(args, mt)
end

return Arguments