218 |
documentation. |
documentation. |
219 |
. |
. |
220 |
. |
. |
221 |
|
.\" HTML <a name="newlines"></a> |
222 |
.SH NEWLINES |
.SH NEWLINES |
223 |
.rs |
.rs |
224 |
.sp |
.sp |
236 |
default can be overridden, either when a pattern is compiled, or when it is |
default can be overridden, either when a pattern is compiled, or when it is |
237 |
matched. |
matched. |
238 |
.P |
.P |
239 |
|
At compile time, the newline convention can be specified by the \fIoptions\fP |
240 |
|
argument of \fBpcre_compile()\fP, or it can be specified by special text at the |
241 |
|
start of the pattern itself; this overrides any other settings. See the |
242 |
|
.\" HREF |
243 |
|
\fBpcrepattern\fP |
244 |
|
.\" |
245 |
|
page for details of the special character sequences. |
246 |
|
.P |
247 |
In the PCRE documentation the word "newline" is used to mean "the character or |
In the PCRE documentation the word "newline" is used to mean "the character or |
248 |
pair of characters that indicate a line break". The choice of newline |
pair of characters that indicate a line break". The choice of newline |
249 |
convention affects the handling of the dot, circumflex, and dollar |
convention affects the handling of the dot, circumflex, and dollar |
250 |
metacharacters, the handling of #-comments in /x mode, and, when CRLF is a |
metacharacters, the handling of #-comments in /x mode, and, when CRLF is a |
251 |
recognized line ending sequence, the match position advancement for a |
recognized line ending sequence, the match position advancement for a |
252 |
non-anchored pattern. The choice of newline convention does not affect the |
non-anchored pattern. There is more detail about this in the |
253 |
interpretation of the \en or \er escape sequences. |
.\" HTML <a href="#execoptions"> |
254 |
|
.\" </a> |
255 |
|
section on \fBpcre_exec()\fP options |
256 |
|
.\" |
257 |
|
below. The choice of newline convention does not affect the interpretation of |
258 |
|
the \en or \er escape sequences. |
259 |
. |
. |
260 |
. |
. |
261 |
.SH MULTITHREADING |
.SH MULTITHREADING |
615 |
PCRE_NO_UTF8_CHECK |
PCRE_NO_UTF8_CHECK |
616 |
.sp |
.sp |
617 |
When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 string is |
When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 string is |
618 |
automatically checked. If an invalid UTF-8 sequence of bytes is found, |
automatically checked. There is a discussion about the |
619 |
\fBpcre_compile()\fP returns an error. If you already know that your pattern is |
.\" HTML <a href="pcre.html#utf8strings"> |
620 |
valid, and you want to skip this check for performance reasons, you can set the |
.\" </a> |
621 |
PCRE_NO_UTF8_CHECK option. When it is set, the effect of passing an invalid |
validity of UTF-8 strings |
622 |
UTF-8 string as a pattern is undefined. It may cause your program to crash. |
.\" |
623 |
Note that this option can also be passed to \fBpcre_exec()\fP and |
in the main |
624 |
\fBpcre_dfa_exec()\fP, to suppress the UTF-8 validity checking of subject |
.\" HREF |
625 |
strings. |
\fBpcre\fP |
626 |
|
.\" |
627 |
|
page. If an invalid UTF-8 sequence of bytes is found, \fBpcre_compile()\fP |
628 |
|
returns an error. If you already know that your pattern is valid, and you want |
629 |
|
to skip this check for performance reasons, you can set the PCRE_NO_UTF8_CHECK |
630 |
|
option. When it is set, the effect of passing an invalid UTF-8 string as a |
631 |
|
pattern is undefined. It may cause your program to crash. Note that this option |
632 |
|
can also be passed to \fBpcre_exec()\fP and \fBpcre_dfa_exec()\fP, to suppress |
633 |
|
the UTF-8 validity checking of subject strings. |
634 |
. |
. |
635 |
. |
. |
636 |
.SH "COMPILATION ERROR CODES" |
.SH "COMPILATION ERROR CODES" |
670 |
26 malformed number or name after (?( |
26 malformed number or name after (?( |
671 |
27 conditional group contains more than two branches |
27 conditional group contains more than two branches |
672 |
28 assertion expected after (?( |
28 assertion expected after (?( |
673 |
29 (?R or (?digits must be followed by ) |
29 (?R or (?[+-]digits must be followed by ) |
674 |
30 unknown POSIX class name |
30 unknown POSIX class name |
675 |
31 POSIX collating elements are not supported |
31 POSIX collating elements are not supported |
676 |
32 this version of PCRE is not compiled with PCRE_UTF8 support |
32 this version of PCRE is not compiled with PCRE_UTF8 support |
691 |
47 unknown property name after \eP or \ep |
47 unknown property name after \eP or \ep |
692 |
48 subpattern name is too long (maximum 32 characters) |
48 subpattern name is too long (maximum 32 characters) |
693 |
49 too many named subpatterns (maximum 10,000) |
49 too many named subpatterns (maximum 10,000) |
694 |
50 repeated subpattern is too long |
50 [this code is not in use] |
695 |
51 octal value is greater than \e377 (not in UTF-8 mode) |
51 octal value is greater than \e377 (not in UTF-8 mode) |
696 |
52 internal error: overran compiling workspace |
52 internal error: overran compiling workspace |
697 |
53 internal error: previously-checked referenced subpattern not found |
53 internal error: previously-checked referenced subpattern not found |
698 |
54 DEFINE group contains more than one branch |
54 DEFINE group contains more than one branch |
699 |
55 repeating a DEFINE group is not allowed |
55 repeating a DEFINE group is not allowed |
700 |
56 inconsistent NEWLINE options" |
56 inconsistent NEWLINE options" |
701 |
|
57 \eg is not followed by a braced name or an optionally braced |
702 |
|
non-zero number |
703 |
|
58 (?+ or (?- or (?(+ or (?(- must be followed by a non-zero number |
704 |
. |
. |
705 |
. |
. |
706 |
.SH "STUDYING A PATTERN" |
.SH "STUDYING A PATTERN" |
896 |
string, a pointer to the table is returned. Otherwise NULL is returned. The |
string, a pointer to the table is returned. Otherwise NULL is returned. The |
897 |
fourth argument should point to an \fBunsigned char *\fP variable. |
fourth argument should point to an \fBunsigned char *\fP variable. |
898 |
.sp |
.sp |
899 |
|
PCRE_INFO_HASCRORLF |
900 |
|
.sp |
901 |
|
Return 1 if the pattern contains any explicit matches for CR or LF characters, |
902 |
|
otherwise 0. The fourth argument should point to an \fBint\fP variable. |
903 |
|
.sp |
904 |
|
PCRE_INFO_JCHANGED |
905 |
|
.sp |
906 |
|
Return 1 if the (?J) option setting is used in the pattern, otherwise 0. The |
907 |
|
fourth argument should point to an \fBint\fP variable. The (?J) internal option |
908 |
|
setting changes the local PCRE_DUPNAMES option. |
909 |
|
.sp |
910 |
PCRE_INFO_LASTLITERAL |
PCRE_INFO_LASTLITERAL |
911 |
.sp |
.sp |
912 |
Return the value of the rightmost literal byte that must exist in any matched |
Return the value of the rightmost literal byte that must exist in any matched |
959 |
name-to-number map, remember that the length of the entries is likely to be |
name-to-number map, remember that the length of the entries is likely to be |
960 |
different for each compiled pattern. |
different for each compiled pattern. |
961 |
.sp |
.sp |
962 |
|
PCRE_INFO_OKPARTIAL |
963 |
|
.sp |
964 |
|
Return 1 if the pattern can be used for partial matching, otherwise 0. The |
965 |
|
fourth argument should point to an \fBint\fP variable. The |
966 |
|
.\" HREF |
967 |
|
\fBpcrepartial\fP |
968 |
|
.\" |
969 |
|
documentation lists the restrictions that apply to patterns when partial |
970 |
|
matching is used. |
971 |
|
.sp |
972 |
PCRE_INFO_OPTIONS |
PCRE_INFO_OPTIONS |
973 |
.sp |
.sp |
974 |
Return a copy of the options with which the pattern was compiled. The fourth |
Return a copy of the options with which the pattern was compiled. The fourth |
975 |
argument should point to an \fBunsigned long int\fP variable. These option bits |
argument should point to an \fBunsigned long int\fP variable. These option bits |
976 |
are those specified in the call to \fBpcre_compile()\fP, modified by any |
are those specified in the call to \fBpcre_compile()\fP, modified by any |
977 |
top-level option settings within the pattern itself. |
top-level option settings at the start of the pattern itself. In other words, |
978 |
|
they are the options that will be in force when matching starts. For example, |
979 |
|
if the pattern /(?im)abc(?-i)d/ is compiled with the PCRE_EXTENDED option, the |
980 |
|
result is PCRE_CASELESS, PCRE_MULTILINE, and PCRE_EXTENDED. |
981 |
.P |
.P |
982 |
A pattern is automatically anchored by PCRE if all of its top-level |
A pattern is automatically anchored by PCRE if all of its top-level |
983 |
alternatives begin with one of the following: |
alternatives begin with one of the following: |
1188 |
.\" |
.\" |
1189 |
documentation for a discussion of saving compiled patterns for later use. |
documentation for a discussion of saving compiled patterns for later use. |
1190 |
. |
. |
1191 |
|
.\" HTML <a name="execoptions"></a> |
1192 |
.SS "Option bits for \fBpcre_exec()\fP" |
.SS "Option bits for \fBpcre_exec()\fP" |
1193 |
.rs |
.rs |
1194 |
.sp |
.sp |
1214 |
\fBpcre_compile()\fP above. During matching, the newline choice affects the |
\fBpcre_compile()\fP above. During matching, the newline choice affects the |
1215 |
behaviour of the dot, circumflex, and dollar metacharacters. It may also alter |
behaviour of the dot, circumflex, and dollar metacharacters. It may also alter |
1216 |
the way the match position is advanced after a match failure for an unanchored |
the way the match position is advanced after a match failure for an unanchored |
1217 |
pattern. When PCRE_NEWLINE_CRLF, PCRE_NEWLINE_ANYCRLF, or PCRE_NEWLINE_ANY is |
pattern. |
1218 |
set, and a match attempt fails when the current position is at a CRLF sequence, |
.P |
1219 |
the match position is advanced by two characters instead of one, in other |
When PCRE_NEWLINE_CRLF, PCRE_NEWLINE_ANYCRLF, or PCRE_NEWLINE_ANY is set, and a |
1220 |
words, to after the CRLF. |
match attempt for an unanchored pattern fails when the current position is at a |
1221 |
|
CRLF sequence, and the pattern contains no explicit matches for CR or LF |
1222 |
|
characters, the match position is advanced by two characters instead of one, in |
1223 |
|
other words, to after the CRLF. |
1224 |
|
.P |
1225 |
|
The above rule is a compromise that makes the most common cases work as |
1226 |
|
expected. For example, if the pattern is .+A (and the PCRE_DOTALL option is not |
1227 |
|
set), it does not match the string "\er\enA" because, after failing at the |
1228 |
|
start, it skips both the CR and the LF before retrying. However, the pattern |
1229 |
|
[\er\en]A does match that string, because it contains an explicit CR or LF |
1230 |
|
reference, and so advances only by one character after the first failure. |
1231 |
|
.P |
1232 |
|
An explicit match for CR of LF is either a literal appearance of one of those |
1233 |
|
characters, or one of the \er or \en escape sequences. Implicit matches such as |
1234 |
|
[^X] do not count, nor does \es (which includes CR and LF in the characters |
1235 |
|
that it matches). |
1236 |
|
.P |
1237 |
|
Notwithstanding the above, anomalous effects may still occur when CRLF is a |
1238 |
|
valid newline sequence and explicit \er or \en escapes appear in the pattern. |
1239 |
.sp |
.sp |
1240 |
PCRE_NOTBOL |
PCRE_NOTBOL |
1241 |
.sp |
.sp |
1278 |
When PCRE_UTF8 is set at compile time, the validity of the subject as a UTF-8 |
When PCRE_UTF8 is set at compile time, the validity of the subject as a UTF-8 |
1279 |
string is automatically checked when \fBpcre_exec()\fP is subsequently called. |
string is automatically checked when \fBpcre_exec()\fP is subsequently called. |
1280 |
The value of \fIstartoffset\fP is also checked to ensure that it points to the |
The value of \fIstartoffset\fP is also checked to ensure that it points to the |
1281 |
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 |
1282 |
\fBpcre_exec()\fP returns the error PCRE_ERROR_BADUTF8. If \fIstartoffset\fP |
strings in the |
1283 |
contains an invalid value, PCRE_ERROR_BADUTF8_OFFSET is returned. |
.\" HTML <a href="pcre.html#utf8strings"> |
1284 |
|
.\" </a> |
1285 |
|
section on UTF-8 support |
1286 |
|
.\" |
1287 |
|
in the main |
1288 |
|
.\" HREF |
1289 |
|
\fBpcre\fP |
1290 |
|
.\" |
1291 |
|
page. If an invalid UTF-8 sequence of bytes is found, \fBpcre_exec()\fP returns |
1292 |
|
the error PCRE_ERROR_BADUTF8. If \fIstartoffset\fP contains an invalid value, |
1293 |
|
PCRE_ERROR_BADUTF8_OFFSET is returned. |
1294 |
.P |
.P |
1295 |
If you already know that your subject is valid, and you want to skip these |
If you already know that your subject is valid, and you want to skip these |
1296 |
checks for performance reasons, you can set the PCRE_NO_UTF8_CHECK option when |
checks for performance reasons, you can set the PCRE_NO_UTF8_CHECK option when |
1522 |
field in a \fBpcre_extra\fP structure (or defaulted) was reached. See the |
field in a \fBpcre_extra\fP structure (or defaulted) was reached. See the |
1523 |
description above. |
description above. |
1524 |
.sp |
.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 |
|
1525 |
PCRE_ERROR_BADNEWLINE (-23) |
PCRE_ERROR_BADNEWLINE (-23) |
1526 |
.sp |
.sp |
1527 |
An invalid combination of PCRE_NEWLINE_\fIxxx\fP options was given. |
An invalid combination of PCRE_NEWLINE_\fIxxx\fP options was given. |
1528 |
.P |
.P |
1529 |
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. |
1530 |
. |
. |
1531 |
. |
. |
1532 |
.SH "EXTRACTING CAPTURED SUBSTRINGS BY NUMBER" |
.SH "EXTRACTING CAPTURED SUBSTRINGS BY NUMBER" |
1691 |
.\" HREF |
.\" HREF |
1692 |
\fBpcrepattern\fP |
\fBpcrepattern\fP |
1693 |
.\" |
.\" |
1694 |
documentation. When duplicates are present, \fBpcre_copy_named_substring()\fP |
documentation. |
1695 |
and \fBpcre_get_named_substring()\fP return the first substring corresponding |
.P |
1696 |
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 |
1697 |
The \fBpcre_get_stringnumber()\fP function returns one of the numbers that are |
\fBpcre_get_named_substring()\fP return the first substring corresponding to |
1698 |
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 |
1699 |
.sp |
returned; no data is returned. The \fBpcre_get_stringnumber()\fP function |
1700 |
|
returns one of the numbers that are associated with the name, but it is not |
1701 |
|
defined which it is. |
1702 |
|
.P |
1703 |
If you want to get full details of all captured substrings for a given name, |
If you want to get full details of all captured substrings for a given name, |
1704 |
you must use the \fBpcre_get_stringtable_entries()\fP function. The first |
you must use the \fBpcre_get_stringtable_entries()\fP function. The first |
1705 |
argument is the compiled pattern, and the second is the name. The third and |
argument is the compiled pattern, and the second is the name. The third and |
1924 |
.rs |
.rs |
1925 |
.sp |
.sp |
1926 |
.nf |
.nf |
1927 |
Last updated: 24 April 2007 |
Last updated: 10 September 2007 |
1928 |
Copyright (c) 1997-2007 University of Cambridge. |
Copyright (c) 1997-2007 University of Cambridge. |
1929 |
.fi |
.fi |