Module:ArgsUtil/doc: Difference between revisions

Latest revision as of 11:54, 20 June 2026

Module:ArgsUtil is a tiny helper that other modules use to collect a template's arguments, merged with any defaults set directly in the Script error: You must specify a function to call. call.

Overview

This is a building-block module, not something used on pages. When a template like Template:Foo calls Script error: No such module "Foo"., a Lua module often wants both sets of arguments combined: the defaults written in the invoke (b=2) plus whatever the editor passed to the template (a=1), with the editor's values winning. Module:ArgsUtil does exactly that in one function.

It has a single exported function, merge, and no configuration. It is required by other modules (for example {{Template link}}^m) rather than invoked from a page.

Functions / entry points

Function (#invoke)	What it does	Called by
`p.merge`	Returns a single args table: it reads the current frame's own args (the invoke) and the parent frame's args (the template), trims them, drops empty values, and merges them so the parent (template) args override the invoke args. Takes no parameters — it fetches the current frame itself.	Other Lua modules via `require`, e.g. `{{Template link}}^m`

How it's used

This is called from Lua, not from wikitext. Typical pattern:

local util_args = require('Module:ArgsUtil')

local p = {}
function p.main(frame)
  local args = util_args.merge() -- no need to pass `frame`; merge() finds it
  -- `args` = invoke defaults overridden by whatever the template was given
end
return p

For example, {{Template link}}^m begins with local getArgs = require('Module:ArgsUtil').merge and calls getArgs() in its p.main.

Ordinary editors never touch this module.

Notes

Precedence: template (parent) values win over invoke values. (This is the opposite of {{Infobox}}^m's internal h.overwrite helper, which deliberately lets the invoke override the template — keep that distinction in mind if you compare the two.)
Empty strings are discarded during the merge, so a blank parameter does not clobber a default.
By design it ships with only this one function and no options, to keep it simple. The pre-existing wiki doc notes an extended version is available on the support wiki if more functionality is needed.
Related: {{Template link}}^m (its main consumer).

@@ Line 1: / Line 1: @@
-This is a basic module for processing args. Usage:
+'''Module:ArgsUtil is a tiny helper that other modules use to collect a template's arguments, merged with any defaults set directly in the {{#invoke:}} call.'''
+__TOC__
+== Overview ==
+This is a building-block module, not something used on pages. When a template like <code>{{Foo|a=1}}</code> calls <code>{{#invoke:Foo|main|b=2}}</code>, a Lua module often wants both sets of arguments combined: the defaults written in the invoke (<code>b=2</code>) plus whatever the editor passed to the template (<code>a=1</code>), with the editor's values winning. <code>Module:ArgsUtil</code> does exactly that in one function.
+It has a single exported function, <code>merge</code>, and no configuration. It is required by other modules (for example {{ml|Template link}}) rather than invoked from a page.
+== Functions / entry points ==
+{| class="wikitable"
+! Function (#invoke) !! What it does !! Called by
+|-
+| <code>p.merge</code> || Returns a single args table: it reads the current frame's own args (the invoke) and the parent frame's args (the template), trims them, drops empty values, and merges them so the '''parent (template) args override''' the invoke args. Takes no parameters — it fetches the current frame itself. || Other Lua modules via <code>require</code>, e.g. {{ml|Template link}}
+|}
+== How it's used ==
+This is called from Lua, not from wikitext. Typical pattern:
 <syntaxhighlight lang="lua">
@@ Line 5: / Line 24: @@
 local p = {}
 function p.main(frame)
-   local args = util_args.merge() -- it is not necessary to pass a `frame` object; `merge` will generate its own
+   local args = util_args.merge() -- no need to pass `frame`; merge() finds it
-  mw.logObject(args)
+   -- `args` = invoke defaults overridden by whatever the template was given
-   -- `args` now contains args passed via the template merged with defaults provided directly via the invoke.
-  -- anything the user sent via the template will be given priority.
 end
 return p
 </syntaxhighlight>
-== Extending this module ==
+For example, {{ml|Template link}} begins with <code>local getArgs = require('Module:ArgsUtil').merge</code> and calls <code>getArgs()</code> in its <code>p.main</code>.
+Ordinary editors never touch this module.
+== Notes ==
-By design, {{ml|ArgsUtil}} is shipped with only a single function and no customization available; this simplifies documentation and covers nearly all use cases. An extended version of this module is available at [[support:Module:ArgsUtil|Module:ArgsUtil on the support wiki]] if you want additional functionality; and you can of course feel free to modify this module on your own wiki as needed.
+* '''Precedence:''' template (parent) values win over invoke values. (This is the opposite of {{ml|Infobox}}'s internal <code>h.overwrite</code> helper, which deliberately lets the invoke override the template — keep that distinction in mind if you compare the two.)
+* Empty strings are discarded during the merge, so a blank parameter does not clobber a default.
+* By design it ships with only this one function and no options, to keep it simple. The pre-existing wiki doc notes an extended version is available on the support wiki if more functionality is needed.
+* '''Related:''' {{ml|Template link}} (its main consumer).