Annotation of parser3/src/lib/pcre/pcre.3.html, revision 1.1
1.1 ! paf 1: <HTML>
! 2: <HEAD>
! 3: <TITLE>pcre specification</TITLE>
! 4: </HEAD>
! 5: <body bgcolor="#FFFFFF" text="#00005A">
! 6: <H1>pcre specification</H1>
! 7: This HTML document has been generated automatically from the original man page.
! 8: If there is any nonsense in it, please consult the man page in case the
! 9: conversion went wrong.
! 10: <UL>
! 11: <LI><A NAME="TOC1" HREF="#SEC1">NAME</A>
! 12: <LI><A NAME="TOC2" HREF="#SEC2">SYNOPSIS</A>
! 13: <LI><A NAME="TOC3" HREF="#SEC3">DESCRIPTION</A>
! 14: <LI><A NAME="TOC4" HREF="#SEC4">MULTI-THREADING</A>
! 15: <LI><A NAME="TOC5" HREF="#SEC5">COMPILING A PATTERN</A>
! 16: <LI><A NAME="TOC6" HREF="#SEC6">STUDYING A PATTERN</A>
! 17: <LI><A NAME="TOC7" HREF="#SEC7">LOCALE SUPPORT</A>
! 18: <LI><A NAME="TOC8" HREF="#SEC8">INFORMATION ABOUT A PATTERN</A>
! 19: <LI><A NAME="TOC9" HREF="#SEC9">MATCHING A PATTERN</A>
! 20: <LI><A NAME="TOC10" HREF="#SEC10">EXTRACTING CAPTURED SUBSTRINGS</A>
! 21: <LI><A NAME="TOC11" HREF="#SEC11">LIMITATIONS</A>
! 22: <LI><A NAME="TOC12" HREF="#SEC12">DIFFERENCES FROM PERL</A>
! 23: <LI><A NAME="TOC13" HREF="#SEC13">REGULAR EXPRESSION DETAILS</A>
! 24: <LI><A NAME="TOC14" HREF="#SEC14">BACKSLASH</A>
! 25: <LI><A NAME="TOC15" HREF="#SEC15">CIRCUMFLEX AND DOLLAR</A>
! 26: <LI><A NAME="TOC16" HREF="#SEC16">FULL STOP (PERIOD, DOT)</A>
! 27: <LI><A NAME="TOC17" HREF="#SEC17">SQUARE BRACKETS</A>
! 28: <LI><A NAME="TOC18" HREF="#SEC18">VERTICAL BAR</A>
! 29: <LI><A NAME="TOC19" HREF="#SEC19">INTERNAL OPTION SETTING</A>
! 30: <LI><A NAME="TOC20" HREF="#SEC20">SUBPATTERNS</A>
! 31: <LI><A NAME="TOC21" HREF="#SEC21">REPETITION</A>
! 32: <LI><A NAME="TOC22" HREF="#SEC22">BACK REFERENCES</A>
! 33: <LI><A NAME="TOC23" HREF="#SEC23">ASSERTIONS</A>
! 34: <LI><A NAME="TOC24" HREF="#SEC24">ONCE-ONLY SUBPATTERNS</A>
! 35: <LI><A NAME="TOC25" HREF="#SEC25">CONDITIONAL SUBPATTERNS</A>
! 36: <LI><A NAME="TOC26" HREF="#SEC26">COMMENTS</A>
! 37: <LI><A NAME="TOC27" HREF="#SEC27">PERFORMANCE</A>
! 38: <LI><A NAME="TOC28" HREF="#SEC28">AUTHOR</A>
! 39: </UL>
! 40: <LI><A NAME="SEC1" HREF="#TOC1">NAME</A>
! 41: <P>
! 42: pcre - Perl-compatible regular expressions.
! 43: </P>
! 44: <LI><A NAME="SEC2" HREF="#TOC1">SYNOPSIS</A>
! 45: <P>
! 46: <B>#include <pcre.h></B>
! 47: </P>
! 48: <P>
! 49: <B>pcre *pcre_compile(const char *<I>pattern</I>, int <I>options</I>,</B>
! 50: <B>const char **<I>errptr</I>, int *<I>erroffset</I>,</B>
! 51: <B>const unsigned char *<I>tableptr</I>);</B>
! 52: </P>
! 53: <P>
! 54: <B>pcre_extra *pcre_study(const pcre *<I>code</I>, int <I>options</I>,</B>
! 55: <B>const char **<I>errptr</I>);</B>
! 56: </P>
! 57: <P>
! 58: <B>int pcre_exec(const pcre *<I>code</I>, const pcre_extra *<I>extra</I>,</B>
! 59: <B>const char *<I>subject</I>, int <I>length</I>, int <I>startoffset</I>,</B>
! 60: <B>int <I>options</I>, int *<I>ovector</I>, int <I>ovecsize</I>);</B>
! 61: </P>
! 62: <P>
! 63: <B>int pcre_copy_substring(const char *<I>subject</I>, int *<I>ovector</I>,</B>
! 64: <B>int <I>stringcount</I>, int <I>stringnumber</I>, char *<I>buffer</I>,</B>
! 65: <B>int <I>buffersize</I>);</B>
! 66: </P>
! 67: <P>
! 68: <B>int pcre_get_substring(const char *<I>subject</I>, int *<I>ovector</I>,</B>
! 69: <B>int <I>stringcount</I>, int <I>stringnumber</I>,</B>
! 70: <B>const char **<I>stringptr</I>);</B>
! 71: </P>
! 72: <P>
! 73: <B>int pcre_get_substring_list(const char *<I>subject</I>,</B>
! 74: <B>int *<I>ovector</I>, int <I>stringcount</I>, const char ***<I>listptr</I>);</B>
! 75: </P>
! 76: <P>
! 77: <B>const unsigned char *pcre_maketables(void);</B>
! 78: </P>
! 79: <P>
! 80: <B>int pcre_info(const pcre *<I>code</I>, int *<I>optptr</I>, int</B>
! 81: <B>*<I>firstcharptr</I>);</B>
! 82: </P>
! 83: <P>
! 84: <B>char *pcre_version(void);</B>
! 85: </P>
! 86: <P>
! 87: <B>void *(*pcre_malloc)(size_t);</B>
! 88: </P>
! 89: <P>
! 90: <B>void (*pcre_free)(void *);</B>
! 91: </P>
! 92: <LI><A NAME="SEC3" HREF="#TOC1">DESCRIPTION</A>
! 93: <P>
! 94: The PCRE library is a set of functions that implement regular expression
! 95: pattern matching using the same syntax and semantics as Perl 5, with just a few
! 96: differences (see below). The current implementation corresponds to Perl 5.005.
! 97: </P>
! 98: <P>
! 99: PCRE has its own native API, which is described in this document. There is also
! 100: a set of wrapper functions that correspond to the POSIX API. These are
! 101: described in the <B>pcreposix</B> documentation.
! 102: </P>
! 103: <P>
! 104: The native API function prototypes are defined in the header file <B>pcre.h</B>,
! 105: and on Unix systems the library itself is called <B>libpcre.a</B>, so can be
! 106: accessed by adding <B>-lpcre</B> to the command for linking an application which
! 107: calls it.
! 108: </P>
! 109: <P>
! 110: The functions <B>pcre_compile()</B>, <B>pcre_study()</B>, and <B>pcre_exec()</B>
! 111: are used for compiling and matching regular expressions, while
! 112: <B>pcre_copy_substring()</B>, <B>pcre_get_substring()</B>, and
! 113: <B>pcre_get_substring_list()</B> are convenience functions for extracting
! 114: captured substrings from a matched subject string. The function
! 115: <B>pcre_maketables()</B> is used (optionally) to build a set of character tables
! 116: in the current locale for passing to <B>pcre_compile()</B>.
! 117: </P>
! 118: <P>
! 119: The function <B>pcre_info()</B> is used to find out information about a compiled
! 120: pattern, while the function <B>pcre_version()</B> returns a pointer to a string
! 121: containing the version of PCRE and its date of release.
! 122: </P>
! 123: <P>
! 124: The global variables <B>pcre_malloc</B> and <B>pcre_free</B> initially contain
! 125: the entry points of the standard <B>malloc()</B> and <B>free()</B> functions
! 126: respectively. PCRE calls the memory management functions via these variables,
! 127: so a calling program can replace them if it wishes to intercept the calls. This
! 128: should be done before calling any PCRE functions.
! 129: </P>
! 130: <LI><A NAME="SEC4" HREF="#TOC1">MULTI-THREADING</A>
! 131: <P>
! 132: The PCRE functions can be used in multi-threading applications, with the
! 133: proviso that the memory management functions pointed to by <B>pcre_malloc</B>
! 134: and <B>pcre_free</B> are shared by all threads.
! 135: </P>
! 136: <P>
! 137: The compiled form of a regular expression is not altered during matching, so
! 138: the same compiled pattern can safely be used by several threads at once.
! 139: </P>
! 140: <LI><A NAME="SEC5" HREF="#TOC1">COMPILING A PATTERN</A>
! 141: <P>
! 142: The function <B>pcre_compile()</B> is called to compile a pattern into an
! 143: internal form. The pattern is a C string terminated by a binary zero, and
! 144: is passed in the argument <I>pattern</I>. A pointer to a single block of memory
! 145: that is obtained via <B>pcre_malloc</B> is returned. This contains the
! 146: compiled code and related data. The <B>pcre</B> type is defined for this for
! 147: convenience, but in fact <B>pcre</B> is just a typedef for <B>void</B>, since the
! 148: contents of the block are not externally defined. It is up to the caller to
! 149: free the memory when it is no longer required.
! 150: </P>
! 151: <P>
! 152: The size of a compiled pattern is roughly proportional to the length of the
! 153: pattern string, except that each character class (other than those containing
! 154: just a single character, negated or not) requires 33 bytes, and repeat
! 155: quantifiers with a minimum greater than one or a bounded maximum cause the
! 156: relevant portions of the compiled pattern to be replicated.
! 157: </P>
! 158: <P>
! 159: The <I>options</I> argument contains independent bits that affect the
! 160: compilation. It should be zero if no options are required. Some of the options,
! 161: in particular, those that are compatible with Perl, can also be set and unset
! 162: from within the pattern (see the detailed description of regular expressions
! 163: below). For these options, the contents of the <I>options</I> argument specifies
! 164: their initial settings at the start of compilation and execution. The
! 165: PCRE_ANCHORED option can be set at the time of matching as well as at compile
! 166: time.
! 167: </P>
! 168: <P>
! 169: If <I>errptr</I> is NULL, <B>pcre_compile()</B> returns NULL immediately.
! 170: Otherwise, if compilation of a pattern fails, <B>pcre_compile()</B> returns
! 171: NULL, and sets the variable pointed to by <I>errptr</I> to point to a textual
! 172: error message. The offset from the start of the pattern to the character where
! 173: the error was discovered is placed in the variable pointed to by
! 174: <I>erroffset</I>, which must not be NULL. If it is, an immediate error is given.
! 175: </P>
! 176: <P>
! 177: If the final argument, <I>tableptr</I>, is NULL, PCRE uses a default set of
! 178: character tables which are built when it is compiled, using the default C
! 179: locale. Otherwise, <I>tableptr</I> must be the result of a call to
! 180: <B>pcre_maketables()</B>. See the section on locale support below.
! 181: </P>
! 182: <P>
! 183: The following option bits are defined in the header file:
! 184: </P>
! 185: <P>
! 186: <PRE>
! 187: PCRE_ANCHORED
! 188: </PRE>
! 189: </P>
! 190: <P>
! 191: If this bit is set, the pattern is forced to be "anchored", that is, it is
! 192: constrained to match only at the start of the string which is being searched
! 193: (the "subject string"). This effect can also be achieved by appropriate
! 194: constructs in the pattern itself, which is the only way to do it in Perl.
! 195: </P>
! 196: <P>
! 197: <PRE>
! 198: PCRE_CASELESS
! 199: </PRE>
! 200: </P>
! 201: <P>
! 202: If this bit is set, letters in the pattern match both upper and lower case
! 203: letters. It is equivalent to Perl's /i option.
! 204: </P>
! 205: <P>
! 206: <PRE>
! 207: PCRE_DOLLAR_ENDONLY
! 208: </PRE>
! 209: </P>
! 210: <P>
! 211: If this bit is set, a dollar metacharacter in the pattern matches only at the
! 212: end of the subject string. Without this option, a dollar also matches
! 213: immediately before the final character if it is a newline (but not before any
! 214: other newlines). The PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE is
! 215: set. There is no equivalent to this option in Perl.
! 216: </P>
! 217: <P>
! 218: <PRE>
! 219: PCRE_DOTALL
! 220: </PRE>
! 221: </P>
! 222: <P>
! 223: If this bit is set, a dot metacharater in the pattern matches all characters,
! 224: including newlines. Without it, newlines are excluded. This option is
! 225: equivalent to Perl's /s option. A negative class such as [^a] always matches a
! 226: newline character, independent of the setting of this option.
! 227: </P>
! 228: <P>
! 229: <PRE>
! 230: PCRE_EXTENDED
! 231: </PRE>
! 232: </P>
! 233: <P>
! 234: If this bit is set, whitespace data characters in the pattern are totally
! 235: ignored except when escaped or inside a character class, and characters between
! 236: an unescaped # outside a character class and the next newline character,
! 237: inclusive, are also ignored. This is equivalent to Perl's /x option, and makes
! 238: it possible to include comments inside complicated patterns. Note, however,
! 239: that this applies only to data characters. Whitespace characters may never
! 240: appear within special character sequences in a pattern, for example within the
! 241: sequence (?( which introduces a conditional subpattern.
! 242: </P>
! 243: <P>
! 244: <PRE>
! 245: PCRE_EXTRA
! 246: </PRE>
! 247: </P>
! 248: <P>
! 249: This option turns on additional functionality of PCRE that is incompatible with
! 250: Perl. Any backslash in a pattern that is followed by a letter that has no
! 251: special meaning causes an error, thus reserving these combinations for future
! 252: expansion. By default, as in Perl, a backslash followed by a letter with no
! 253: special meaning is treated as a literal. There are at present no other features
! 254: controlled by this option.
! 255: </P>
! 256: <P>
! 257: <PRE>
! 258: PCRE_MULTILINE
! 259: </PRE>
! 260: </P>
! 261: <P>
! 262: By default, PCRE treats the subject string as consisting of a single "line" of
! 263: characters (even if it actually contains several newlines). The "start of line"
! 264: metacharacter (^) matches only at the start of the string, while the "end of
! 265: line" metacharacter ($) matches only at the end of the string, or before a
! 266: terminating newline (unless PCRE_DOLLAR_ENDONLY is set). This is the same as
! 267: Perl.
! 268: </P>
! 269: <P>
! 270: When PCRE_MULTILINE it is set, the "start of line" and "end of line" constructs
! 271: match immediately following or immediately before any newline in the subject
! 272: string, respectively, as well as at the very start and end. This is equivalent
! 273: to Perl's /m option. If there are no "\n" characters in a subject string, or
! 274: no occurrences of ^ or $ in a pattern, setting PCRE_MULTILINE has no
! 275: effect.
! 276: </P>
! 277: <P>
! 278: <PRE>
! 279: PCRE_UNGREEDY
! 280: </PRE>
! 281: </P>
! 282: <P>
! 283: This option inverts the "greediness" of the quantifiers so that they are not
! 284: greedy by default, but become greedy if followed by "?". It is not compatible
! 285: with Perl. It can also be set by a (?U) option setting within the pattern.
! 286: </P>
! 287: <LI><A NAME="SEC6" HREF="#TOC1">STUDYING A PATTERN</A>
! 288: <P>
! 289: When a pattern is going to be used several times, it is worth spending more
! 290: time analyzing it in order to speed up the time taken for matching. The
! 291: function <B>pcre_study()</B> takes a pointer to a compiled pattern as its first
! 292: argument, and returns a pointer to a <B>pcre_extra</B> block (another <B>void</B>
! 293: typedef) containing additional information about the pattern; this can be
! 294: passed to <B>pcre_exec()</B>. If no additional information is available, NULL
! 295: is returned.
! 296: </P>
! 297: <P>
! 298: The second argument contains option bits. At present, no options are defined
! 299: for <B>pcre_study()</B>, and this argument should always be zero.
! 300: </P>
! 301: <P>
! 302: The third argument for <B>pcre_study()</B> is a pointer to an error message. If
! 303: studying succeeds (even if no data is returned), the variable it points to is
! 304: set to NULL. Otherwise it points to a textual error message.
! 305: </P>
! 306: <P>
! 307: At present, studying a pattern is useful only for non-anchored patterns that do
! 308: not have a single fixed starting character. A bitmap of possible starting
! 309: characters is created.
! 310: </P>
! 311: <LI><A NAME="SEC7" HREF="#TOC1">LOCALE SUPPORT</A>
! 312: <P>
! 313: PCRE handles caseless matching, and determines whether characters are letters,
! 314: digits, or whatever, by reference to a set of tables. The library contains a
! 315: default set of tables which is created in the default C locale when PCRE is
! 316: compiled. This is used when the final argument of <B>pcre_compile()</B> is NULL,
! 317: and is sufficient for many applications.
! 318: </P>
! 319: <P>
! 320: An alternative set of tables can, however, be supplied. Such tables are built
! 321: by calling the <B>pcre_maketables()</B> function, which has no arguments, in the
! 322: relevant locale. The result can then be passed to <B>pcre_compile()</B> as often
! 323: as necessary. For example, to build and use tables that are appropriate for the
! 324: French locale (where accented characters with codes greater than 128 are
! 325: treated as letters), the following code could be used:
! 326: </P>
! 327: <P>
! 328: <PRE>
! 329: setlocale(LC_CTYPE, "fr");
! 330: tables = pcre_maketables();
! 331: re = pcre_compile(..., tables);
! 332: </PRE>
! 333: </P>
! 334: <P>
! 335: The tables are built in memory that is obtained via <B>pcre_malloc</B>. The
! 336: pointer that is passed to <B>pcre_compile</B> is saved with the compiled
! 337: pattern, and the same tables are used via this pointer by <B>pcre_study()</B>
! 338: and <B>pcre_exec()</B>. Thus for any single pattern, compilation, studying and
! 339: matching all happen in the same locale, but different patterns can be compiled
! 340: in different locales. It is the caller's responsibility to ensure that the
! 341: memory containing the tables remains available for as long as it is needed.
! 342: </P>
! 343: <LI><A NAME="SEC8" HREF="#TOC1">INFORMATION ABOUT A PATTERN</A>
! 344: <P>
! 345: The <B>pcre_info()</B> function returns information about a compiled pattern.
! 346: Its yield is the number of capturing subpatterns, or one of the following
! 347: negative numbers:
! 348: </P>
! 349: <P>
! 350: <PRE>
! 351: PCRE_ERROR_NULL the argument <I>code</I> was NULL
! 352: PCRE_ERROR_BADMAGIC the "magic number" was not found
! 353: </PRE>
! 354: </P>
! 355: <P>
! 356: If the <I>optptr</I> argument is not NULL, a copy of the options with which the
! 357: pattern was compiled is placed in the integer it points to. These option bits
! 358: are those specified in the call to <B>pcre_compile()</B>, modified by any
! 359: top-level option settings within the pattern itself, and with the PCRE_ANCHORED
! 360: bit set if the form of the pattern implies that it can match only at the start
! 361: of a subject string.
! 362: </P>
! 363: <P>
! 364: If the pattern is not anchored and the <I>firstcharptr</I> argument is not NULL,
! 365: it is used to pass back information about the first character of any matched
! 366: string. If there is a fixed first character, e.g. from a pattern such as
! 367: (cat|cow|coyote), then it is returned in the integer pointed to by
! 368: <I>firstcharptr</I>. Otherwise, if either
! 369: </P>
! 370: <P>
! 371: (a) the pattern was compiled with the PCRE_MULTILINE option, and every branch
! 372: starts with "^", or
! 373: </P>
! 374: <P>
! 375: (b) every branch of the pattern starts with ".*" and PCRE_DOTALL is not set
! 376: (if it were set, the pattern would be anchored),
! 377: </P>
! 378: <P>
! 379: then -1 is returned, indicating that the pattern matches only at the
! 380: start of a subject string or after any "\n" within the string. Otherwise -2 is
! 381: returned.
! 382: </P>
! 383: <LI><A NAME="SEC9" HREF="#TOC1">MATCHING A PATTERN</A>
! 384: <P>
! 385: The function <B>pcre_exec()</B> is called to match a subject string against a
! 386: pre-compiled pattern, which is passed in the <I>code</I> argument. If the
! 387: pattern has been studied, the result of the study should be passed in the
! 388: <I>extra</I> argument. Otherwise this must be NULL.
! 389: </P>
! 390: <P>
! 391: The PCRE_ANCHORED option can be passed in the <I>options</I> argument, whose
! 392: unused bits must be zero. However, if a pattern was compiled with
! 393: PCRE_ANCHORED, or turned out to be anchored by virtue of its contents, it
! 394: cannot be made unachored at matching time.
! 395: </P>
! 396: <P>
! 397: There are also three further options that can be set only at matching time:
! 398: </P>
! 399: <P>
! 400: <PRE>
! 401: PCRE_NOTBOL
! 402: </PRE>
! 403: </P>
! 404: <P>
! 405: The first character of the string is not the beginning of a line, so the
! 406: circumflex metacharacter should not match before it. Setting this without
! 407: PCRE_MULTILINE (at compile time) causes circumflex never to match.
! 408: </P>
! 409: <P>
! 410: <PRE>
! 411: PCRE_NOTEOL
! 412: </PRE>
! 413: </P>
! 414: <P>
! 415: The end of the string is not the end of a line, so the dollar metacharacter
! 416: should not match it nor (except in multiline mode) a newline immediately before
! 417: it. Setting this without PCRE_MULTILINE (at compile time) causes dollar never
! 418: to match.
! 419: </P>
! 420: <P>
! 421: <PRE>
! 422: PCRE_NOTEMPTY
! 423: </PRE>
! 424: </P>
! 425: <P>
! 426: An empty string is not considered to be a valid match if this option is set. If
! 427: there are alternatives in the pattern, they are tried. If all the alternatives
! 428: match the empty string, the entire match fails. For example, if the pattern
! 429: </P>
! 430: <P>
! 431: <PRE>
! 432: a?b?
! 433: </PRE>
! 434: </P>
! 435: <P>
! 436: is applied to a string not beginning with "a" or "b", it matches the empty
! 437: string at the start of the subject. With PCRE_NOTEMPTY set, this match is not
! 438: valid, so PCRE searches further into the string for occurrences of "a" or "b".
! 439: Perl has no direct equivalent of this option, but it makes a special case of
! 440: a pattern match of the empty string within its <B>split()</B> function, or when
! 441: using the /g modifier. Using PCRE_NOTEMPTY it is possible to emulate this
! 442: behaviour.
! 443: </P>
! 444: <P>
! 445: The subject string is passed as a pointer in <I>subject</I>, a length in
! 446: <I>length</I>, and a starting offset in <I>startoffset</I>. Unlike the pattern
! 447: string, it may contain binary zero characters. When the starting offset is
! 448: zero, the search for a match starts at the beginning of the subject, and this
! 449: is by far the most common case.
! 450: </P>
! 451: <P>
! 452: A non-zero starting offset is useful when searching for another match in the
! 453: same subject by calling <B>pcre_exec()</B> again after a previous success.
! 454: Setting <I>startoffset</I> differs from just passing over a shortened string and
! 455: setting PCRE_NOTBOL in the case of a pattern that begins with any kind of
! 456: lookbehind. For example, consider the pattern
! 457: </P>
! 458: <P>
! 459: <PRE>
! 460: \Biss\B
! 461: </PRE>
! 462: </P>
! 463: <P>
! 464: which finds occurrences of "iss" in the middle of words. (\B matches only if
! 465: the current position in the subject is not a word boundary.) When applied to
! 466: the string "Mississipi" the first call to <B>pcre_exec()</B> finds the first
! 467: occurrence. If <B>pcre_exec()</B> is called again with just the remainder of the
! 468: subject, namely "issipi", it does not match, because \B is always false at the
! 469: start of the subject, which is deemed to be a word boundary. However, if
! 470: <B>pcre_exec()</B> is passed the entire string again, but with <I>startoffset</I>
! 471: set to 4, it finds the second occurrence of "iss" because it is able to look
! 472: behind the starting point to discover that it is preceded by a letter.
! 473: </P>
! 474: <P>
! 475: If a non-zero starting offset is passed when the pattern is anchored, one
! 476: attempt to match at the given offset is tried. This can only succeed if the
! 477: pattern does not require the match to be at the start of the subject.
! 478: </P>
! 479: <P>
! 480: In general, a pattern matches a certain portion of the subject, and in
! 481: addition, further substrings from the subject may be picked out by parts of the
! 482: pattern. Following the usage in Jeffrey Friedl's book, this is called
! 483: "capturing" in what follows, and the phrase "capturing subpattern" is used for
! 484: a fragment of a pattern that picks out a substring. PCRE supports several other
! 485: kinds of parenthesized subpattern that do not cause substrings to be captured.
! 486: </P>
! 487: <P>
! 488: Captured substrings are returned to the caller via a vector of integer offsets
! 489: whose address is passed in <I>ovector</I>. The number of elements in the vector
! 490: is passed in <I>ovecsize</I>. The first two-thirds of the vector is used to pass
! 491: back captured substrings, each substring using a pair of integers. The
! 492: remaining third of the vector is used as workspace by <B>pcre_exec()</B> while
! 493: matching capturing subpatterns, and is not available for passing back
! 494: information. The length passed in <I>ovecsize</I> should always be a multiple of
! 495: three. If it is not, it is rounded down.
! 496: </P>
! 497: <P>
! 498: When a match has been successful, information about captured substrings is
! 499: returned in pairs of integers, starting at the beginning of <I>ovector</I>, and
! 500: continuing up to two-thirds of its length at the most. The first element of a
! 501: pair is set to the offset of the first character in a substring, and the second
! 502: is set to the offset of the first character after the end of a substring. The
! 503: first pair, <I>ovector[0]</I> and <I>ovector[1]</I>, identify the portion of the
! 504: subject string matched by the entire pattern. The next pair is used for the
! 505: first capturing subpattern, and so on. The value returned by <B>pcre_exec()</B>
! 506: is the number of pairs that have been set. If there are no capturing
! 507: subpatterns, the return value from a successful match is 1, indicating that
! 508: just the first pair of offsets has been set.
! 509: </P>
! 510: <P>
! 511: Some convenience functions are provided for extracting the captured substrings
! 512: as separate strings. These are described in the following section.
! 513: </P>
! 514: <P>
! 515: It is possible for an capturing subpattern number <I>n+1</I> to match some
! 516: part of the subject when subpattern <I>n</I> has not been used at all. For
! 517: example, if the string "abc" is matched against the pattern (a|(z))(bc)
! 518: subpatterns 1 and 3 are matched, but 2 is not. When this happens, both offset
! 519: values corresponding to the unused subpattern are set to -1.
! 520: </P>
! 521: <P>
! 522: If a capturing subpattern is matched repeatedly, it is the last portion of the
! 523: string that it matched that gets returned.
! 524: </P>
! 525: <P>
! 526: If the vector is too small to hold all the captured substrings, it is used as
! 527: far as possible (up to two-thirds of its length), and the function returns a
! 528: value of zero. In particular, if the substring offsets are not of interest,
! 529: <B>pcre_exec()</B> may be called with <I>ovector</I> passed as NULL and
! 530: <I>ovecsize</I> as zero. However, if the pattern contains back references and
! 531: the <I>ovector</I> isn't big enough to remember the related substrings, PCRE has
! 532: to get additional memory for use during matching. Thus it is usually advisable
! 533: to supply an <I>ovector</I>.
! 534: </P>
! 535: <P>
! 536: Note that <B>pcre_info()</B> can be used to find out how many capturing
! 537: subpatterns there are in a compiled pattern. The smallest size for
! 538: <I>ovector</I> that will allow for <I>n</I> captured substrings in addition to
! 539: the offsets of the substring matched by the whole pattern is (<I>n</I>+1)*3.
! 540: </P>
! 541: <P>
! 542: If <B>pcre_exec()</B> fails, it returns a negative number. The following are
! 543: defined in the header file:
! 544: </P>
! 545: <P>
! 546: <PRE>
! 547: PCRE_ERROR_NOMATCH (-1)
! 548: </PRE>
! 549: </P>
! 550: <P>
! 551: The subject string did not match the pattern.
! 552: </P>
! 553: <P>
! 554: <PRE>
! 555: PCRE_ERROR_NULL (-2)
! 556: </PRE>
! 557: </P>
! 558: <P>
! 559: Either <I>code</I> or <I>subject</I> was passed as NULL, or <I>ovector</I> was
! 560: NULL and <I>ovecsize</I> was not zero.
! 561: </P>
! 562: <P>
! 563: <PRE>
! 564: PCRE_ERROR_BADOPTION (-3)
! 565: </PRE>
! 566: </P>
! 567: <P>
! 568: An unrecognized bit was set in the <I>options</I> argument.
! 569: </P>
! 570: <P>
! 571: <PRE>
! 572: PCRE_ERROR_BADMAGIC (-4)
! 573: </PRE>
! 574: </P>
! 575: <P>
! 576: PCRE stores a 4-byte "magic number" at the start of the compiled code, to catch
! 577: the case when it is passed a junk pointer. This is the error it gives when the
! 578: magic number isn't present.
! 579: </P>
! 580: <P>
! 581: <PRE>
! 582: PCRE_ERROR_UNKNOWN_NODE (-5)
! 583: </PRE>
! 584: </P>
! 585: <P>
! 586: While running the pattern match, an unknown item was encountered in the
! 587: compiled pattern. This error could be caused by a bug in PCRE or by overwriting
! 588: of the compiled pattern.
! 589: </P>
! 590: <P>
! 591: <PRE>
! 592: PCRE_ERROR_NOMEMORY (-6)
! 593: </PRE>
! 594: </P>
! 595: <P>
! 596: If a pattern contains back references, but the <I>ovector</I> that is passed to
! 597: <B>pcre_exec()</B> is not big enough to remember the referenced substrings, PCRE
! 598: gets a block of memory at the start of matching to use for this purpose. If the
! 599: call via <B>pcre_malloc()</B> fails, this error is given. The memory is freed at
! 600: the end of matching.
! 601: </P>
! 602: <LI><A NAME="SEC10" HREF="#TOC1">EXTRACTING CAPTURED SUBSTRINGS</A>
! 603: <P>
! 604: Captured substrings can be accessed directly by using the offsets returned by
! 605: <B>pcre_exec()</B> in <I>ovector</I>. For convenience, the functions
! 606: <B>pcre_copy_substring()</B>, <B>pcre_get_substring()</B>, and
! 607: <B>pcre_get_substring_list()</B> are provided for extracting captured substrings
! 608: as new, separate, zero-terminated strings. A substring that contains a binary
! 609: zero is correctly extracted and has a further zero added on the end, but the
! 610: result does not, of course, function as a C string.
! 611: </P>
! 612: <P>
! 613: The first three arguments are the same for all three functions: <I>subject</I>
! 614: is the subject string which has just been successfully matched, <I>ovector</I>
! 615: is a pointer to the vector of integer offsets that was passed to
! 616: <B>pcre_exec()</B>, and <I>stringcount</I> is the number of substrings that
! 617: were captured by the match, including the substring that matched the entire
! 618: regular expression. This is the value returned by <B>pcre_exec</B> if it
! 619: is greater than zero. If <B>pcre_exec()</B> returned zero, indicating that it
! 620: ran out of space in <I>ovector</I>, then the value passed as
! 621: <I>stringcount</I> should be the size of the vector divided by three.
! 622: </P>
! 623: <P>
! 624: The functions <B>pcre_copy_substring()</B> and <B>pcre_get_substring()</B>
! 625: extract a single substring, whose number is given as <I>stringnumber</I>. A
! 626: value of zero extracts the substring that matched the entire pattern, while
! 627: higher values extract the captured substrings. For <B>pcre_copy_substring()</B>,
! 628: the string is placed in <I>buffer</I>, whose length is given by
! 629: <I>buffersize</I>, while for <B>pcre_get_substring()</B> a new block of store is
! 630: obtained via <B>pcre_malloc</B>, and its address is returned via
! 631: <I>stringptr</I>. The yield of the function is the length of the string, not
! 632: including the terminating zero, or one of
! 633: </P>
! 634: <P>
! 635: <PRE>
! 636: PCRE_ERROR_NOMEMORY (-6)
! 637: </PRE>
! 638: </P>
! 639: <P>
! 640: The buffer was too small for <B>pcre_copy_substring()</B>, or the attempt to get
! 641: memory failed for <B>pcre_get_substring()</B>.
! 642: </P>
! 643: <P>
! 644: <PRE>
! 645: PCRE_ERROR_NOSUBSTRING (-7)
! 646: </PRE>
! 647: </P>
! 648: <P>
! 649: There is no substring whose number is <I>stringnumber</I>.
! 650: </P>
! 651: <P>
! 652: The <B>pcre_get_substring_list()</B> function extracts all available substrings
! 653: and builds a list of pointers to them. All this is done in a single block of
! 654: memory which is obtained via <B>pcre_malloc</B>. The address of the memory block
! 655: is returned via <I>listptr</I>, which is also the start of the list of string
! 656: pointers. The end of the list is marked by a NULL pointer. The yield of the
! 657: function is zero if all went well, or
! 658: </P>
! 659: <P>
! 660: <PRE>
! 661: PCRE_ERROR_NOMEMORY (-6)
! 662: </PRE>
! 663: </P>
! 664: <P>
! 665: if the attempt to get the memory block failed.
! 666: </P>
! 667: <P>
! 668: When any of these functions encounter a substring that is unset, which can
! 669: happen when capturing subpattern number <I>n+1</I> matches some part of the
! 670: subject, but subpattern <I>n</I> has not been used at all, they return an empty
! 671: string. This can be distinguished from a genuine zero-length substring by
! 672: inspecting the appropriate offset in <I>ovector</I>, which is negative for unset
! 673: substrings.
! 674: </P>
! 675: <LI><A NAME="SEC11" HREF="#TOC1">LIMITATIONS</A>
! 676: <P>
! 677: There are some size limitations in PCRE but it is hoped that they will never in
! 678: practice be relevant.
! 679: The maximum length of a compiled pattern is 65539 (sic) bytes.
! 680: All values in repeating quantifiers must be less than 65536.
! 681: The maximum number of capturing subpatterns is 99.
! 682: The maximum number of all parenthesized subpatterns, including capturing
! 683: subpatterns, assertions, and other types of subpattern, is 200.
! 684: </P>
! 685: <P>
! 686: The maximum length of a subject string is the largest positive number that an
! 687: integer variable can hold. However, PCRE uses recursion to handle subpatterns
! 688: and indefinite repetition. This means that the available stack space may limit
! 689: the size of a subject string that can be processed by certain patterns.
! 690: </P>
! 691: <LI><A NAME="SEC12" HREF="#TOC1">DIFFERENCES FROM PERL</A>
! 692: <P>
! 693: The differences described here are with respect to Perl 5.005.
! 694: </P>
! 695: <P>
! 696: 1. By default, a whitespace character is any character that the C library
! 697: function <B>isspace()</B> recognizes, though it is possible to compile PCRE with
! 698: alternative character type tables. Normally <B>isspace()</B> matches space,
! 699: formfeed, newline, carriage return, horizontal tab, and vertical tab. Perl 5
! 700: no longer includes vertical tab in its set of whitespace characters. The \v
! 701: escape that was in the Perl documentation for a long time was never in fact
! 702: recognized. However, the character itself was treated as whitespace at least
! 703: up to 5.002. In 5.004 and 5.005 it does not match \s.
! 704: </P>
! 705: <P>
! 706: 2. PCRE does not allow repeat quantifiers on lookahead assertions. Perl permits
! 707: them, but they do not mean what you might think. For example, (?!a){3} does
! 708: not assert that the next three characters are not "a". It just asserts that the
! 709: next character is not "a" three times.
! 710: </P>
! 711: <P>
! 712: 3. Capturing subpatterns that occur inside negative lookahead assertions are
! 713: counted, but their entries in the offsets vector are never set. Perl sets its
! 714: numerical variables from any such patterns that are matched before the
! 715: assertion fails to match something (thereby succeeding), but only if the
! 716: negative lookahead assertion contains just one branch.
! 717: </P>
! 718: <P>
! 719: 4. Though binary zero characters are supported in the subject string, they are
! 720: not allowed in a pattern string because it is passed as a normal C string,
! 721: terminated by zero. The escape sequence "\0" can be used in the pattern to
! 722: represent a binary zero.
! 723: </P>
! 724: <P>
! 725: 5. The following Perl escape sequences are not supported: \l, \u, \L, \U,
! 726: \E, \Q. In fact these are implemented by Perl's general string-handling and
! 727: are not part of its pattern matching engine.
! 728: </P>
! 729: <P>
! 730: 6. The Perl \G assertion is not supported as it is not relevant to single
! 731: pattern matches.
! 732: </P>
! 733: <P>
! 734: 7. Fairly obviously, PCRE does not support the (?{code}) construction.
! 735: </P>
! 736: <P>
! 737: 8. There are at the time of writing some oddities in Perl 5.005_02 concerned
! 738: with the settings of captured strings when part of a pattern is repeated. For
! 739: example, matching "aba" against the pattern /^(a(b)?)+$/ sets $2 to the value
! 740: "b", but matching "aabbaa" against /^(aa(bb)?)+$/ leaves $2 unset. However, if
! 741: the pattern is changed to /^(aa(b(b))?)+$/ then $2 (and $3) get set.
! 742: </P>
! 743: <P>
! 744: In Perl 5.004 $2 is set in both cases, and that is also true of PCRE. If in the
! 745: future Perl changes to a consistent state that is different, PCRE may change to
! 746: follow.
! 747: </P>
! 748: <P>
! 749: 9. Another as yet unresolved discrepancy is that in Perl 5.005_02 the pattern
! 750: /^(a)?(?(1)a|b)+$/ matches the string "a", whereas in PCRE it does not.
! 751: However, in both Perl and PCRE /^(a)?a/ matched against "a" leaves $1 unset.
! 752: </P>
! 753: <P>
! 754: 10. PCRE provides some extensions to the Perl regular expression facilities:
! 755: </P>
! 756: <P>
! 757: (a) Although lookbehind assertions must match fixed length strings, each
! 758: alternative branch of a lookbehind assertion can match a different length of
! 759: string. Perl 5.005 requires them all to have the same length.
! 760: </P>
! 761: <P>
! 762: (b) If PCRE_DOLLAR_ENDONLY is set and PCRE_MULTILINE is not set, the $ meta-
! 763: character matches only at the very end of the string.
! 764: </P>
! 765: <P>
! 766: (c) If PCRE_EXTRA is set, a backslash followed by a letter with no special
! 767: meaning is faulted.
! 768: </P>
! 769: <P>
! 770: (d) If PCRE_UNGREEDY is set, the greediness of the repetition quantifiers is
! 771: inverted, that is, by default they are not greedy, but if followed by a
! 772: question mark they are.
! 773: </P>
! 774: <P>
! 775: (e) PCRE_ANCHORED can be used to force a pattern to be tried only at the start
! 776: of the subject.
! 777: </P>
! 778: <P>
! 779: (f) The PCRE_NOTBOL, PCRE_NOTEOL, and PCRE_NOTEMPTY options for
! 780: <B>pcre_exec()</B> have no Perl equivalents.
! 781: </P>
! 782: <LI><A NAME="SEC13" HREF="#TOC1">REGULAR EXPRESSION DETAILS</A>
! 783: <P>
! 784: The syntax and semantics of the regular expressions supported by PCRE are
! 785: described below. Regular expressions are also described in the Perl
! 786: documentation and in a number of other books, some of which have copious
! 787: examples. Jeffrey Friedl's "Mastering Regular Expressions", published by
! 788: O'Reilly (ISBN 1-56592-257-3), covers them in great detail. The description
! 789: here is intended as reference documentation.
! 790: </P>
! 791: <P>
! 792: A regular expression is a pattern that is matched against a subject string from
! 793: left to right. Most characters stand for themselves in a pattern, and match the
! 794: corresponding characters in the subject. As a trivial example, the pattern
! 795: </P>
! 796: <P>
! 797: <PRE>
! 798: The quick brown fox
! 799: </PRE>
! 800: </P>
! 801: <P>
! 802: matches a portion of a subject string that is identical to itself. The power of
! 803: regular expressions comes from the ability to include alternatives and
! 804: repetitions in the pattern. These are encoded in the pattern by the use of
! 805: <I>meta-characters</I>, which do not stand for themselves but instead are
! 806: interpreted in some special way.
! 807: </P>
! 808: <P>
! 809: There are two different sets of meta-characters: those that are recognized
! 810: anywhere in the pattern except within square brackets, and those that are
! 811: recognized in square brackets. Outside square brackets, the meta-characters are
! 812: as follows:
! 813: </P>
! 814: <P>
! 815: <PRE>
! 816: \ general escape character with several uses
! 817: ^ assert start of subject (or line, in multiline mode)
! 818: $ assert end of subject (or line, in multiline mode)
! 819: . match any character except newline (by default)
! 820: [ start character class definition
! 821: | start of alternative branch
! 822: ( start subpattern
! 823: ) end subpattern
! 824: ? extends the meaning of (
! 825: also 0 or 1 quantifier
! 826: also quantifier minimizer
! 827: * 0 or more quantifier
! 828: + 1 or more quantifier
! 829: { start min/max quantifier
! 830: </PRE>
! 831: </P>
! 832: <P>
! 833: Part of a pattern that is in square brackets is called a "character class". In
! 834: a character class the only meta-characters are:
! 835: </P>
! 836: <P>
! 837: <PRE>
! 838: \ general escape character
! 839: ^ negate the class, but only if the first character
! 840: - indicates character range
! 841: ] terminates the character class
! 842: </PRE>
! 843: </P>
! 844: <P>
! 845: The following sections describe the use of each of the meta-characters.
! 846: </P>
! 847: <LI><A NAME="SEC14" HREF="#TOC1">BACKSLASH</A>
! 848: <P>
! 849: The backslash character has several uses. Firstly, if it is followed by a
! 850: non-alphameric character, it takes away any special meaning that character may
! 851: have. This use of backslash as an escape character applies both inside and
! 852: outside character classes.
! 853: </P>
! 854: <P>
! 855: For example, if you want to match a "*" character, you write "\*" in the
! 856: pattern. This applies whether or not the following character would otherwise be
! 857: interpreted as a meta-character, so it is always safe to precede a
! 858: non-alphameric with "\" to specify that it stands for itself. In particular,
! 859: if you want to match a backslash, you write "\\".
! 860: </P>
! 861: <P>
! 862: If a pattern is compiled with the PCRE_EXTENDED option, whitespace in the
! 863: pattern (other than in a character class) and characters between a "#" outside
! 864: a character class and the next newline character are ignored. An escaping
! 865: backslash can be used to include a whitespace or "#" character as part of the
! 866: pattern.
! 867: </P>
! 868: <P>
! 869: A second use of backslash provides a way of encoding non-printing characters
! 870: in patterns in a visible manner. There is no restriction on the appearance of
! 871: non-printing characters, apart from the binary zero that terminates a pattern,
! 872: but when a pattern is being prepared by text editing, it is usually easier to
! 873: use one of the following escape sequences than the binary character it
! 874: represents:
! 875: </P>
! 876: <P>
! 877: <PRE>
! 878: \a alarm, that is, the BEL character (hex 07)
! 879: \cx "control-x", where x is any character
! 880: \e escape (hex 1B)
! 881: \f formfeed (hex 0C)
! 882: \n newline (hex 0A)
! 883: \r carriage return (hex 0D)
! 884: \t tab (hex 09)
! 885: \xhh character with hex code hh
! 886: \ddd character with octal code ddd, or backreference
! 887: </PRE>
! 888: </P>
! 889: <P>
! 890: The precise effect of "\cx" is as follows: if "x" is a lower case letter, it
! 891: is converted to upper case. Then bit 6 of the character (hex 40) is inverted.
! 892: Thus "\cz" becomes hex 1A, but "\c{" becomes hex 3B, while "\c;" becomes hex
! 893: 7B.
! 894: </P>
! 895: <P>
! 896: After "\x", up to two hexadecimal digits are read (letters can be in upper or
! 897: lower case).
! 898: </P>
! 899: <P>
! 900: After "\0" up to two further octal digits are read. In both cases, if there
! 901: are fewer than two digits, just those that are present are used. Thus the
! 902: sequence "\0\x\07" specifies two binary zeros followed by a BEL character.
! 903: Make sure you supply two digits after the initial zero if the character that
! 904: follows is itself an octal digit.
! 905: </P>
! 906: <P>
! 907: The handling of a backslash followed by a digit other than 0 is complicated.
! 908: Outside a character class, PCRE reads it and any following digits as a decimal
! 909: number. If the number is less than 10, or if there have been at least that many
! 910: previous capturing left parentheses in the expression, the entire sequence is
! 911: taken as a <I>back reference</I>. A description of how this works is given
! 912: later, following the discussion of parenthesized subpatterns.
! 913: </P>
! 914: <P>
! 915: Inside a character class, or if the decimal number is greater than 9 and there
! 916: have not been that many capturing subpatterns, PCRE re-reads up to three octal
! 917: digits following the backslash, and generates a single byte from the least
! 918: significant 8 bits of the value. Any subsequent digits stand for themselves.
! 919: For example:
! 920: </P>
! 921: <P>
! 922: <PRE>
! 923: \040 is another way of writing a space
! 924: \40 is the same, provided there are fewer than 40
! 925: previous capturing subpatterns
! 926: \7 is always a back reference
! 927: \11 might be a back reference, or another way of
! 928: writing a tab
! 929: \011 is always a tab
! 930: \0113 is a tab followed by the character "3"
! 931: \113 is the character with octal code 113 (since there
! 932: can be no more than 99 back references)
! 933: \377 is a byte consisting entirely of 1 bits
! 934: \81 is either a back reference, or a binary zero
! 935: followed by the two characters "8" and "1"
! 936: </PRE>
! 937: </P>
! 938: <P>
! 939: Note that octal values of 100 or greater must not be introduced by a leading
! 940: zero, because no more than three octal digits are ever read.
! 941: </P>
! 942: <P>
! 943: All the sequences that define a single byte value can be used both inside and
! 944: outside character classes. In addition, inside a character class, the sequence
! 945: "\b" is interpreted as the backspace character (hex 08). Outside a character
! 946: class it has a different meaning (see below).
! 947: </P>
! 948: <P>
! 949: The third use of backslash is for specifying generic character types:
! 950: </P>
! 951: <P>
! 952: <PRE>
! 953: \d any decimal digit
! 954: \D any character that is not a decimal digit
! 955: \s any whitespace character
! 956: \S any character that is not a whitespace character
! 957: \w any "word" character
! 958: \W any "non-word" character
! 959: </PRE>
! 960: </P>
! 961: <P>
! 962: Each pair of escape sequences partitions the complete set of characters into
! 963: two disjoint sets. Any given character matches one, and only one, of each pair.
! 964: </P>
! 965: <P>
! 966: A "word" character is any letter or digit or the underscore character, that is,
! 967: any character which can be part of a Perl "word". The definition of letters and
! 968: digits is controlled by PCRE's character tables, and may vary if locale-
! 969: specific matching is taking place (see "Locale support" above). For example, in
! 970: the "fr" (French) locale, some character codes greater than 128 are used for
! 971: accented letters, and these are matched by \w.
! 972: </P>
! 973: <P>
! 974: These character type sequences can appear both inside and outside character
! 975: classes. They each match one character of the appropriate type. If the current
! 976: matching point is at the end of the subject string, all of them fail, since
! 977: there is no character to match.
! 978: </P>
! 979: <P>
! 980: The fourth use of backslash is for certain simple assertions. An assertion
! 981: specifies a condition that has to be met at a particular point in a match,
! 982: without consuming any characters from the subject string. The use of
! 983: subpatterns for more complicated assertions is described below. The backslashed
! 984: assertions are
! 985: </P>
! 986: <P>
! 987: <PRE>
! 988: \b word boundary
! 989: \B not a word boundary
! 990: \A start of subject (independent of multiline mode)
! 991: \Z end of subject or newline at end (independent of multiline mode)
! 992: \z end of subject (independent of multiline mode)
! 993: </PRE>
! 994: </P>
! 995: <P>
! 996: These assertions may not appear in character classes (but note that "\b" has a
! 997: different meaning, namely the backspace character, inside a character class).
! 998: </P>
! 999: <P>
! 1000: A word boundary is a position in the subject string where the current character
! 1001: and the previous character do not both match \w or \W (i.e. one matches
! 1002: \w and the other matches \W), or the start or end of the string if the
! 1003: first or last character matches \w, respectively.
! 1004: </P>
! 1005: <P>
! 1006: The \A, \Z, and \z assertions differ from the traditional circumflex and
! 1007: dollar (described below) in that they only ever match at the very start and end
! 1008: of the subject string, whatever options are set. They are not affected by the
! 1009: PCRE_NOTBOL or PCRE_NOTEOL options. If the <I>startoffset</I> argument of
! 1010: <B>pcre_exec()</B> is non-zero, \A can never match. The difference between \Z
! 1011: and \z is that \Z matches before a newline that is the last character of the
! 1012: string as well as at the end of the string, whereas \z matches only at the
! 1013: end.
! 1014: </P>
! 1015: <LI><A NAME="SEC15" HREF="#TOC1">CIRCUMFLEX AND DOLLAR</A>
! 1016: <P>
! 1017: Outside a character class, in the default matching mode, the circumflex
! 1018: character is an assertion which is true only if the current matching point is
! 1019: at the start of the subject string. If the <I>startoffset</I> argument of
! 1020: <B>pcre_exec()</B> is non-zero, circumflex can never match. Inside a character
! 1021: class, circumflex has an entirely different meaning (see below).
! 1022: </P>
! 1023: <P>
! 1024: Circumflex need not be the first character of the pattern if a number of
! 1025: alternatives are involved, but it should be the first thing in each alternative
! 1026: in which it appears if the pattern is ever to match that branch. If all
! 1027: possible alternatives start with a circumflex, that is, if the pattern is
! 1028: constrained to match only at the start of the subject, it is said to be an
! 1029: "anchored" pattern. (There are also other constructs that can cause a pattern
! 1030: to be anchored.)
! 1031: </P>
! 1032: <P>
! 1033: A dollar character is an assertion which is true only if the current matching
! 1034: point is at the end of the subject string, or immediately before a newline
! 1035: character that is the last character in the string (by default). Dollar need
! 1036: not be the last character of the pattern if a number of alternatives are
! 1037: involved, but it should be the last item in any branch in which it appears.
! 1038: Dollar has no special meaning in a character class.
! 1039: </P>
! 1040: <P>
! 1041: The meaning of dollar can be changed so that it matches only at the very end of
! 1042: the string, by setting the PCRE_DOLLAR_ENDONLY option at compile or matching
! 1043: time. This does not affect the \Z assertion.
! 1044: </P>
! 1045: <P>
! 1046: The meanings of the circumflex and dollar characters are changed if the
! 1047: PCRE_MULTILINE option is set. When this is the case, they match immediately
! 1048: after and immediately before an internal "\n" character, respectively, in
! 1049: addition to matching at the start and end of the subject string. For example,
! 1050: the pattern /^abc$/ matches the subject string "def\nabc" in multiline mode,
! 1051: but not otherwise. Consequently, patterns that are anchored in single line mode
! 1052: because all branches start with "^" are not anchored in multiline mode, and a
! 1053: match for circumflex is possible when the <I>startoffset</I> argument of
! 1054: <B>pcre_exec()</B> is non-zero. The PCRE_DOLLAR_ENDONLY option is ignored if
! 1055: PCRE_MULTILINE is set.
! 1056: </P>
! 1057: <P>
! 1058: Note that the sequences \A, \Z, and \z can be used to match the start and
! 1059: end of the subject in both modes, and if all branches of a pattern start with
! 1060: \A is it always anchored, whether PCRE_MULTILINE is set or not.
! 1061: </P>
! 1062: <LI><A NAME="SEC16" HREF="#TOC1">FULL STOP (PERIOD, DOT)</A>
! 1063: <P>
! 1064: Outside a character class, a dot in the pattern matches any one character in
! 1065: the subject, including a non-printing character, but not (by default) newline.
! 1066: If the PCRE_DOTALL option is set, then dots match newlines as well. The
! 1067: handling of dot is entirely independent of the handling of circumflex and
! 1068: dollar, the only relationship being that they both involve newline characters.
! 1069: Dot has no special meaning in a character class.
! 1070: </P>
! 1071: <LI><A NAME="SEC17" HREF="#TOC1">SQUARE BRACKETS</A>
! 1072: <P>
! 1073: An opening square bracket introduces a character class, terminated by a closing
! 1074: square bracket. A closing square bracket on its own is not special. If a
! 1075: closing square bracket is required as a member of the class, it should be the
! 1076: first data character in the class (after an initial circumflex, if present) or
! 1077: escaped with a backslash.
! 1078: </P>
! 1079: <P>
! 1080: A character class matches a single character in the subject; the character must
! 1081: be in the set of characters defined by the class, unless the first character in
! 1082: the class is a circumflex, in which case the subject character must not be in
! 1083: the set defined by the class. If a circumflex is actually required as a member
! 1084: of the class, ensure it is not the first character, or escape it with a
! 1085: backslash.
! 1086: </P>
! 1087: <P>
! 1088: For example, the character class [aeiou] matches any lower case vowel, while
! 1089: [^aeiou] matches any character that is not a lower case vowel. Note that a
! 1090: circumflex is just a convenient notation for specifying the characters which
! 1091: are in the class by enumerating those that are not. It is not an assertion: it
! 1092: still consumes a character from the subject string, and fails if the current
! 1093: pointer is at the end of the string.
! 1094: </P>
! 1095: <P>
! 1096: When caseless matching is set, any letters in a class represent both their
! 1097: upper case and lower case versions, so for example, a caseless [aeiou] matches
! 1098: "A" as well as "a", and a caseless [^aeiou] does not match "A", whereas a
! 1099: caseful version would.
! 1100: </P>
! 1101: <P>
! 1102: The newline character is never treated in any special way in character classes,
! 1103: whatever the setting of the PCRE_DOTALL or PCRE_MULTILINE options is. A class
! 1104: such as [^a] will always match a newline.
! 1105: </P>
! 1106: <P>
! 1107: The minus (hyphen) character can be used to specify a range of characters in a
! 1108: character class. For example, [d-m] matches any letter between d and m,
! 1109: inclusive. If a minus character is required in a class, it must be escaped with
! 1110: a backslash or appear in a position where it cannot be interpreted as
! 1111: indicating a range, typically as the first or last character in the class.
! 1112: </P>
! 1113: <P>
! 1114: It is not possible to have the literal character "]" as the end character of a
! 1115: range. A pattern such as [W-]46] is interpreted as a class of two characters
! 1116: ("W" and "-") followed by a literal string "46]", so it would match "W46]" or
! 1117: "-46]". However, if the "]" is escaped with a backslash it is interpreted as
! 1118: the end of range, so [W-\]46] is interpreted as a single class containing a
! 1119: range followed by two separate characters. The octal or hexadecimal
! 1120: representation of "]" can also be used to end a range.
! 1121: </P>
! 1122: <P>
! 1123: Ranges operate in ASCII collating sequence. They can also be used for
! 1124: characters specified numerically, for example [\000-\037]. If a range that
! 1125: includes letters is used when caseless matching is set, it matches the letters
! 1126: in either case. For example, [W-c] is equivalent to [][\^_`wxyzabc], matched
! 1127: caselessly, and if character tables for the "fr" locale are in use,
! 1128: [\xc8-\xcb] matches accented E characters in both cases.
! 1129: </P>
! 1130: <P>
! 1131: The character types \d, \D, \s, \S, \w, and \W may also appear in a
! 1132: character class, and add the characters that they match to the class. For
! 1133: example, [\dABCDEF] matches any hexadecimal digit. A circumflex can
! 1134: conveniently be used with the upper case character types to specify a more
! 1135: restricted set of characters than the matching lower case type. For example,
! 1136: the class [^\W_] matches any letter or digit, but not underscore.
! 1137: </P>
! 1138: <P>
! 1139: All non-alphameric characters other than \, -, ^ (at the start) and the
! 1140: terminating ] are non-special in character classes, but it does no harm if they
! 1141: are escaped.
! 1142: </P>
! 1143: <LI><A NAME="SEC18" HREF="#TOC1">VERTICAL BAR</A>
! 1144: <P>
! 1145: Vertical bar characters are used to separate alternative patterns. For example,
! 1146: the pattern
! 1147: </P>
! 1148: <P>
! 1149: <PRE>
! 1150: gilbert|sullivan
! 1151: </PRE>
! 1152: </P>
! 1153: <P>
! 1154: matches either "gilbert" or "sullivan". Any number of alternatives may appear,
! 1155: and an empty alternative is permitted (matching the empty string).
! 1156: The matching process tries each alternative in turn, from left to right,
! 1157: and the first one that succeeds is used. If the alternatives are within a
! 1158: subpattern (defined below), "succeeds" means matching the rest of the main
! 1159: pattern as well as the alternative in the subpattern.
! 1160: </P>
! 1161: <LI><A NAME="SEC19" HREF="#TOC1">INTERNAL OPTION SETTING</A>
! 1162: <P>
! 1163: The settings of PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, and PCRE_EXTENDED
! 1164: can be changed from within the pattern by a sequence of Perl option letters
! 1165: enclosed between "(?" and ")". The option letters are
! 1166: </P>
! 1167: <P>
! 1168: <PRE>
! 1169: i for PCRE_CASELESS
! 1170: m for PCRE_MULTILINE
! 1171: s for PCRE_DOTALL
! 1172: x for PCRE_EXTENDED
! 1173: </PRE>
! 1174: </P>
! 1175: <P>
! 1176: For example, (?im) sets caseless, multiline matching. It is also possible to
! 1177: unset these options by preceding the letter with a hyphen, and a combined
! 1178: setting and unsetting such as (?im-sx), which sets PCRE_CASELESS and
! 1179: PCRE_MULTILINE while unsetting PCRE_DOTALL and PCRE_EXTENDED, is also
! 1180: permitted. If a letter appears both before and after the hyphen, the option is
! 1181: unset.
! 1182: </P>
! 1183: <P>
! 1184: The scope of these option changes depends on where in the pattern the setting
! 1185: occurs. For settings that are outside any subpattern (defined below), the
! 1186: effect is the same as if the options were set or unset at the start of
! 1187: matching. The following patterns all behave in exactly the same way:
! 1188: </P>
! 1189: <P>
! 1190: <PRE>
! 1191: (?i)abc
! 1192: a(?i)bc
! 1193: ab(?i)c
! 1194: abc(?i)
! 1195: </PRE>
! 1196: </P>
! 1197: <P>
! 1198: which in turn is the same as compiling the pattern abc with PCRE_CASELESS set.
! 1199: In other words, such "top level" settings apply to the whole pattern (unless
! 1200: there are other changes inside subpatterns). If there is more than one setting
! 1201: of the same option at top level, the rightmost setting is used.
! 1202: </P>
! 1203: <P>
! 1204: If an option change occurs inside a subpattern, the effect is different. This
! 1205: is a change of behaviour in Perl 5.005. An option change inside a subpattern
! 1206: affects only that part of the subpattern that follows it, so
! 1207: </P>
! 1208: <P>
! 1209: <PRE>
! 1210: (a(?i)b)c
! 1211: </PRE>
! 1212: </P>
! 1213: <P>
! 1214: matches abc and aBc and no other strings (assuming PCRE_CASELESS is not used).
! 1215: By this means, options can be made to have different settings in different
! 1216: parts of the pattern. Any changes made in one alternative do carry on
! 1217: into subsequent branches within the same subpattern. For example,
! 1218: </P>
! 1219: <P>
! 1220: <PRE>
! 1221: (a(?i)b|c)
! 1222: </PRE>
! 1223: </P>
! 1224: <P>
! 1225: matches "ab", "aB", "c", and "C", even though when matching "C" the first
! 1226: branch is abandoned before the option setting. This is because the effects of
! 1227: option settings happen at compile time. There would be some very weird
! 1228: behaviour otherwise.
! 1229: </P>
! 1230: <P>
! 1231: The PCRE-specific options PCRE_UNGREEDY and PCRE_EXTRA can be changed in the
! 1232: same way as the Perl-compatible options by using the characters U and X
! 1233: respectively. The (?X) flag setting is special in that it must always occur
! 1234: earlier in the pattern than any of the additional features it turns on, even
! 1235: when it is at top level. It is best put at the start.
! 1236: </P>
! 1237: <LI><A NAME="SEC20" HREF="#TOC1">SUBPATTERNS</A>
! 1238: <P>
! 1239: Subpatterns are delimited by parentheses (round brackets), which can be nested.
! 1240: Marking part of a pattern as a subpattern does two things:
! 1241: </P>
! 1242: <P>
! 1243: 1. It localizes a set of alternatives. For example, the pattern
! 1244: </P>
! 1245: <P>
! 1246: <PRE>
! 1247: cat(aract|erpillar|)
! 1248: </PRE>
! 1249: </P>
! 1250: <P>
! 1251: matches one of the words "cat", "cataract", or "caterpillar". Without the
! 1252: parentheses, it would match "cataract", "erpillar" or the empty string.
! 1253: </P>
! 1254: <P>
! 1255: 2. It sets up the subpattern as a capturing subpattern (as defined above).
! 1256: When the whole pattern matches, that portion of the subject string that matched
! 1257: the subpattern is passed back to the caller via the <I>ovector</I> argument of
! 1258: <B>pcre_exec()</B>. Opening parentheses are counted from left to right (starting
! 1259: from 1) to obtain the numbers of the capturing subpatterns.
! 1260: </P>
! 1261: <P>
! 1262: For example, if the string "the red king" is matched against the pattern
! 1263: </P>
! 1264: <P>
! 1265: <PRE>
! 1266: the ((red|white) (king|queen))
! 1267: </PRE>
! 1268: </P>
! 1269: <P>
! 1270: the captured substrings are "red king", "red", and "king", and are numbered 1,
! 1271: 2, and 3.
! 1272: </P>
! 1273: <P>
! 1274: The fact that plain parentheses fulfil two functions is not always helpful.
! 1275: There are often times when a grouping subpattern is required without a
! 1276: capturing requirement. If an opening parenthesis is followed by "?:", the
! 1277: subpattern does not do any capturing, and is not counted when computing the
! 1278: number of any subsequent capturing subpatterns. For example, if the string "the
! 1279: white queen" is matched against the pattern
! 1280: </P>
! 1281: <P>
! 1282: <PRE>
! 1283: the ((?:red|white) (king|queen))
! 1284: </PRE>
! 1285: </P>
! 1286: <P>
! 1287: the captured substrings are "white queen" and "queen", and are numbered 1 and
! 1288: 2. The maximum number of captured substrings is 99, and the maximum number of
! 1289: all subpatterns, both capturing and non-capturing, is 200.
! 1290: </P>
! 1291: <P>
! 1292: As a convenient shorthand, if any option settings are required at the start of
! 1293: a non-capturing subpattern, the option letters may appear between the "?" and
! 1294: the ":". Thus the two patterns
! 1295: </P>
! 1296: <P>
! 1297: <PRE>
! 1298: (?i:saturday|sunday)
! 1299: (?:(?i)saturday|sunday)
! 1300: </PRE>
! 1301: </P>
! 1302: <P>
! 1303: match exactly the same set of strings. Because alternative branches are tried
! 1304: from left to right, and options are not reset until the end of the subpattern
! 1305: is reached, an option setting in one branch does affect subsequent branches, so
! 1306: the above patterns match "SUNDAY" as well as "Saturday".
! 1307: </P>
! 1308: <LI><A NAME="SEC21" HREF="#TOC1">REPETITION</A>
! 1309: <P>
! 1310: Repetition is specified by quantifiers, which can follow any of the following
! 1311: items:
! 1312: </P>
! 1313: <P>
! 1314: <PRE>
! 1315: a single character, possibly escaped
! 1316: the . metacharacter
! 1317: a character class
! 1318: a back reference (see next section)
! 1319: a parenthesized subpattern (unless it is an assertion - see below)
! 1320: </PRE>
! 1321: </P>
! 1322: <P>
! 1323: The general repetition quantifier specifies a minimum and maximum number of
! 1324: permitted matches, by giving the two numbers in curly brackets (braces),
! 1325: separated by a comma. The numbers must be less than 65536, and the first must
! 1326: be less than or equal to the second. For example:
! 1327: </P>
! 1328: <P>
! 1329: <PRE>
! 1330: z{2,4}
! 1331: </PRE>
! 1332: </P>
! 1333: <P>
! 1334: matches "zz", "zzz", or "zzzz". A closing brace on its own is not a special
! 1335: character. If the second number is omitted, but the comma is present, there is
! 1336: no upper limit; if the second number and the comma are both omitted, the
! 1337: quantifier specifies an exact number of required matches. Thus
! 1338: </P>
! 1339: <P>
! 1340: <PRE>
! 1341: [aeiou]{3,}
! 1342: </PRE>
! 1343: </P>
! 1344: <P>
! 1345: matches at least 3 successive vowels, but may match many more, while
! 1346: </P>
! 1347: <P>
! 1348: <PRE>
! 1349: \d{8}
! 1350: </PRE>
! 1351: </P>
! 1352: <P>
! 1353: matches exactly 8 digits. An opening curly bracket that appears in a position
! 1354: where a quantifier is not allowed, or one that does not match the syntax of a
! 1355: quantifier, is taken as a literal character. For example, {,6} is not a
! 1356: quantifier, but a literal string of four characters.
! 1357: </P>
! 1358: <P>
! 1359: The quantifier {0} is permitted, causing the expression to behave as if the
! 1360: previous item and the quantifier were not present.
! 1361: </P>
! 1362: <P>
! 1363: For convenience (and historical compatibility) the three most common
! 1364: quantifiers have single-character abbreviations:
! 1365: </P>
! 1366: <P>
! 1367: <PRE>
! 1368: * is equivalent to {0,}
! 1369: + is equivalent to {1,}
! 1370: ? is equivalent to {0,1}
! 1371: </PRE>
! 1372: </P>
! 1373: <P>
! 1374: It is possible to construct infinite loops by following a subpattern that can
! 1375: match no characters with a quantifier that has no upper limit, for example:
! 1376: </P>
! 1377: <P>
! 1378: <PRE>
! 1379: (a?)*
! 1380: </PRE>
! 1381: </P>
! 1382: <P>
! 1383: Earlier versions of Perl and PCRE used to give an error at compile time for
! 1384: such patterns. However, because there are cases where this can be useful, such
! 1385: patterns are now accepted, but if any repetition of the subpattern does in fact
! 1386: match no characters, the loop is forcibly broken.
! 1387: </P>
! 1388: <P>
! 1389: By default, the quantifiers are "greedy", that is, they match as much as
! 1390: possible (up to the maximum number of permitted times), without causing the
! 1391: rest of the pattern to fail. The classic example of where this gives problems
! 1392: is in trying to match comments in C programs. These appear between the
! 1393: sequences /* and */ and within the sequence, individual * and / characters may
! 1394: appear. An attempt to match C comments by applying the pattern
! 1395: </P>
! 1396: <P>
! 1397: <PRE>
! 1398: /\*.*\*/
! 1399: </PRE>
! 1400: </P>
! 1401: <P>
! 1402: to the string
! 1403: </P>
! 1404: <P>
! 1405: <PRE>
! 1406: /* first command */ not comment /* second comment */
! 1407: </PRE>
! 1408: </P>
! 1409: <P>
! 1410: fails, because it matches the entire string due to the greediness of the .*
! 1411: item.
! 1412: </P>
! 1413: <P>
! 1414: However, if a quantifier is followed by a question mark, then it ceases to be
! 1415: greedy, and instead matches the minimum number of times possible, so the
! 1416: pattern
! 1417: </P>
! 1418: <P>
! 1419: <PRE>
! 1420: /\*.*?\*/
! 1421: </PRE>
! 1422: </P>
! 1423: <P>
! 1424: does the right thing with the C comments. The meaning of the various
! 1425: quantifiers is not otherwise changed, just the preferred number of matches.
! 1426: Do not confuse this use of question mark with its use as a quantifier in its
! 1427: own right. Because it has two uses, it can sometimes appear doubled, as in
! 1428: </P>
! 1429: <P>
! 1430: <PRE>
! 1431: \d??\d
! 1432: </PRE>
! 1433: </P>
! 1434: <P>
! 1435: which matches one digit by preference, but can match two if that is the only
! 1436: way the rest of the pattern matches.
! 1437: </P>
! 1438: <P>
! 1439: If the PCRE_UNGREEDY option is set (an option which is not available in Perl)
! 1440: then the quantifiers are not greedy by default, but individual ones can be made
! 1441: greedy by following them with a question mark. In other words, it inverts the
! 1442: default behaviour.
! 1443: </P>
! 1444: <P>
! 1445: When a parenthesized subpattern is quantified with a minimum repeat count that
! 1446: is greater than 1 or with a limited maximum, more store is required for the
! 1447: compiled pattern, in proportion to the size of the minimum or maximum.
! 1448: </P>
! 1449: <P>
! 1450: If a pattern starts with .* or .{0,} and the PCRE_DOTALL option (equivalent
! 1451: to Perl's /s) is set, thus allowing the . to match newlines, then the pattern
! 1452: is implicitly anchored, because whatever follows will be tried against every
! 1453: character position in the subject string, so there is no point in retrying the
! 1454: overall match at any position after the first. PCRE treats such a pattern as
! 1455: though it were preceded by \A. In cases where it is known that the subject
! 1456: string contains no newlines, it is worth setting PCRE_DOTALL when the pattern
! 1457: begins with .* in order to obtain this optimization, or alternatively using ^
! 1458: to indicate anchoring explicitly.
! 1459: </P>
! 1460: <P>
! 1461: When a capturing subpattern is repeated, the value captured is the substring
! 1462: that matched the final iteration. For example, after
! 1463: </P>
! 1464: <P>
! 1465: <PRE>
! 1466: (tweedle[dume]{3}\s*)+
! 1467: </PRE>
! 1468: </P>
! 1469: <P>
! 1470: has matched "tweedledum tweedledee" the value of the captured substring is
! 1471: "tweedledee". However, if there are nested capturing subpatterns, the
! 1472: corresponding captured values may have been set in previous iterations. For
! 1473: example, after
! 1474: </P>
! 1475: <P>
! 1476: <PRE>
! 1477: /(a|(b))+/
! 1478: </PRE>
! 1479: </P>
! 1480: <P>
! 1481: matches "aba" the value of the second captured substring is "b".
! 1482: </P>
! 1483: <LI><A NAME="SEC22" HREF="#TOC1">BACK REFERENCES</A>
! 1484: <P>
! 1485: Outside a character class, a backslash followed by a digit greater than 0 (and
! 1486: possibly further digits) is a back reference to a capturing subpattern earlier
! 1487: (i.e. to its left) in the pattern, provided there have been that many previous
! 1488: capturing left parentheses.
! 1489: </P>
! 1490: <P>
! 1491: However, if the decimal number following the backslash is less than 10, it is
! 1492: always taken as a back reference, and causes an error only if there are not
! 1493: that many capturing left parentheses in the entire pattern. In other words, the
! 1494: parentheses that are referenced need not be to the left of the reference for
! 1495: numbers less than 10. See the section entitled "Backslash" above for further
! 1496: details of the handling of digits following a backslash.
! 1497: </P>
! 1498: <P>
! 1499: A back reference matches whatever actually matched the capturing subpattern in
! 1500: the current subject string, rather than anything matching the subpattern
! 1501: itself. So the pattern
! 1502: </P>
! 1503: <P>
! 1504: <PRE>
! 1505: (sens|respons)e and \1ibility
! 1506: </PRE>
! 1507: </P>
! 1508: <P>
! 1509: matches "sense and sensibility" and "response and responsibility", but not
! 1510: "sense and responsibility". If caseful matching is in force at the time of the
! 1511: back reference, then the case of letters is relevant. For example,
! 1512: </P>
! 1513: <P>
! 1514: <PRE>
! 1515: ((?i)rah)\s+\1
! 1516: </PRE>
! 1517: </P>
! 1518: <P>
! 1519: matches "rah rah" and "RAH RAH", but not "RAH rah", even though the original
! 1520: capturing subpattern is matched caselessly.
! 1521: </P>
! 1522: <P>
! 1523: There may be more than one back reference to the same subpattern. If a
! 1524: subpattern has not actually been used in a particular match, then any back
! 1525: references to it always fail. For example, the pattern
! 1526: </P>
! 1527: <P>
! 1528: <PRE>
! 1529: (a|(bc))\2
! 1530: </PRE>
! 1531: </P>
! 1532: <P>
! 1533: always fails if it starts to match "a" rather than "bc". Because there may be
! 1534: up to 99 back references, all digits following the backslash are taken
! 1535: as part of a potential back reference number. If the pattern continues with a
! 1536: digit character, then some delimiter must be used to terminate the back
! 1537: reference. If the PCRE_EXTENDED option is set, this can be whitespace.
! 1538: Otherwise an empty comment can be used.
! 1539: </P>
! 1540: <P>
! 1541: A back reference that occurs inside the parentheses to which it refers fails
! 1542: when the subpattern is first used, so, for example, (a\1) never matches.
! 1543: However, such references can be useful inside repeated subpatterns. For
! 1544: example, the pattern
! 1545: </P>
! 1546: <P>
! 1547: <PRE>
! 1548: (a|b\1)+
! 1549: </PRE>
! 1550: </P>
! 1551: <P>
! 1552: matches any number of "a"s and also "aba", "ababaa" etc. At each iteration of
! 1553: the subpattern, the back reference matches the character string corresponding
! 1554: to the previous iteration. In order for this to work, the pattern must be such
! 1555: that the first iteration does not need to match the back reference. This can be
! 1556: done using alternation, as in the example above, or by a quantifier with a
! 1557: minimum of zero.
! 1558: </P>
! 1559: <LI><A NAME="SEC23" HREF="#TOC1">ASSERTIONS</A>
! 1560: <P>
! 1561: An assertion is a test on the characters following or preceding the current
! 1562: matching point that does not actually consume any characters. The simple
! 1563: assertions coded as \b, \B, \A, \Z, \z, ^ and $ are described above. More
! 1564: complicated assertions are coded as subpatterns. There are two kinds: those
! 1565: that look ahead of the current position in the subject string, and those that
! 1566: look behind it.
! 1567: </P>
! 1568: <P>
! 1569: An assertion subpattern is matched in the normal way, except that it does not
! 1570: cause the current matching position to be changed. Lookahead assertions start
! 1571: with (?= for positive assertions and (?! for negative assertions. For example,
! 1572: </P>
! 1573: <P>
! 1574: <PRE>
! 1575: \w+(?=;)
! 1576: </PRE>
! 1577: </P>
! 1578: <P>
! 1579: matches a word followed by a semicolon, but does not include the semicolon in
! 1580: the match, and
! 1581: </P>
! 1582: <P>
! 1583: <PRE>
! 1584: foo(?!bar)
! 1585: </PRE>
! 1586: </P>
! 1587: <P>
! 1588: matches any occurrence of "foo" that is not followed by "bar". Note that the
! 1589: apparently similar pattern
! 1590: </P>
! 1591: <P>
! 1592: <PRE>
! 1593: (?!foo)bar
! 1594: </PRE>
! 1595: </P>
! 1596: <P>
! 1597: does not find an occurrence of "bar" that is preceded by something other than
! 1598: "foo"; it finds any occurrence of "bar" whatsoever, because the assertion
! 1599: (?!foo) is always true when the next three characters are "bar". A
! 1600: lookbehind assertion is needed to achieve this effect.
! 1601: </P>
! 1602: <P>
! 1603: Lookbehind assertions start with (?<= for positive assertions and (?<! for
! 1604: negative assertions. For example,
! 1605: </P>
! 1606: <P>
! 1607: <PRE>
! 1608: (?<!foo)bar
! 1609: </PRE>
! 1610: </P>
! 1611: <P>
! 1612: does find an occurrence of "bar" that is not preceded by "foo". The contents of
! 1613: a lookbehind assertion are restricted such that all the strings it matches must
! 1614: have a fixed length. However, if there are several alternatives, they do not
! 1615: all have to have the same fixed length. Thus
! 1616: </P>
! 1617: <P>
! 1618: <PRE>
! 1619: (?<=bullock|donkey)
! 1620: </PRE>
! 1621: </P>
! 1622: <P>
! 1623: is permitted, but
! 1624: </P>
! 1625: <P>
! 1626: <PRE>
! 1627: (?<!dogs?|cats?)
! 1628: </PRE>
! 1629: </P>
! 1630: <P>
! 1631: causes an error at compile time. Branches that match different length strings
! 1632: are permitted only at the top level of a lookbehind assertion. This is an
! 1633: extension compared with Perl 5.005, which requires all branches to match the
! 1634: same length of string. An assertion such as
! 1635: </P>
! 1636: <P>
! 1637: <PRE>
! 1638: (?<=ab(c|de))
! 1639: </PRE>
! 1640: </P>
! 1641: <P>
! 1642: is not permitted, because its single top-level branch can match two different
! 1643: lengths, but it is acceptable if rewritten to use two top-level branches:
! 1644: </P>
! 1645: <P>
! 1646: <PRE>
! 1647: (?<=abc|abde)
! 1648: </PRE>
! 1649: </P>
! 1650: <P>
! 1651: The implementation of lookbehind assertions is, for each alternative, to
! 1652: temporarily move the current position back by the fixed width and then try to
! 1653: match. If there are insufficient characters before the current position, the
! 1654: match is deemed to fail. Lookbehinds in conjunction with once-only subpatterns
! 1655: can be particularly useful for matching at the ends of strings; an example is
! 1656: given at the end of the section on once-only subpatterns.
! 1657: </P>
! 1658: <P>
! 1659: Several assertions (of any sort) may occur in succession. For example,
! 1660: </P>
! 1661: <P>
! 1662: <PRE>
! 1663: (?<=\d{3})(?<!999)foo
! 1664: </PRE>
! 1665: </P>
! 1666: <P>
! 1667: matches "foo" preceded by three digits that are not "999". Notice that each of
! 1668: the assertions is applied independently at the same point in the subject
! 1669: string. First there is a check that the previous three characters are all
! 1670: digits, then there is a check that the same three characters are not "999".
! 1671: This pattern does <I>not</I> match "foo" preceded by six characters, the first
! 1672: of which are digits and the last three of which are not "999". For example, it
! 1673: doesn't match "123abcfoo". A pattern to do that is
! 1674: </P>
! 1675: <P>
! 1676: <PRE>
! 1677: (?<=\d{3}...)(?<!999)foo
! 1678: </PRE>
! 1679: </P>
! 1680: <P>
! 1681: This time the first assertion looks at the preceding six characters, checking
! 1682: that the first three are digits, and then the second assertion checks that the
! 1683: preceding three characters are not "999".
! 1684: </P>
! 1685: <P>
! 1686: Assertions can be nested in any combination. For example,
! 1687: </P>
! 1688: <P>
! 1689: <PRE>
! 1690: (?<=(?<!foo)bar)baz
! 1691: </PRE>
! 1692: </P>
! 1693: <P>
! 1694: matches an occurrence of "baz" that is preceded by "bar" which in turn is not
! 1695: preceded by "foo", while
! 1696: </P>
! 1697: <P>
! 1698: <PRE>
! 1699: (?<=\d{3}(?!999)...)foo
! 1700: </PRE>
! 1701: </P>
! 1702: <P>
! 1703: is another pattern which matches "foo" preceded by three digits and any three
! 1704: characters that are not "999".
! 1705: </P>
! 1706: <P>
! 1707: Assertion subpatterns are not capturing subpatterns, and may not be repeated,
! 1708: because it makes no sense to assert the same thing several times. If any kind
! 1709: of assertion contains capturing subpatterns within it, these are counted for
! 1710: the purposes of numbering the capturing subpatterns in the whole pattern.
! 1711: However, substring capturing is carried out only for positive assertions,
! 1712: because it does not make sense for negative assertions.
! 1713: </P>
! 1714: <P>
! 1715: Assertions count towards the maximum of 200 parenthesized subpatterns.
! 1716: </P>
! 1717: <LI><A NAME="SEC24" HREF="#TOC1">ONCE-ONLY SUBPATTERNS</A>
! 1718: <P>
! 1719: With both maximizing and minimizing repetition, failure of what follows
! 1720: normally causes the repeated item to be re-evaluated to see if a different
! 1721: number of repeats allows the rest of the pattern to match. Sometimes it is
! 1722: useful to prevent this, either to change the nature of the match, or to cause
! 1723: it fail earlier than it otherwise might, when the author of the pattern knows
! 1724: there is no point in carrying on.
! 1725: </P>
! 1726: <P>
! 1727: Consider, for example, the pattern \d+foo when applied to the subject line
! 1728: </P>
! 1729: <P>
! 1730: <PRE>
! 1731: 123456bar
! 1732: </PRE>
! 1733: </P>
! 1734: <P>
! 1735: After matching all 6 digits and then failing to match "foo", the normal
! 1736: action of the matcher is to try again with only 5 digits matching the \d+
! 1737: item, and then with 4, and so on, before ultimately failing. Once-only
! 1738: subpatterns provide the means for specifying that once a portion of the pattern
! 1739: has matched, it is not to be re-evaluated in this way, so the matcher would
! 1740: give up immediately on failing to match "foo" the first time. The notation is
! 1741: another kind of special parenthesis, starting with (?> as in this example:
! 1742: </P>
! 1743: <P>
! 1744: <PRE>
! 1745: (?>\d+)bar
! 1746: </PRE>
! 1747: </P>
! 1748: <P>
! 1749: This kind of parenthesis "locks up" the part of the pattern it contains once
! 1750: it has matched, and a failure further into the pattern is prevented from
! 1751: backtracking into it. Backtracking past it to previous items, however, works as
! 1752: normal.
! 1753: </P>
! 1754: <P>
! 1755: An alternative description is that a subpattern of this type matches the string
! 1756: of characters that an identical standalone pattern would match, if anchored at
! 1757: the current point in the subject string.
! 1758: </P>
! 1759: <P>
! 1760: Once-only subpatterns are not capturing subpatterns. Simple cases such as the
! 1761: above example can be thought of as a maximizing repeat that must swallow
! 1762: everything it can. So, while both \d+ and \d+? are prepared to adjust the
! 1763: number of digits they match in order to make the rest of the pattern match,
! 1764: (?>\d+) can only match an entire sequence of digits.
! 1765: </P>
! 1766: <P>
! 1767: This construction can of course contain arbitrarily complicated subpatterns,
! 1768: and it can be nested.
! 1769: </P>
! 1770: <P>
! 1771: Once-only subpatterns can be used in conjunction with lookbehind assertions to
! 1772: specify efficient matching at the end of the subject string. Consider a simple
! 1773: pattern such as
! 1774: </P>
! 1775: <P>
! 1776: <PRE>
! 1777: abcd$
! 1778: </PRE>
! 1779: </P>
! 1780: <P>
! 1781: when applied to a long string which does not match it. Because matching
! 1782: proceeds from left to right, PCRE will look for each "a" in the subject and
! 1783: then see if what follows matches the rest of the pattern. If the pattern is
! 1784: specified as
! 1785: </P>
! 1786: <P>
! 1787: <PRE>
! 1788: ^.*abcd$
! 1789: </PRE>
! 1790: </P>
! 1791: <P>
! 1792: then the initial .* matches the entire string at first, but when this fails, it
! 1793: backtracks to match all but the last character, then all but the last two
! 1794: characters, and so on. Once again the search for "a" covers the entire string,
! 1795: from right to left, so we are no better off. However, if the pattern is written
! 1796: as
! 1797: </P>
! 1798: <P>
! 1799: <PRE>
! 1800: ^(?>.*)(?<=abcd)
! 1801: </PRE>
! 1802: </P>
! 1803: <P>
! 1804: then there can be no backtracking for the .* item; it can match only the entire
! 1805: string. The subsequent lookbehind assertion does a single test on the last four
! 1806: characters. If it fails, the match fails immediately. For long strings, this
! 1807: approach makes a significant difference to the processing time.
! 1808: </P>
! 1809: <LI><A NAME="SEC25" HREF="#TOC1">CONDITIONAL SUBPATTERNS</A>
! 1810: <P>
! 1811: It is possible to cause the matching process to obey a subpattern
! 1812: conditionally or to choose between two alternative subpatterns, depending on
! 1813: the result of an assertion, or whether a previous capturing subpattern matched
! 1814: or not. The two possible forms of conditional subpattern are
! 1815: </P>
! 1816: <P>
! 1817: <PRE>
! 1818: (?(condition)yes-pattern)
! 1819: (?(condition)yes-pattern|no-pattern)
! 1820: </PRE>
! 1821: </P>
! 1822: <P>
! 1823: If the condition is satisfied, the yes-pattern is used; otherwise the
! 1824: no-pattern (if present) is used. If there are more than two alternatives in the
! 1825: subpattern, a compile-time error occurs.
! 1826: </P>
! 1827: <P>
! 1828: There are two kinds of condition. If the text between the parentheses consists
! 1829: of a sequence of digits, then the condition is satisfied if the capturing
! 1830: subpattern of that number has previously matched. Consider the following
! 1831: pattern, which contains non-significant white space to make it more readable
! 1832: (assume the PCRE_EXTENDED option) and to divide it into three parts for ease
! 1833: of discussion:
! 1834: </P>
! 1835: <P>
! 1836: <PRE>
! 1837: ( \( )? [^()]+ (?(1) \) )
! 1838: </PRE>
! 1839: </P>
! 1840: <P>
! 1841: The first part matches an optional opening parenthesis, and if that
! 1842: character is present, sets it as the first captured substring. The second part
! 1843: matches one or more characters that are not parentheses. The third part is a
! 1844: conditional subpattern that tests whether the first set of parentheses matched
! 1845: or not. If they did, that is, if subject started with an opening parenthesis,
! 1846: the condition is true, and so the yes-pattern is executed and a closing
! 1847: parenthesis is required. Otherwise, since no-pattern is not present, the
! 1848: subpattern matches nothing. In other words, this pattern matches a sequence of
! 1849: non-parentheses, optionally enclosed in parentheses.
! 1850: </P>
! 1851: <P>
! 1852: If the condition is not a sequence of digits, it must be an assertion. This may
! 1853: be a positive or negative lookahead or lookbehind assertion. Consider this
! 1854: pattern, again containing non-significant white space, and with the two
! 1855: alternatives on the second line:
! 1856: </P>
! 1857: <P>
! 1858: <PRE>
! 1859: (?(?=[^a-z]*[a-z])
! 1860: \d{2}[a-z]{3}-\d{2} | \d{2}-\d{2}-\d{2} )
! 1861: </PRE>
! 1862: </P>
! 1863: <P>
! 1864: The condition is a positive lookahead assertion that matches an optional
! 1865: sequence of non-letters followed by a letter. In other words, it tests for the
! 1866: presence of at least one letter in the subject. If a letter is found, the
! 1867: subject is matched against the first alternative; otherwise it is matched
! 1868: against the second. This pattern matches strings in one of the two forms
! 1869: dd-aaa-dd or dd-dd-dd, where aaa are letters and dd are digits.
! 1870: </P>
! 1871: <LI><A NAME="SEC26" HREF="#TOC1">COMMENTS</A>
! 1872: <P>
! 1873: The sequence (?# marks the start of a comment which continues up to the next
! 1874: closing parenthesis. Nested parentheses are not permitted. The characters
! 1875: that make up a comment play no part in the pattern matching at all.
! 1876: </P>
! 1877: <P>
! 1878: If the PCRE_EXTENDED option is set, an unescaped # character outside a
! 1879: character class introduces a comment that continues up to the next newline
! 1880: character in the pattern.
! 1881: </P>
! 1882: <LI><A NAME="SEC27" HREF="#TOC1">PERFORMANCE</A>
! 1883: <P>
! 1884: Certain items that may appear in patterns are more efficient than others. It is
! 1885: more efficient to use a character class like [aeiou] than a set of alternatives
! 1886: such as (a|e|i|o|u). In general, the simplest construction that provides the
! 1887: required behaviour is usually the most efficient. Jeffrey Friedl's book
! 1888: contains a lot of discussion about optimizing regular expressions for efficient
! 1889: performance.
! 1890: </P>
! 1891: <P>
! 1892: When a pattern begins with .* and the PCRE_DOTALL option is set, the pattern is
! 1893: implicitly anchored by PCRE, since it can match only at the start of a subject
! 1894: string. However, if PCRE_DOTALL is not set, PCRE cannot make this optimization,
! 1895: because the . metacharacter does not then match a newline, and if the subject
! 1896: string contains newlines, the pattern may match from the character immediately
! 1897: following one of them instead of from the very start. For example, the pattern
! 1898: </P>
! 1899: <P>
! 1900: <PRE>
! 1901: (.*) second
! 1902: </PRE>
! 1903: </P>
! 1904: <P>
! 1905: matches the subject "first\nand second" (where \n stands for a newline
! 1906: character) with the first captured substring being "and". In order to do this,
! 1907: PCRE has to retry the match starting after every newline in the subject.
! 1908: </P>
! 1909: <P>
! 1910: If you are using such a pattern with subject strings that do not contain
! 1911: newlines, the best performance is obtained by setting PCRE_DOTALL, or starting
! 1912: the pattern with ^.* to indicate explicit anchoring. That saves PCRE from
! 1913: having to scan along the subject looking for a newline to restart at.
! 1914: </P>
! 1915: <P>
! 1916: Beware of patterns that contain nested indefinite repeats. These can take a
! 1917: long time to run when applied to a string that does not match. Consider the
! 1918: pattern fragment
! 1919: </P>
! 1920: <P>
! 1921: <PRE>
! 1922: (a+)*
! 1923: </PRE>
! 1924: </P>
! 1925: <P>
! 1926: This can match "aaaa" in 33 different ways, and this number increases very
! 1927: rapidly as the string gets longer. (The * repeat can match 0, 1, 2, 3, or 4
! 1928: times, and for each of those cases other than 0, the + repeats can match
! 1929: different numbers of times.) When the remainder of the pattern is such that the
! 1930: entire match is going to fail, PCRE has in principle to try every possible
! 1931: variation, and this can take an extremely long time.
! 1932: </P>
! 1933: <P>
! 1934: An optimization catches some of the more simple cases such as
! 1935: </P>
! 1936: <P>
! 1937: <PRE>
! 1938: (a+)*b
! 1939: </PRE>
! 1940: </P>
! 1941: <P>
! 1942: where a literal character follows. Before embarking on the standard matching
! 1943: procedure, PCRE checks that there is a "b" later in the subject string, and if
! 1944: there is not, it fails the match immediately. However, when there is no
! 1945: following literal this optimization cannot be used. You can see the difference
! 1946: by comparing the behaviour of
! 1947: </P>
! 1948: <P>
! 1949: <PRE>
! 1950: (a+)*\d
! 1951: </PRE>
! 1952: </P>
! 1953: <P>
! 1954: with the pattern above. The former gives a failure almost instantly when
! 1955: applied to a whole line of "a" characters, whereas the latter takes an
! 1956: appreciable time with strings longer than about 20 characters.
! 1957: </P>
! 1958: <LI><A NAME="SEC28" HREF="#TOC1">AUTHOR</A>
! 1959: <P>
! 1960: Philip Hazel <ph10@cam.ac.uk>
! 1961: <BR>
! 1962: University Computing Service,
! 1963: <BR>
! 1964: New Museums Site,
! 1965: <BR>
! 1966: Cambridge CB2 3QG, England.
! 1967: <BR>
! 1968: Phone: +44 1223 334714
! 1969: </P>
! 1970: <P>
! 1971: Last updated: 29 July 1999
! 1972: <BR>
! 1973: Copyright (c) 1997-1999 University of Cambridge.
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to pcre.3.html CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [parser3project] / parser3 / src / lib / pcre