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