MATCH and MATCHREF Expressions

MATCH and MATCHREF expressions provide the ability to match strings against a pattern, and to generate new strings that incorporate substrings from the original string. Their specific use is described by the documentation for each mapfile directive that supports these expressions, in the sections that follow.

A MATCH expression allows strings to be matched against a pattern, delimited by slash (/) characters.

        MATCH(g/match-pattern/[i])
        MATCH(r/match-pattern/[i])
        MATCH(t/match-pattern/[i])

The type of matching to be done is specified by a single character code that precedes the pattern. The type of matching to be done defines the syntax of the match-pattern.

g

Glob pattern matching. The match-pattern is specified using the glob syntax described by fnmatch(7).

r

Regular Expression matching. The match-pattern is specified using the extended regular expression (ERE) syntax described by regex(7).

t

Plain text matching. The match-pattern follows the standard mapfile syntax for double quoted strings, where the slash (/) character is used in place of the usual (") quote character. The rules for double quoted strings are described in Mapfile Structure and Syntax.

By default, case sensitive pattern matching is employed. Case insensitive matching can be specified by specifying the character 'i' immediately following the closing slash (/) character.

The MATCHREF expression is used to generate a new string, based on a template string, which can incorporate substrings matched by a previous MATCH. MATCHREF, particularly in conjunction with a regular expression MATCH, provides a flexible mechanism for renaming.

        MATCHREF(/template-string/)

The template-string follows the standard mapfile syntax for double quoted strings, where the slash (/) character is used in place of the usual quote (") character. The rules for double quoted strings are described in Mapfile Structure and Syntax.

Within template-string, substrings to be copied from the related MATCH expression are indicated by tokens of the form ${c N}, where c is a single character that identifies a MATCH directive, and N is an integer that identifies a substring within that MATCH. The identifier characters allowed with MATCHREF depend on the mapfile directive that employs the MATCHREF. The documentation for each mapfile directive that supports the use of MATCH and MATCHREF defines the set of MATCHREF identifier characters that are allowed by that directive.

The string that results from a MATCHREF expression consists of the template-string, with all ${c N} tokens replaced by the MATCH substrings that they refer to. The zeroth token, ${c0}, represents the full string matched by the MATCH expression, and is supported with all MATCH expressions. Tokens specifying a value of n larger than 0 are only supported with regular expression MATCH expressions. When used with a regular expression, a value of n larger than 0 corresponds to the nth open parenthesis found in the MATCH pattern, and represents the substring matched by that subpart of the regular expression.

If a given ${c N} does not correspond to any MATCH substring, an empty ("") string is substituted. This occurs for any non-zero value of n with glob or text matching, or for a value of n greater than the number of parenthesis within a regular expression pattern.