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

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

Parent Directory | Revision Log | View Patch Patch

-revision 128 by ph10,
Tue Mar 20 11:46:50 2007 UTC
+revision 243 by ph10,
Thu Sep 13 09:28:14 2007 UTC
 Line 218 
 points during a matching operation. Deta
  documentation.
  .
  .
+ .\" HTML <a name="newlines"></a>
  .SH NEWLINES
  .rs
  .sp
- 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
  Each of the first three conventions is used by at least one operating system as
  its standard newline sequence. When PCRE is built, a default can be specified.
-Line 234 
 The default default is LF, which is the
+Line 236 
 The default default is LF, which is the
  default can be overridden, either when a pattern is compiled, or when it is
  matched.
  .P
+ At compile time, the newline convention can be specified by the \fIoptions\fP
+ argument of \fBpcre_compile()\fP, or it can be specified by special text at the
+ start of the pattern itself; this overrides any other settings. See the
+ .\" HREF
+ \fBpcrepattern\fP
+ .\"
+ page for details of the special character sequences.
+ .P
  In the PCRE documentation the word "newline" is used to mean "the character or
  pair of characters that indicate a line break". The choice of newline
  convention affects the handling of the dot, circumflex, and dollar
  metacharacters, the handling of #-comments in /x mode, and, when CRLF is a
  recognized line ending sequence, the match position advancement for a
- non-anchored pattern. The choice of newline convention does not affect the
+ non-anchored pattern. There is more detail about this in the
- interpretation of the \en or \er escape sequences.
+ .\" HTML <a href="#execoptions">
+ .\" </a>
+ section on \fBpcre_exec()\fP options
+ .\"
+ below.
+ .P
+ The choice of newline convention does not affect the interpretation of
+ the \en or \er escape sequences, nor does it affect what \eR matches, which is
+ controlled in a similar way, but by separate options.
  .
  .
  .SH MULTITHREADING
-Line 264 
 which it was compiled. Details are given
+Line 282 
 which it was compiled. Details are given
  .\" HREF
  \fBpcreprecompile\fP
  .\"
- 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.
  .
  .
  .SH "CHECKING BUILD-TIME OPTIONS"
-Line 297 
 properties is available; otherwise it is
+Line 317 
 properties is available; otherwise it is
  .sp
  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.
+ .sp
+   PCRE_CONFIG_BSR
+ .sp
+ The output is an integer whose value indicates what character sequences the \eR
+ escape sequence matches by default. A value of 0 means that \eR matches any
+ Unicode line ending sequence; a value of 1 means that \eR matches only CR, LF,
+ or CRLF. The default can be overridden when a pattern is compiled or matched.
  .sp
    PCRE_CONFIG_LINK_SIZE
  .sp
-Line 441 
 facility, see the
+Line 468 
 facility, see the
  .\"
  documentation.
  .sp
+   PCRE_BSR_ANYCRLF
+   PCRE_BSR_UNICODE
+ .sp
+ These options (which are mutually exclusive) control what the \eR escape
+ sequence matches. The choice is either to match only CR, LF, or CRLF, or to
+ match any Unicode newline sequence. The default is specified when PCRE is
+ built. It can be overridden from within the pattern, or by setting an option
+ when a compiled pattern is matched.
+ .sp
    PCRE_CASELESS
  .sp
  If this bit is set, letters in the pattern match both upper and lower case
-Line 532 
 occurrences of ^ or $ in a pattern, sett
+Line 568 
 occurrences of ^ or $ in a pattern, sett
    PCRE_NEWLINE_CR
    PCRE_NEWLINE_LF
    PCRE_NEWLINE_CRLF
+   PCRE_NEWLINE_ANYCRLF
    PCRE_NEWLINE_ANY
  .sp
  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
  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
  The only time that a line break is specially recognized when compiling a
  pattern is if PCRE_EXTENDED is set, and an unescaped # outside a character
-Line 595 
 page.
+Line 634 
 page.
    PCRE_NO_UTF8_CHECK
  .sp
  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
- \fBpcre_compile()\fP returns an error. If you already know that your pattern is
+ .\" HTML <a href="pcre.html#utf8strings">
- valid, and you want to skip this check for performance reasons, you can set the
+ .\" </a>
- PCRE_NO_UTF8_CHECK option. When it is set, the effect of passing an invalid
+ validity of UTF-8 strings
- UTF-8 string as a pattern is undefined. It may cause your program to crash.
+ .\"
- Note that this option can also be passed to \fBpcre_exec()\fP and
+ in the main
- \fBpcre_dfa_exec()\fP, to suppress the UTF-8 validity checking of subject
+ .\" HREF
- strings.
+ \fBpcre\fP
+ .\"
+ page. If an invalid UTF-8 sequence of bytes is found, \fBpcre_compile()\fP
+ returns an 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 be passed to \fBpcre_exec()\fP and \fBpcre_dfa_exec()\fP, to suppress
+ the UTF-8 validity checking of subject strings.
  .
  .
  .SH "COMPILATION ERROR CODES"
-Line 642 
 out of use. To avoid confusion, they hav
+Line 689 
 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 663 
 out of use. To avoid confusion, they hav
+Line 710 
 out of use. To avoid confusion, they hav
  unknown property name after \eP or \ep
  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 \e377 (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"
+ inconsistent NEWLINE options
+ \eg 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
  .
  .
  .SH "STUDYING A PATTERN"
-Line 729 
 bytes is created.
+Line 779 
 bytes is created.
  .SH "LOCALE SUPPORT"
  .rs
  .sp
- 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 \ew or \ed, but
  can be tested with \ep 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
- An internal set of tables is created in the default C locale when PCRE is
+ Unicode, or use locales, but not try to mix the two.
- built. This is used when the final argument of \fBpcre_compile()\fP 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 \fBpcre_compile()\fP 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
+ 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
  External tables are built by calling the \fBpcre_maketables()\fP function,
  which has no arguments, in the relevant locale. The result can then be passed
-Line 754 
 the following code could be used:
+Line 810 
 the following code could be used:
    tables = pcre_maketables();
    re = pcre_compile(..., tables);
  .sp
+ 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
  When \fBpcre_maketables()\fP runs, the tables are built in memory that is
  obtained via \fBpcre_malloc\fP. It is the caller's responsibility to ensure
  that the memory containing the tables remains available for as long as it is
-Line 856 
 table indicating a fixed set of bytes fo
+Line 915 
 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 \fBunsigned char *\fP variable.
  .sp
+   PCRE_INFO_HASCRORLF
+ .sp
+ Return 1 if the pattern contains any explicit matches for CR or LF characters,
+ otherwise 0. The fourth argument should point to an \fBint\fP variable. An
+ explicit match is either a literal CR or LF character, or \er or \en.
+ .sp
+   PCRE_INFO_JCHANGED
+ .sp
+ Return 1 if the (?J) option setting is used in the pattern, otherwise 0. The
+ fourth argument should point to an \fBint\fP variable. The (?J) internal option
+ setting changes the local PCRE_DUPNAMES option.
+ .sp
    PCRE_INFO_LASTLITERAL
  .sp
  Return the value of the rightmost literal byte that must exist in any matched
-Line 908 
 When writing code to extract data from n
+Line 979 
 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.
  .sp
+   PCRE_INFO_OKPARTIAL
+ .sp
+ Return 1 if the pattern can be used for partial matching, otherwise 0. The
+ fourth argument should point to an \fBint\fP variable. The
+ .\" HREF
+ \fBpcrepartial\fP
+ .\"
+ documentation lists the restrictions that apply to patterns when partial
+ matching is used.
+ .sp
    PCRE_INFO_OPTIONS
  .sp
  Return a copy of the options with which the pattern was compiled. The fourth
  argument should point to an \fBunsigned long int\fP variable. These option bits
  are those specified in the call to \fBpcre_compile()\fP, 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
  A pattern is automatically anchored by PCRE if all of its top-level
  alternatives begin with one of the following:
-Line 1124 
 called. See the
+Line 1208 
 called. See the
  .\"
  documentation for a discussion of saving compiled patterns for later use.
  .
+ .\" HTML <a name="execoptions"></a>
  .SS "Option bits for \fBpcre_exec()\fP"
  .rs
  .sp
-Line 1138 
 matching position. If a pattern was comp
+Line 1223 
 matching position. If a pattern was comp
  to be anchored by virtue of its contents, it cannot be made unachored at
  matching time.
  .sp
+   PCRE_BSR_ANYCRLF
+   PCRE_BSR_UNICODE
+ .sp
+ These options (which are mutually exclusive) control what the \eR escape
+ sequence matches. The choice is either to match only CR, LF, or CRLF, or to
+ match any Unicode newline sequence. These options override the choice that was
+ made or defaulted when the pattern was compiled.
+ .sp
    PCRE_NEWLINE_CR
    PCRE_NEWLINE_LF
    PCRE_NEWLINE_CRLF
+   PCRE_NEWLINE_ANYCRLF
    PCRE_NEWLINE_ANY
  .sp
  These options override the newline definition that was chosen or defaulted when
-Line 1148 
 the pattern was compiled. For details, s
+Line 1242 
 the pattern was compiled. For details, s
  \fBpcre_compile()\fP 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.
- fails when the current position is at a CRLF sequence, the match position is
+ .P
- advanced by two characters instead of one, in other words, to after the CRLF.
+ When PCRE_NEWLINE_CRLF, PCRE_NEWLINE_ANYCRLF, or PCRE_NEWLINE_ANY is set, and a
+ match attempt for an unanchored pattern fails when the current position is at a
+ CRLF sequence, and the pattern contains no explicit matches for CR or LF
+ characters, the match position is advanced by two characters instead of one, in
+ other words, to after the CRLF.
+ .P
+ The above rule is a compromise that makes the most common cases work as
+ expected. For example, if the pattern is .+A (and the PCRE_DOTALL option is not
+ set), it does not match the string "\er\enA" because, after failing at the
+ start, it skips both the CR and the LF before retrying. However, the pattern
+ [\er\en]A does match that string, because it contains an explicit CR or LF
+ reference, and so advances only by one character after the first failure.
+ .P
+ An explicit match for CR of LF is either a literal appearance of one of those
+ characters, or one of the \er or \en escape sequences. Implicit matches such as
+ [^X] do not count, nor does \es (which includes CR and LF in the characters
+ that it matches).
+ .P
+ Notwithstanding the above, anomalous effects may still occur when CRLF is a
+ valid newline sequence and explicit \er or \en escapes appear in the pattern.
  .sp
    PCRE_NOTBOL
  .sp
-Line 1193 
 code that demonstrates how to do this in
+Line 1306 
 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 \fBpcre_exec()\fP is subsequently called.
  The value of \fIstartoffset\fP 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
- \fBpcre_exec()\fP returns the error PCRE_ERROR_BADUTF8. If \fIstartoffset\fP
+ strings in the
- contains an invalid value, PCRE_ERROR_BADUTF8_OFFSET is returned.
+ .\" HTML <a href="pcre.html#utf8strings">
+ .\" </a>
+ section on UTF-8 support
+ .\"
+ in the main
+ .\" HREF
+ \fBpcre\fP
+ .\"
+ page. If an invalid UTF-8 sequence of bytes is found, \fBpcre_exec()\fP returns
+ the error PCRE_ERROR_BADUTF8. If \fIstartoffset\fP contains an invalid value,
+ PCRE_ERROR_BADUTF8_OFFSET is returned.
  .P
  If you already know that your subject is valid, and you want to skip these
  checks for performance reasons, you can set the PCRE_NO_UTF8_CHECK option when
-Line 1427 
 The internal recursion limit, as specifi
+Line 1550 
 The internal recursion limit, as specifi
  field in a \fBpcre_extra\fP structure (or defaulted) was reached. See the
  description above.
  .sp
-   PCRE_ERROR_NULLWSLIMIT    (-22)
- .sp
- 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.
- .sp
    PCRE_ERROR_BADNEWLINE     (-23)
  .sp
  An invalid combination of PCRE_NEWLINE_\fIxxx\fP options was given.
  .P
- Error numbers -16 to -20 are not used by \fBpcre_exec()\fP.
+ Error numbers -16 to -20 and -22 are not used by \fBpcre_exec()\fP.
  .
  .
  .SH "EXTRACTING CAPTURED SUBSTRINGS BY NUMBER"
-Line 1604 
 example is shown in the
+Line 1719 
 example is shown in the
  .\" HREF
  \fBpcrepattern\fP
  .\"
- documentation. When duplicates are present, \fBpcre_copy_named_substring()\fP
+ documentation.
- and \fBpcre_get_named_substring()\fP return the first substring corresponding
+ .P
- to the given name that is set. If none are set, an empty string is returned.
+ When duplicates are present, \fBpcre_copy_named_substring()\fP and
- The \fBpcre_get_stringnumber()\fP function returns one of the numbers that are
+ \fBpcre_get_named_substring()\fP return the first substring corresponding to
- associated with the name, but it is not defined which it is.
+ the given name that is set. If none are set, PCRE_ERROR_NOSUBSTRING (-7) is
- .sp
+ returned; no data is returned. The \fBpcre_get_stringnumber()\fP function
+ returns one of the numbers that are associated with the name, but it is not
+ defined which it is.
+ .P
  If you want to get full details of all captured substrings for a given name,
  you must use the \fBpcre_get_stringtable_entries()\fP function. The first
  argument is the compiled pattern, and the second is the name. The third and
-Line 1834 
 Cambridge CB2 3QH, England.
+Line 1952 
 Cambridge CB2 3QH, England.
  .rs
  .sp
  .nf
- Last updated: 06 March 2007
+ Last updated: 11 September 2007
  Copyright (c) 1997-2007 University of Cambridge.
  .fi

 Legend:



Removed from v.128
 


changed lines


 
Added in v.243
 Legend:



Removed from v.128
 


changed lines


 
Added in v.243
-Removed from v.128
+Added in v.243

webmaster@exim.org	ViewVC Help
Powered by ViewVC 1.1.12