20.5 Syntax of Regular Expressions

This manual describes regular expression features that users typically want to use. There are additional features that are mainly used in Lisp programs; see (elisp)Regular Expressions section `Regular Expressions' in The Emacs Lisp Reference Manual.

Regular expressions have a syntax in which a few characters are special constructs and the rest are ordinary. An ordinary character is a simple regular expression which matches that same character and nothing else. The special characters are ‘$’, ‘^’, ‘.’, ‘*’, ‘+’, ‘?’, ‘[’, and ‘\’. The character ‘]’ is special if it ends a character alternative (see later). The character ‘-’ is special inside a character alternative. Any other character appearing in a regular expression is ordinary, unless a ‘\’ precedes it. (When you use regular expressions in a Lisp program, each ‘\’ must be doubled, see the example near the end of this section.)

For example, ‘f’ is not a special character, so it is ordinary, and therefore ‘f’ is a regular expression that matches the string ‘f’ and no other string. (It does not match the string ‘ff’.) Likewise, ‘o’ is a regular expression that matches only ‘o’. (When case distinctions are being ignored, these regexps also match ‘F’ and ‘O’, but we consider this a generalization of “the same string,” rather than an exception.)

Any two regular expressions a and b can be concatenated. The result is a regular expression which matches a string if a matches some amount of the beginning of that string and b matches the rest of the string.

As a simple example, we can concatenate the regular expressions ‘f’ and ‘o’ to get the regular expression ‘fo’, which matches only the string ‘fo’. Still trivial. To do something nontrivial, you need to use one of the special characters. Here is a list of them.

. (Period)

is a special character that matches any single character except a newline. Using concatenation, we can make regular expressions like ‘a.b’, which matches any three-character string that begins with ‘a’ and ends with ‘b’.

*

is not a construct by itself; it is a postfix operator that means to match the preceding regular expression repetitively as many times as possible. Thus, ‘o*’ matches any number of ‘o’s (including no ‘o’s).

‘*’ always applies to the smallest possible preceding expression. Thus, ‘fo*’ has a repeating ‘o’, not a repeating ‘fo’. It matches ‘f’, ‘fo’, ‘foo’, and so on.

The matcher processes a ‘*’ construct by matching, immediately, as many repetitions as can be found. Then it continues with the rest of the pattern. If that fails, backtracking occurs, discarding some of the matches of the ‘*’-modified construct in case that makes it possible to match the rest of the pattern. For example, in matching ‘ca*ar’ against the string ‘caaar’, the ‘a*’ first tries to match all three ‘a’s; but the rest of the pattern is ‘ar’ and there is only ‘r’ left to match, so this try fails. The next alternative is for ‘a*’ to match only two ‘a’s. With this choice, the rest of the regexp matches successfully.

+

is a postfix operator, similar to ‘*’ except that it must match the preceding expression at least once. So, for example, ‘ca+r’ matches the strings ‘car’ and ‘caaaar’ but not the string ‘cr’, whereas ‘ca*r’ matches all three strings.

?

is a postfix operator, similar to ‘*’ except that it can match the preceding expression either once or not at all. For example, ‘ca?r’ matches ‘car’ or ‘cr’; nothing else.

*?, +?, ??

are non-greedy variants of the operators above. The normal operators ‘*’, ‘+’, ‘?’ are greedy in that they match as much as they can, as long as the overall regexp can still match. With a following ‘?’, they are non-greedy: they will match as little as possible.

Thus, both ‘ab*’ and ‘ab*?’ can match the string ‘a’ and the string ‘abbbb’; but if you try to match them both against the text ‘abbb’, ‘ab*’ will match it all (the longest valid match), while ‘ab*?’ will match just ‘a’ (the shortest valid match).

Non-greedy operators match the shortest possible string starting at a given starting point; in a forward search, though, the earliest possible starting point for match is always the one chosen. Thus, if you search for ‘a.*?$’ against the text ‘abbab’ followed by a newline, it matches the whole string. Since it can match starting at the first ‘a’, it does.

\{n\}

is a postfix operator that specifies repetition n times—that is, the preceding regular expression must match exactly n times in a row. For example, ‘x\{4\}’ matches the string ‘xxxx’ and nothing else.

\{n,m\}

is a postfix operator that specifies repetition between n and m times—that is, the preceding regular expression must match at least n times, but no more than m times. If m is omitted, then there is no upper limit, but the preceding regular expression must match at least n times.
‘\{0,1\}’ is equivalent to ‘?’.
‘\{0,\}’ is equivalent to ‘*’.
‘\{1,\}’ is equivalent to ‘+’.

[ … ]

is a character set, which begins with ‘[’ and is terminated by ‘]’. In the simplest case, the characters between the two brackets are what this set can match.

Thus, ‘[ad]’ matches either one ‘a’ or one ‘d’, and ‘[ad]*’ matches any string composed of just ‘a’s and ‘d’s (including the empty string), from which it follows that ‘c[ad]*r’ matches ‘cr’, ‘car’, ‘cdr’, ‘caddaar’, etc.

You can also include character ranges in a character set, by writing the starting and ending characters with a ‘-’ between them. Thus, ‘[a-z]’ matches any lower-case ASCII letter. Ranges may be intermixed freely with individual characters, as in ‘[a-z$%.]’, which matches any lower-case ASCII letter or ‘$’, ‘%’ or period.

Note that the usual regexp special characters are not special inside a character set. A completely different set of special characters exists inside character sets: ‘]’, ‘-’ and ‘^’.

To include a ‘]’ in a character set, you must make it the first character. For example, ‘[]a]’ matches ‘]’ or ‘a’. To include a ‘-’, write ‘-’ as the first or last character of the set, or put it after a range. Thus, ‘[]-]’ matches both ‘]’ and ‘-’.

To include ‘^’ in a set, put it anywhere but at the beginning of the set. (At the beginning, it complements the set—see below.)

When you use a range in case-insensitive search, you should write both ends of the range in upper case, or both in lower case, or both should be non-letters. The behavior of a mixed-case range such as ‘A-z’ is somewhat ill-defined, and it may change in future Emacs versions.

[^ … ]

‘[^’ begins a complemented character set, which matches any character except the ones specified. Thus, ‘[^a-z0-9A-Z]’ matches all characters except ASCII letters and digits.

‘^’ is not special in a character set unless it is the first character. The character following the ‘^’ is treated as if it were first (in other words, ‘-’ and ‘]’ are not special there).

A complemented character set can match a newline, unless newline is mentioned as one of the characters not to match. This is in contrast to the handling of regexps in programs such as grep.

^

is a special character that matches the empty string, but only at the beginning of a line in the text being matched. Otherwise it fails to match anything. Thus, ‘^foo’ matches a ‘foo’ that occurs at the beginning of a line.

For historical compatibility reasons, ‘^’ can be used with this meaning only at the beginning of the regular expression, or after ‘\(’ or ‘\|’.

$

is similar to ‘^’ but matches only at the end of a line. Thus, ‘x+$’ matches a string of one ‘x’ or more at the end of a line.

For historical compatibility reasons, ‘$’ can be used with this meaning only at the end of the regular expression, or before ‘\)’ or ‘\|’.

\

has two functions: it quotes the special characters (including ‘\’), and it introduces additional special constructs.

Because ‘\’ quotes special characters, ‘\$’ is a regular expression that matches only ‘$’, and ‘\[’ is a regular expression that matches only ‘[’, and so on.

See the following section for the special constructs that begin with ‘\’.

Note: for historical compatibility, special characters are treated as ordinary ones if they are in contexts where their special meanings make no sense. For example, ‘*foo’ treats ‘*’ as ordinary since there is no preceding expression on which the ‘*’ can act. It is poor practice to depend on this behavior; it is better to quote the special character anyway, regardless of where it appears.

As a ‘\’ is not special inside a character alternative, it can never remove the special meaning of ‘-’ or ‘]’. So you should not quote these characters when they have no special meaning either. This would not clarify anything, since backslashes can legitimately precede these characters where they have special meaning, as in ‘[^\]’ ("[^\\]" for Lisp string syntax), which matches any single character except a backslash.