lib/libc/regex/re_format.7

   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 .\" $FreeBSD: src/lib/libc/regex/re_format.7,v 1.4.2.5 2002/01/22 12:40:10 ru Exp $
  38 .\" $DragonFly: src/lib/libc/regex/re_format.7,v 1.2 2003/06/17 04:26:44 dillon Exp $
  39 .\"
  40 .Dd March 20, 1994
  41 .Dt RE_FORMAT 7
  42 .Os
  43 .Sh NAME
  44 .Nm re_format
  45 .Nd POSIX 1003.2 regular expressions
  46 .Sh DESCRIPTION
  47 Regular expressions
  48 .Pq Dq RE Ns s ,
  49 as defined in
  50 .St -p1003.2 ,
  51 come in two forms:
  52 modern REs (roughly those of
  53 .Xr egrep 1 ;
  54 1003.2 calls these
  55 .Dq extended
  56 REs)
  57 and obsolete REs (roughly those of
  58 .Xr ed 1 ;
  59 1003.2
  60 .Dq basic
  61 REs).
  62 Obsolete REs mostly exist for backward compatibility in some old programs;
  63 they will be discussed at the end.
  64 .St -p1003.2
  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
  68 .St -p1003.2
  69 implementations.
  70 .Pp
  71 A (modern) RE is one\(dd or more non-empty\(dd
  72 .Em branches ,
  73 separated by
  74 .Ql \&| .
  75 It matches anything that matches one of the branches.
  76 .Pp
  77 A branch is one\(dd or more
  78 .Em pieces ,
  79 concatenated.
  80 It matches a match for the first, followed by a match for the second, etc.
  81 .Pp
  82 A piece is an
  83 .Em atom
  84 possibly followed
  85 by a single\(dd
  86 .Ql \&* ,
  87 .Ql \&+ ,
  88 .Ql \&? ,
  89 or
  90 .Em bound .
  91 An atom followed by
  92 .Ql \&*
  93 matches a sequence of 0 or more matches of the atom.
  94 An atom followed by
  95 .Ql \&+
  96 matches a sequence of 1 or more matches of the atom.
  97 An atom followed by
  98 .Ql ?\&
  99 matches a sequence of 0 or 1 matches of the atom.
 100 .Pp
 101 A
 102 .Em bound
 103 is
 104 .Ql \&{
 105 followed by an unsigned decimal integer,
 106 possibly followed by
 107 .Ql \&,
 108 possibly followed by another unsigned decimal integer,
 109 always followed by
 110 .Ql \&} .
 111 The integers must lie between 0 and
 112 .Dv RE_DUP_MAX
 113 (255\(dd) inclusive,
 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
 116 .Em i
 117 and no comma matches
 118 a sequence of exactly
 119 .Em i
 120 matches of the atom.
 121 An atom followed by a bound
 122 containing one integer
 123 .Em i
 124 and a comma matches
 125 a sequence of
 126 .Em i
 127 or more matches of the atom.
 128 An atom followed by a bound
 129 containing two integers
 130 .Em i
 131 and
 132 .Em j
 133 matches
 134 a sequence of
 135 .Em i
 136 through
 137 .Em j
 138 (inclusive) matches of the atom.
 139 .Pp
 140 An atom is a regular expression enclosed in
 141 .Ql ()
 142 (matching a match for the
 143 regular expression),
 144 an empty set of
 145 .Ql ()
 146 (matching the null string)\(dd,
 147 a
 148 .Em bracket expression
 149 (see below),
 150 .Ql .\&
 151 (matching any single character),
 152 .Ql \&^
 153 (matching the null string at the beginning of a line),
 154 .Ql \&$
 155 (matching the null string at the end of a line), a
 156 .Ql \e
 157 followed by one of the characters
 158 .Ql ^.[$()|*+?{\e
 159 (matching that character taken as an ordinary character),
 160 a
 161 .Ql \e
 162 followed by any other character\(dd
 163 (matching that character taken as an ordinary character,
 164 as if the
 165 .Ql \e
 166 had not been present\(dd),
 167 or a single character with no other significance (matching that character).
 168 A
 169 .Ql \&{
 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
 173 .Ql \e .
 174 .Pp
 175 A
 176 .Em bracket expression
 177 is a list of characters enclosed in
 178 .Ql [] .
 179 It normally matches any single character from the list (but see below).
 180 If the list begins with
 181 .Ql \&^ ,
 182 it matches any single character
 183 (but see below)
 184 .Em not
 185 from the rest of the list.
 186 If two characters in the list are separated by
 187 .Ql \&- ,
 188 this is shorthand
 189 for the full
 190 .Em range
 191 of characters between those two (inclusive) in the
 192 collating sequence,
 193 .No e.g. Ql [0-9]
 194 in ASCII matches any decimal digit.
 195 It is illegal\(dd for two ranges to share an
 196 endpoint,
 197 .No e.g. Ql a-c-e .
 198 Ranges are very collating-sequence-dependent,
 199 and portable programs should avoid relying on them.
 200 .Pp
 201 To include a literal
 202 .Ql \&]
 203 in the list, make it the first character
 204 (following a possible
 205 .Ql \&^ ) .
 206 To include a literal
 207 .Ql \&- ,
 208 make it the first or last character,
 209 or the second endpoint of a range.
 210 To use a literal
 211 .Ql \&-
 212 as the first endpoint of a range,
 213 enclose it in
 214 .Ql [.\&
 215 and
 216 .Ql .]\&
 217 to make it a collating element (see below).
 218 With the exception of these and some combinations using
 219 .Ql \&[
 220 (see next paragraphs), all other special characters, including
 221 .Ql \e ,
 222 lose their special significance within a bracket expression.
 223 .Pp
 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)
 227 enclosed in
 228 .Ql [.\&
 229 and
 230 .Ql .]\&
 231 stands for the
 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
 237 .Ql ch
 238 collating element,
 239 then the RE
 240 .Ql [[.ch.]]*c
 241 matches the first five characters
 242 of
 243 .Ql chchcc .
 244 .Pp
 245 Within a bracket expression, a collating element enclosed in
 246 .Ql [=
 247 and
 248 .Ql =]
 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
 253 .Ql [.\&
 254 and
 255 .Ql .] . )
 256 For example, if
 257 .Ql x
 258 and
 259 .Ql y
 260 are the members of an equivalence class,
 261 then
 262 .Ql [[=x=]] ,
 263 .Ql [[=y=]] ,
 264 and
 265 .Ql [xy]
 266 are all synonymous.
 267 An equivalence class may not\(dd be an endpoint
 268 of a range.
 269 .Pp
 270 Within a bracket expression, the name of a
 271 .Em character class
 272 enclosed in
 273 .Ql [:
 274 and
 275 .Ql :]
 276 stands for the list of all characters belonging to that
 277 class.
 278 Standard character class names are:
 279 .Pp
 280 .Bl -column "alnum" "digit" "xdigit" -offset indent
 281 .It Em "alnum   digit   punct"
 282 .It Em "alpha   graph   space"
 283 .It Em "blank   lower   upper"
 284 .It Em "cntrl   print   xdigit"
 285 .El
 286 .Pp
 287 These stand for the character classes defined in
 288 .Xr ctype 3 .
 289 A locale may provide others.
 290 A character class may not be used as an endpoint of a range.
 291 .Pp
 292 There are two special cases\(dd of bracket expressions:
 293 the bracket expressions
 294 .Ql [[:<:]]
 295 and
 296 .Ql [[:>:]]
 297 match the null string at the beginning and end of a word respectively.
 298 A word is defined as a sequence of word characters
 299 which is neither preceded nor followed by
 300 word characters.
 301 A word character is an
 302 .Em alnum
 303 character (as defined by
 304 .Xr ctype 3 )
 305 or an underscore.
 306 This is an extension,
 307 compatible with but not specified by
 308 .St -p1003.2 ,
 309 and should be used with
 310 caution in software intended to be portable to other systems.
 311 .Pp
 312 In the event that an RE could match more than one substring of a given
 313 string,
 314 the RE matches the one starting earliest in the string.
 315 If the RE could match more than one substring starting at that point,
 316 it matches the longest.
 317 Subexpressions also match the longest possible substrings, subject to
 318 the constraint that the whole match be as long as possible,
 319 with subexpressions starting earlier in the RE taking priority over
 320 ones starting later.
 321 Note that higher-level subexpressions thus take priority over
 322 their lower-level component subexpressions.
 323 .Pp
 324 Match lengths are measured in characters, not collating elements.
 325 A null string is considered longer than no match at all.
 326 For example,
 327 .Ql bb*
 328 matches the three middle characters of
 329 .Ql abbbc ,
 330 .Ql (wee|week)(knights|nights)
 331 matches all ten characters of
 332 .Ql weeknights ,
 333 when
 334 .Ql (.*).*\&
 335 is matched against
 336 .Ql abc
 337 the parenthesized subexpression
 338 matches all three characters, and
 339 when
 340 .Ql (a*)*
 341 is matched against
 342 .Ql bc
 343 both the whole RE and the parenthesized
 344 subexpression match the null string.
 345 .Pp
 346 If case-independent matching is specified,
 347 the effect is much as if all case distinctions had vanished from the
 348 alphabet.
 349 When an alphabetic that exists in multiple cases appears as an
 350 ordinary character outside a bracket expression, it is effectively
 351 transformed into a bracket expression containing both cases,
 352 .No e.g. Ql x
 353 becomes
 354 .Ql [xX] .
 355 When it appears inside a bracket expression, all case counterparts
 356 of it are added to the bracket expression, so that (e.g.)
 357 .Ql [x]
 358 becomes
 359 .Ql [xX]
 360 and
 361 .Ql [^x]
 362 becomes
 363 .Ql [^xX] .
 364 .Pp
 365 No particular limit is imposed on the length of REs\(dd.
 366 Programs intended to be portable should not employ REs longer
 367 than 256 bytes,
 368 as an implementation can refuse to accept such REs and remain
 369 POSIX-compliant.
 370 .Pp
 371 Obsolete
 372 .Pq Dq basic
 373 regular expressions differ in several respects.
 374 .Ql \&|
 375 is an ordinary character and there is no equivalent
 376 for its functionality.
 377 .Ql \&+
 378 and
 379 .Ql ?\&
 380 are ordinary characters, and their functionality
 381 can be expressed using bounds
 382 .No ( Ql {1,}
 383 or
 384 .Ql {0,1}
 385 respectively).
 386 Also note that
 387 .Ql x+
 388 in modern REs is equivalent to
 389 .Ql xx* .
 390 The delimiters for bounds are
 391 .Ql \e{
 392 and
 393 .Ql \e} ,
 394 with
 395 .Ql \&{
 396 and
 397 .Ql \&}
 398 by themselves ordinary characters.
 399 The parentheses for nested subexpressions are
 400 .Ql \e(
 401 and
 402 .Ql \e) ,
 403 with
 404 .Ql \&(
 405 and
 406 .Ql \&)
 407 by themselves ordinary characters.
 408 .Ql \&^
 409 is an ordinary character except at the beginning of the
 410 RE or\(dd the beginning of a parenthesized subexpression,
 411 .Ql \&$
 412 is an ordinary character except at the end of the
 413 RE or\(dd the end of a parenthesized subexpression,
 414 and
 415 .Ql \&*
 416 is an ordinary character if it appears at the beginning of the
 417 RE or the beginning of a parenthesized subexpression
 418 (after a possible leading
 419 .Ql \&^ ) .
 420 Finally, there is one new type of atom, a
 421 .Em back reference :
 422 .Ql \e
 423 followed by a non-zero decimal digit
 424 .Em d
 425 matches the same sequence of characters
 426 matched by the
 427 .Em d Ns th
 428 parenthesized subexpression
 429 (numbering subexpressions by the positions of their opening parentheses,
 430 left to right),
 431 so that (e.g.)
 432 .Ql \e([bc]\e)\e1
 433 matches
 434 .Ql bb
 435 or
 436 .Ql cc
 437 but not
 438 .Ql bc .
 439 .Sh SEE ALSO
 440 .Xr regex 3
 441 .Rs
 442 .%T Regular Expression Notation
 443 .%R IEEE Std
 444 .%N 1003.2
 445 .%P section 2.8
 446 .Re
 447 .Sh BUGS
 448 Having two kinds of REs is a botch.
 449 .Pp
 450 The current
 451 .St -p1003.2
 452 spec says that
 453 .Ql \&)
 454 is an ordinary character in
 455 the absence of an unmatched
 456 .Ql \&( ;
 457 this was an unintentional result of a wording error,
 458 and change is likely.
 459 Avoid relying on it.
 460 .Pp
 461 Back references are a dreadful botch,
 462 posing major problems for efficient implementations.
 463 They are also somewhat vaguely defined
 464 (does
 465 .Ql a\e(\e(b\e)*\e2\e)*d
 466 match
 467 .Ql abbbd ? ) .
 468 Avoid using them.
 469 .Pp
 470 .St -p1003.2
 471 specification of case-independent matching is vague.
 472 The
 473 .Dq one case implies all cases
 474 definition given above
 475 is current consensus among implementors as to the right interpretation.
 476 .Pp
 477 The syntax for word boundaries is incredibly ugly.