Quelltext der Seite Wikiup:Lua/Modul/TemplatePar/en

{{LuaModuleDoc}}
<onlyinclude>'''<code>TemplatePar</code>''' – Module with support for template programming, focussing on parameters of template transclusion.
<noinclude>
While the module name suggests usage with templates, lua modules are supported as well.
* [[#assert|assert]] – Check single string</noinclude>
* [[#check|check]] – Check transclusion of template
* [[#count|count]] – Number of template parameters
* [[#countNotEmpty|countNotEmpty]] – Number of template parameters which contain more than whitespace<noinclude>
* [[#downcase|downcase]] – All template transclusion parameters in lower case</noinclude>
* [[#match|match]] – Combined analysis of parameters and their values
* [[#valid|valid]] – Test single template parameter value<noinclude>
* [[#verify|verify]] – Check <code>#invoke</code> parameter set</noinclude>
* [[#failsafe|failsafe]] – Module versioning

<noinclude>__TOC__</noinclude>
== {{Anker|template}} Functions for templates ==
The analysis is operating on the template transclusion parameters. Parameters of <code>#invoke</code> are described below; they are controlling the analysis.

==== assert ====
: Check single string
:; 1
:: String to be tested
:; 2
:: [[#Parameter format|Condition]] (optional but recommended and meaningful)

==== check ====
: Test for assigned and unexpected parameters at template transclusion; completeness of required values. Details [[#Parameter test|below]].
: An error message will be returned enclosed in <code>class=error</code>.
: 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 <code>=</code> (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 <code>=</code> (equal sign).
:; low
:: <code>true</code>: ignore case

==== count ====
: Number of parameters at template transclusion.
: ''Parameter:'' None (at #invoke)
: The result is a number beginning at <code>0</code>.

==== countNotEmpty ====
: Number of parameters at template transclusion which contain more than whitespace.
: ''Parameter:'' None (at #invoke)
: The result is a number beginning at <code>0</code>.

==== match ====
: Combined analysis of parameters and their values; is template profile matching current transclusion?
:; 1
:: Rule in format &nbsp; <code>1=</code>''parameter name''<code>=</code>''[[#Parameter format|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 <code>*</code> condition.
: An error message will be returned enclosed in <code>class=error</code>. Fatal errors will be visible at following levels: Unknown parameter name&nbsp;– missing parameter&nbsp;– invalid parameter value.
: If “nothing” is returned no error was detected.

==== valid ====
: Check validity of one particular template parameter.
: An error message will be returned enclosed in <code>class=error</code>.
: 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 [[#Parameter format|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
:: <code>true</code>: ignore case

==== failsafe ====
: Version identification: <code>{{#invoke:TemplatePar|failsafe}}</code>
: Optional additional parameter <code>1</code> – requested minimal version identification, or <code>wikidata</code>
:: ''Returns:''
::* (empty), if minimal version condition not matched
::* version ID (local or @wikidata: <code>{{#invoke:TemplatePar|failsafe|wikidata}}</code>)

=== {{Anker|error handling}} Common error handling ===
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 <code>cat</code> as well.
; cat
: Title of a maintenance category. (do not add <code>category:</code> prefix)
: In case of error this will be activated (appended to result).
: If the string <code>@@@</code> is found in title and <code>template</code> is provided, that will be replaced by <code>template</code>.
; errNS
: Space separated list of namespace numbers to limit <code>cat</code> triggering, otherwise causing the maintenance category to appear in all namespaces.
; format
: Format or suppress error message.
:* Standard case, default message formatted by <code>class="error"</code> markup:
:** Parameter <code>format</code> not provided.
:** <code>|format=*|</code>
:* Suppress (then <code>cat=</code> should be declared):
:** <code>|format=|</code>
:** <code>|format=0|</code>
:** <code>|format=-|</code>
:* Constant text, own formatting, any syntax:
:** <code>|format=<start>Constant text</end>|</code>
:* Free formatting of default message:
:** Contains <code>@@@</code> as placeholder for the unformatted default message text, any syntax.
:** <code>|format=<start>Constant text; @@@</end>|</code>
; preview
: Suppress message suppression in preview mode, show default message always even if <code>|format=0|</code> has been requested:
:* <code>|preview=1|</code>
: Constant text in preview mode, own formatting, any syntax:
:* <code>|preview=<start>Constant text</end>|</code>
: Free formatting of default message in preview mode:
:* <code>|preview=<start>Constant text; @@@</end>|</code>
<noinclude>Lua modules yield <code>false</code> if no problem detected, else error message.</noinclude>

=== {{Anker|Parameter test}} Parameter test (check) ===
Use case on [[commons:Template:Information]] example:
<syntaxhighlight lang="text">
{{#invoke:TemplatePar
         |check
         |all= description= source= author=
         |opt= date= permission= other_versions= other_fields=
         |template=Information}}
</syntaxhighlight>
* Since the name of a template parameter can’t contain an <code>=</code> 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 <code>all=</code> nor in <code>opt=</code> 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 <code>all=</code> and <code>opt=</code>.
*#* This might not be suppressed by <code>format=</code> since it has been caused by template programmer and not page author.
*# ''Error in template: unknown parameter name''
*#* On template transclusion a parameter has been used which is not listed at <code>all=</code> nor <code>opt=</code>.
*# ''Error in template: mandatory parameter missing''
*#* On template transclusion a parameter from the <code>all=</code> list is missing.
*# ''Error in template: undefined value for mandatory''
*#* On template transclusion a parameter from the <code>all=</code> list is given with equal sign but no visible value, or an unnamed parameter is empty, leaving a gap between two pipe symbols.

=== {{Anker|Parameter format}} Parameter format (valid) ===
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 <code>/</code> to distinguish from keyword and detect closing and trailing whitespace on values of unnamed template parameters.
#* The strings <code>|</code> as well as <code>{&#123;</code> and <code>}}</code> are not possible in template programming. They are to be replaced:
#** <code>|</code> → <code>%!</code>
#** <code>{&#123;</code> → <code>%((</code>
#** <code>}}</code> → <code>%))</code>

{{Anker|key|pattern}}
{| class="wikitable"
|+ Keys for simplified access
! Key
! Meaning
! Implementation
|-
| <code>ASCII</code>
|[[American Standard Code for Information Interchange|ASCII]] character (codes 32–126), within one line only, or empty
| <code>^[ -~]*$</code>
|-
| <code>ASCII+</code>
| as before; not empty
| <code>^[ -~]+$</code>
|-
| <code>ASCII+1</code>
| in one word; else as before und not empty
| <code>^[!-~]+$</code>
|-
| <code>n</code>
| ASCII digits 0–9 only, and leading sign ASCII minus, or empty
| <code>^[%-]?[0-9]*$</code><br />exclude single minus
|-
| <code>n>0</code>
| ASCII digits 0–9 only, no sign, not empty and and least one digit non-zero
| <code>^[0-9]*[1-9][0-9]*$</code>
|-
| <code>N+</code>
| Like <code>n</code>; but leading zero not permitted and not empty
| <code>^[%-]?[1-9][0-9]*$</code>
|-
| <code>N>0</code>
| Like <code>n>0</code>
| <code>^[1-9][0-9]*$</code>; but leading zero not permitted
|-
| <code>x</code>
| Hexdec number; ASCII digits 0–9 letters a–f A–F, or empty
| <code>^[0-9A-Fa-f]*$</code>
|-
| <code>x+</code>
| as before; but not empty.
| <code>^[0-9A-Fa-f]+$</code>
|-
| <code>X</code>
| Hexdec number; ASCII digits 0–9 letters A–F, or empty
| <code>^[0-9A-F]*$</code>
|-
| <code>X+</code>
| as before; but not empty.
| <code>^[0-9A-F]+$</code>
|-
| <code>0,0</code>
| Any number; also less than zero; might contain comma; or empty
| <code>^[%-]?[0-9]*,?[0-9]*$</code><br />exclude single minus or comma
|-
| <code>0,0+</code>
| Any number; contains one comma; also less than zero
| <code>^[%-]?[0-9]+,[0-9]+$</code>
|-
| <code>0,0+?</code>
| Any number; also less than zero; might contain comma and digits after comma; not empty
| <code>^[%-]?[0-9]+,?[0-9]*$</code>
|-
| <code>0.0</code>
| Any number; also less than zero; might contain period; or empty
| <code>^[%-]?[0-9]*[%.]?[0-9]*$</code><br />exclude single minus or comma
|-
| <code>0.0+</code>
| Number with period and significant figures; also less than zero
| <code>^[%-]?[0-9]+%.[0-9]+$</code>
|-
| <code>0.0+?</code>
| Any number; also less than zero; might contain period and significant figures; not empty
| <code>^[%-]?[0-9]+[%.]?[0-9]*$</code>
|-
| <code>.0+</code>
| Any number; also less than zero; might contain period and significant figures, but not necessarily digit before period; not empty
| <code>^[%-]?[0-9]*[%.]?[0-9]+$</code>
|-
| <code>aa</code>
| At least two letters (not necessarily aside: ''N.N.'') or a CJK
| <code>%a.*%a</code><br />or CJK
|-
| <code>ID</code>
| Identifier with restrictions common to many languages: ASCII, beginning with letter; later digits and underscore; or empty.<br />Subsequent ASCII words might be regarded as such identifiers, too; e.g. URL component.
| <code style="white-space: nowrap">^[A-Za-z]?[A-Za-z_0-9]*$</code>
|-
| <code>ID+</code>
| as before; but not empty.
| <code>^[A-Za-z][A-Za-z_0-9]*$</code>
|-
| <code>ABC</code>
| Word of ASCII capital letters; or empty.
| <code>^[A-Z]*$</code>
|-
| <code>ABC+</code>
| as before; but not empty.
| <code>^[A-Z]+$</code>
|-
| <code>Abc</code>
| Word of ASCII letters, first letter capitalized only; or empty.
| <code>^[A-Z]*[a-z]*$</code>
|-
| <code>Abc+</code>
| as before; but not empty.
| <code>^[A-Z][a-z]+$</code>
|-
| <code>abc</code>
| Word of ASCII lowercase letters; or empty.
| <code>^[a-z]*$</code>
|-
| <code>abc+</code>
| as before; but not empty.
| <code>^[a-z]+$</code>
|-
| <code>aBc+</code>
| Word of ASCII letters with lower camel casing; not empty.
| <code>^[a-z]+[A-Z][A-Za-z]*$</code>
|-
| <code>base64</code>
| [[Base64]]; or empty.
| <code>^[A-Za-z0-9%+/]*$</code>
|-
| <code>base64+</code>
| as before; but not empty.
| <code>^[A-Za-z0-9%+/]+$</code>
|-
| <code>pagename</code>
| Permitted page name; not empty.
| not <code><nowiki>#<>[]|{}</nowiki></code> or 127<sub>10</sub> or 1–31<sub>10</sub>
|-
|
<code>file</code><br />
<code>file+</code><br />
<code>file:</code><br />
<code>file:+</code><br />
<code>image</code><br />
<code>image+</code><br />
<code>image:</code><br />
<code>image:+</code>
|
Permitted title or name of a media file at <code>file</code> (name space might be prepended).
* not empty with <code>+</code>.
* existing with <code>:</code>.
With <code>image</code> the file format is to be appropriate for a single file.
|-
|
<code><</code>''nnnn''<br />
<code><=</code>''nnnn''<br />
<code>></code>''nnnn''<br />
<code>>=</code>''nnnn''<br />
<code>==</code>''nnnn''<br />
<code>!=</code>''nnnn''
| Condition: arithmetic comparison or (also) numeric inequality
|
|-
| <code>url</code><br /> <code>url+</code>
| empty or exactly one Internet URL<br /> (mandatory)
|
|-
| <code>ref</code>
| containing <code>&lt;ref></code> – ''Citation needed''
|
|-
|
<code>lang</code><br /> <code>langs</code><br /> <code>langW</code><br /> <code>langsW</code><br />
<code>lang+</code><br /> <code>langs+</code><br /> <code>langW+</code><br /> <code>langsW+</code>
|style="vertical-align:top"| empty or language code<br />
empty or space separated list of language codes<br />
empty or Wiki language version<br />
empty or list of Wiki language versions<br />
(mandatory)<br /> …
|
|-
!colspan="3"| In Planung
|-
| <code>date</code>
| Irgendein bekanntes Format für Datum und auch Zeit.
|-
| <code>*</code>
| empty or arbitrary
|
|-
| <code>+</code><br /> ''nothing''
| not empty
| <code>%S</code>
|}

=== Examples (test page) ===
A [[Wikipedia:Lua/Modul/TemplatePar/test|test page]] illustrates practical use.</onlyinclude>

== {{Anker|Lua}} Functions for Lua modules (API) ==
All functions for templates are accessible; for basic functionality see above. Further functions can be used by modules only.

Usage by <code>require()</code>:
<syntaxhighlight lang="lua">
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
</syntaxhighlight>

; TemplatePar.[[#assert|assert]](analyze,append,options)
: Analyse a string as by [[#valid|valid]].
:; analyze
::* ''string'' to be analysed
:; append
::* ''string;'' append error message; prepend <code>&lt;br /></code> if not empty
::* else: throw error
:; options
:: ''table;'' Details; <code>options</code> and all components optional
::* <code>key</code>
::*: ''string;'' [[#key|key]]
::* <code>pattern</code>
::*: ''string;'' [[#pattern|Lua pattern]]
::* <code>min</code>
::*: ''number''
::* <code>max</code>
::*: ''number''
::* <code>template</code>
::* <code>cat</code>
::* <code>errNS</code>
::* <code>format</code>
::* <code>preview</code>
: ''Return:'' <code>false</code>, if valid; else error message
; TemplatePar.[[#check|check]](options)
:; options
:: ''table;'' Details; <code>options</code> and all components optional
::* <code>mandatory</code>
::*: ''table;'' sequence with names of mandatory parameters
::* <code>optional</code>
::*: ''table;'' sequence with names of optional parameters
::* <code>low</code>
::*: <code>true</code>: ignore case
::* <code>template</code>
::* <code>cat</code>
::* <code>errNS</code>
::* <code>format</code>
::* <code>preview</code>
: ''Return:'' <code>false</code>, if valid; else error message
; TemplatePar.[[#count|count]]()
; TemplatePar.[[#countNotEmpty|countNotEmpty]]()
; {{Anker|downcase}} TemplatePar.downcase(options)
: All template transclusion parameters in lower case
: Returns ''table'' with  <code>.args</code> (''number'' of unnamed, ''string'' of named template parameters).
: Error message, if the same name occurs in different spellings.
:; options
:: ''table;'' Details; <code>options</code> and all components optional
::* <code>template</code>
::* <code>cat</code>
::* <code>errNS</code>
::* <code>format</code>
::* <code>preview</code>
; TemplatePar.[[#valid|valid]](seek, options)
:; seek
:: ''Zeichenkette;'' name of template parameter.
:; options
:: ''table;'' Details; <code>options</code> and all components optional
::* <code>key</code>
::*: ''string;'' [[#key|key]]
::* <code>pattern</code>
::*: ''string;'' [[#pattern|Lua pattern]]
::* <code>min</code>
::*: ''number''
::* <code>max</code>
::*: ''number''
::* <code>low</code>
::*: <code>true</code>: ignore case
::* <code>template</code>
::* <code>cat</code>
::* <code>errNS</code>
::* <code>format</code>
::* <code>preview</code>
:: Both <code>key</code> and  <code>pattern</code> must not be used.
: Returns <code>false</code> if valid; else error message
; TemplatePar.verify(options)   {{Anker|verify}}
: Like <code>TemplatePar.[[#check|check()]]</code>, but parameters of <code>#invoke</code>
; TemplatePar.[[#failsafe|failsafe]](atleast)   {{Anker|failsafe}}
:# atleast<br /> ''optional''<br /> ''nil'' or minimal version request or <code>"wikidata"</code>
: Returns: ''string'' or ''false''
; TemplatePar()
: Returns ''table'' with access to functions.

== Usage ==
General library; no limitations.

== Dependencies ==
For advanced parameter syntax checks the following libraries are required:
* [[Wikipedia:Lua/Modul/FileMedia/en|FileMedia]] – <code>file</code>/<code>image</code>
* [[Wikipedia:Lua/Modul/Multilingual/en|Multilingual]] – <code>lang</code>
* [[Wikipedia:Lua/Modul/URLutil/en|URLutil]] – <code>url</code>

== Internationalization ==
* 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 <code>mw.loadData()</code> might be: [[Module:TemplatePar/als|als]], [[Module:TemplatePar/ast|ast]], [[Module:TemplatePar/de|de]], [[Module:TemplatePar/frr|frr]], [[Module:TemplatePar/ilo|ilo]], [[Module:TemplatePar/sr|sr]] etc.
* System messages take precedence over definitions by Lua.

{| class="wikitable"
|+ System messages
{{{{#rel2abs:../I18N}}#}}
|}

[[Kategorie:Wikipedia:Lua/Modul/Dokumentation|TemplatePar]]