/[pcre]/code/trunk/doc/html/pcreapi.html

Diff of /code/trunk/doc/html/pcreapi.html

Parent Directory | Revision Log | View Patch Patch

-revision 1403 by ph10,
Fri Jun 14 09:09:28 2013 UTC
+revision 1404 by ph10,
Tue Nov 19 15:36:57 2013 UTC
 Line 484 
 the
  <a href="pcreposix.html"><b>pcreposix</b></a>
  documentation.
  <pre>
+   PCRE_CONFIG_PARENS_LIMIT
+ </pre>
+ The output is a long integer that gives the maximum depth of nesting of
+ parentheses (of any kind) in a pattern. This limit is imposed to cap the amount
+ of system stack used when a pattern is compiled. It is specified when PCRE is
+ built; the default is 250.
+ <pre>
    PCRE_CONFIG_MATCH_LIMIT
  </pre>
  The output is a long integer that gives the default limit for the number of
-Line 582 
 If the final argument, <i>tableptr</i>,
+Line 589 
 If the final argument, <i>tableptr</i>,
  character tables that are built when PCRE is compiled, using the default C
  locale. Otherwise, <i>tableptr</i> must be an address that is the result of a
  call to <b>pcre_maketables()</b>. This value is stored with the compiled
- pattern, and used again by <b>pcre_exec()</b>, unless another table pointer is
+ pattern, and used again by <b>pcre_exec()</b> and <b>pcre_dfa_exec()</b> when the
- passed to it. For more discussion, see the section on locale support below.
+ pattern is matched. For more discussion, see the section on locale support
+ below.
  </P>
  <P>
  This code fragment shows a typical straightforward call to <b>pcre_compile()</b>:
-Line 668 
 documentation.
+Line 676 
 documentation.
  <pre>
    PCRE_EXTENDED
  </pre>
- If this bit is set, white space data characters in the pattern are totally
+ If this bit is set, most white space characters in the pattern are totally
- ignored except when escaped or inside a character class. White space does not
+ ignored except when escaped or inside a character class. However, white space
- include the VT character (code 11). In addition, characters between an
+ is not allowed within sequences such as (?&#62; that introduce various
- unescaped # outside a character class and the next newline, inclusive, are also
+ parenthesized subpatterns, nor within a numerical quantifier such as {1,3}.
- ignored. This is equivalent to Perl's /x option, and it can be changed within a
+ However, ignorable white space is permitted between an item and a following
- pattern by a (?x) option setting.
+ quantifier and between a quantifier and a following + that indicates
+ possessiveness.
+ </P>
+ <P>
+ White space did not used to include the VT character (code 11), because Perl
+ did not treat this character as white space. However, Perl changed at release
+.18, so PCRE followed at release 8.34, and VT is now treated as white space.
+ </P>
+ <P>
+ PCRE_EXTENDED also causes characters between an unescaped # outside a character
+ class and the next newline, inclusive, to be ignored. PCRE_EXTENDED is
+ equivalent to Perl's /x option, and it can be changed within a pattern by a
+ (?x) option setting.
  </P>
  <P>
  Which characters are interpreted as newlines is controlled by the options
-Line 827 
 were followed by ?: but named parenthese
+Line 847 
 were followed by ?: but named parenthese
  they acquire numbers in the usual way). There is no equivalent of this option
  in Perl.
  <pre>
+   PCRE_NO_AUTO_POSSESS
+ </pre>
+ If this option is set, it disables "auto-possessification". This is an
+ optimization that, for example, turns a+b into a++b in order to avoid
+ backtracks into a+ that can never be successful. However, if callouts are in
+ use, auto-possessification means that some of them are never taken. You can set
+ this option if you want the matching functions to do a full unoptimized search
+ and run all the callouts, but it is mainly provided for testing purposes.
+ <pre>
    PCRE_NO_START_OPTIMIZE
  </pre>
  This is an option that acts at matching time; that is, it is really an option
-Line 877 
 page. If an invalid UTF-8 sequence is fo
+Line 906 
 page. If an invalid UTF-8 sequence is fo
  error. If you already know that your pattern is valid, and you want to skip
  this check for performance reasons, you can set the PCRE_NO_UTF8_CHECK option.
  When it is set, the effect of passing an invalid UTF-8 string as a pattern is
- undefined. It may cause your program to crash. Note that this option can also
+ undefined. It may cause your program to crash or loop. Note that this option
- be passed to <b>pcre_exec()</b> and <b>pcre_dfa_exec()</b>, to suppress the
+ can also be passed to <b>pcre_exec()</b> and <b>pcre_dfa_exec()</b>, to suppress
- validity checking of subject strings only. If the same string is being matched
+ the validity checking of subject strings only. If the same string is being
- many times, the option can be safely set for the second and subsequent
+ matched many times, the option can be safely set for the second and subsequent
  matchings to improve performance.
  </P>
  <br><a name="SEC12" href="#TOC1">COMPILATION ERROR CODES</a><br>
-Line 925 
 have fallen out of use. To avoid confusi
+Line 954 
 have fallen out of use. To avoid confusi
  POSIX collating elements are not supported
  this version of PCRE is compiled without UTF support
  [this code is not in use]
- character value in \x{...} sequence is too large
+ character value in \x{} or \o{} is too large
  invalid condition (?(0)
  \C not allowed in lookbehind assertion
  PCRE does not support \L, \l, \N{name}, \U, or \u
-Line 973 
 have fallen out of use. To avoid confusi
+Line 1002 
 have fallen out of use. To avoid confusi
  name is too long in (*MARK), (*PRUNE), (*SKIP), or (*THEN)
  character value in \u.... sequence is too large
  invalid UTF-32 string (specifically UTF-32)
+ setting UTF is disabled by the application
+ non-hex character in \x{} (closing brace missing?)
+ non-octal character in \o{} (closing brace missing?)
+ missing opening brace after \o
+ parentheses are too deeply nested
+ invalid range in character class
  </pre>
  The numbers 32 and 10000 in errors 48 and 49 are defaults; different values may
  be used if the limits were changed when PCRE was built.
-Line 1103 
 There is a longer discussion of PCRE_NO_
+Line 1138 
 There is a longer discussion of PCRE_NO_
  <P>
  PCRE handles caseless matching, and determines whether characters are letters,
  digits, or whatever, by reference to a set of tables, indexed by character
- value. When running in UTF-8 mode, this applies only to characters
+ code point. When running in UTF-8 mode, or in the 16- or 32-bit libraries, this
- with codes less than 128. By default, higher-valued codes never match escapes
+ applies only to characters with code points less than 256. By default,
- such as \w or \d, but they can be tested with \p if PCRE is built with
+ higher-valued code points never match escapes such as \w or \d. However, if
- Unicode character property support. Alternatively, the PCRE_UCP option can be
+ PCRE is built with Unicode property support, all characters can be tested with
- set at compile time; this causes \w and friends to use Unicode property
+ \p and \P, or, alternatively, the PCRE_UCP option can be set when a pattern
- support instead of built-in tables. The use of locales with Unicode is
+ is compiled; this causes \w and friends to use Unicode property support
- discouraged. If you are handling characters with codes greater than 128, you
+ instead of the built-in tables.
- should either use UTF-8 and Unicode, or use locales, but not try to mix the
+ </P>
- two.
+ <P>
+ The use of locales with Unicode is discouraged. If you are handling characters
+ with code points greater than 128, you should either use Unicode support, or
+ use locales, but not try to mix the two.
  </P>
  <P>
  PCRE contains an internal set of tables that are used when the final argument
-Line 1129 
 for this locale support is expected to d
+Line 1167 
 for this locale support is expected to d
  <P>
  External tables are built by calling the <b>pcre_maketables()</b> function,
  which has no arguments, in the relevant locale. The result can then be passed
- to <b>pcre_compile()</b> or <b>pcre_exec()</b> as often as necessary. For
+ to <b>pcre_compile()</b> as often as necessary. For example, to build and use
- example, to build and use tables that are appropriate for the French locale
+ tables that are appropriate for the French locale (where accented characters
- (where accented characters with values greater than 128 are treated as letters),
+ with values greater than 128 are treated as letters), the following code could
- the following code could be used:
+ be used:
  <pre>
    setlocale(LC_CTYPE, "fr_FR");
    tables = pcre_maketables();
-Line 1150 
 needed.
+Line 1188 
 needed.
  <P>
  The pointer that is passed to <b>pcre_compile()</b> is saved with the compiled
  pattern, and the same tables are used via this pointer by <b>pcre_study()</b>
- and normally also by <b>pcre_exec()</b>. Thus, by default, for any single
+ and also by <b>pcre_exec()</b> and <b>pcre_dfa_exec()</b>. Thus, for any single
  pattern, compilation, studying and matching all happen in the same locale, but
- different patterns can be compiled in different locales.
+ different patterns can be processed in different locales.
  </P>
  <P>
  It is possible to pass a table pointer or NULL (indicating the use of the
- internal tables) to <b>pcre_exec()</b>. Although not intended for this purpose,
+ internal tables) to <b>pcre_exec()</b> or <b>pcre_dfa_exec()</b> (see the
- this facility could be used to match a pattern in a different locale from the
+ discussion below in the section on matching a pattern). This facility is
- one in which it was compiled. Passing table pointers at run time is discussed
+ provided for use with pre-compiled patterns that have been saved and reloaded.
- below in the section on matching a pattern.
+ Character tables are not saved with patterns, so if a non-standard table was
+ used at compile time, it must be provided again when the reloaded pattern is
+ matched. Attempting to use this facility to match a pattern in a different
+ locale from the one in which it was compiled is likely to lead to anomalous
+ (usually incorrect) results.
  <a name="infoaboutpattern"></a></P>
  <br><a name="SEC15" href="#TOC1">INFORMATION ABOUT A PATTERN</a><br>
  <P>
-Line 1305 
 is -1.
+Line 1347 
 is -1.
  </P>
  <P>
  Since for the 32-bit library using the non-UTF-32 mode, this function is unable
- to return the full 32-bit range of the character, this value is deprecated;
+ to return the full 32-bit range of characters, this value is deprecated;
  instead the PCRE_INFO_REQUIREDCHARFLAGS and PCRE_INFO_REQUIREDCHAR values should
  be used.
  <pre>
+   PCRE_INFO_MATCH_EMPTY
+ </pre>
+ Return 1 if the pattern can match an empty string, otherwise 0. The fourth
+ argument should point to an <b>int</b> variable.
+ <pre>
    PCRE_INFO_MATCHLIMIT
  </pre>
  If the pattern set a match limit by including an item of the form
-Line 1366 
 contains the parenthesis number. The res
+Line 1413 
 contains the parenthesis number. The res
  name, zero terminated.
  </P>
  <P>
- The names are in alphabetical order. Duplicate names may appear if (?| is used
+ The names are in alphabetical order. If (?| is used to create multiple groups
- to create multiple groups with the same number, as described in the
+ with the same number, as described in the
  <a href="pcrepattern.html#dupsubpatternnumber">section on duplicate subpattern numbers</a>
  in the
  <a href="pcrepattern.html"><b>pcrepattern</b></a>
- page. Duplicate names for subpatterns with different numbers are permitted only
+ page, the groups may be given the same name, but there is only one entry in the
- if PCRE_DUPNAMES is set. In all cases of duplicate names, they appear in the
+ table. Different names for groups of the same number are not permitted.
- table in the order in which they were found in the pattern. In the absence of
+ Duplicate names for subpatterns with different numbers are permitted,
- (?| this is the order of increasing number; when (?| is used this is not
+ but only if PCRE_DUPNAMES is set. They appear in the table in the order in
- necessarily the case because later subpatterns may have lower numbers.
+ which they were found in the pattern. In the absence of (?| this is the order
+ of increasing number; when (?| is used this is not necessarily the case because
+ later subpatterns may have lower numbers.
  </P>
  <P>
  As a simple example of the name/number table, consider the following pattern
-Line 1489 
 returned. For anchored patterns, 0 is re
+Line 1538 
 returned. For anchored patterns, 0 is re
  <pre>
    PCRE_INFO_FIRSTCHARACTER
  </pre>
- Return the fixed first character value, if PCRE_INFO_FIRSTCHARACTERFLAGS
+ Return the fixed first character value in the situation where
- returned 1; otherwise returns 0. The fourth argument should point to an
+ PCRE_INFO_FIRSTCHARACTERFLAGS returns 1; otherwise return 0. The fourth
- <b>uint_t</b> variable.
+ argument should point to an <b>uint_t</b> variable.
  </P>
  <P>
  In the 8-bit library, the value is always less than 256. In the 16-bit library
  the value can be up to 0xffff. In the 32-bit library in UTF-32 mode the value
  can be up to 0x10ffff, and up to 0xffffffff when not using UTF-32 mode.
- </P>
- <P>
- If there is no fixed first value, and if either
- <br>
- <br>
- (a) the pattern was compiled with the PCRE_MULTILINE option, and every branch
- starts with "^", or
- <br>
- <br>
- (b) every branch of the pattern starts with ".*" and PCRE_DOTALL is not set
- (if it were set, the pattern would be anchored),
- <br>
- <br>
- -1 is returned, indicating that the pattern matches only at the start of a
- subject string or after any newline within the string. Otherwise -2 is
- returned. For anchored patterns, -2 is returned.
  <pre>
    PCRE_INFO_REQUIREDCHARFLAGS
  </pre>
-Line 1725 
 and is described in the
+Line 1758 
 and is described in the
  documentation.
  </P>
  <P>
- The <i>tables</i> field is used to pass a character tables pointer to
+ The <i>tables</i> field is provided for use with patterns that have been
- <b>pcre_exec()</b>; this overrides the value that is stored with the compiled
+ pre-compiled using custom character tables, saved to disc or elsewhere, and
- pattern. A non-NULL value is stored with the compiled pattern only if custom
+ then reloaded, because the tables that were used to compile a pattern are not
- tables were supplied to <b>pcre_compile()</b> via its <i>tableptr</i> argument.
+ saved with it. See the
- If NULL is passed to <b>pcre_exec()</b> using this mechanism, it forces PCRE's
- internal tables to be used. This facility is helpful when re-using patterns
- that have been saved after compiling with an external set of tables, because
- the external tables might be at a different address when <b>pcre_exec()</b> is
- called. See the
  <a href="pcreprecompile.html"><b>pcreprecompile</b></a>
- documentation for a discussion of saving compiled patterns for later use.
+ documentation for a discussion of saving compiled patterns for later use. If
+ NULL is passed using this mechanism, it forces PCRE's internal tables to be
+ used.
+ </P>
+ <P>
+ <b>Warning:</b> The tables that <b>pcre_exec()</b> uses must be the same as those
+ that were used when the pattern was compiled. If this is not the case, the
+ behaviour of <b>pcre_exec()</b> is undefined. Therefore, when a pattern is
+ compiled and matched in the same process, this field should never be set. In
+ this (the most common) case, the correct table pointer is automatically passed
+ with the compiled pattern from <b>pcre_compile()</b> to <b>pcre_exec()</b>.
  </P>
  <P>
  If PCRE_EXTRA_MARK is set in the <i>flags</i> field, the <i>mark</i> field must
-Line 1953 
 all the matches in a single subject stri
+Line 1991 
 all the matches in a single subject stri
  the value of <i>startoffset</i> points to the start of a character (or the end
  of the subject). When PCRE_NO_UTF8_CHECK is set, the effect of passing an
  invalid string as a subject or an invalid value of <i>startoffset</i> is
- undefined. Your program may crash.
+ undefined. Your program may crash or loop.
  <pre>
    PCRE_PARTIAL_HARD
    PCRE_PARTIAL_SOFT
-Line 2786 
 matching string is given first. If there
+Line 2824 
 matching string is given first. If there
  the longest matches. Unlike <b>pcre_exec()</b>, <b>pcre_dfa_exec()</b> can use
  the entire <i>ovector</i> for returning matched strings.
  </P>
+ <P>
+ NOTE: PCRE's "auto-possessification" optimization usually applies to character
+ repeats at the end of a pattern (as well as internally). For example, the
+ pattern "a\d+" is compiled as if it were "a\d++" because there is no point
+ even considering the possibility of backtracking into the repeated digits. For
+ DFA matching, this means that only one possible match is found. If you really
+ do want multiple matches in such cases, either use an ungreedy repeat
+ ("a\d+?") or set the PCRE_NO_AUTO_POSSESS option when compiling.
+ </P>
  <br><b>
  Error returns from <b>pcre_dfa_exec()</b>
  </b><br>
-Line 2852 
 Cambridge CB2 3QH, England.
+Line 2899 
 Cambridge CB2 3QH, England.
  </P>
  <br><a name="SEC26" href="#TOC1">REVISION</a><br>
  <P>
- Last updated: 12 June 2013
+ Last updated: 12 November 2013
  <br>
  Copyright &copy; 1997-2013 University of Cambridge.
  <br>

 Legend:



Removed from v.1403
 


changed lines


 
Added in v.1404
 Legend:



Removed from v.1403
 


changed lines


 
Added in v.1404
-Removed from v.1403
+Added in v.1404

	ViewVC Help
Powered by ViewVC 1.1.5