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

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

Parent Directory | Revision Log | View Patch Patch

-revision 111 by ph10,
Thu Mar  8 16:53:09 2007 UTC
+revision 211 by ph10,
Thu Aug  9 09:52:43 2007 UTC
 Line 246 
 documentation.
  </P>
  <br><a name="SEC3" href="#TOC1">NEWLINES</a><br>
  <P>
- PCRE supports four different conventions for indicating line breaks in
+ PCRE supports five different conventions for indicating line breaks in
  strings: a single CR (carriage return) character, a single LF (linefeed)
- character, the two-character sequence CRLF, or any Unicode newline sequence.
+ character, the two-character sequence CRLF, any of the three preceding, or any
- The Unicode newline sequences are the three just mentioned, plus the single
+ Unicode newline sequence. The Unicode newline sequences are the three just
- characters VT (vertical tab, U+000B), FF (formfeed, U+000C), NEL (next line,
+ mentioned, plus the single characters VT (vertical tab, U+000B), FF (formfeed,
- U+0085), LS (line separator, U+2028), and PS (paragraph separator, U+2029).
+ U+000C), NEL (next line, U+0085), LS (line separator, U+2028), and PS
+ (paragraph separator, U+2029).
  </P>
  <P>
  Each of the first three conventions is used by at least one operating system as
-Line 286 
 The compiled form of a regular expressio
+Line 287 
 The compiled form of a regular expressio
  time, possibly by a different program, and even on a host other than the one on
  which it was compiled. Details are given in the
  <a href="pcreprecompile.html"><b>pcreprecompile</b></a>
- documentation.
+ documentation. However, compiling a regular expression with one version of PCRE
+ for use with a different version is not guaranteed to work and may cause
+ crashes.
  </P>
  <br><a name="SEC6" href="#TOC1">CHECKING BUILD-TIME OPTIONS</a><br>
  <P>
-Line 317 
 properties is available; otherwise it is
+Line 320 
 properties is available; otherwise it is
  </pre>
  The output is an integer whose value specifies the default character sequence
  that is recognized as meaning "newline". The four values that are supported
- are: 10 for LF, 13 for CR, 3338 for CRLF, and -1 for ANY. The default should
+ are: 10 for LF, 13 for CR, 3338 for CRLF, -2 for ANYCRLF, and -1 for ANY. The
- normally be the standard sequence for your operating system.
+ default should normally be the standard sequence for your operating system.
  <pre>
    PCRE_CONFIG_LINK_SIZE
  </pre>
-Line 546 
 occurrences of ^ or $ in a pattern, sett
+Line 549 
 occurrences of ^ or $ in a pattern, sett
    PCRE_NEWLINE_CR
    PCRE_NEWLINE_LF
    PCRE_NEWLINE_CRLF
+   PCRE_NEWLINE_ANYCRLF
    PCRE_NEWLINE_ANY
  </pre>
  These options override the default newline definition that was chosen when PCRE
  was built. Setting the first or the second specifies that a newline is
  indicated by a single character (CR or LF, respectively). Setting
  PCRE_NEWLINE_CRLF specifies that a newline is indicated by the two-character
- CRLF sequence. Setting PCRE_NEWLINE_ANY specifies that any Unicode newline
+ CRLF sequence. Setting PCRE_NEWLINE_ANYCRLF specifies that any of the three
- sequence should be recognized. The Unicode newline sequences are the three just
+ preceding sequences should be recognized. Setting PCRE_NEWLINE_ANY specifies
- mentioned, plus the single characters VT (vertical tab, U+000B), FF (formfeed,
+ that any Unicode newline sequence should be recognized. The Unicode newline
- U+000C), NEL (next line, U+0085), LS (line separator, U+2028), and PS
+ sequences are the three just mentioned, plus the single characters VT (vertical
- (paragraph separator, U+2029). The last two are recognized only in UTF-8 mode.
+ tab, U+000B), FF (formfeed, U+000C), NEL (next line, U+0085), LS (line
+ separator, U+2028), and PS (paragraph separator, U+2029). The last two are
+ recognized only in UTF-8 mode.
  </P>
  <P>
  The newline setting in the options word uses three bits that are treated
- as a number, giving eight possibilities. Currently only five are used (default
+ as a number, giving eight possibilities. Currently only six are used (default
- plus the four values above). This means that if you set more than one newline
+ plus the five values above). This means that if you set more than one newline
  option, the combination may or may not be sensible. For example,
  PCRE_NEWLINE_CR with PCRE_NEWLINE_LF is equivalent to PCRE_NEWLINE_CRLF, but
- other combinations yield unused numbers and cause an error.
+ other combinations may yield unused numbers and cause an error.
  </P>
  <P>
  The only time that a line break is specially recognized when compiling a
-Line 607 
 page.
+Line 613 
 page.
    PCRE_NO_UTF8_CHECK
  </pre>
  When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 string is
- automatically checked. If an invalid UTF-8 sequence of bytes is found,
+ automatically checked. There is a discussion about the
- <b>pcre_compile()</b> returns an error. If you already know that your pattern is
+ <a href="pcre.html#utf8strings">validity of UTF-8 strings</a>
- valid, and you want to skip this check for performance reasons, you can set the
+ in the main
- PCRE_NO_UTF8_CHECK option. When it is set, the effect of passing an invalid
+ <a href="pcre.html"><b>pcre</b></a>
- UTF-8 string as a pattern is undefined. It may cause your program to crash.
+ page. If an invalid UTF-8 sequence of bytes is found, <b>pcre_compile()</b>
- Note that this option can also be passed to <b>pcre_exec()</b> and
+ returns an error. If you already know that your pattern is valid, and you want
- <b>pcre_dfa_exec()</b>, to suppress the UTF-8 validity checking of subject
+ to skip this check for performance reasons, you can set the PCRE_NO_UTF8_CHECK
- strings.
+ 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 be passed to <b>pcre_exec()</b> and <b>pcre_dfa_exec()</b>, to suppress
+ the UTF-8 validity checking of subject strings.
  </P>
  <br><a name="SEC8" href="#TOC1">COMPILATION ERROR CODES</a><br>
  <P>
-Line 652 
 out of use. To avoid confusion, they hav
+Line 661 
 out of use. To avoid confusion, they hav
  malformed number or name after (?(
  conditional group contains more than two branches
  assertion expected after (?(
- (?R or (?digits must be followed by )
+ (?R or (?[+-]digits must be followed by )
  unknown POSIX class name
  POSIX collating elements are not supported
  this version of PCRE is not compiled with PCRE_UTF8 support
-Line 673 
 out of use. To avoid confusion, they hav
+Line 682 
 out of use. To avoid confusion, they hav
  unknown property name after \P or \p
  subpattern name is too long (maximum 32 characters)
  too many named subpatterns (maximum 10,000)
- repeated subpattern is too long
+ [this code is not in use]
  octal value is greater than \377 (not in UTF-8 mode)
  internal error: overran compiling workspace
  internal error: previously-checked referenced subpattern not found
  DEFINE group contains more than one branch
  repeating a DEFINE group is not allowed
  inconsistent NEWLINE options"
+ \g is not followed by a braced name or an optionally braced
+         non-zero number
+ (?+ or (?- or (?(+ or (?(- must be followed by a non-zero number
  </PRE>
  </P>
  <br><a name="SEC9" href="#TOC1">STUDYING A PATTERN</a><br>
-Line 737 
 bytes is created.
+Line 749 
 bytes is created.
  <a name="localesupport"></a></P>
  <br><a name="SEC10" href="#TOC1">LOCALE SUPPORT</a><br>
  <P>
- PCRE handles caseless matching, and determines whether characters are letters
+ 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 with codes
  less than 128. Higher-valued codes never match escapes such as \w or \d, but
  can be tested with \p if PCRE is built with Unicode character property
- support. The use of locales with Unicode is discouraged.
+ support. The use of locales with Unicode is discouraged. If you are handling
- </P>
+ characters with codes greater than 128, you should either use UTF-8 and
- <P>
+ Unicode, or use locales, but not try to mix the two.
- An internal set of tables is created in the default C locale when PCRE is
+ </P>
- built. This is used when the final argument of <b>pcre_compile()</b> is NULL,
+ <P>
- and is sufficient for many applications. An alternative set of tables can,
+ PCRE contains an internal set of tables that are used when the final argument
- however, be supplied. These may be created in a different locale from the
+ of <b>pcre_compile()</b> is NULL. These are sufficient for many applications.
- default. As more and more applications change to using Unicode, the need for
+ Normally, the internal tables recognize only ASCII characters. However, when
- this locale support is expected to die away.
+ PCRE is built, it is possible to cause the internal tables to be rebuilt in the
+ default "C" locale of the local system, which may cause them to be different.
+ </P>
+ <P>
+ The internal tables can always be overridden by tables supplied by the
+ application that calls PCRE. These may be created in a different locale from
+ the default. As more and more applications change to using Unicode, the need
+ for this locale support is expected to die away.
  </P>
  <P>
  External tables are built by calling the <b>pcre_maketables()</b> function,
-Line 764 
 the following code could be used:
+Line 783 
 the following code could be used:
    tables = pcre_maketables();
    re = pcre_compile(..., tables);
  </pre>
+ The locale name "fr_FR" is used on Linux and other Unix-like systems; if you
+ are using Windows, the name for the French locale is "french".
+ </P>
+ <P>
  When <b>pcre_maketables()</b> runs, the tables are built in memory that is
  obtained via <b>pcre_malloc</b>. It is the caller's responsibility to ensure
  that the memory containing the tables remains available for as long as it is
-Line 871 
 table indicating a fixed set of bytes fo
+Line 894 
 table indicating a fixed set of bytes fo
  string, a pointer to the table is returned. Otherwise NULL is returned. The
  fourth argument should point to an <b>unsigned char *</b> variable.
  <pre>
+   PCRE_INFO_JCHANGED
+ </pre>
+ Return 1 if the (?J) option setting is used in the pattern, otherwise 0. The
+ fourth argument should point to an <b>int</b> variable. The (?J) internal option
+ setting changes the local PCRE_DUPNAMES option.
+ <pre>
    PCRE_INFO_LASTLITERAL
  </pre>
  Return the value of the rightmost literal byte that must exist in any matched
-Line 922 
 When writing code to extract data from n
+Line 951 
 When writing code to extract data from n
  name-to-number map, remember that the length of the entries is likely to be
  different for each compiled pattern.
  <pre>
+   PCRE_INFO_OKPARTIAL
+ </pre>
+ Return 1 if the pattern can be used for partial matching, otherwise 0. The
+ fourth argument should point to an <b>int</b> variable. The
+ <a href="pcrepartial.html"><b>pcrepartial</b></a>
+ documentation lists the restrictions that apply to patterns when partial
+ matching is used.
+ <pre>
    PCRE_INFO_OPTIONS
  </pre>
  Return a copy of the options with which the pattern was compiled. The fourth
  argument should point to an <b>unsigned long int</b> variable. These option bits
  are those specified in the call to <b>pcre_compile()</b>, modified by any
- top-level option settings within the pattern itself.
+ top-level option settings at the start of the pattern itself. In other words,
+ they are the options that will be in force when matching starts. For example,
+ if the pattern /(?im)abc(?-i)d/ is compiled with the PCRE_EXTENDED option, the
+ result is PCRE_CASELESS, PCRE_MULTILINE, and PCRE_EXTENDED.
  </P>
  <P>
  A pattern is automatically anchored by PCRE if all of its top-level
-Line 1155 
 matching time.
+Line 1195 
 matching time.
    PCRE_NEWLINE_CR
    PCRE_NEWLINE_LF
    PCRE_NEWLINE_CRLF
+   PCRE_NEWLINE_ANYCRLF
    PCRE_NEWLINE_ANY
  </pre>
  These options override the newline definition that was chosen or defaulted when
-Line 1162 
 the pattern was compiled. For details, s
+Line 1203 
 the pattern was compiled. For details, s
  <b>pcre_compile()</b> above. During matching, the newline choice affects the
  behaviour of the dot, circumflex, and dollar metacharacters. It may also alter
  the way the match position is advanced after a match failure for an unanchored
- pattern. When PCRE_NEWLINE_CRLF or PCRE_NEWLINE_ANY is set, and a match attempt
+ pattern. When PCRE_NEWLINE_CRLF, PCRE_NEWLINE_ANYCRLF, or PCRE_NEWLINE_ANY is
- fails when the current position is at a CRLF sequence, the match position is
+ set, and a match attempt fails when the current position is at a CRLF sequence,
- advanced by two characters instead of one, in other words, to after the CRLF.
+ the match position is advanced by two characters instead of one, in other
+ words, to after the CRLF.
  <pre>
    PCRE_NOTBOL
  </pre>
-Line 1208 
 code that demonstrates how to do this in
+Line 1250 
 code that demonstrates how to do this in
  When PCRE_UTF8 is set at compile time, the validity of the subject as a UTF-8
  string is automatically checked when <b>pcre_exec()</b> is subsequently called.
  The value of <i>startoffset</i> is also checked to ensure that it points to the
- start of a UTF-8 character. If an invalid UTF-8 sequence of bytes is found,
+ start of a UTF-8 character. There is a discussion about the validity of UTF-8
- <b>pcre_exec()</b> returns the error PCRE_ERROR_BADUTF8. If <i>startoffset</i>
+ strings in the
- contains an invalid value, PCRE_ERROR_BADUTF8_OFFSET is returned.
+ <a href="pcre.html#utf8strings">section on UTF-8 support</a>
+ in the main
+ <a href="pcre.html"><b>pcre</b></a>
+ page. If an invalid UTF-8 sequence of bytes is found, <b>pcre_exec()</b> returns
+ the error PCRE_ERROR_BADUTF8. If <i>startoffset</i> contains an invalid value,
+ PCRE_ERROR_BADUTF8_OFFSET is returned.
  </P>
  <P>
  If you already know that your subject is valid, and you want to skip these
-Line 1448 
 The internal recursion limit, as specifi
+Line 1495 
 The internal recursion limit, as specifi
  field in a <b>pcre_extra</b> structure (or defaulted) was reached. See the
  description above.
  <pre>
-   PCRE_ERROR_NULLWSLIMIT    (-22)
- </pre>
- When a group that can match an empty substring is repeated with an unbounded
- upper limit, the subject position at the start of the group must be remembered,
- so that a test for an empty string can be made when the end of the group is
- reached. Some workspace is required for this; if it runs out, this error is
- given.
- <pre>
    PCRE_ERROR_BADNEWLINE     (-23)
  </pre>
  An invalid combination of PCRE_NEWLINE_<i>xxx</i> options was given.
  </P>
  <P>
- Error numbers -16 to -20 are not used by <b>pcre_exec()</b>.
+ Error numbers -16 to -20 and -22 are not used by <b>pcre_exec()</b>.
  </P>
  <br><a name="SEC15" href="#TOC1">EXTRACTING CAPTURED SUBSTRINGS BY NUMBER</a><br>
  <P>
-Line 1607 
 translation table.
+Line 1646 
 translation table.
  </P>
  <P>
  These functions call <b>pcre_get_stringnumber()</b>, and if it succeeds, they
- then call <i>pcre_copy_substring()</i> or <i>pcre_get_substring()</i>, as
+ then call <b>pcre_copy_substring()</b> or <b>pcre_get_substring()</b>, as
- appropriate.
+ appropriate. <b>NOTE:</b> If PCRE_DUPNAMES is set and there are duplicate names,
+ the behaviour may not be what you want (see the next section).
  </P>
  <br><a name="SEC17" href="#TOC1">DUPLICATE SUBPATTERN NAMES</a><br>
  <P>
-Line 1621 
 are not required to be unique. Normally,
+Line 1661 
 are not required to be unique. Normally,
  that in any one match, only one of the named subpatterns participates. An
  example is shown in the
  <a href="pcrepattern.html"><b>pcrepattern</b></a>
- documentation. When duplicates are present, <b>pcre_copy_named_substring()</b>
+ documentation.
- and <b>pcre_get_named_substring()</b> return the first substring corresponding
+ </P>
- to the given name that is set. If none are set, an empty string is returned.
+ <P>
- The <b>pcre_get_stringnumber()</b> function returns one of the numbers that are
+ When duplicates are present, <b>pcre_copy_named_substring()</b> and
- associated with the name, but it is not defined which it is.
+ <b>pcre_get_named_substring()</b> return the first substring corresponding to
- <br>
+ the given name that is set. If none are set, PCRE_ERROR_NOSUBSTRING (-7) is
- <br>
+ returned; no data is returned. The <b>pcre_get_stringnumber()</b> function
+ returns one of the numbers that are associated with the name, but it is not
+ defined which it is.
+ </P>
+ <P>
  If you want to get full details of all captured substrings for a given name,
  you must use the <b>pcre_get_stringtable_entries()</b> function. The first
  argument is the compiled pattern, and the second is the name. The third and
-Line 1839 
 Cambridge CB2 3QH, England.
+Line 1883 
 Cambridge CB2 3QH, England.
  </P>
  <br><a name="SEC22" href="#TOC1">REVISION</a><br>
  <P>
- Last updated: 06 March 2007
+ Last updated: 09 August 2007
  <br>
  Copyright &copy; 1997-2007 University of Cambridge.
  <br>

 Legend:



Removed from v.111
 


changed lines


 
Added in v.211
 Legend:



Removed from v.111
 


changed lines


 
Added in v.211
-Removed from v.111
+Added in v.211

webmaster@exim.org	ViewVC Help
Powered by ViewVC 1.1.12