Okapi Shared Help

Overview

This section provides an overview of the syntax to use when working with regular expressions.

The regular expression language is designed and optimized to manipulate text. The language comprises two basic character types: literal (normal) text characters and meta-characters which are instructions for the regular expression.

For example, the regular expression \scat matches all occurrences of the string "cat" that are preceded by any white-space character, such as a space or a tab. So in the string "A bearcat is bigger than a cat" the match would be: "A bearcat is bigger than a cat", but not "A bearcat is bigger than a cat".

Regular expressions can perform very complex searches, using classes of characters, groupings, back-referencing, zero-width assertions and many different types of conditions and options.

Examples

Here are a few examples of regular expressions. The text matched by the expression is highlighted in yellow. Named groups and their corresponding matches are sometimes highlighted in other colors. All the examples assume no options are set, except is stated otherwise.

Expression: tag1|tag2
   Options: None.
   Matches: Before <tag1> and <tag2> after

Expression: tag\b
   Options: None.
   Matches: Before tag tagtag after

Expression: <.*>
   Options: None.
   Matches: Before <tag1> and <tag2> after

Expression: <.*?>
   Options: None.
   Matches: Before <tag1> and <tag2> after

Expression: colou?r
   Options: None.
   Matches: Color, colour, color

Expression: (C|c)olou?r
   Options: None.
   Matches: Color, colour, color

Expression: (?<grp1>\s\w+)\k<grp1>
   Options: None.
   Matches: Like the theory or the the theme

Expression: (?<grp1>\s\w+)\k<grp1>\b
   Options: None.
   Matches: Like the theory or the the theme

Expression: <img.*?((alt\s*=\s*(?<q>'|"))(?<text>.*?)\k<q>.*?)?>
   Options: Single-line: on, Ignore case: on.
   Matches: Click <img src='go.png' alt ='Start Now!'> to start.
   Matches: Click <img alt='Start Now!'> to start.
   Matches: Click <IMG  ALT  =  "Start Now!" SRC="go.png"> to start.
   Matches: Click <img src='go.png'> to start.

Expression: <\w+.*?((?<q>"|')(.*?)\k<q>.*?)?>|</\w+.*?>
   Options: Single-line: on, Ignore case: on.
   Matches: <P id="1">This is<br> a<a attr="&lt;test>" href='#abc'>link</a>.</P>

Expression: %(([-0+ #]?)[-0+ #]?)((\d\$)?)(([\d\*]*)(\.[\d\*]*)?)[dioxXucsfeEgGpn]
   Options: Ignore case: on
   Matches: %d files not found, including %s (%3.2d%% done)
   Matches: %1$d files not found, including %2$s (%3$*.*d%% done)

Escapes

Characters other than '.', '$', '^', '{', '[', '(', '|', ')', '*', '+', '?', and '\' match themselves. Otherwise you must prefix the character with a '\' to match as a literal. For example, to match the question mark ('?') character you must use "\?" or to match the backslash ('\') you must use "\\".

Character Classes

A character class is a set of characters that will find a match if any one of the characters included in the set matches. You can specify character classes using the sequences listed in the following table:

Unicode groups and block ranges (to use with \p{name}):

Quantifiers

Quantifiers add optional quantity data to a regular expression. A quantifier expression applies to the character, group, or character class that immediately precedes it. You can specify quantifiers using the sequences listed in the following table:

Options

You can apply options to a regular expression to modify the matching behavior. Options can be set outside the expression, using the user interface check boxes, and they can be set within the regular expression pattern itself, using the inline (?imnsx-imnsx:) grouping construct or (?imnsx-imnsx) miscellaneous construct.

In inline option constructs, a minus sign '-' before an option or set of options turns off those options. For example, the inline construct (?ix-ms) turns on the Ignore Case and Ignore Pattern White Space options and turns off the Multiline and Single-line options.

The options available are the following:

Zero-width Assertions

Zero-width assertions do not cause the matching engine to advance through the string or consume characters. They only cause a match to succeed or fail depending on the current position in the string. For example, ^ specifies that the current position is at the beginning of a line or string. Therefore, the regular expression ^FTP returns only those occurrences of the character string "FTP" that occur at the beginning of a line.

The assertions are expressed using the following meta-characters:

Grouping Constructs

Grouping constructs allow you to capture groups of sub-expressions and to increase the efficiency of regular expressions with non-capturing look-ahead and look-behind modifiers. The available grouping constructs are listed in the following table:

Back-reference Constructs

Back-references provide a way to find repeating groups of characters. You can think of them as a shorthand instruction to match the same string again. You can use the following constructs:

Back-references and octal notation

The expressions \1 through \9 always refer to back-references, not octal codes. Multi-digit expressions \11 and up are considered back-references if there is a back-reference corresponding to that number; otherwise, they are interpreted as octal codes (unless the starting digits are 8 or 9, in which case they are treated as literal "8" and "9"). If a regular expression contains a back-reference to an undefined group number, it is considered a parsing error.

If the ambiguity is a problem, you can always use the \k<n> notation, which cannot be confused with octal codes. Similarly, hexadecimal codes such as \xHH are unambiguous and cannot be confused with back-references.

Back-reference matching

A back-reference refers to the most recent definition of a group (the definition most immediately to the left, when matching left to right). That is, when a group makes multiple captures, a back-reference refers to the most recent capture. For example, (?<1>a)(?<1>\1b)* matches aababb, with the capturing pattern (a)(ab)(abb). Note that looping quantifiers do not clear group definitions.

If a group has not captured any substring, a back-reference to that group is undefined and never matches. For example, the expression \1() never matches anything, but the expression ()\1 matches the empty string.

Conditional Constructs

Conditional constructs let you define expressions with either/or matching. The available constructs are listed in the following table:

Miscellaneous Constructs

The following table lists other constructs you can use in a regular expression:

Substitutions

Substitutions are allowed only within replacement patterns. For similar functionality within regular expressions, use a back-reference (e.g. \1).

Character escapes and substitutions are the only special constructs recognized in a replacement pattern. All other constructs are not recognized in replacement patterns. For example, the replacement pattern a*${txt}b inserts the string "a*" followed by the substring matched by the "txt" capturing group (if any), followed by the string "b". The character '*' is not recognized as a meta-character within a replacement pattern. Similarly, $ patterns are not recognized within regular expression search patterns (within the search pattern $ designates the end of the string).

You can use the following named and numbered replacement patterns: