Debian Codegraph @

upstream/debian-trixie/man7/regex.7

raw
1 '\" t
2 .\" From Henry Spencer's regex package (as found in the apache
3 .\" distribution). The package carries the following copyright:
4 .\"
5 .\" Copyright 1992, 1993, 1994 Henry Spencer. All rights reserved.
6 .\" %%%LICENSE_START(MISC)
7 .\" This software is not subject to any license of the American Telephone
8 .\" and Telegraph Company or of the Regents of the University of California.
9 .\"
10 .\" Permission is granted to anyone to use this software for any purpose
11 .\" on any computer system, and to alter it and redistribute it, subject
12 .\" to the following restrictions:
13 .\"
14 .\" 1. The author is not responsible for the consequences of use of this
15 .\" software, no matter how awful, even if they arise from flaws in it.
16 .\"
17 .\" 2. The origin of this software must not be misrepresented, either by
18 .\" explicit claim or by omission. Since few users ever read sources,
19 .\" credits must appear in the documentation.
20 .\"
21 .\" 3. Altered versions must be plainly marked as such, and must not be
22 .\" misrepresented as being the original software. Since few users
23 .\" ever read sources, credits must appear in the documentation.
24 .\"
25 .\" 4. This notice may not be removed or altered.
26 .\" %%%LICENSE_END
27 .\"
28 .\" In order to comply with `credits must appear in the documentation'
29 .\" I added an AUTHOR paragraph below - aeb.
30 .\"
31 .\" In the default nroff environment there is no dagger \(dg.
32 .\"
33 .\" 2005-05-11 Removed discussion of `[[:<:]]' and `[[:>:]]', which
34 .\" appear not to be in the glibc implementation of regcomp
35 .\"
36 .ie t .ds dg \(dg
37 .el .ds dg (!)
38 .TH regex 7 2024-06-15 "Linux man-pages 6.9.1"
39 .SH NAME
40 regex \- POSIX.2 regular expressions
41 .SH DESCRIPTION
42 Regular expressions ("RE"s),
43 as defined in POSIX.2, come in two forms:
44 modern REs (roughly those of
45 .BR egrep (1);
46 POSIX.2 calls these "extended" REs)
47 and obsolete REs (roughly those of
48 .BR ed (1);
49 POSIX.2 "basic" REs).
50 Obsolete REs mostly exist for backward compatibility in some old programs;
51 they will be discussed at the end.
52 POSIX.2 leaves some aspects of RE syntax and semantics open;
53 "\*(dg" marks decisions on these aspects that
54 may not be fully portable to other POSIX.2 implementations.
55 .P
56 A (modern) RE is one\*(dg or more nonempty\*(dg \fIbranches\fR,
57 separated by \[aq]|\[aq].
58 It matches anything that matches one of the branches.
59 .P
60 A branch is one\*(dg or more \fIpieces\fR, concatenated.
61 It matches a match for the first, followed by a match for the second,
62 and so on.
63 .P
64 A piece is an \fIatom\fR possibly followed
65 by a single\*(dg \[aq]*\[aq], \[aq]+\[aq], \[aq]?\[aq], or \fIbound\fR.
66 An atom followed by \[aq]*\[aq]
67 matches a sequence of 0 or more matches of the atom.
68 An atom followed by \[aq]+\[aq]
69 matches a sequence of 1 or more matches of the atom.
70 An atom followed by \[aq]?\[aq]
71 matches a sequence of 0 or 1 matches of the atom.
72 .P
73 A \fIbound\fR is \[aq]{\[aq] followed by an unsigned decimal integer,
74 possibly followed by \[aq],\[aq]
75 possibly followed by another unsigned decimal integer,
76 always followed by \[aq]}\[aq].
77 The integers must lie between 0 and
78 .B RE_DUP_MAX
79 (255\*(dg) inclusive,
80 and if there are two of them, the first may not exceed the second.
81 An atom followed by a bound containing one integer \fIi\fR
82 and no comma matches
83 a sequence of exactly \fIi\fR matches of the atom.
84 An atom followed by a bound
85 containing one integer \fIi\fR and a comma matches
86 a sequence of \fIi\fR or more matches of the atom.
87 An atom followed by a bound
88 containing two integers \fIi\fR and \fIj\fR matches
89 a sequence of \fIi\fR through \fIj\fR (inclusive) matches of the atom.
90 .P
91 An atom is a regular expression enclosed in "\fI()\fP"
92 (matching a match for the regular expression),
93 an empty set of "\fI()\fP" (matching the null string)\*(dg,
94 a \fIbracket expression\fR (see below),
95 \[aq].\[aq] (matching any single character),
96 \[aq]\[ha]\[aq] (matching the null string at the beginning of a line),
97 \[aq]$\[aq] (matching the null string at the end of a line),
98 a \[aq]\[rs]\[aq] followed by one of the characters "\fI\[ha].[$()|*+?{\[rs]\fP"
99 (matching that character taken as an ordinary character),
100 a \[aq]\[rs]\[aq] followed by any other character\*(dg
101 (matching that character taken as an ordinary character,
102 as if the \[aq]\[rs]\[aq] had not been present\*(dg),
103 or a single character with no other significance (matching that character).
104 A \[aq]{\[aq] followed by a character other than a digit
105 is an ordinary character,
106 not the beginning of a bound\*(dg.
107 It is illegal to end an RE with \[aq]\[rs]\[aq].
108 .P
109 A \fIbracket expression\fR is a list of characters enclosed in "\fI[]\fP".
110 It normally matches any single character from the list (but see below).
111 If the list begins with \[aq]\[ha]\[aq],
112 it matches any single character
113 (but see below) \fInot\fR from the rest of the list.
114 If two characters in the list are separated by \[aq]\-\[aq], this is shorthand
115 for the full \fIrange\fR of characters between those two (inclusive) in the
116 collating sequence,
117 for example, "\fI[0\-9]\fP" in ASCII matches any decimal digit.
118 It is illegal\*(dg for two ranges to share an
119 endpoint, for example, "\fIa\-c\-e\fP".
120 Ranges are very collating-sequence-dependent,
121 and portable programs should avoid relying on them.
122 .P
123 To include a literal \[aq]]\[aq] in the list, make it the first character
124 (following a possible \[aq]\[ha]\[aq]).
125 To include a literal \[aq]\-\[aq], make it the first or last character,
126 or the second endpoint of a range.
127 To use a literal \[aq]\-\[aq] as the first endpoint of a range,
128 enclose it in "\fI[.\fP" and "\fI.]\fP"
129 to make it a collating element (see below).
130 With the exception of these and some combinations using \[aq][\[aq] (see next
131 paragraphs), all other special characters, including \[aq]\[rs]\[aq], lose their
132 special significance within a bracket expression.
133 .P
134 Within a bracket expression, a collating element (a character,
135 a multicharacter sequence that collates as if it were a single character,
136 or a collating-sequence name for either)
137 enclosed in "\fI[.\fP" and "\fI.]\fP" stands for the
138 sequence of characters of that collating element.
139 The sequence is a single element of the bracket expression's list.
140 A bracket expression containing a multicharacter collating element
141 can thus match more than one character,
142 for example, if the collating sequence includes a "ch" collating element,
143 then the RE "\fI[[.ch.]]*c\fP" matches the first five characters
144 of "chchcc".
145 .P
146 Within a bracket expression, a collating element enclosed in "\fI[=\fP" and
147 "\fI=]\fP" is an equivalence class, standing for the sequences of characters
148 of all collating elements equivalent to that one, including itself.
149 (If there are no other equivalent collating elements,
150 the treatment is as if the enclosing delimiters
151 were "\fI[.\fP" and "\fI.]\fP".)
152 For example, if o and \(^o are the members of an equivalence class,
153 then "\fI[[=o=]]\fP", "\fI[[=\(^o=]]\fP",
154 and "\fI[o\(^o]\fP" are all synonymous.
155 An equivalence class may not\*(dg be an endpoint
156 of a range.
157 .P
158 Within a bracket expression, the name of a \fIcharacter class\fR enclosed
159 in "\fI[:\fP" and "\fI:]\fP" stands for the list
160 of all characters belonging to that
161 class.
162 Standard character class names are:
163 .P
164 .RS
165 .TS
166 l l l.
167 alnum digit punct
168 alpha graph space
169 blank lower upper
170 cntrl print xdigit
171 .TE
172 .RE
173 .P
174 These stand for the character classes defined in
175 .BR wctype (3).
176 A locale may provide others.
177 A character class may not be used as an endpoint of a range.
178 .\" As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=295666
179 .\" The following does not seem to apply in the glibc implementation
180 .\" .P
181 .\" There are two special cases\*(dg of bracket expressions:
182 .\" the bracket expressions "\fI[[:<:]]\fP" and "\fI[[:>:]]\fP" match
183 .\" the null string at the beginning and end of a word respectively.
184 .\" A word is defined as a sequence of
185 .\" word characters
186 .\" which is neither preceded nor followed by
187 .\" word characters.
188 .\" A word character is an
189 .\" .I alnum
190 .\" character (as defined by
191 .\" .BR wctype (3))
192 .\" or an underscore.
193 .\" This is an extension,
194 .\" compatible with but not specified by POSIX.2,
195 .\" and should be used with
196 .\" caution in software intended to be portable to other systems.
197 .P
198 In the event that an RE could match more than one substring of a given
199 string,
200 the RE matches the one starting earliest in the string.
201 If the RE could match more than one substring starting at that point,
202 it matches the longest.
203 Subexpressions also match the longest possible substrings, subject to
204 the constraint that the whole match be as long as possible,
205 with subexpressions starting earlier in the RE taking priority over
206 ones starting later.
207 Note that higher-level subexpressions thus take priority over
208 their lower-level component subexpressions.
209 .P
210 Match lengths are measured in characters, not collating elements.
211 A null string is considered longer than no match at all.
212 For example,
213 "\fIbb*\fP" matches the three middle characters of "abbbc",
214 "\fI(wee|week)(knights|nights)\fP"
215 matches all ten characters of "weeknights",
216 when "\fI(.*).*\fP" is matched against "abc" the parenthesized subexpression
217 matches all three characters, and
218 when "\fI(a*)*\fP" is matched against "bc"
219 both the whole RE and the parenthesized
220 subexpression match the null string.
221 .P
222 If case-independent matching is specified,
223 the effect is much as if all case distinctions had vanished from the
224 alphabet.
225 When an alphabetic that exists in multiple cases appears as an
226 ordinary character outside a bracket expression, it is effectively
227 transformed into a bracket expression containing both cases,
228 for example, \[aq]x\[aq] becomes "\fI[xX]\fP".
229 When it appears inside a bracket expression, all case counterparts
230 of it are added to the bracket expression, so that, for example, "\fI[x]\fP"
231 becomes "\fI[xX]\fP" and "\fI[\[ha]x]\fP" becomes "\fI[\[ha]xX]\fP".
232 .P
233 No particular limit is imposed on the length of REs\*(dg.
234 Programs intended to be portable should not employ REs longer
235 than 256 bytes,
236 as an implementation can refuse to accept such REs and remain
237 POSIX-compliant.
238 .P
239 Obsolete ("basic") regular expressions differ in several respects.
240 \[aq]|\[aq], \[aq]+\[aq], and \[aq]?\[aq] are
241 ordinary characters and there is no equivalent
242 for their functionality.
243 The delimiters for bounds are "\fI\[rs]{\fP" and "\fI\[rs]}\fP",
244 with \[aq]{\[aq] and \[aq]}\[aq] by themselves ordinary characters.
245 The parentheses for nested subexpressions are "\fI\[rs](\fP" and "\fI\[rs])\fP",
246 with \[aq](\[aq] and \[aq])\[aq] by themselves ordinary characters.
247 \[aq]\[ha]\[aq] is an ordinary character except at the beginning of the
248 RE or\*(dg the beginning of a parenthesized subexpression,
249 \[aq]$\[aq] is an ordinary character except at the end of the
250 RE or\*(dg the end of a parenthesized subexpression,
251 and \[aq]*\[aq] is an ordinary character if it appears at the beginning of the
252 RE or the beginning of a parenthesized subexpression
253 (after a possible leading \[aq]\[ha]\[aq]).
254 .P
255 Finally, there is one new type of atom, a \fIback reference\fR:
256 \[aq]\[rs]\[aq] followed by a nonzero decimal digit \fId\fR
257 matches the same sequence of characters
258 matched by the \fId\fRth parenthesized subexpression
259 (numbering subexpressions by the positions of their opening parentheses,
260 left to right),
261 so that, for example,
262 .I \[dq]\[rs]([bc]\[rs])\[rs]1\[dq]
263 matches
264 .I \[dq]bb\[dq]
265 or
266 .I \[dq]cc\[dq]
267 but not
268 .IR \[dq]bc\[dq] .
269 .SH BUGS
270 Having two kinds of REs is a botch.
271 .P
272 The current POSIX.2 spec says that \[aq])\[aq] is an ordinary character in
273 the absence of an unmatched \[aq](\[aq];
274 this was an unintentional result of a wording error,
275 and change is likely.
276 Avoid relying on it.
277 .P
278 Back references are a dreadful botch,
279 posing major problems for efficient implementations.
280 They are also somewhat vaguely defined
281 (does
282 "\fIa\[rs](\[rs](b\[rs])*\[rs]2\[rs])*d\fP" match "abbbd"?).
283 Avoid using them.
284 .P
285 POSIX.2's specification of case-independent matching is vague.
286 The "one case implies all cases" definition given above
287 is current consensus among implementors as to the right interpretation.
288 .\" As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=295666
289 .\" The following does not seem to apply in the glibc implementation
290 .\" .P
291 .\" The syntax for word boundaries is incredibly ugly.
292 .SH AUTHOR
293 .\" Sigh... The page license means we must have the author's name
294 .\" in the formatted output.
295 This page was taken from Henry Spencer's regex package.
296 .SH SEE ALSO
297 .BR grep (1),
298 .BR regex (3)
299 .P
300 POSIX.2, section 2.8 (Regular Expression Notation).