source: trunk/minix/lib/regex/re_format.7@ 10

Last change on this file since 10 was 9, checked in by Mattia Monga, 13 years ago

Minix 3.1.2a

File size: 11.5 KB
Line 
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.
4.\"
5.\" This code is derived from software contributed to Berkeley by
6.\" Henry Spencer.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
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.
23.\"
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
34.\" SUCH DAMAGE.
35.\"
36.\" @(#)re_format.7 8.3 (Berkeley) 3/20/94
37.\"
38.TH RE_FORMAT 7 "March 20, 1994"
39.SH NAME
40re_format \- POSIX 1003.2 regular expressions
41.SH DESCRIPTION
42Regular expressions (``RE''s),
43as defined in POSIX 1003.2, come in two forms:
44modern REs (roughly those of
45.BR egrep ;
461003.2 calls these ``extended'' REs)
47and obsolete REs (roughly those of
48.BR ed ;
491003.2 ``basic'' REs).
50Obsolete REs mostly exist for backward compatibility in some old programs;
51they will be discussed at the end.
521003.2 leaves some aspects of RE syntax and semantics open;
53`\(dg' marks decisions on these aspects that
54may not be fully portable to other 1003.2 implementations.
55.PP
56A (modern) RE is one\(dg or more non-empty\(dg \fIbranches\fR,
57separated by `|'.
58It matches anything that matches one of the branches.
59.PP
60A branch is one\(dg or more \fIpieces\fR, concatenated.
61It matches a match for the first, followed by a match for the second, etc.
62.PP
63A piece is an \fIatom\fR possibly followed
64by a single\(dg `*', `+', `?', or \fIbound\fR.
65An atom followed by `*' matches a sequence of 0 or more matches of the atom.
66An atom followed by `+' matches a sequence of 1 or more matches of the atom.
67An atom followed by `?' matches a sequence of 0 or 1 matches of the atom.
68.PP
69A \fIbound\fR is `{' followed by an unsigned decimal integer,
70possibly followed by `,'
71possibly followed by another unsigned decimal integer,
72always followed by `}'.
73The integers must lie between 0 and RE_DUP_MAX (255\(dg) inclusive,
74and if there are two of them, the first may not exceed the second.
75An atom followed by a bound containing one integer \fIi\fR
76and no comma matches
77a sequence of exactly \fIi\fR matches of the atom.
78An atom followed by a bound
79containing one integer \fIi\fR and a comma matches
80a sequence of \fIi\fR or more matches of the atom.
81An atom followed by a bound
82containing two integers \fIi\fR and \fIj\fR matches
83a sequence of \fIi\fR through \fIj\fR (inclusive) matches of the atom.
84.PP
85An atom is a regular expression enclosed in `()' (matching a match for the
86regular expression),
87an empty set of `()' (matching the null string)\(dg,
88a \fIbracket expression\fR (see below), `.'
89(matching any single character), `^' (matching the null string at the
90beginning of a line), `$' (matching the null string at the
91end of a line), a `\e' followed by one of the characters
92`^.[$()|*+?{\e'
93(matching that character taken as an ordinary character),
94a `\e' followed by any other character\(dg
95(matching that character taken as an ordinary character,
96as if the `\e' had not been present\(dg),
97or a single character with no other significance (matching that character).
98A `{' followed by a character other than a digit is an ordinary
99character, not the beginning of a bound\(dg.
100It is illegal to end an RE with `\e'.
101.PP
102A \fIbracket expression\fR is a list of characters enclosed in `[]'.
103It normally matches any single character from the list (but see below).
104If the list begins with `^',
105it matches any single character
106(but see below) \fInot\fR from the rest of the list.
107If two characters in the list are separated by `\-', this is shorthand
108for the full \fIrange\fR of characters between those two (inclusive) in the
109collating sequence,
110e.g. `[0-9]' in ASCII matches any decimal digit.
111It is illegal\(dg for two ranges to share an
112endpoint, e.g. `a-c-e'.
113Ranges are very collating-sequence-dependent,
114and portable programs should avoid relying on them.
115.PP
116To include a literal `]' in the list, make it the first character
117(following a possible `^').
118To include a literal `\-', make it the first or last character,
119or the second endpoint of a range.
120To use a literal `\-' as the first endpoint of a range,
121enclose it in `[.' and `.]' to make it a collating element (see below).
122With the exception of these and some combinations using `[' (see next
123paragraphs), all other special characters, including `\e', lose their
124special significance within a bracket expression.
125.PP
126Within a bracket expression, a collating element (a character,
127a multi-character sequence that collates as if it were a single character,
128or a collating-sequence name for either)
129enclosed in `[.' and `.]' stands for the
130sequence of characters of that collating element.
131The sequence is a single element of the bracket expression's list.
132A bracket expression containing a multi-character collating element
133can thus match more than one character,
134e.g. if the collating sequence includes a `ch' collating element,
135then the RE `[[.ch.]]*c' matches the first five characters
136of `chchcc'.
137.PP
138Within a bracket expression, a collating element enclosed in `[=' and
139`=]' is an equivalence class, standing for the sequences of characters
140of all collating elements equivalent to that one, including itself.
141(If there are no other equivalent collating elements,
142the treatment is as if the enclosing delimiters were `[.' and `.]'.)
143For example, if o and \o'o^' are the members of an equivalence class,
144then `[[=o=]]', `[[=\o'o^'=]]', and `[o\o'o^']' are all synonymous.
145An equivalence class may not\(dg be an endpoint
146of a range.
147.PP
148Within a bracket expression, the name of a \fIcharacter class\fR enclosed
149in `[:' and `:]' stands for the list of all characters belonging to that
150class.
151Standard character class names are:
152.PP
153.RS
154.nf
155.ta 3c 6c 9c
156alnum digit punct
157alpha graph space
158blank lower upper
159cntrl print xdigit
160.fi
161.RE
162.PP
163These stand for the character classes defined in
164.BR ctype (3).
165A locale may provide others.
166A character class may not be used as an endpoint of a range.
167.PP
168There are two special cases\(dg of bracket expressions:
169the bracket expressions `[[:<:]]' and `[[:>:]]' match the null string at
170the beginning and end of a word respectively.
171A word is defined as a sequence of
172word characters
173which is neither preceded nor followed by
174word characters.
175A word character is an
176.B alnum
177character (as defined by
178.BR ctype (3))
179or an underscore.
180This is an extension,
181compatible with but not specified by POSIX 1003.2,
182and should be used with
183caution in software intended to be portable to other systems.
184.PP
185In the event that an RE could match more than one substring of a given
186string,
187the RE matches the one starting earliest in the string.
188If the RE could match more than one substring starting at that point,
189it matches the longest.
190Subexpressions also match the longest possible substrings, subject to
191the constraint that the whole match be as long as possible,
192with subexpressions starting earlier in the RE taking priority over
193ones starting later.
194Note that higher-level subexpressions thus take priority over
195their lower-level component subexpressions.
196.PP
197Match lengths are measured in characters, not collating elements.
198A null string is considered longer than no match at all.
199For example,
200`bb*' matches the three middle characters of `abbbc',
201`(wee|week)(knights|nights)' matches all ten characters of `weeknights',
202when `(.*).*' is matched against `abc' the parenthesized subexpression
203matches all three characters, and
204when `(a*)*' is matched against `bc' both the whole RE and the parenthesized
205subexpression match the null string.
206.PP
207If case-independent matching is specified,
208the effect is much as if all case distinctions had vanished from the
209alphabet.
210When an alphabetic that exists in multiple cases appears as an
211ordinary character outside a bracket expression, it is effectively
212transformed into a bracket expression containing both cases,
213e.g. `x' becomes `[xX]'.
214When it appears inside a bracket expression, all case counterparts
215of it are added to the bracket expression, so that (e.g.) `[x]'
216becomes `[xX]' and `[^x]' becomes `[^xX]'.
217.PP
218No particular limit is imposed on the length of REs\(dg.
219Programs intended to be portable should not employ REs longer
220than 256 bytes,
221as an implementation can refuse to accept such REs and remain
222POSIX-compliant.
223.PP
224Obsolete (``basic'') regular expressions differ in several respects.
225`|', `+', and `?' are ordinary characters and there is no equivalent
226for their functionality.
227The delimiters for bounds are `\e{' and `\e}',
228with `{' and `}' by themselves ordinary characters.
229The parentheses for nested subexpressions are `\e(' and `\e)',
230with `(' and `)' by themselves ordinary characters.
231`^' is an ordinary character except at the beginning of the
232RE or\(dg the beginning of a parenthesized subexpression,
233`$' is an ordinary character except at the end of the
234RE or\(dg the end of a parenthesized subexpression,
235and `*' is an ordinary character if it appears at the beginning of the
236RE or the beginning of a parenthesized subexpression
237(after a possible leading `^').
238Finally, there is one new type of atom, a \fIback reference\fR:
239`\e' followed by a non-zero decimal digit \fId\fR
240matches the same sequence of characters
241matched by the \fId\fRth parenthesized subexpression
242(numbering subexpressions by the positions of their opening parentheses,
243left to right),
244so that (e.g.) `\e([bc]\e)\e1' matches `bb' or `cc' but not `bc'.
245.SH SEE ALSO
246regex(3)
247.PP
248POSIX 1003.2, section 2.8 (Regular Expression Notation).
249.SH BUGS
250Having two kinds of REs is a botch.
251.PP
252The current 1003.2 spec says that `)' is an ordinary character in
253the absence of an unmatched `(';
254this was an unintentional result of a wording error,
255and change is likely.
256Avoid relying on it.
257.PP
258Back references are a dreadful botch,
259posing major problems for efficient implementations.
260They are also somewhat vaguely defined
261(does
262`a\e(\e(b\e)*\e2\e)*d' match `abbbd'?).
263Avoid using them.
264.PP
2651003.2's specification of case-independent matching is vague.
266The ``one case implies all cases'' definition given above
267is current consensus among implementors as to the right interpretation.
268.PP
269The syntax for word boundaries is incredibly ugly.
Note: See TracBrowser for help on using the repository browser.