Module:Arguments/doc: Difference between revisions
add info about frames and parent frames |
add info on writing to the args table |
||
Line 180: | Line 180: | ||
}) |
}) |
||
</source> |
</source> |
||
=== Writing to the args table === |
|||
Sometimes it can be useful to write new values to the args table. This is possible with the default settings of this module. (However, bear in mind that it is usually better coding style to create a new table with your new values and copy arguments from the args table as needed.) |
|||
<source lang="lua"> |
|||
args.foo = 'some value' |
|||
</source> |
|||
It is possible to alter this behaviour with the <code>readOnly</code> and <code>noOverwrite</code> options. If <code>readOnly</code> is set then it is not possible to write any values to the args table at all. If <code>noOverwrite</code> is set, then it is possible to add new values to the table, but it is not possible to add a value if it would overwrite any arguments that are passed from #invoke. |
Revision as of 07:12, December 9, 2013
This module provides easy processing of arguments passed from #invoke. It is a meta-module, meant for use by other modules, and should not be called from #invoke directly. Its features include:
- Easy trimming of arguments and removal of blank arguments.
- Arguments can be passed by both the current frame and by the parent frame at the same time. (More details below.)
- Arguments can be passed in directly from another Lua module or from the debug console.
- Most features can be customized.
Basic use
First, you need to load the module. It contains one function, named getArgs
.
local getArgs = require('Module:Arguments').getArgs
In the most basic scenario, you can use getArgs inside your main function. The variable args
is a table containing the arguments from #invoke. (See below for details.)
local getArgs = require('Module:Arguments').getArgs
local p = {}
function p.main(frame)
local args = getArgs(frame)
-- Main module code goes here.
end
return p
However, the recommended practice is to use a function just for processing arguments from #invoke. This means that if someone calls your module from another Lua module you don't have to have a frame object available, which improves performance.
local getArgs = require('Module:Arguments').getArgs
local p = {}
function p.main(frame)
local args = getArgs(frame)
return p._main(args)
end
function p._main(args)
-- Main module code goes here.
end
return p
If you want multiple functions to use the arguments, and you also want them to be accessible from #invoke, you can use a wrapper function.
local getArgs = require('Module:Arguments').getArgs
local function makeInvokeFunc(funcName)
return function (frame)
local args = getArgs(frame)
return p[funcName](args)
end
end
local p = {}
p.func1 = makeInvokeFunc('_func1')
function p._func1(args)
-- Code for the first function goes here.
end
p.func2 = makeInvokeFunc('_func2')
function p._func2(args)
-- Code for the second function goes here.
end
return p
Options
The following options are available. They are explained in the sections below.
local args = getArgs(frame, {
trim = false,
removeBlanks = false,
valueFunc = function(key, val)
-- Code for processing one argument
end,
parentFirst = true,
readOnly = true,
noOverwrite = true
})
Trimming and removing blanks
Blank arguments often trip up coders new to converting MediaWiki templates to Lua. In template syntax, blank strings and strings consisting only of whitespace are considered false. However, in Lua, blank strings and strings consisting of whitespace are considered true. This means that if you don't pay attention to such arguments when you write your Lua modules, you might treat something as true that should actually be treated as false. To avoid this, by default this module removes all blank arguments.
Similarly, whitespace can cause problems when dealing with positional arguments. Although whitespace is trimmed for named arguments coming from #invoke, it is preserved for positional arguments. Most of the time this additional whitespace is not desired, so this module trims it off by default.
However, sometimes you want to use blank arguments as input, and sometimes you want to keep additional whitespace. This can be necessary to convert some templates exactly as they were written. If you want to do this, you can set the trim
and removeBlanks
arguments to false
.
local args = getArgs(frame, {
trim = false,
removeBlanks = false
})
Custom trimming and blank removal
Sometimes you want to remove some blank arguments but not others, or perhaps you might want to put all of the positional arguments in lower case. To do things like this you can use the valueFunc
option. The input to this option must be a function that takes two parameters, key
value
, and returns the value of the argument. This function is called every time an argument is requested from the args
table.
Example 1: this function preserves whitespace for the first positional argument, but trims all other arguments and removes all other blank arguments.
local args = getArgs(frame, {
valueFunc = function(key, value)
if key == 1 then
return value
else
value = mw.text.trim(value)
if value ~= '' then
return value
end
end
end
})
Example 2: this function removes blank arguments and converts all arguments to lower case, but doesn't trim whitespace from positional parameters.
local args = getArgs(frame, {
valueFunc = function(key, value)
value = mw.ustring.lower(value)
if mw.ustring.find(value, '%S') then
return value
end
end
})
Note: if you are using the getArgs
function in the main function of your module, be aware that if it is called from another Lua module then value
might not always be a string. This is not a problem if you are using a function specially for arguments from #invoke (i.e. you have p.main
and p._main
functions, or something similar).
Frames and parent frames
Arguments in the args
table can be passed from the current frame or from its parent frame at the same time. To understand what this means, it is easiest to give an example. Let's say that we have a module called Module:ExampleArgs
. This module prints the first three positional arguments that it is passed.
local getArgs = require('Module:Arguments').getArgs
local p = {}
function p.main(frame)
local args = getArgs(frame)
return p._main(args)
end
function p._main(args)
local first = args[1] or ''
local second = args[2] or ''
local third = args[3] or ''
return first .. ' ' .. second .. ' ' .. third
end
return p
Module:ExampleArgs
is then called by Template:ExampleArgs
, which contains the code {{#invoke:ExampleArgs|main|firstArg}}
. This produces the result "firstArg".
Now if we were to call Template:ExampleArgs
, the following would happen:
{{ExampleArgs}}
→ firstArg{{ExampleArgs|myFirstArg}}
→ firstArg{{ExampleArgs|myFirstArg|mySecondArg|myThirdArg}}
→ firstArg mySecondArg myThirdArg
If you want the value from the parent frame to have precedence over the value from the current frame (i.e. if you would like "myFirstArg" instead of "firstArg" in the second example above), you can do so with the parentFirst
option.
local args = getArgs(frame, {
parentFirst = true
})
Writing to the args table
Sometimes it can be useful to write new values to the args table. This is possible with the default settings of this module. (However, bear in mind that it is usually better coding style to create a new table with your new values and copy arguments from the args table as needed.)
args.foo = 'some value'
It is possible to alter this behaviour with the readOnly
and noOverwrite
options. If readOnly
is set then it is not possible to write any values to the args table at all. If noOverwrite
is set, then it is possible to add new values to the table, but it is not possible to add a value if it would overwrite any arguments that are passed from #invoke.