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

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

assert

Check single string

1

String to be tested

2

Condition (optional but recommended and meaningful)

check

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

Number of parameters at template transclusion.

Parameter: None (at #invoke)

The result is a number beginning at 0.

countNotEmpty

Number of parameters at template transclusion which contain more than whitespace.

Parameter: None (at #invoke)

The result is a number beginning at 0.

match

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

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

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

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)

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)

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)

A test page illustrates practical use.

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

Usage

General library; no limitations.

Dependencies

For advanced parameter syntax checks the following libraries are required:

• FileMedia – file/image
• Multilingual – lang
• URLutil – url

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 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	#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