Wikipedia:Lua/Modul/TemplatePar/en

aus Wikipedia, der freien Enzyklopädie
Zur Navigation springen Zur Suche springen
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

[Quelltext bearbeiten]

The analysis is operating on the template transclusion parameters. Parameters of #invoke are described below; they are controlling the analysis.

Check single string
1
String to be tested
2
Condition (optional but recommended and meaningful)
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
Number of parameters at template transclusion.
Parameter: None (at #invoke)
The result is a number beginning at 0.

countNotEmpty

[Quelltext bearbeiten]
Number of parameters at template transclusion which contain more than whitespace.
Parameter: None (at #invoke)
The result is a number beginning at 0.
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.
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

The Failsafe interface is heading for version management of globally distributed Lua modules. It enables modules equipped with this interface to

  • ensure, that a library module required by a template or another module available as local copy does support certain functionality, or complain if not.
  • administrate global updating and linking of module codes via Wikidata.

The Failsafe interface is present both at template level and for direct Lua access.

The functions in detail are (not all supported yet completely by every library):

Parameter
Value Result current
nothing
false
local version ID »2023-03-20«
Minimal version version ID required at least
date in ISO format

It will be compared whether the current local implementation matches this version or later.

  • empty, if minimal version not achieved
  • 2001-01-01 → »2023-03-20«
  • 2099-01-01 → »«
wikidata version ID of global upstream
  • version ID at Wikidata
  • local, if not found there
»2023-03-20«
item ID of the Wikidata item
  • empty if not defined
Q15393417
~ Corresponding version ID locally and registered at Wikidata
  • empty, if up to date
  • version ID at Wikidata, if not equal
»«
@ Is the current (module) page linked correctly with Wikidata item?
  • empty, if linked to the item which is supposed
  • Iitem ID, if not
»Q15393417«
The return value is in template programming empty or under Lua false, otherwis a non-empty string as described.

Common error handling

[Quelltext bearbeiten]

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 and template is provided, that will be replaced by template.
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=*|
  • 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>|
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)

[Quelltext bearbeiten]

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 in opt= 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:
    1. TemplatePar#invoke: repeated optional parameter
      • On module invocation a name has been listed in both all= and opt=.
      • This might not be suppressed by format= since it has been caused by template programmer and not page author.
    2. Error in template: unknown parameter name
      • On template transclusion a parameter has been used which is not listed at all= nor opt=.
    3. Error in template: mandatory parameter missing
      • On template transclusion a parameter from the all= list is missing.
    4. 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.

Parameter format (valid)

[Quelltext bearbeiten]

There are two methods for the optional condition 2:

  1. 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.
  2. 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:
      • |%!
      • {{%((
      • }}%))

Keys for simplified access
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

file
file+
file:
file:+
image
image+
image:
image:+

Permitted title or name of a media file at file (name space might be prepended).

  • not empty with +.
  • existing with :.

With image the file format is to be appropriate for a single file.

<nnnn
<=nnnn
>nnnn
>=nnnn
==nnnn
!=nnnn

Condition: arithmetic comparison or (also) numeric inequality
url
url+
empty or exactly one Internet URL
(mandatory)
ref containing <ref>Citation needed

lang
langs
langW
langsW
lang+
langs+
langW+
langsW+

empty or language code

empty or space separated list of language codes
empty or Wiki language version
empty or list of Wiki language versions
(mandatory)

In Planung
date Irgendein bekanntes Format für Datum und auch Zeit.
* empty or arbitrary
+
nothing
not empty %S

Examples (test page)

[Quelltext bearbeiten]

A test page illustrates practical use.

Functions for Lua modules (API)

[Quelltext bearbeiten]

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()
else
    -- error; TemplatePar contains error message
    return "<span class='error'>" .. TemplatePar .. "</span>"
end

Then there is available:

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
options
table; Details; options and all components optional
  • key
    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 optional
  • mandatory
    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 optional
  • template
  • cat
  • errNS
  • format
  • preview
TemplatePar.valid(seek, options)
seek
Zeichenkette; name of template parameter.
options
table; Details; options and all components optional
  • key
    string; key
  • pattern
    string; Lua pattern
  • min
    number
  • max
    number
  • low
    true: ignore case
  • template
  • cat
  • errNS
  • format
  • preview
Both key and pattern must not be used.
Returns false if valid; else error message
TemplatePar.verify(options)
Like TemplatePar.check(), but parameters of #invoke
TemplatePar.failsafe(atleast)
  1. atleast
    optional
    nil or minimal version request or "wikidata"
Returns: string or false
TemplatePar()
Returns table with access to functions (deprecated).

General library; no limitations.

Dependencies

[Quelltext bearbeiten]

For advanced parameter syntax checks the following libraries are required:

Internationalization

[Quelltext bearbeiten]
  • 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.
System messages
lua-module-TemplatePar-badPattern &#35;invoke:TemplatePar pattern syntax error
&#35;invoke:TemplatePar Syntaxfehler des pattern
lua-module-TemplatePar-dupOpt &#35;invoke:TemplatePar repeated optional parameter
&#35;invoke:TemplatePar Optionsparameter wiederholt
lua-module-TemplatePar-dupRule &#35;invoke:TemplatePar parameter conflict key/pattern
&#35;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 &#35;invoke:TemplatePar invalid parameter
&#35;invoke:TemplatePar Ungültiger Parameter
lua-module-TemplatePar-minmax &#35;invoke:TemplatePar min > max
&#35;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 &#35;invoke:TemplatePar neither message nor category
&#35;invoke:TemplatePar weder Meldung noch Kategorie
lua-module-TemplatePar-noname &#35;invoke:TemplatePar missing parameter name
&#35;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 &#35;invoke:TemplatePar unknown rule
&#35;invoke:TemplatePar Unbekannte Regel