Module:Arguments/doc: Difference between revisions
add info on trimming and removing blanks |
add valueFunc info |
||
Line 13: | Line 13: | ||
</source> |
</source> |
||
In the most basic scenario, you can use getArgs inside your main function. |
In the most basic scenario, you can use getArgs inside your main function. The variable <code>args</code> is a table containing the arguments from #invoke. (See below for details.) |
||
<source lang="lua"> |
<source lang="lua"> |
||
Line 102: | Line 102: | ||
local args = getArgs(frame, { |
local args = getArgs(frame, { |
||
trim = false, |
trim = false, |
||
removeBlanks = false |
removeBlanks = false |
||
}) |
}) |
||
</source> |
</source> |
||
=== 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 <code>valueFunc</code> option. The input to this option must be a function that takes two parameters, <code>key</code> <code>value</code>, and returns the value of the argument. This function is called every time an argument is requested from the <code>args</code> table. |
|||
Example 1: this function preserves whitespace for the first positional argument, but trims all other arguments and removes all other blank arguments. |
|||
<source lang="lua"> |
|||
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 |
|||
}) |
|||
</source> |
|||
Example 2: this function removes blank arguments and converts all arguments to lower case, but doesn't trim whitespace from positional parameters. |
|||
<source lang="lua"> |
|||
local args = getArgs(frame, { |
|||
valueFunc = function(key, value) |
|||
value = mw.ustring.lower(value) |
|||
if mw.ustring.find(value, '%S') then |
|||
return value |
|||
end |
|||
end |
|||
}) |
|||
</source> |
|||
Note: if you are using the <code>getArgs</code> function in the main function of your module, be aware that if it is called from another Lua module then <code>value</code> 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 <code>p.main</code> and <code>p._main</code> functions, or something similar). |
Revision as of 06:18, 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).