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. All advertising materials mentioning features or use of this software
17 .\" must display the following acknowledgement:
18 .\" This product includes software developed by the University of
19 .\" California, Berkeley and its contributors.
20 .\" 4. Neither the name of the University nor the names of its contributors
21 .\" may be used to endorse or promote products derived from this software
22 .\" without specific prior written permission.
24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36 .\" @(#)re_format.7 8.3 (Berkeley) 3/20/94
37 .\" $FreeBSD: src/lib/libc/regex/re_format.7,v 1.12 2008/09/05 17:41:20 keramida Exp $
38 .\" $DragonFly: src/lib/libc/regex/re_format.7,v 1.3 2008/05/02 02:05:04 swildner Exp $
45 .Nd POSIX 1003.2 regular expressions
52 modern REs (roughly those of
57 and obsolete REs (roughly those of
62 Obsolete REs mostly exist for backward compatibility in some old programs;
63 they will be discussed at the end.
65 leaves some aspects of RE syntax and semantics open;
66 `\(dd' marks decisions on these aspects that
67 may not be fully portable to other
71 A (modern) RE is one\(dd or more non-empty\(dd
75 It matches anything that matches one of the branches.
77 A branch is one\(dd or more
80 It matches a match for the first, followed by a match for the second, etc.
93 matches a sequence of 0 or more matches of the atom.
96 matches a sequence of 1 or more matches of the atom.
99 matches a sequence of 0 or 1 matches of the atom.
105 followed by an unsigned decimal integer,
108 possibly followed by another unsigned decimal integer,
111 The integers must lie between 0 and
114 and if there are two of them, the first may not exceed the second.
115 An atom followed by a bound containing one integer
118 a sequence of exactly
121 An atom followed by a bound
122 containing one integer
127 or more matches of the atom.
128 An atom followed by a bound
129 containing two integers
138 (inclusive) matches of the atom.
140 An atom is a regular expression enclosed in
142 (matching a match for the
146 (matching the null string)\(dd,
148 .Em bracket expression
151 (matching any single character),
153 (matching the null string at the beginning of a line),
155 (matching the null string at the end of a line), a
157 followed by one of the characters
159 (matching that character taken as an ordinary character),
162 followed by any other character\(dd
163 (matching that character taken as an ordinary character,
166 had not been present\(dd),
167 or a single character with no other significance (matching that character).
170 followed by a character other than a digit is an ordinary
171 character, not the beginning of a bound\(dd.
172 It is illegal to end an RE with
176 .Em bracket expression
177 is a list of characters enclosed in
179 It normally matches any single character from the list (but see below).
180 If the list begins with
182 it matches any single character
185 from the rest of the list.
186 If two characters in the list are separated by
191 of characters between those two (inclusive) in the
194 in ASCII matches any decimal digit.
195 It is illegal\(dd for two ranges to share an
198 Ranges are very collating-sequence-dependent,
199 and portable programs should avoid relying on them.
203 in the list, make it the first character
204 (following a possible
208 make it the first or last character,
209 or the second endpoint of a range.
212 as the first endpoint of a range,
217 to make it a collating element (see below).
218 With the exception of these and some combinations using
220 (see next paragraphs), all other special characters, including
222 lose their special significance within a bracket expression.
224 Within a bracket expression, a collating element (a character,
225 a multi-character sequence that collates as if it were a single character,
226 or a collating-sequence name for either)
232 sequence of characters of that collating element.
233 The sequence is a single element of the bracket expression's list.
234 A bracket expression containing a multi-character collating element
235 can thus match more than one character,
236 e.g.\& if the collating sequence includes a
241 matches the first five characters
245 Within a bracket expression, a collating element enclosed in
249 is an equivalence class, standing for the sequences of characters
250 of all collating elements equivalent to that one, including itself.
251 (If there are no other equivalent collating elements,
252 the treatment is as if the enclosing delimiters were
260 are the members of an equivalence class,
267 An equivalence class may not\(dd be an endpoint
270 Within a bracket expression, the name of a
276 stands for the list of all characters belonging to that
278 Standard character class names are:
279 .Bl -column "alnum" "digit" "xdigit" -offset indent
280 .It Em "alnum digit punct"
281 .It Em "alpha graph space"
282 .It Em "blank lower upper"
283 .It Em "cntrl print xdigit"
286 These stand for the character classes defined in
288 A locale may provide others.
289 A character class may not be used as an endpoint of a range.
291 A bracketed expression like
293 can be used to match a single character that belongs to a character
295 The reverse, matching any character that does not belong to a specific
296 class, the negation operator of bracket expressions may be used:
299 There are two special cases\(dd of bracket expressions:
300 the bracket expressions
304 match the null string at the beginning and end of a word respectively.
305 A word is defined as a sequence of word characters
306 which is neither preceded nor followed by
308 A word character is an
310 character (as defined by
313 This is an extension,
314 compatible with but not specified by
316 and should be used with
317 caution in software intended to be portable to other systems.
319 In the event that an RE could match more than one substring of a given
321 the RE matches the one starting earliest in the string.
322 If the RE could match more than one substring starting at that point,
323 it matches the longest.
324 Subexpressions also match the longest possible substrings, subject to
325 the constraint that the whole match be as long as possible,
326 with subexpressions starting earlier in the RE taking priority over
328 Note that higher-level subexpressions thus take priority over
329 their lower-level component subexpressions.
331 Match lengths are measured in characters, not collating elements.
332 A null string is considered longer than no match at all.
335 matches the three middle characters of
337 .Ql (wee|week)(knights|nights)
338 matches all ten characters of
344 the parenthesized subexpression
345 matches all three characters, and
350 both the whole RE and the parenthesized
351 subexpression match the null string.
353 If case-independent matching is specified,
354 the effect is much as if all case distinctions had vanished from the
356 When an alphabetic that exists in multiple cases appears as an
357 ordinary character outside a bracket expression, it is effectively
358 transformed into a bracket expression containing both cases,
362 When it appears inside a bracket expression, all case counterparts
363 of it are added to the bracket expression, so that (e.g.)
372 No particular limit is imposed on the length of REs\(dd.
373 Programs intended to be portable should not employ REs longer
375 as an implementation can refuse to accept such REs and remain
380 regular expressions differ in several respects.
382 is an ordinary character and there is no equivalent
383 for its functionality.
387 are ordinary characters, and their functionality
388 can be expressed using bounds
395 in modern REs is equivalent to
397 The delimiters for bounds are
405 by themselves ordinary characters.
406 The parentheses for nested subexpressions are
414 by themselves ordinary characters.
416 is an ordinary character except at the beginning of the
417 RE or\(dd the beginning of a parenthesized subexpression,
419 is an ordinary character except at the end of the
420 RE or\(dd the end of a parenthesized subexpression,
423 is an ordinary character if it appears at the beginning of the
424 RE or the beginning of a parenthesized subexpression
425 (after a possible leading
427 Finally, there is one new type of atom, a
430 followed by a non-zero decimal digit
432 matches the same sequence of characters
435 parenthesized subexpression
436 (numbering subexpressions by the positions of their opening parentheses,
449 .%T Regular Expression Notation
455 Having two kinds of REs is a botch.
461 is an ordinary character in
462 the absence of an unmatched
464 this was an unintentional result of a wording error,
465 and change is likely.
468 Back references are a dreadful botch,
469 posing major problems for efficient implementations.
470 They are also somewhat vaguely defined
472 .Ql a\e(\e(b\e)*\e2\e)*d
478 specification of case-independent matching is vague.
480 .Dq one case implies all cases
481 definition given above
482 is current consensus among implementors as to the right interpretation.
484 The syntax for word boundaries is incredibly ugly.