1 .\" Copyright (c) 1992, 1993, 1994 Henry Spencer.
2 .\" Copyright (c) 1992, 1993, 1994
3 .\" The Regents of the University of California. All rights reserved.
5 .\" This code is derived from software contributed to Berkeley by
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 3. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" @(#)re_format.7 8.3 (Berkeley) 3/20/94
33 .\" $FreeBSD: src/lib/libc/regex/re_format.7,v 1.12 2008/09/05 17:41:20 keramida Exp $
34 .\" $DragonFly: src/lib/libc/regex/re_format.7,v 1.3 2008/05/02 02:05:04 swildner Exp $
41 .Nd POSIX 1003.2 regular expressions
48 modern REs (roughly those of
53 and obsolete REs (roughly those of
58 Obsolete REs mostly exist for backward compatibility in some old programs;
59 they will be discussed at the end.
61 leaves some aspects of RE syntax and semantics open;
62 `\(dd' marks decisions on these aspects that
63 may not be fully portable to other
67 A (modern) RE is one\(dd or more non-empty\(dd
71 It matches anything that matches one of the branches.
73 A branch is one\(dd or more
76 It matches a match for the first, followed by a match for the second, etc.
89 matches a sequence of 0 or more matches of the atom.
92 matches a sequence of 1 or more matches of the atom.
95 matches a sequence of 0 or 1 matches of the atom.
101 followed by an unsigned decimal integer,
104 possibly followed by another unsigned decimal integer,
107 The integers must lie between 0 and
110 and if there are two of them, the first may not exceed the second.
111 An atom followed by a bound containing one integer
114 a sequence of exactly
117 An atom followed by a bound
118 containing one integer
123 or more matches of the atom.
124 An atom followed by a bound
125 containing two integers
134 (inclusive) matches of the atom.
136 An atom is a regular expression enclosed in
138 (matching a match for the
142 (matching the null string)\(dd,
144 .Em bracket expression
147 (matching any single character),
149 (matching the null string at the beginning of a line),
151 (matching the null string at the end of a line), a
153 followed by one of the characters
155 (matching that character taken as an ordinary character),
158 followed by any other character\(dd
159 (matching that character taken as an ordinary character,
162 had not been present\(dd),
163 or a single character with no other significance (matching that character).
166 followed by a character other than a digit is an ordinary
167 character, not the beginning of a bound\(dd.
168 It is illegal to end an RE with
172 .Em bracket expression
173 is a list of characters enclosed in
175 It normally matches any single character from the list (but see below).
176 If the list begins with
178 it matches any single character
181 from the rest of the list.
182 If two characters in the list are separated by
187 of characters between those two (inclusive) in the
190 in ASCII matches any decimal digit.
191 It is illegal\(dd for two ranges to share an
194 Ranges are very collating-sequence-dependent,
195 and portable programs should avoid relying on them.
199 in the list, make it the first character
200 (following a possible
204 make it the first or last character,
205 or the second endpoint of a range.
208 as the first endpoint of a range,
213 to make it a collating element (see below).
214 With the exception of these and some combinations using
216 (see next paragraphs), all other special characters, including
218 lose their special significance within a bracket expression.
220 Within a bracket expression, a collating element (a character,
221 a multi-character sequence that collates as if it were a single character,
222 or a collating-sequence name for either)
228 sequence of characters of that collating element.
229 The sequence is a single element of the bracket expression's list.
230 A bracket expression containing a multi-character collating element
231 can thus match more than one character,
232 e.g.\& if the collating sequence includes a
237 matches the first five characters
241 Within a bracket expression, a collating element enclosed in
245 is an equivalence class, standing for the sequences of characters
246 of all collating elements equivalent to that one, including itself.
247 (If there are no other equivalent collating elements,
248 the treatment is as if the enclosing delimiters were
256 are the members of an equivalence class,
263 An equivalence class may not\(dd be an endpoint
266 Within a bracket expression, the name of a
272 stands for the list of all characters belonging to that
274 Standard character class names are:
275 .Bl -column "alnum" "digit" "xdigit" -offset indent
276 .It Em "alnum digit punct"
277 .It Em "alpha graph space"
278 .It Em "blank lower upper"
279 .It Em "cntrl print xdigit"
282 These stand for the character classes defined in
284 A locale may provide others.
285 A character class may not be used as an endpoint of a range.
287 A bracketed expression like
289 can be used to match a single character that belongs to a character
291 The reverse, matching any character that does not belong to a specific
292 class, the negation operator of bracket expressions may be used:
295 There are two special cases\(dd of bracket expressions:
296 the bracket expressions
300 match the null string at the beginning and end of a word respectively.
301 A word is defined as a sequence of word characters
302 which is neither preceded nor followed by
304 A word character is an
306 character (as defined by
309 This is an extension,
310 compatible with but not specified by
312 and should be used with
313 caution in software intended to be portable to other systems.
315 In the event that an RE could match more than one substring of a given
317 the RE matches the one starting earliest in the string.
318 If the RE could match more than one substring starting at that point,
319 it matches the longest.
320 Subexpressions also match the longest possible substrings, subject to
321 the constraint that the whole match be as long as possible,
322 with subexpressions starting earlier in the RE taking priority over
324 Note that higher-level subexpressions thus take priority over
325 their lower-level component subexpressions.
327 Match lengths are measured in characters, not collating elements.
328 A null string is considered longer than no match at all.
331 matches the three middle characters of
333 .Ql (wee|week)(knights|nights)
334 matches all ten characters of
340 the parenthesized subexpression
341 matches all three characters, and
346 both the whole RE and the parenthesized
347 subexpression match the null string.
349 If case-independent matching is specified,
350 the effect is much as if all case distinctions had vanished from the
352 When an alphabetic that exists in multiple cases appears as an
353 ordinary character outside a bracket expression, it is effectively
354 transformed into a bracket expression containing both cases,
358 When it appears inside a bracket expression, all case counterparts
359 of it are added to the bracket expression, so that (e.g.)
368 No particular limit is imposed on the length of REs\(dd.
369 Programs intended to be portable should not employ REs longer
371 as an implementation can refuse to accept such REs and remain
376 regular expressions differ in several respects.
378 is an ordinary character and there is no equivalent
379 for its functionality.
383 are ordinary characters, and their functionality
384 can be expressed using bounds
391 in modern REs is equivalent to
393 The delimiters for bounds are
401 by themselves ordinary characters.
402 The parentheses for nested subexpressions are
410 by themselves ordinary characters.
412 is an ordinary character except at the beginning of the
413 RE or\(dd the beginning of a parenthesized subexpression,
415 is an ordinary character except at the end of the
416 RE or\(dd the end of a parenthesized subexpression,
419 is an ordinary character if it appears at the beginning of the
420 RE or the beginning of a parenthesized subexpression
421 (after a possible leading
423 Finally, there is one new type of atom, a
426 followed by a non-zero decimal digit
428 matches the same sequence of characters
431 parenthesized subexpression
432 (numbering subexpressions by the positions of their opening parentheses,
445 .%T Regular Expression Notation
451 Having two kinds of REs is a botch.
457 is an ordinary character in
458 the absence of an unmatched
460 this was an unintentional result of a wording error,
461 and change is likely.
464 Back references are a dreadful botch,
465 posing major problems for efficient implementations.
466 They are also somewhat vaguely defined
468 .Ql a\e(\e(b\e)*\e2\e)*d
474 specification of case-independent matching is vague.
476 .Dq one case implies all cases
477 definition given above
478 is current consensus among implementors as to the right interpretation.
480 The syntax for word boundaries is incredibly ugly.