Syntax

substitutionlist(list)

                

The SUBSTITUTIONLIST function has the following arguments:

Description

The substitutionlist function will create an output value by testing matches in a list of alternatives. The first alternative match that succeeds is used.

The alternatives are expressed as elements in the input list. Each element in the input list is itself a list containing three values. The first value is an expression that will be evaluated to obtain the value to be tested. The second value is a regular expression that derived value from the first argument will be tested against. If the match succeeds then the third argument will be used as translation template to create the result value.

Processing proceeds by evaluating each element in the list in sequence until a match is found. At each element a potentially new input value is evaluated, allowing for complex search strategies that employ multiple alternate inputs.

When an input value matches against the regular expression the translation template is used to format the output value. The translation template contains characters and substitution symbols. Substitution symbols are digits enclosed by braces (e.g. {1}). The numbers in the substitution symbols refer to the corresponding match group within the regular expression. Substitution symbol {1} refers to the first match group. Substitution symbol {0} refers to the entire matched sequence.

An error condition will occur if no matches are found in the list of alternatives. If you need to prevent this occurrence then have the last element in the list be a 'catchall' category with a regular expression string of '.*'.

Examples

The following example shows a substitutionList function having series of alternative translation strategies.

substitutionList({{KeywordFile,'GROW','GROW'},
                  {KeywordFile,'Owl_Mgnt|Owl_Mgntregen','SOFR'},
                  {KeywordFile,'Owl_Mgnt_p(\d)','SOFR_{1}'},
                  {KeywordFile,'Regen','REGE'},
                  {KeywordFile,'Riparian|Riparianregen','RIPR'},
                  {KeywordFile,'Riparian_p(\d)','RIPR_{1}'},
                  {KeywordFile,'Thin','THRD'},
                  {KeywordFile,'Thin_p(\d)','THRD_{1}'},
                  {KeywordFile,'Unev_(\d+)(regen)?','U{1}'},
                  {KeywordFile,'Unev_(\d+)_p(\d)','U{1}_{2}'}})

For this example the same input variable KeywordFile is used for all cases, although this is not required.

Assume that the KeywordFile expression evaluates to 'Owl_Mgmt'. This value is first matched by the regular expression in the second line, and the translation template returns the value of 'SOFR'. Processing does not continue any further and 'SOFR' is returned.

Next let's assume that the KeywordFile expression evaluates to 'Riparian_p3'. This value is first matched by the regular expression in the fifth line, and the translation template extracts the value of the first match group of the regular expression and returns the value of 'RIPR_3'. Processing does not continue any further and 'RIPR_3' is returned.

Note

The code shown in this example has been formatted for clarity. Although the Patchworks Query Language ignores all white space (blanks and new lines) the scripting language may not allow string to extend over multiple lines, so some manipulation may be required. The escape character '\' used in the regular expression is also an escape character in many scripting languages, for example to indicate unprintable or otherwise special characters. In order to protect the escape character from being improperly interpreted by the script processor it will need itself to be 'escaped'. This is done in BeanShell and Java by preceding the '\' characters by another '\' character to indicate that the following '\' should be left alone and not processed specially. With these caveats in mind a typical pattern for entering the above complex expression in a script would be: regimeTransform = new StringBuilder("substitutionList({") .append("{KeywordFile,'GROW','GROW'},") .append("{KeywordFile,'Owl_Mgnt|Owl_Mgntregen','SOFR'},") .append("{KeywordFile,'Owl_Mgnt_p(\\d)','SOFR_{1}'},") .append("{KeywordFile,'Regen','REGE'},") .append("{KeywordFile,'Riparian|Riparianregen','RIPR'},") .append("{KeywordFile,'Riparian_p(\\d)','RIPR_{1}'},") .append("{KeywordFile,'Thin','THRD'},") .append("{KeywordFile,'Thin_p(\\d)','THRD_{1}'},") .append("{KeywordFile,'Unev_(\\d+)(regen)?','U{1}'},") .append("{KeywordFile,'Unev_(\\d+)_p(\\d)','U{1}_{2}'}") .append("})").toString();