Module:Arguments/doc

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.

In the most basic scenario, you can use getArgs inside your main function. The variable  is a table containing the arguments from #invoke. (See below for details.)

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.

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.

Options
The following options are available. They are explained in the sections below.

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  and   arguments to.

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  option. The input to this option must be a function that takes two parameters,  , and returns the value of the argument. This function is called every time an argument is requested from the  table.

Example 1: this function preserves whitespace for the first positional argument, but trims all other arguments and removes all other blank arguments.

Example 2: this function removes blank arguments and converts all arguments to lower case, but doesn't trim whitespace from positional parameters.

Note: if you are using the  function in the main function of your module, be aware that if it is called from another Lua module then   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  and   functions, or something similar).

Frames and parent frames
Arguments in the  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. This module prints the first three positional arguments that it is passed.

is then called by, which contains the code. This produces the result "firstArg".

Now if we were to call, the following would happen:


 * 1)   &rarr; firstArg
 * 2)   &rarr; firstArg
 * 3)   &rarr; 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  option.

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.)

It is possible to alter this behaviour with the  and   options. If  is set then it is not possible to write any values to the args table at all. If  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.