Wikipedia:Lua/Modul/TemplatePar/en
Vorlagenprogrammierung | Diskussionen | Lua | Test | Unterseiten | |||
Modul | Deutsch | English
|
Modul: | Dokumentation |
TemplatePar
– Module with support for template programming, focussing on parameters of template transclusion.
While the module name suggests usage with templates, lua modules are supported as well.
- assert – Check single string
- check – Check transclusion of template
- count – Number of template parameters
- countNotEmpty – Number of template parameters which contain more than whitespace
- downcase – All template transclusion parameters in lower case
- match – Combined analysis of parameters and their values
- valid – Test single template parameter value
- verify – Check
#invoke
parameter set - failsafe – Module versioning
Functions for templates
[Am Gwëntext werkeln]The analysis is operating on the template transclusion parameters. Parameters of #invoke
are described below; they are controlling the analysis.
assert
[Am Gwëntext werkeln]- Check single string
- 1
- String to be tested
- 2
- Condition (optional but recommended and meaningful)
check
[Am Gwëntext werkeln]- Test for assigned and unexpected parameters at template transclusion; completeness of required values. Details below.
- An error message will be returned enclosed in
class=error
. - If nothing is returned no error was detected.
- Parameters (all optional):
- all
- Names of mandatory parameters (all to be supplied); they are also to be provided with trimmed non-empty value.
- Multiple items separated by
=
(equal sign). - If lacking in transclusion a standard message will be triggered. For individual handling it should be mentioned at opt and analysed by template programming.
- opt
- Names of all optional parameters
- These parameters are separated by
=
(equal sign). - low
true
: ignore case
count
[Am Gwëntext werkeln]- Number of parameters at template transclusion.
- Parameter: None (at #invoke)
- The result is a number beginning at
0
.
countNotEmpty
[Am Gwëntext werkeln]- Number of parameters at template transclusion which contain more than whitespace.
- Parameter: None (at #invoke)
- The result is a number beginning at
0
.
match
[Am Gwëntext werkeln]- Combined analysis of parameters and their values; is template profile matching current transclusion?
- 1
- Rule in format
1=
parameter name=
condition - n…
- Like 1 – any unnamed parameter in any order imposes further rules on template parameters.
- All permitted optional template parameters are to be mentioned, at least by
*
condition. - An error message will be returned enclosed in
class=error
. Fatal errors will be visible at following levels: Unknown parameter name – missing parameter – invalid parameter value. - If “nothing” is returned no error was detected.
valid
[Am Gwëntext werkeln]- Check validity of one particular template parameter.
- An error message will be returned enclosed in
class=error
. - If nothing is returned no error was detected.
- Parameters (all but 1 optional):
- 1
- Name of analyzed template parameter.
- 2
- Format („Digits only“, „ASCII“, limited character set, Lua-pattern); see below.
- min
- Minimal length ≥0.
- max
- Maximal length >0.
- From the group 2, min, max at least one condition should be provided for meaningful rules.
- low
true
: ignore case
failsafe
[Am Gwëntext werkeln]- Version identification:
2018-08-10
- Optional additional parameter
1
– requested minimal version identification, orwikidata
- Returns:
- (empty), if minimal version condition not matched
- version ID (local or @wikidata:
2018-08-10
)
- Returns:
Common error handling
[Am Gwëntext werkeln]All functions described above which detect an error condition (check, valid as well as downcase, verify) maintain also the following parameters:
- template
- Title of template visible to page editors (for error messages).
- Might be a different identifier. Mainly intended for sub-templates.
- May contain wikilinks, or surrounded by arbitrary text. Note that this is used by
cat
as well. - cat
- Title of a maintenance category. (do not add
category:
prefix) - In case of error this will be activated (appended to result).
- If the string
@@@
is found in title andtemplate
is provided, that will be replaced bytemplate
. - errNS
- Space separated list of namespace numbers to limit
cat
triggering, otherwise causing the maintenance category to appear in all namespaces. - format
- Format or suppress error message.
- Standard case, default message formatted by
class="error"
markup:- Parameter
format
not provided. |format=*|
- Parameter
- Suppress (then
cat=
should be declared):|format=|
|format=0|
|format=-|
- Constant text, own formatting, any syntax:
|format=<start>Constant text</end>|
- Free formatting of default message:
- Contains
@@@
as placeholder for the unformatted default message text, any syntax. |format=<start>Constant text; @@@</end>|
- Contains
- Standard case, default message formatted by
- preview
- Suppress message suppression in preview mode, show default message always even if
|format=0|
has been requested:|preview=1|
- Constant text in preview mode, own formatting, any syntax:
|preview=<start>Constant text</end>|
- Free formatting of default message in preview mode:
|preview=<start>Constant text; @@@</end>|
Lua modules yield false
if no problem detected, else error message.
Parameter test (check)
[Am Gwëntext werkeln]Use case on commons:Template:Information example:
{{#invoke:TemplatePar
|check
|all= description= source= author=
|opt= date= permission= other_versions= other_fields=
|template=Information}}
- Since the name of a template parameter can’t contain an
=
equal sign, those are used for separation of names. Whitespace before and after names will be ignored; as well as additional equal signs. - The first three parameters of this example are mandatory and need to be provided including non-empty value.
- Any parameter name appearing in template transclusion, which is neither listed in
all=
nor inopt=
will trigger an error message. - Unnamed template parameters are identified by their sequence number. Those will be used in the error message.
- There are four error messages:
- TemplatePar#invoke: repeated optional parameter
- On module invocation a name has been listed in both
all=
andopt=
. - This might not be suppressed by
format=
since it has been caused by template programmer and not page author.
- On module invocation a name has been listed in both
- Error in template: unknown parameter name
- On template transclusion a parameter has been used which is not listed at
all=
noropt=
.
- On template transclusion a parameter has been used which is not listed at
- Error in template: mandatory parameter missing
- On template transclusion a parameter from the
all=
list is missing.
- On template transclusion a parameter from the
- Error in template: undefined value for mandatory
- On template transclusion a parameter from the
all=
list is given with equal sign but no visible value, or an unnamed parameter is empty, leaving a gap between two pipe symbols.
- On template transclusion a parameter from the
- TemplatePar#invoke: repeated optional parameter
Parameter format (valid)
[Am Gwëntext werkeln]There are two methods for the optional condition 2:
- Keyword
- Makes life easier for template programmers.
- Only generic formats are subject to this module. Specific formats like DOI, ISBN, URL, or date and time would cause too many changes, extensions and need too many maintenance updates.
- Lua-Pattern (Ustring)
- Enclosed in slashes
/
to distinguish from keyword and detect closing and trailing whitespace on values of unnamed template parameters. - The strings
|
as well as{{
and}}
are not possible in template programming. They are to be replaced:|
→%!
{{
→%((
}}
→%))
- Enclosed in slashes
Key | Meaning | Implementation |
---|---|---|
ASCII
|
ASCII character (codes 32–126), within one line only, or empty | ^[ -~]*$
|
ASCII+
|
as before; not empty | ^[ -~]+$
|
ASCII+1
|
in one word; else as before und not empty | ^[!-~]+$
|
n
|
ASCII digits 0–9 only, and leading sign ASCII minus, or empty | ^[%-]?[0-9]*$ exclude single minus |
n>0
|
ASCII digits 0–9 only, no sign, not empty and and least one digit non-zero | ^[0-9]*[1-9][0-9]*$
|
N+
|
Like n ; but leading zero not permitted and not empty
|
^[%-]?[1-9][0-9]*$
|
N>0
|
Like n>0
|
^[1-9][0-9]*$ ; but leading zero not permitted
|
x
|
Hexdec number; ASCII digits 0–9 letters a–f A–F, or empty | ^[0-9A-Fa-f]*$
|
x+
|
as before; but not empty. | ^[0-9A-Fa-f]+$
|
X
|
Hexdec number; ASCII digits 0–9 letters A–F, or empty | ^[0-9A-F]*$
|
X+
|
as before; but not empty. | ^[0-9A-F]+$
|
0,0
|
Any number; also less than zero; might contain comma; or empty | ^[%-]?[0-9]*,?[0-9]*$ exclude single minus or comma |
0,0+
|
Any number; contains one comma; also less than zero | ^[%-]?[0-9]+,[0-9]+$
|
0,0+?
|
Any number; also less than zero; might contain comma and digits after comma; not empty | ^[%-]?[0-9]+,?[0-9]*$
|
0.0
|
Any number; also less than zero; might contain period; or empty | ^[%-]?[0-9]*[%.]?[0-9]*$ exclude single minus or comma |
0.0+
|
Number with period and significant figures; also less than zero | ^[%-]?[0-9]+%.[0-9]+$
|
0.0+?
|
Any number; also less than zero; might contain period and significant figures; not empty | ^[%-]?[0-9]+[%.]?[0-9]*$
|
.0+
|
Any number; also less than zero; might contain period and significant figures, but not necessarily digit before period; not empty | ^[%-]?[0-9]*[%.]?[0-9]+$
|
aa
|
At least two letters (not necessarily aside: N.N.) or a CJK | %a.*%a or CJK |
ID
|
Identifier with restrictions common to many languages: ASCII, beginning with letter; later digits and underscore; or empty. Subsequent ASCII words might be regarded as such identifiers, too; e.g. URL component. |
^[A-Za-z]?[A-Za-z_0-9]*$
|
ID+
|
as before; but not empty. | ^[A-Za-z][A-Za-z_0-9]*$
|
ABC
|
Word of ASCII capital letters; or empty. | ^[A-Z]*$
|
ABC+
|
as before; but not empty. | ^[A-Z]+$
|
Abc
|
Word of ASCII letters, first letter capitalized only; or empty. | ^[A-Z]*[a-z]*$
|
Abc+
|
as before; but not empty. | ^[A-Z][a-z]+$
|
abc
|
Word of ASCII lowercase letters; or empty. | ^[a-z]*$
|
abc+
|
as before; but not empty. | ^[a-z]+$
|
aBc+
|
Word of ASCII letters with lower camel casing; not empty. | ^[a-z]+[A-Z][A-Za-z]*$
|
base64
|
Base64; or empty. | ^[A-Za-z0-9%+/]*$
|
base64+
|
as before; but not empty. | ^[A-Za-z0-9%+/]+$
|
pagename
|
Permitted page name; not empty. | not #<>[]|{} or 12710 or 1–3110
|
|
Permitted title or name of a media file at
With | |
|
Condition: arithmetic comparison or (also) numeric inequality | |
url url+
|
empty or exactly one Internet URL (mandatory) |
|
ref
|
containing <ref> – Citation needed
|
|
|
empty or language code empty or space separated list of language codes |
|
In Planung | ||
date
|
Irgendein bekanntes Format für Datum und auch Zeit. | |
*
|
empty or arbitrary | |
+ nothing |
not empty | %S
|
Examples (test page)
[Am Gwëntext werkeln]A test page illustrates practical use.
Functions for Lua modules (API)
[Am Gwëntext werkeln]All functions for templates are accessible; for basic functionality see above. Further functions can be used by modules only.
Usage by require()
:
local lucky, TemplatePar = pcall( require, "Module:TemplatePar" )
if type( TemplatePar ) == "table" then
TemplatePar = TemplatePar.TemplatePar()
else
-- error; TemplatePar contains error message
return "<span class='error'>" .. TemplatePar .. "</span>"
end
- TemplatePar.assert(analyze,append,options)
- Analyse a string as by valid.
- analyze
-
- string to be analysed
- append
-
- string; append error message; prepend
<br />
if not empty - else: throw error
- string; append error message; prepend
- options
- table; Details;
options
and all components optionalkey
- string; key
pattern
- string; Lua pattern
min
- number
max
- number
template
cat
errNS
format
preview
- Return:
false
, if valid; else error message - TemplatePar.check(options)
-
- options
- table; Details;
options
and all components optionalmandatory
- table; sequence with names of mandatory parameters
optional
- table; sequence with names of optional parameters
low
true
: ignore case
template
cat
errNS
format
preview
- Return:
false
, if valid; else error message - TemplatePar.count()
- TemplatePar.countNotEmpty()
- TemplatePar.downcase(options)
- All template transclusion parameters in lower case
- Returns table with
.args
(number of unnamed, string of named template parameters). - Error message, if the same name occurs in different spellings.
- options
- table; Details;
options
and all components optionaltemplate
cat
errNS
format
preview
- TemplatePar.valid(seek, options)
-
- seek
- Zeichenkette; name of template parameter.
- options
- table; Details;
options
and all components optionalkey
- string; key
pattern
- string; Lua pattern
min
- number
max
- number
low
true
: ignore case
template
cat
errNS
format
preview
- Both
key
andpattern
must not be used.
- Returns
false
if valid; else error message - TemplatePar.verify(options)
- Like
TemplatePar.check()
, but parameters of#invoke
- TemplatePar.failsafe(atleast)
-
- atleast
optional
nil or minimal version request or"wikidata"
- atleast
- Returns: string or false
- TemplatePar()
- Returns table with access to functions.
Usage
[Am Gwëntext werkeln]General library; no limitations.
Dependencies
[Am Gwëntext werkeln]For advanced parameter syntax checks the following libraries are required:
- FileMedia –
file
/image
- Multilingual –
lang
- URLutil –
url
Internationalization
[Am Gwëntext werkeln]- Internationalization is prepared.
- The Module looks whether a localization for the current project language is available. If not found, messages are returned in English.
- Submodules for
mw.loadData()
might be: als, ast, de, frr, ilo, sr etc. - System messages take precedence over definitions by Lua.
lua-module-TemplatePar-badPattern
|
#invoke:TemplatePar pattern syntax error #invoke:TemplatePar Syntaxfehler des pattern |
lua-module-TemplatePar-dupOpt
|
#invoke:TemplatePar repeated optional parameter #invoke:TemplatePar Optionsparameter wiederholt |
lua-module-TemplatePar-dupRule
|
#invoke:TemplatePar parameter conflict key/pattern #invoke:TemplatePar Parameterkonflikt key/pattern |
lua-module-TemplatePar-empty
|
Error in template * undefined value for mandatory Fehler bei Vorlage: Pflichtparameter ohne Wert |
lua-module-TemplatePar-invalid
|
Error in template * invalid parameter Fehler bei Vorlage: Parameter ungültig |
lua-module-TemplatePar-invalidPar
|
#invoke:TemplatePar invalid parameter #invoke:TemplatePar Ungültiger Parameter |
lua-module-TemplatePar-minmax
|
#invoke:TemplatePar min > max #invoke:TemplatePar min > max |
lua-module-TemplatePar-multiSpell
|
Error in template * multiple spelling of parameter Fehler bei Vorlage * Mehrere Parameter-Schreibweisen |
lua-module-TemplatePar-noMSGnoCAT
|
#invoke:TemplatePar neither message nor category #invoke:TemplatePar weder Meldung noch Kategorie |
lua-module-TemplatePar-noname
|
#invoke:TemplatePar missing parameter name #invoke:TemplatePar Parametername nicht angegeben |
lua-module-TemplatePar-tooLong
|
Error in template * parameter too long Fehler bei Vorlage: Parameter zu lang |
lua-module-TemplatePar-tooShort
|
Error in template * parameter too short Fehler bei Vorlage: Parameter zu kurz |
lua-module-TemplatePar-undefined
|
Error in template * mandatory parameter missing Fehler bei Vorlage: Pflichtparameter fehlt |
lua-module-TemplatePar-unknown
|
Error in template * unknown parameter name Fehler bei Vorlage: Parametername unbekannt |
lua-module-TemplatePar-unknownRule
|
#invoke:TemplatePar unknown rule #invoke:TemplatePar Unbekannte Regel |