match

The match statement is to used search either a specified string or the contents of a named buffer using a regular expression.

Syntax

match_label expression target

Details

The three parameters serve the following purposes:

Parameter Value
label A unique name to associate with this match
expression The regular expression to apply to the target
target The data to search using the expression

Label

The label associates a meaningful name to the search. Once the match has been attempted, two variables will be created or updated as follows:

Variable Possible Values Notes
label.STATUS MATCH NOMATCH ERROR The result of applying the expression (ERROR infers an invalid expression)
label.RESULT (A string) (Empty value) The text matched by the subgroup in the expression, if any

These variables can be checked after the match in order to determine the result status and access the results.

Expression

The regular expression must contain one or more characters enclosed in brackets - () - the contents of which are termed a subgroup. If a successful match is made then the portion of the target text that was matched by the subgroup will be returned in the _label.RESULT_variable.

Target

The target determines whether a supplied string or the contents of a named buffer are searched. By default the parameter will be treated as a string.

If the string contains white-space then it must be enclosed in double quotes.

If the target argument is surrounded with curly braces - {} - then it is taken to be the name of a buffer and the expression will be applied to the contents of that buffer.

Regular expressions are generally used for searching ASCII data. Searching binary data is possible but may be of limited usefulness.

Examples

Search the contents of a variable for the text following the word ‘connection:’ with or without a capital ‘C’:

match varsearch "[Cc]onnection: (.*)" ${variable}
          if (${varsearch.STATUS} = MATCH) {
              print Connection string is: ${varsearch.RESULT}
          } else {
              print No match found
          }

Search a text file previously retrieved from a HTTP request to locate the word ‘Error’ or ‘error’

match error_check "([Ee]rror)" {text_data}
          if (${error_check.STATUS} == MATCH) {
              print Found: ${error_check.RESULT}
          } else {
              print No error was found
          }

How did we do?