emacs: Regexps
15.6 Syntax of Regular Expressions
==================================
This manual describes regular expression features that users typically
use. (elisp)Regular Expressions, for additional features used
mainly in Lisp programs.
Regular expressions have a syntax in which a few characters are
special constructs and the rest are “ordinary”. An ordinary character
matches that same character and nothing else. The special characters
are ‘$^.*+?[\’. 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.
For example, concatenating the regular expressions ‘f’ and ‘o’ gives 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. For example, the regular expressions ‘a.b’ 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 any number
of times, 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. Thus, ‘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. Thus, ‘ca?r’
matches ‘car’ or ‘cr’, and nothing else.
‘*?’, ‘+?’, ‘??’
are non-“greedy” variants of the operators above. The normal
operators ‘*’, ‘+’, ‘?’ match as much as they can, as long as the
overall regexp can still match. With a following ‘?’, 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 specifying N repetitions—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 specifying between N and M repetitions—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”, beginning with ‘[’ and 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). 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.
You can also include certain special “character classes” in a
character set. A ‘[:’ and balancing ‘:]’ enclose a character class
inside a character alternative. For instance, ‘[[:alnum:]]’
matches any letter or digit. (elisp)Char Classes, for a
list of character classes.
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.