Module:Parameters/documentation

From Imperivm Romanvm
Jump to navigation Jump to search

This module provides processing and checking of template arguments.

process[edit source]

lua

Processes arguments with a given list of parameters, and returns a table containing the processed arguments. The args parameter specifies the arguments to be processed; they are the arguments you might retrieve from lua. The params parameter specifies a list of valid parameters, and consists of a table. If an argument is encountered that is not in the parameter table, an error is shown.

The parameters table should have the parameter names as the indexes, and a (possibly empty) table of parameter tags as the value. An empty table as the value merely states that the parameter exists, but should not receive any special treatment. Possible parameter tags are listed below.

An example parameters table (from Module:translations):

{
	[1] = {required = true, default = "und"},
	[2] = {},
	[3] = {list = true},
	["alt"] = {},
	["sc"] = {},
	["tr"] = {},
}

The return_unknown parameter, if set to lua, prevents the function from triggering an error when it comes across an argument with a name that it doesn't recognise. Instead, the return value is a pair of values: the first is the processed arguments as usual, while the second contains all the unrecognised arguments that were left unprocessed. This allows you to do multi-stage processing, where the entire set of arguments that a template should accept is not known at once. For example, an inflection-table might do some generic processing on some arguments, but then defer processing of the remainder to the function that handles a specific inflectional type.

Parameter tags[edit source]

lua
The parameter is required; an error is shown if it is not present. The template's page itself is an exception; no error is shown there.
lua
Specifies a default value for the parameter, if it is absent or empty. When used on list parameters, this specifies a default value for the first item in the list only. Note that it is not possible to generate a default that depends on the value of other parameters.
If used together with lua, the default applies only to the template's page itself. This can be used to show an example text.
lua
Treat the parameter as an alias of another. When arguments are specified for this parameter, they will automatically be renamed and stored under the alias name. This allows for parameters with multiple alternative names, while still treating them as if they had only one name. It is even possible for the lua to have a name that is not a parameter itself.
Aliases should not be required, as this prevents the other name or names of the parameter from being used. Parameters that are aliases and required at the same time are tracked (see Special:WhatLinksHere/Template:tracking/parameters/required alias).
lua
If the argument is an empty string value, it is not converted to lua, but kept as-is.
lua
Spacing characters such as spaces and newlines at the beginning and end of a positional parameter are not removed.
lua
Specifies what value type to convert the argument into. The default is to leave it as a text string. Alternatives are:
lua
The value is treated as a boolean value, either true or false. No value, the empty string, and the strings lua, lua, lua and lua are treated as lua, all other values are considered lua.
lua
The value is converted into a number, or lua if the value is not parsable as a number.
lua
Treat the parameter as a list of values, each having its own parameter name, rather than a single value. The parameters will have a number at the end, except optionally for the first (but see also lua). For example, lua on a parameter named "head" will include the parameters |head= (or |head1=), |head2=, |head3= and so on. If the parameter name is a number, another number doesn't get appended, but the counting simply continues, e.g. for parameter lua the sequence is |3=, |4=, |5= etc. List parameters are returned as numbered lists, so for a template that is given the parameters |head=a|head2=b|head3=c, the processed value of the parameter lua will be lua.
The value for lua can also be a string. This tells the module that parameters other than the first should have a different name, which is useful when the first parameter in a list is a number, but the remainder is named. An example would be for genders: lua on a parameter named lua would have parameters |1=, |g2=, |g3= etc.
If the number is not located at the end, it can be specified by putting an equal sign "=" at the number position. For example, parameters |f1accel=, |f2accel=, ... can be captured by using the parameter name lua, as is done in Module:headword/templates.
lua
This is used in conjunction with list-type parameters. By default, the values are tightly packed in the resulting list. This means that if, for example, an entry specified head=a|head3=c but not |head2=, the returned list will be lua, with the values stored at the indices lua and lua, not lua and lua. If it is desirable to keep the numbering intact, for example if the numbers of several list parameters correlate with each other (like those of {{compound}}), then this tag should be specified.
If lua is given, there may be lua values in between two real values, which makes many of Lua's table processing functions no longer work, like lua or lua. To remedy this, the resulting table will contain an additional named value, maxindex, which tells you the highest numeric index that is present in the table. In the example above, the resulting table will now be lua. That way, you can iterate over the values from lua to maxindex, while skipping lua values in between.
lua
This is used in conjunction with list-type parameters. By default, the first parameter can have its index omitted. For example, a list parameter named head can have its first parameter specified as either |head= or |head1=. If lua is specified, however, only |head1= is recognized, and |head= will be treated as an unknown parameter. {{affixusex}} (and variants {{suffixusex}}, {{prefixusex}}) use this, for example, on all list parameters. One possible use opened up by this is to distinguish between |head= and |head1= as different parameters. This is used in {{affixusex}} and variants, for example, to distinguish between |sc= (a script code for all elements in the usex's language) and |sc1= (the script code of the first element, used when |lang1= is also specified to indicate that the first element is in a different language).