Template:ParseInputValues

ParseInputValues is a utility function that processes a generic list of arguments to determine which ones match a list of allowed/expected values. It is intended for use only within other templates, to allow those templates to process their input data.

Notes

There are two main purposes for this function:

• Flexible handling of different user inputs: case-insensitive comparisons are done, and then input is converted to a standard case. Also, allows input data to contain links or certain formatting (italics).
• Integrates translation on non-english wikis: allows english or other-language equivalents to be used interchangeably in input parameters for other templates.

Usage

Syntax

Standard initialization:

{{ParseInputValues| code=code || allowed_values }}

Standard usage:

{{ParseInputValues| code=code | input_values }}

Complete argument list:

{{ParseInputValues| input_values | allowed_values | code=code | exclude=values
                  | default=true;values | translate=true;index | vary_end=true | case=lc;uc }}

An example of typical usage within another template would be to take input data ({{{1|}}})), see whether it matches any of Parsnip, Potato, Tulip, and store results in array named $cleaned_input:

{{#arraydefine:$cleaned_input | {{ParseInputValues| {{{1|}}} | Parsnip,, Potato,, Tulip}}}}

Parameters

There are two unnamed arguments (input_values, allowed_values). All other parameters are named and optional. Default value for all arguments is empty unless specified otherwise.

• input_values:
  • First unnamed argument. Required except on initialization.
  • The user input that needs to be processed. Should be a comma-separated list of one or more values.
  • Links (i.e., square brackets surrounding a word) will be automatically stripped, as will '' (italics).
  • The processing is non-case-sensitive; return values will always match the case used in allowed_values (unless the case parameter is used).

• allowed_values
  • Second unnamed argument.
  • A comma-separated list of the allowed and/or expected values.
  • Typically the allowed values are initialized in one call to ParseInputValues, using code to store the processed data for later use.
  • The order of the provided values is important. Within a single list of synonyms:
    • The first value is the standard english version of the term. This is the value that is returned by default.
    • The second value is the standard local version of the term (e.g., translated into the current wiki's language). This is the value that is returned when translate=true is set. On the english wiki the second value normally matches the first value (and can be omitted if there are no synonyms).
    • All other values are allowed synonyms, both english and local.
  • Multiple lists of synonyms can be specified simultaneously. An empty entry is used to separate each set of synonyms (for ease of reading, a line break is often included in the empty entry, but the only requirement for the separator is that it contain nothing except spaces).

• code = code
  • A unique identifier assigned to a set of allowed values.
  • When using this parameter, the first call to ParseInputValues should be an initialization call, providing a list of allowed values that are processed and stored.
  • Subsequent calls to ParseInputValues can omit the allowed values list, and instead use code to retrieve previously-stored data.
  • Use of this parameter makes it easier to reuse a set of allowed values repeatedly within a template. It also creates more efficient templates, especially on wiki articles that end up calling a template multiple times. The overhead associated with processing a set of allowed values only needs to happen once on a wiki article, because defined arrays are effectively global variables.

• exclude = exclude_values
  • A comma-separated list of values to exclude from the final output.
  • Entries are processed the same way as input_values.

• default = true;values
  • A default value that should be used only if no input_values match.
  • Set to true if the original input_values should be used. Implies exclude, translate, and case should be ignored -- original values are returned exactly as is.
  • Otherwise should be a comma-separated list of entries that exactly match values found in allowed_values. Note that in this case exclude values are applied AFTER default is set.

• translate = true;index
  • Set to true if the return values should be translated, i.e., replace entries from allowed_values with the corresponding entry in alt_allowed. If the alt_allowed entry is missing, the entry is deleted.
  • Set to index if the return value should be a number specifying the array index of the matching value

• case = uc;lc
  • Set to one of lc or uc to convert the case of all return values
    • uc: all upper case
    • lc: all lower case
  • All other values of case are ignored (meaning returned values match the case provided in allowed_values)

• vary_end = true
  • Set to true if variations in the final characters of the return text should be allowed, in particular for support of gender- and/or plural-specific versions of the return text.
  • Only relevant if translate=true is also set.
  • When this option is set, the input value may be returned instead of the standard translated term, but only if the input value also appears in the allowed list and the input value is identical (including case) to the standard term except for the last three characters.

Return Value

A comma-separated list of values.

(This value is printed into the page HTML. Depending upon the calling function, it may might become part of the displayed page, or a template function such as #arraydefine can be used to assign it to a variable)

Examples

{{ParseInputValues
   |wheat, parsnip, iron ore
   |Honey,, Hops,, Parsnip,, Wheat
}}

Only matching words are returned; return values use same case and order as allowed_values. (Double commas are necessary to have each entry treated as a different term, instead of all being one set of synonyms.)
Returns: Parsnip,Wheat

{{ParseInputValues|code=weather||
 ,Sunny,         Sol,        Sun,   Soleado,    
 ,Pollen fall,   Viento,     Wind,  Pollen,     Polleny,    Windy, Polen, Ventoso, 
 ,Pollen spring, Viento,     Wind,  Springwind, 
 ,Rain,          Lluvia,     Rainy, Lluvioso,   
 ,Thunderstorm,  Tormenta,   Storm, Stormy,     Tormentoso, 
 ,Snow,          Nieve,      Snowy, Nevando,
}}

Demonstrating use of code to initialize a list of english and spanish terms for weather (copied from es:Template:Weather inline). Each line provides one set of synonyms (note the commas at the start and end of each line; these pairs of commas produce an empty entry at each line break which tells the code a new set of synonyms is starting).
Has no return value:

{{ParseInputValues|code=weather|case=lc|
  SNOW, RaINy, [[Soleado]], Abigail, Springwind, wind
}}

Use previously-stored weather data. Demonstrating synonyms, automatic case-conversion, link removal.
Returns: sunny,pollen fall,pollen spring,rain,snow

{{ParseInputValues|code=weather|translate=true|
  SNOW, RaINy, ''Soleado'', Abigail, Springwind, wind
}}

Translate (return second value on each line instead of first). Note that both wind terms return the same word -- although the english terms are unique, the translated terms do not have to be. Plus automatic italics removal.
Returns: Sol,Viento,Viento,Lluvia,Nieve

{{ParseInputValues|code=weather|exclude=nieve,WINDY,[[rain]]|
  SNOW, RaINy, ''Soleado'', Abigail, Springwind, Ventoso
}}

Demonstrating exclude -- with same flexbility as input values.
Returns: Sunny,Pollen spring

{{ParseInputValues|code=nosale|Bad value|translate=true|default=Cannot be sold|
,Cannot be sold, Ne peut pas être vendu, Can not be sold, N/A, Invendable, Ne peut être vendue, Ne peut pas être vendue, Ne peut être vendu,
}}

Initialize a new list and use it simultaneously. Default translated return value is masculine version.
Returns: Ne peut pas être vendu

{{ParseInputValues|code=nosale|Ne peut pas être vendue|translate=true|vary_end=true}}

Use feminine version if vary_end=true and input value matches.
Returns: Ne peut pas être vendue