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