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