diff options
| author | ph10 <ph10@2f5784b3-3f2a-0410-8824-cb99058d5e15> | 2009-03-17 21:30:30 +0000 |
|---|---|---|
| committer | ph10 <ph10@2f5784b3-3f2a-0410-8824-cb99058d5e15> | 2009-03-17 21:30:30 +0000 |
| commit | a83b1e0fa77f854d51e40f8fda3b62ecee7bcbf1 (patch) | |
| tree | 023ec8b0b3251ac24965726211ea44d7d8c5ff99 | |
| parent | f6cacbfecd16ac9d19ee6fe6c26c107ee4846b1c (diff) | |
| download | pcre-a83b1e0fa77f854d51e40f8fda3b62ecee7bcbf1.tar.gz | |
Update after detrailing for a test release.
git-svn-id: svn://vcs.exim.org/pcre/code/trunk@392 2f5784b3-3f2a-0410-8824-cb99058d5e15
| -rw-r--r-- | ChangeLog | 62 | ||||
| -rw-r--r-- | NON-UNIX-USE | 6 | ||||
| -rw-r--r-- | README | 10 | ||||
| -rw-r--r-- | configure.ac | 4 | ||||
| -rw-r--r-- | doc/html/pcre_dfa_exec.html | 1 | ||||
| -rw-r--r-- | doc/html/pcre_exec.html | 1 | ||||
| -rw-r--r-- | doc/html/pcreapi.html | 33 | ||||
| -rw-r--r-- | doc/html/pcrebuild.html | 20 | ||||
| -rw-r--r-- | doc/html/pcrecallout.html | 13 | ||||
| -rw-r--r-- | doc/html/pcrecpp.html | 7 | ||||
| -rw-r--r-- | doc/html/pcregrep.html | 77 | ||||
| -rw-r--r-- | doc/html/pcrepattern.html | 9 | ||||
| -rw-r--r-- | doc/html/pcreposix.html | 20 | ||||
| -rw-r--r-- | doc/html/pcretest.html | 10 | ||||
| -rw-r--r-- | doc/pcre.txt | 1809 | ||||
| -rw-r--r-- | doc/pcre_dfa_exec.3 | 2 | ||||
| -rw-r--r-- | doc/pcre_exec.3 | 2 | ||||
| -rw-r--r-- | doc/pcreapi.3 | 8 | ||||
| -rw-r--r-- | doc/pcrebuild.3 | 10 | ||||
| -rw-r--r-- | doc/pcrecallout.3 | 6 | ||||
| -rw-r--r-- | doc/pcrecpp.3 | 4 | ||||
| -rw-r--r-- | doc/pcregrep.1 | 14 | ||||
| -rw-r--r-- | doc/pcregrep.txt | 264 | ||||
| -rw-r--r-- | doc/pcreposix.3 | 4 | ||||
| -rw-r--r-- | doc/pcretest.1 | 2 | ||||
| -rw-r--r-- | doc/pcretest.txt | 189 | ||||
| -rw-r--r-- | pcre.h.in | 2 | ||||
| -rw-r--r-- | pcre_compile.c | 142 | ||||
| -rw-r--r-- | pcre_dfa_exec.c | 30 | ||||
| -rw-r--r-- | pcre_exec.c | 32 | ||||
| -rw-r--r-- | pcre_internal.h | 18 | ||||
| -rw-r--r-- | pcre_tables.c | 4 | ||||
| -rw-r--r-- | pcrecpp.h | 4 | ||||
| -rw-r--r-- | pcregrep.c | 32 | ||||
| -rw-r--r-- | pcretest.c | 12 |
35 files changed, 1501 insertions, 1362 deletions
@@ -4,66 +4,66 @@ ChangeLog for PCRE Version 7.9 xx-xxx-09 --------------------- -1. When building with support for bzlib/zlib (pcregrep) and/or readline +1. When building with support for bzlib/zlib (pcregrep) and/or readline (pcretest), all targets were linked against these libraries. This included libpcre, libpcreposix, and libpcrecpp, even though they do not use these libraries. This caused unwanted dependencies to be created. This problem - has been fixed, and now only pcregrep is linked with bzlib/zlib and only + has been fixed, and now only pcregrep is linked with bzlib/zlib and only pcretest is linked with readline. - + 2. The "typedef int BOOL" in pcre_internal.h that was included inside the "#ifndef FALSE" condition by an earlier change (probably 7.8/18) has been moved outside it again, because FALSE and TRUE are already defined in AIX, but BOOL is not. - -3. The pcre_config() function was treating the PCRE_MATCH_LIMIT and + +3. The pcre_config() function was treating the PCRE_MATCH_LIMIT and PCRE_MATCH_LIMIT_RETURSION values as ints, when they should be long ints. - + 4. The pcregrep documentation said spaces were inserted as well as colons (or hyphens) following file names and line numbers when outputting matching - lines. This is not true; no spaces are inserted. I have also clarified the + lines. This is not true; no spaces are inserted. I have also clarified the wording for the --colour (or --color) option. - + 5. In pcregrep, when --colour was used with -o, the list of matching strings was not coloured; this is different to GNU grep, so I have changed it to be the same. - + 6. When --colo(u)r was used in pcregrep, only the first matching substring in - each matching line was coloured. Now it goes on to look for further matches - of any of the test patterns, which is the same behaviour as GNU grep. - -7. A pattern that could match an empty string could cause pcregrep to loop; it - doesn't make sense to accept an empty string match in pcregrep, so I have + each matching line was coloured. Now it goes on to look for further matches + of any of the test patterns, which is the same behaviour as GNU grep. + +7. A pattern that could match an empty string could cause pcregrep to loop; it + doesn't make sense to accept an empty string match in pcregrep, so I have locked it out (using PCRE's PCRE_NOTEMPTY option). By experiment, this seems to be how GNU grep behaves. - + 8. The pattern (?(?=.*b)b|^) was incorrectly compiled as "match must be at - start or after a newline", because the conditional assertion was not being - correctly handled. The rule now is that both the assertion and what follows - in the first alternative must satisfy the test. - -9. If auto-callout was enabled in a pattern with a conditional group, PCRE + start or after a newline", because the conditional assertion was not being + correctly handled. The rule now is that both the assertion and what follows + in the first alternative must satisfy the test. + +9. If auto-callout was enabled in a pattern with a conditional group, PCRE could crash during matching. - -10. The PCRE_DOLLAR_ENDONLY option was not working when pcre_dfa_exec() was - used for matching. - -11. Unicode property support in character classes was not working for + +10. The PCRE_DOLLAR_ENDONLY option was not working when pcre_dfa_exec() was + used for matching. + +11. Unicode property support in character classes was not working for characters (bytes) greater than 127 when not in UTF-8 mode. - -12. Added the -M command line option to pcretest. + +12. Added the -M command line option to pcretest. 14. Added the non-standard REG_NOTEMPTY option to the POSIX interface. 15. Added the PCRE_NO_START_OPTIMIZE match-time option. -16. Added comments and documentation about mis-use of no_arg in the C++ +16. Added comments and documentation about mis-use of no_arg in the C++ wrapper. - + 17. Implemented support for UTF-8 encoding in EBCDIC environments, a patch - from Martin Jerabek that uses macro names for all relevant character and + from Martin Jerabek that uses macro names for all relevant character and string constants. - + Version 7.8 05-Sep-08 --------------------- diff --git a/NON-UNIX-USE b/NON-UNIX-USE index 958ee51..ca47c05 100644 --- a/NON-UNIX-USE +++ b/NON-UNIX-USE @@ -371,12 +371,12 @@ Michael Roy sent these comments about building PCRE under Windows with BCC5.5: When linking a project with BCC5.5, pcre.lib must be included before any of the libraries cw32.lib, cw32i.lib, cw32mt.lib, and cw32mti.lib on the command line. - + BUILDING UNDER WINDOWS CE WITH VISUAL STUDIO 200x -Vincent Richomme sent a zip archive of files to help with this process. They -can be found in the file "pcre-vsbuild.zip" in the Contrib directory of the FTP +Vincent Richomme sent a zip archive of files to help with this process. They +can be found in the file "pcre-vsbuild.zip" in the Contrib directory of the FTP site. @@ -262,8 +262,8 @@ library. You can read more about them in the pcrebuild man page. --enable-ebcdic - This automatically implies --enable-rebuild-chartables (see above). However, - when PCRE is built this way, it always operates in EBCDIC. It cannot support + This automatically implies --enable-rebuild-chartables (see above). However, + when PCRE is built this way, it always operates in EBCDIC. It cannot support both EBCDIC and UTF-8. . It is possible to compile pcregrep to use libz and/or libbz2, in order to @@ -291,9 +291,9 @@ library. You can read more about them in the pcrebuild man page. to specify something like LIBS="-lncurses" as well. This is because, to quote the readline INSTALL, "Readline uses the termcap functions, but does not link with the termcap or curses library itself, allowing applications which link - with readline the to choose an appropriate library." If you get error - messages about missing functions tgetstr, tgetent, tputs, tgetflag, or tgoto, - this is the problem, and linking with the ncurses library should fix it. + with readline the to choose an appropriate library." If you get error + messages about missing functions tgetstr, tgetent, tputs, tgetflag, or tgoto, + this is the problem, and linking with the ncurses library should fix it. The "configure" script builds the following files for the basic C library: diff --git a/configure.ac b/configure.ac index 7b7c46f..cf850be 100644 --- a/configure.ac +++ b/configure.ac @@ -513,8 +513,8 @@ if test "$enable_ebcdic" = "yes"; then If you are compiling for a system that uses EBCDIC instead of ASCII character codes, define this macro as 1. On systems that can use "configure", this can be done via --enable-ebcdic. PCRE will then - assume that all input strings are in EBCDIC. If you do not define - this macro, PCRE will assume input strings are ASCII or UTF-8 Unicode. + assume that all input strings are in EBCDIC. If you do not define + this macro, PCRE will assume input strings are ASCII or UTF-8 Unicode. It is not possible to build a version of PCRE that supports both EBCDIC and UTF-8.]) fi diff --git a/doc/html/pcre_dfa_exec.html b/doc/html/pcre_dfa_exec.html index 02e7c8d..a243ee8 100644 --- a/doc/html/pcre_dfa_exec.html +++ b/doc/html/pcre_dfa_exec.html @@ -59,6 +59,7 @@ The options are: PCRE_NOTBOL Subject is not the beginning of a line PCRE_NOTEOL Subject is not the end of a line PCRE_NOTEMPTY An empty string is not a valid match + PCRE_NO_START_OPTIMIZE Do not do "start-match" optimizations PCRE_NO_UTF8_CHECK Do not check the subject for UTF-8 validity (only relevant if PCRE_UTF8 was set at compile time) diff --git a/doc/html/pcre_exec.html b/doc/html/pcre_exec.html index 86dcc02..ef43830 100644 --- a/doc/html/pcre_exec.html +++ b/doc/html/pcre_exec.html @@ -55,6 +55,7 @@ The options are: PCRE_NOTBOL Subject is not the beginning of a line PCRE_NOTEOL Subject is not the end of a line PCRE_NOTEMPTY An empty string is not a valid match + PCRE_NO_START_OPTIMIZE Do not do "start-match" optimizations PCRE_NO_UTF8_CHECK Do not check the subject for UTF-8 validity (only relevant if PCRE_UTF8 was set at compile time) diff --git a/doc/html/pcreapi.html b/doc/html/pcreapi.html index d6a1612..59ae9b3 100644 --- a/doc/html/pcreapi.html +++ b/doc/html/pcreapi.html @@ -333,8 +333,10 @@ properties is available; otherwise it is set to zero. </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, -2 for ANYCRLF, and -1 for ANY. The -default should normally be the standard sequence for your operating system. +are: 10 for LF, 13 for CR, 3338 for CRLF, -2 for ANYCRLF, and -1 for ANY. +Though they are derived from ASCII, the same values are returned in EBCDIC +environments. The default should normally correspond to the standard sequence +for your operating system. <pre> PCRE_CONFIG_BSR </pre> @@ -361,13 +363,13 @@ documentation. <pre> PCRE_CONFIG_MATCH_LIMIT </pre> -The output is an integer that gives the default limit for the number of +The output is a long integer that gives the default limit for the number of internal matching function calls in a <b>pcre_exec()</b> execution. Further details are given with <b>pcre_exec()</b> below. <pre> PCRE_CONFIG_MATCH_LIMIT_RECURSION </pre> -The output is an integer that gives the default limit for the depth of +The output is a long integer that gives the default limit for the depth of recursion when calling the internal matching function in a <b>pcre_exec()</b> execution. Further details are given with <b>pcre_exec()</b> below. <pre> @@ -1242,7 +1244,8 @@ Option bits for <b>pcre_exec()</b> <P> The unused bits of the <i>options</i> argument for <b>pcre_exec()</b> must be zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_<i>xxx</i>, -PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NO_UTF8_CHECK and PCRE_PARTIAL. +PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NO_START_OPTIMIZE, +PCRE_NO_UTF8_CHECK and PCRE_PARTIAL. <pre> PCRE_ANCHORED </pre> @@ -1334,6 +1337,16 @@ PCRE_NOTEMPTY and PCRE_ANCHORED, and then if that fails by advancing the starting offset (see below) and trying an ordinary match again. There is some code that demonstrates how to do this in the <i>pcredemo.c</i> sample program. <pre> + PCRE_NO_START_OPTIMIZE +</pre> +There are a number of optimizations that <b>pcre_exec()</b> uses at the start of +a match, in order to speed up the process. For example, if it is known that a +match must start with a specific character, it searches the subject for that +character, and fails immediately if it cannot find it, without actually running +the main matching function. When callouts are in use, these optimizations can +cause them to be skipped. This option disables the "start-up" optimizations, +causing performance to suffer, but ensuring that the callouts do occur. +<pre> PCRE_NO_UTF8_CHECK </pre> When PCRE_UTF8 is set at compile time, the validity of the subject as a UTF-8 @@ -1743,6 +1756,12 @@ then call <b>pcre_copy_substring()</b> or <b>pcre_get_substring()</b>, as 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> +<P> +<b>Warning:</b> If the pattern uses the "(?|" feature to set up multiple +subpatterns with the same number, you cannot use names to distinguish them, +because names are not included in the compiled code. The matching process uses +only numbers. +</P> <br><a name="SEC17" href="#TOC1">DUPLICATE SUBPATTERN NAMES</a><br> <P> <b>int pcre_get_stringtable_entries(const pcre *<i>code</i>,</b> @@ -1976,9 +1995,9 @@ Cambridge CB2 3QH, England. </P> <br><a name="SEC22" href="#TOC1">REVISION</a><br> <P> -Last updated: 24 August 2008 +Last updated: 17 March 2009 <br> -Copyright © 1997-2008 University of Cambridge. +Copyright © 1997-2009 University of Cambridge. <br> <p> Return to the <a href="index.html">PCRE index page</a>. diff --git a/doc/html/pcrebuild.html b/doc/html/pcrebuild.html index 6fe0c67..7f06250 100644 --- a/doc/html/pcrebuild.html +++ b/doc/html/pcrebuild.html @@ -67,7 +67,7 @@ to the <b>configure</b> command. </P> <br><a name="SEC3" href="#TOC1">UTF-8 SUPPORT</a><br> <P> -To build PCRE with support for UTF-8 character strings, add +To build PCRE with support for UTF-8 Unicode character strings, add <pre> --enable-utf8 </pre> @@ -76,6 +76,13 @@ strings as UTF-8. As well as compiling PCRE with this option, you also have have to set the PCRE_UTF8 option when you call the <b>pcre_compile()</b> function. </P> +<P> +If you set --enable-utf8 when compiling in an EBCDIC environment, PCRE expects +its input to be either ASCII or UTF-8 (depending on the runtime option). It is +not possible to support both EBCDIC and UTF-8 codes in the same version of the +library. Consequently, --enable-utf8 and --enable-ebcdic are mutually +exclusive. +</P> <br><a name="SEC4" href="#TOC1">UNICODE CHARACTER PROPERTY SUPPORT</a><br> <P> UTF-8 support allows PCRE to process character values greater than 255 in the @@ -98,9 +105,9 @@ documentation. </P> <br><a name="SEC5" href="#TOC1">CODE VALUE OF NEWLINE</a><br> <P> -By default, PCRE interprets character 10 (linefeed, LF) as indicating the end +By default, PCRE interprets the linefeed (LF) character as indicating the end of a line. This is the normal newline character on Unix-like systems. You can -compile PCRE to use character 13 (carriage return, CR) instead, by adding +compile PCRE to use carriage return (CR) instead, by adding <pre> --enable-newline-is-cr </pre> @@ -270,7 +277,8 @@ EBCDIC environment by adding </pre> to the <b>configure</b> command. This setting implies --enable-rebuild-chartables. You should only use it if you know that you are in -an EBCDIC environment (for example, an IBM mainframe operating system). +an EBCDIC environment (for example, an IBM mainframe operating system). The +--enable-ebcdic option is incompatible with --enable-utf8. </P> <br><a name="SEC14" href="#TOC1">PCREGREP OPTIONS FOR COMPRESSED FILE SUPPORT</a><br> <P> @@ -331,9 +339,9 @@ Cambridge CB2 3QH, England. </P> <br><a name="SEC18" href="#TOC1">REVISION</a><br> <P> -Last updated: 13 April 2008 +Last updated: 17 March 2009 <br> -Copyright © 1997-2008 University of Cambridge. +Copyright © 1997-2009 University of Cambridge. <br> <p> Return to the <a href="index.html">PCRE index page</a>. diff --git a/doc/html/pcrecallout.html b/doc/html/pcrecallout.html index f8b5e2e..217764e 100644 --- a/doc/html/pcrecallout.html +++ b/doc/html/pcrecallout.html @@ -62,7 +62,8 @@ trying to optimize the performance of a particular pattern. <br><a name="SEC2" href="#TOC1">MISSING CALLOUTS</a><br> <P> You should be aware that, because of optimizations in the way PCRE matches -patterns, callouts sometimes do not happen. For example, if the pattern is +patterns by default, callouts sometimes do not happen. For example, if the +pattern is <pre> ab(?C4)cd </pre> @@ -71,6 +72,12 @@ string is "abyz", the lack of "d" means that matching doesn't ever start, and the callout is never reached. However, with "abyd", though the result is still no match, the callout is obeyed. </P> +<P> +You can disable these optimizations by passing the PCRE_NO_START_OPTIMIZE +option to <b>pcre_exec()</b> or <b>pcre_dfa_exec()</b>. This slows down the +matching process, but does ensure that callouts such as the example above are +obeyed. +</P> <br><a name="SEC3" href="#TOC1">THE CALLOUT INTERFACE</a><br> <P> During matching, when PCRE reaches a callout point, the external function @@ -192,9 +199,9 @@ Cambridge CB2 3QH, England. </P> <br><a name="SEC6" href="#TOC1">REVISION</a><br> <P> -Last updated: 29 May 2007 +Last updated: 15 March 2009 <br> -Copyright © 1997-2007 University of Cambridge. +Copyright © 1997-2009 University of Cambridge. <br> <p> Return to the <a href="index.html">PCRE index page</a>. diff --git a/doc/html/pcrecpp.html b/doc/html/pcrecpp.html index bda1675..7b52d92 100644 --- a/doc/html/pcrecpp.html +++ b/doc/html/pcrecpp.html @@ -118,6 +118,11 @@ If you need more, consider using the more general interface <b>pcrecpp::RE::DoMatch</b>. See <b>pcrecpp.h</b> for the signature for <b>DoMatch</b>. </P> +<P> +NOTE: Do not use <b>no_arg</b>, which is used internally to mark the end of a +list of optional arguments, as a placeholder for missing arguments, as this can +lead to segfaults. +</P> <br><a name="SEC4" href="#TOC1">QUOTING METACHARACTERS</a><br> <P> You can use the "QuoteMeta" operation to insert backslashes before all @@ -358,7 +363,7 @@ Copyright © 2007 Google Inc. </P> <br><a name="SEC12" href="#TOC1">REVISION</a><br> <P> -Last updated: 12 November 2007 +Last updated: 17 March 2009 <br> <p> Return to the <a href="index.html">PCRE index page</a>. diff --git a/doc/html/pcregrep.html b/doc/html/pcregrep.html index 4367031..13e45d9 100644 --- a/doc/html/pcregrep.html +++ b/doc/html/pcregrep.html @@ -78,17 +78,30 @@ Patterns are limited to 8K or BUFSIZ characters, whichever is the greater. BUFSIZ is defined in <b><stdio.h></b>. When there is more than one pattern (specified by the use of <b>-e</b> and/or <b>-f</b>), each pattern is applied to each line in the order in which they are defined, except that all the <b>-e</b> -patterns are tried before the <b>-f</b> patterns. As soon as one pattern matches -(or fails to match when <b>-v</b> is used), no further patterns are considered. +patterns are tried before the <b>-f</b> patterns. </P> <P> -When <b>--only-matching</b>, <b>--file-offsets</b>, or <b>--line-offsets</b> -is used, the output is the part of the line that matched (either shown -literally, or as an offset). In this case, scanning resumes immediately -following the match, so that further matches on the same line can be found. -If there are multiple patterns, they are all tried on the remainder of the -line. However, patterns that follow the one that matched are not tried on the -earlier part of the line. +By default, as soon as one pattern matches (or fails to match when <b>-v</b> is +used), no further patterns are considered. However, if <b>--colour</b> (or +<b>--color</b>) is used to colour the matching substrings, or if +<b>--only-matching</b>, <b>--file-offsets</b>, or <b>--line-offsets</b> is used to +output only the part of the line that matched (either shown literally, or as an +offset), scanning resumes immediately following the match, so that further +matches on the same line can be found. If there are multiple patterns, they are +all tried on the remainder of the line, but patterns that follow the one that +matched are not tried on the earlier part of the line. +</P> +<P> +This is the same behaviour as GNU grep, but it does mean that the order in +which multiple patterns are specified can affect the output when one of the +above options is used. +</P> +<P> +Patterns that can match an empty string are accepted, but empty string +matches are not recognized. An example is the pattern "(super)?(man)?", in +which all components are optional. This pattern finds all occurrences of both +"super" and "man"; the output differs from matching with "super|man" when only +the matching substrings are being shown. </P> <P> If the <b>LC_ALL</b> or <b>LC_CTYPE</b> environment variable is set, @@ -149,16 +162,21 @@ equals sign. </P> <P> <b>--colour=</b><i>value</i>, <b>--color=</b><i>value</i> -This option specifies under what circumstances the part of a line that matched -a pattern should be coloured in the output. The value may be "never" (the -default), "always", or "auto". In the latter case, colouring happens only if -the standard output is connected to a terminal. The colour can be specified by -setting the environment variable PCREGREP_COLOUR or PCREGREP_COLOR. The value -of this variable should be a string of two numbers, separated by a semicolon. -They are copied directly into the control string for setting colour on a -terminal, so it is your responsibility to ensure that they make sense. If -neither of the environment variables is set, the default is "1;31", which gives -red. +This option specifies under what circumstances the parts of a line that matched +a pattern should be coloured in the output. By default, the output is not +coloured. The value (which is optional, see above) may be "never", "always", or +"auto". In the latter case, colouring happens only if the standard output is +connected to a terminal. More resources are used when colouring is enabled, +because <b>pcregrep</b> has to search for all possible matches in a line, not +just one, in order to colour them all. +</P> +<P> +The colour that is used can be specified by setting the environment variable +PCREGREP_COLOUR or PCREGREP_COLOR. The value of this variable should be a +string of two numbers, separated by a semicolon. They are copied directly into +the control string for setting colour on a terminal, so it is your +responsibility to ensure that they make sense. If neither of the environment +variables is set, the default is "1;31", which gives red. </P> <P> <b>-D</b> <i>action</i>, <b>--devices=</b><i>action</i> @@ -247,17 +265,16 @@ and <b>--only-matching</b>. <b>-H</b>, <b>--with-filename</b> Force the inclusion of the filename at the start of output lines when searching a single file. By default, the filename is not shown in this case. For matching -lines, the filename is followed by a colon and a space; for context lines, a -hyphen separator is used. If a line number is also being output, it follows the -file name without a space. +lines, the filename is followed by a colon; for context lines, a hyphen +separator is used. If a line number is also being output, it follows the file +name. </P> <P> <b>-h</b>, <b>--no-filename</b> Suppress the output filenames when searching multiple files. By default, filenames are shown when multiple files are searched. For matching lines, the -filename is followed by a colon and a space; for context lines, a hyphen -separator is used. If a line number is also being output, it follows the file -name without a space. +filename is followed by a colon; for context lines, a hyphen separator is used. +If a line number is also being output, it follows the file name. </P> <P> <b>--help</b> @@ -362,9 +379,9 @@ being scanned does not agree with the convention set by this option, <P> <b>-n</b>, <b>--line-number</b> Precede each output line by its line number in the file, followed by a colon -and a space for matching lines or a hyphen and a space for context lines. If -the filename is also being output, it precedes the line number. This option is -forced if <b>--line-offsets</b> is used. +for matching lines or a hyphen for context lines. If the filename is also being +output, it precedes the line number. This option is forced if +<b>--line-offsets</b> is used. </P> <P> <b>-o</b>, <b>--only-matching</b> @@ -507,9 +524,9 @@ Cambridge CB2 3QH, England. </P> <br><a name="SEC13" href="#TOC1">REVISION</a><br> <P> -Last updated: 08 March 2008 +Last updated: 01 March 2009 <br> -Copyright © 1997-2008 University of Cambridge. +Copyright © 1997-2009 University of Cambridge. <br> <p> Return to the <a href="index.html">PCRE index page</a>. diff --git a/doc/html/pcrepattern.html b/doc/html/pcrepattern.html index 9cc055c..95886c1 100644 --- a/doc/html/pcrepattern.html +++ b/doc/html/pcrepattern.html @@ -1202,6 +1202,11 @@ details of the interfaces for handling named subpatterns, see the <a href="pcreapi.html"><b>pcreapi</b></a> documentation. </P> +<P> +<b>Warning:</b> You cannot use different names to distinguish between two +subpatterns with the same number (see the previous section) because PCRE uses +only the numbers when matching. +</P> <br><a name="SEC15" href="#TOC1">REPETITION</a><br> <P> Repetition is specified by quantifiers, which can follow any of the following @@ -2238,9 +2243,9 @@ Cambridge CB2 3QH, England. </P> <br><a name="SEC28" href="#TOC1">REVISION</a><br> <P> -Last updated: 19 April 2008 +Last updated: 08 March 2009 <br> -Copyright © 1997-2008 University of Cambridge. +Copyright © 1997-2009 University of Cambridge. <br> <p> Return to the <a href="index.html">PCRE index page</a>. diff --git a/doc/html/pcreposix.html b/doc/html/pcreposix.html index e52261f..3a35664 100644 --- a/doc/html/pcreposix.html +++ b/doc/html/pcreposix.html @@ -59,11 +59,11 @@ command for linking an application that uses them. Because the POSIX functions call the native ones, it is also necessary to add <b>-lpcre</b>. </P> <P> -I have implemented only those option bits that can be reasonably mapped to PCRE -native options. In addition, the option REG_EXTENDED is defined with the value -zero. This has no effect, but since programs that are written to the POSIX -interface often use it, this makes it easier to slot in PCRE as a replacement -library. Other POSIX options are not even defined. +I have implemented only those POSIX option bits that can be reasonably mapped +to PCRE native options. In addition, the option REG_EXTENDED is defined with +the value zero. This has no effect, but since programs that are written to the +POSIX interface often use it, this makes it easier to slot in PCRE as a +replacement library. Other POSIX options are not even defined. </P> <P> When PCRE is called via these functions, it is only the API that is POSIX-like @@ -189,6 +189,12 @@ be: The PCRE_NOTBOL option is set when calling the underlying PCRE matching function. <pre> + REG_NOTEMPTY +</pre> +The PCRE_NOTEMPTY option is set when calling the underlying PCRE matching +function. Note that REG_NOTEMPTY is not part of the POSIX standard. However, +setting this option can give more POSIX-like behaviour in some situations. +<pre> REG_NOTEOL </pre> The PCRE_NOTEOL option is set when calling the underlying PCRE matching @@ -251,9 +257,9 @@ Cambridge CB2 3QH, England. </P> <br><a name="SEC9" href="#TOC1">REVISION</a><br> <P> -Last updated: 05 April 2008 +Last updated: 11 March 2009 <br> -Copyright © 1997-2008 University of Cambridge. +Copyright © 1997-2009 University of Cambridge. <br> <p> Return to the <a href="index.html">PCRE index page</a>. diff --git a/doc/html/pcretest.html b/doc/html/pcretest.html index 5482eae..0358958 100644 --- a/doc/html/pcretest.html +++ b/doc/html/pcretest.html @@ -77,6 +77,12 @@ Behave as if each regex has the <b>/I</b> modifier; information about the compiled pattern is given after compilation. </P> <P> +<b>-M</b> +Behave as if each data line contains the \M escape sequence; this causes +PCRE to discover the minimum MATCH_LIMIT and MATCH_LIMIT_RECURSION settings by +calling <b>pcre_exec()</b> repeatedly with different limits. +</P> +<P> <b>-m</b> Output the size of each compiled pattern after it has been compiled. This is equivalent to adding <b>/M</b> to each regular expression. For compatibility @@ -697,9 +703,9 @@ Cambridge CB2 3QH, England. </P> <br><a name="SEC15" href="#TOC1">REVISION</a><br> <P> -Last updated: 12 April 2008 +Last updated: 10 March 2009 <br> -Copyright © 1997-2008 University of Cambridge. +Copyright © 1997-2009 University of Cambridge. <br> <p> Return to the <a href="index.html">PCRE index page</a>. diff --git a/doc/pcre.txt b/doc/pcre.txt index d07bfea..e7c5bb3 100644 --- a/doc/pcre.txt +++ b/doc/pcre.txt @@ -94,21 +94,21 @@ USER DOCUMENTATION pcrestack discussion of stack usage pcretest description of the pcretest testing command - In addition, in the "man" and HTML formats, there is a short page for + In addition, in the "man" and HTML formats, there is a short page for each C library function, listing its arguments and results. LIMITATIONS - There are some size limitations in PCRE but it is hoped that they will + There are some size limitations in PCRE but it is hoped that they will never in practice be relevant. - The maximum length of a compiled pattern is 65539 (sic) bytes if PCRE + The maximum length of a compiled pattern is 65539 (sic) bytes if PCRE is compiled with the default internal linkage size of 2. If you want to - process regular expressions that are truly enormous, you can compile - PCRE with an internal linkage size of 3 or 4 (see the README file in - the source distribution and the pcrebuild documentation for details). - In these cases the limit is substantially larger. However, the speed + process regular expressions that are truly enormous, you can compile + PCRE with an internal linkage size of 3 or 4 (see the README file in + the source distribution and the pcrebuild documentation for details). + In these cases the limit is substantially larger. However, the speed of execution is slower. All values in repeating quantifiers must be less than 65536. @@ -119,129 +119,129 @@ LIMITATIONS The maximum length of name for a named subpattern is 32 characters, and the maximum number of named subpatterns is 10000. - The maximum length of a subject string is the largest positive number - that an integer variable can hold. However, when using the traditional + The maximum length of a subject string is the largest positive number + that an integer variable can hold. However, when using the traditional matching function, PCRE uses recursion to handle subpatterns and indef- - inite repetition. This means that the available stack space may limit + inite repetition. This means that the available stack space may limit the size of a subject string that can be processed by certain patterns. For a discussion of stack issues, see the pcrestack documentation. UTF-8 AND UNICODE PROPERTY SUPPORT - From release 3.3, PCRE has had some support for character strings - encoded in the UTF-8 format. For release 4.0 this was greatly extended - to cover most common requirements, and in release 5.0 additional sup- + From release 3.3, PCRE has had some support for character strings + encoded in the UTF-8 format. For release 4.0 this was greatly extended + to cover most common requirements, and in release 5.0 additional sup- port for Unicode general category properties was added. - In order process UTF-8 strings, you must build PCRE to include UTF-8 - support in the code, and, in addition, you must call pcre_compile() - with the PCRE_UTF8 option flag. When you do this, both the pattern and - any subject strings that are matched against it are treated as UTF-8 + In order process UTF-8 strings, you must build PCRE to include UTF-8 + support in the code, and, in addition, you must call pcre_compile() + with the PCRE_UTF8 option flag. When you do this, both the pattern and + any subject strings that are matched against it are treated as UTF-8 strings instead of just strings of bytes. - If you compile PCRE with UTF-8 support, but do not use it at run time, - the library will be a bit bigger, but the additional run time overhead + If you compile PCRE with UTF-8 support, but do not use it at run time, + the library will be a bit bigger, but the additional run time overhead is limited to testing the PCRE_UTF8 flag occasionally, so should not be very big. If PCRE is built with Unicode character property support (which implies - UTF-8 support), the escape sequences \p{..}, \P{..}, and \X are sup- + UTF-8 support), the escape sequences \p{..}, \P{..}, and \X are sup- ported. The available properties that can be tested are limited to the - general category properties such as Lu for an upper case letter or Nd - for a decimal number, the Unicode script names such as Arabic or Han, - and the derived properties Any and L&. A full list is given in the + general category properties such as Lu for an upper case letter or Nd + for a decimal number, the Unicode script names such as Arabic or Han, + and the derived properties Any and L&. A full list is given in the pcrepattern documentation. Only the short names for properties are sup- - ported. For example, \p{L} matches a letter. Its Perl synonym, \p{Let- - ter}, is not supported. Furthermore, in Perl, many properties may - optionally be prefixed by "Is", for compatibility with Perl 5.6. PCRE + ported. For example, \p{L} matches a letter. Its Perl synonym, \p{Let- + ter}, is not supported. Furthermore, in Perl, many properties may + optionally be prefixed by "Is", for compatibility with Perl 5.6. PCRE does not support this. Validity of UTF-8 strings - When you set the PCRE_UTF8 flag, the strings passed as patterns and + When you set the PCRE_UTF8 flag, the strings passed as patterns and subjects are (by default) checked for validity on entry to the relevant - functions. From release 7.3 of PCRE, the check is according the rules - of RFC 3629, which are themselves derived from the Unicode specifica- - tion. Earlier releases of PCRE followed the rules of RFC 2279, which - allows the full range of 31-bit values (0 to 0x7FFFFFFF). The current + functions. From release 7.3 of PCRE, the check is according the rules + of RFC 3629, which are themselves derived from the Unicode specifica- + tion. Earlier releases of PCRE followed the rules of RFC 2279, which + allows the full range of 31-bit values (0 to 0x7FFFFFFF). The current check allows only values in the range U+0 to U+10FFFF, excluding U+D800 to U+DFFF. - The excluded code points are the "Low Surrogate Area" of Unicode, of - which the Unicode Standard says this: "The Low Surrogate Area does not - contain any character assignments, consequently no character code + The excluded code points are the "Low Surrogate Area" of Unicode, of + which the Unicode Standard says this: "The Low Surrogate Area does not + contain any character assignments, consequently no character code charts or namelists are provided for this area. Surrogates are reserved - for use with UTF-16 and then must be used in pairs." The code points - that are encoded by UTF-16 pairs are available as independent code - points in the UTF-8 encoding. (In other words, the whole surrogate + for use with UTF-16 and then must be used in pairs." The code points + that are encoded by UTF-16 pairs are available as independent code + points in the UTF-8 encoding. (In other words, the whole surrogate thing is a fudge for UTF-16 which unfortunately messes up UTF-8.) - If an invalid UTF-8 string is passed to PCRE, an error return + If an invalid UTF-8 string is passed to PCRE, an error return (PCRE_ERROR_BADUTF8) is given. In some situations, you may already know that your strings are valid, and therefore want to skip these checks in order to improve performance. If you set the PCRE_NO_UTF8_CHECK flag at - compile time or at run time, PCRE assumes that the pattern or subject - it is given (respectively) contains only valid UTF-8 codes. In this + compile time or at run time, PCRE assumes that the pattern or subject + it is given (respectively) contains only valid UTF-8 codes. In this case, it does not diagnose an invalid UTF-8 string. - If you pass an invalid UTF-8 string when PCRE_NO_UTF8_CHECK is set, - what happens depends on why the string is invalid. If the string con- + If you pass an invalid UTF-8 string when PCRE_NO_UTF8_CHECK is set, + what happens depends on why the string is invalid. If the string con- forms to the "old" definition of UTF-8 (RFC 2279), it is processed as a - string of characters in the range 0 to 0x7FFFFFFF. In other words, + string of characters in the range 0 to 0x7FFFFFFF. In other words, apart from the initial validity test, PCRE (when in UTF-8 mode) handles - strings according to the more liberal rules of RFC 2279. However, if - the string does not even conform to RFC 2279, the result is undefined. + strings according to the more liberal rules of RFC 2279. However, if + the string does not even conform to RFC 2279, the result is undefined. Your program may crash. - If you want to process strings of values in the full range 0 to - 0x7FFFFFFF, encoded in a UTF-8-like manner as per the old RFC, you can + If you want to process strings of values in the full range 0 to + 0x7FFFFFFF, encoded in a UTF-8-like manner as per the old RFC, you can set PCRE_NO_UTF8_CHECK to bypass the more restrictive test. However, in this situation, you will have to apply your own validity check. General comments about UTF-8 mode - 1. An unbraced hexadecimal escape sequence (such as \xb3) matches a + 1. An unbraced hexadecimal escape sequence (such as \xb3) matches a two-byte UTF-8 character if the value is greater than 127. - 2. Octal numbers up to \777 are recognized, and match two-byte UTF-8 + 2. Octal numbers up to \777 are recognized, and match two-byte UTF-8 characters for values greater than \177. - 3. Repeat quantifiers apply to complete UTF-8 characters, not to indi- + 3. Repeat quantifiers apply to complete UTF-8 characters, not to indi- vidual bytes, for example: \x{100}{3}. - 4. The dot metacharacter matches one UTF-8 character instead of a sin- + 4. The dot metacharacter matches one UTF-8 character instead of a sin- gle byte. - 5. The escape sequence \C can be used to match a single byte in UTF-8 - mode, but its use can lead to some strange effects. This facility is + 5. The escape sequence \C can be used to match a single byte in UTF-8 + mode, but its use can lead to some strange effects. This facility is not available in the alternative matching function, pcre_dfa_exec(). - 6. The character escapes \b, \B, \d, \D, \s, \S, \w, and \W correctly - test characters of any code value, but the characters that PCRE recog- - nizes as digits, spaces, or word characters remain the same set as + 6. The character escapes \b, \B, \d, \D, \s, \S, \w, and \W correctly + test characters of any code value, but the characters that PCRE recog- + nizes as digits, spaces, or word characters remain the same set as before, all with values less than 256. This remains true even when PCRE - includes Unicode property support, because to do otherwise would slow - down PCRE in many common cases. If you really want to test for a wider - sense of, say, "digit", you must use Unicode property tests such as + includes Unicode property support, because to do otherwise would slow + down PCRE in many common cases. If you really want to test for a wider + sense of, say, "digit", you must use Unicode property tests such as \p{Nd}. - 7. Similarly, characters that match the POSIX named character classes + 7. Similarly, characters that match the POSIX named character classes are all low-valued characters. - 8. However, the Perl 5.10 horizontal and vertical whitespace matching + 8. However, the Perl 5.10 horizontal and vertical whitespace matching escapes (\h, \H, \v, and \V) do match all the appropriate Unicode char- acters. - 9. Case-insensitive matching applies only to characters whose values - are less than 128, unless PCRE is built with Unicode property support. - Even when Unicode property support is available, PCRE still uses its - own character tables when checking the case of low-valued characters, - so as not to degrade performance. The Unicode property information is + 9. Case-insensitive matching applies only to characters whose values + are less than 128, unless PCRE is built with Unicode property support. + Even when Unicode property support is available, PCRE still uses its + own character tables when checking the case of low-valued characters, + so as not to degrade performance. The Unicode property information is used only for characters with higher values. Even when Unicode property support is available, PCRE supports case-insensitive matching only when - there is a one-to-one mapping between a letter's cases. There are a - small number of many-to-one mappings in Unicode; these are not sup- + there is a one-to-one mapping between a letter's cases. There are a + small number of many-to-one mappings in Unicode; these are not sup- ported by PCRE. @@ -251,8 +251,8 @@ AUTHOR University Computing Service Cambridge CB2 3QH, England. - Putting an actual email address here seems to have been a spam magnet, - so I've taken it away. If you want to email me, use my two initials, + Putting an actual email address here seems to have been a spam magnet, + so I've taken it away. If you want to email me, use my two initials, followed by the two digits 10, at the domain cam.ac.uk. @@ -307,7 +307,7 @@ C++ SUPPORT UTF-8 SUPPORT - To build PCRE with support for UTF-8 character strings, add + To build PCRE with support for UTF-8 Unicode character strings, add --enable-utf8 @@ -316,6 +316,12 @@ UTF-8 SUPPORT have have to set the PCRE_UTF8 option when you call the pcre_compile() function. + If you set --enable-utf8 when compiling in an EBCDIC environment, PCRE + expects its input to be either ASCII or UTF-8 (depending on the runtime + option). It is not possible to support both EBCDIC and UTF-8 codes in + the same version of the library. Consequently, --enable-utf8 and + --enable-ebcdic are mutually exclusive. + UNICODE CHARACTER PROPERTY SUPPORT @@ -337,10 +343,10 @@ UNICODE CHARACTER PROPERTY SUPPORT CODE VALUE OF NEWLINE - By default, PCRE interprets character 10 (linefeed, LF) as indicating + By default, PCRE interprets the linefeed (LF) character as indicating the end of a line. This is the normal newline character on Unix-like - systems. You can compile PCRE to use character 13 (carriage return, CR) - instead, by adding + systems. You can compile PCRE to use carriage return (CR) instead, by + adding --enable-newline-is-cr @@ -363,28 +369,28 @@ CODE VALUE OF NEWLINE causes PCRE to recognize any Unicode newline sequence. - Whatever line ending convention is selected when PCRE is built can be - overridden when the library functions are called. At build time it is + Whatever line ending convention is selected when PCRE is built can be + overridden when the library functions are called. At build time it is conventional to use the standard for your operating system. WHAT \R MATCHES - By default, the sequence \R in a pattern matches any Unicode newline - sequence, whatever has been selected as the line ending sequence. If + By default, the sequence \R in a pattern matches any Unicode newline + sequence, whatever has been selected as the line ending sequence. If you specify --enable-bsr-anycrlf - the default is changed so that \R matches only CR, LF, or CRLF. What- - ever is selected when PCRE is built can be overridden when the library + the default is changed so that \R matches only CR, LF, or CRLF. What- + ever is selected when PCRE is built can be overridden when the library functions are called. BUILDING SHARED AND STATIC LIBRARIES - The PCRE building process uses libtool to build both shared and static - Unix libraries by default. You can suppress one of these by adding one + The PCRE building process uses libtool to build both shared and static + Unix libraries by default. You can suppress one of these by adding one of --disable-shared @@ -396,9 +402,9 @@ BUILDING SHARED AND STATIC LIBRARIES POSIX MALLOC USAGE When PCRE is called through the POSIX interface (see the pcreposix doc- - umentation), additional working storage is required for holding the - pointers to capturing substrings, because PCRE requires three integers - per substring, whereas the POSIX interface provides only two. If the + umentation), additional working storage is required for holding the + pointers to capturing substrings, because PCRE requires three integers + per substring, whereas the POSIX interface provides only two. If the number of expected substrings is small, the wrapper function uses space on the stack, because this is faster than using malloc() for each call. The default threshold above which the stack is no longer used is 10; it @@ -411,112 +417,113 @@ POSIX MALLOC USAGE HANDLING VERY LARGE PATTERNS - Within a compiled pattern, offset values are used to point from one - part to another (for example, from an opening parenthesis to an alter- - nation metacharacter). By default, two-byte values are used for these - offsets, leading to a maximum size for a compiled pattern of around - 64K. This is sufficient to handle all but the most gigantic patterns. - Nevertheless, some people do want to process enormous patterns, so it - is possible to compile PCRE to use three-byte or four-byte offsets by + Within a compiled pattern, offset values are used to point from one + part to another (for example, from an opening parenthesis to an alter- + nation metacharacter). By default, two-byte values are used for these + offsets, leading to a maximum size for a compiled pattern of around + 64K. This is sufficient to handle all but the most gigantic patterns. + Nevertheless, some people do want to process enormous patterns, so it + is possible to compile PCRE to use three-byte or four-byte offsets by adding a setting such as --with-link-size=3 - to the configure command. The value given must be 2, 3, or 4. Using - longer offsets slows down the operation of PCRE because it has to load + to the configure command. The value given must be 2, 3, or 4. Using + longer offsets slows down the operation of PCRE because it has to load additional bytes when handling them. AVOIDING EXCESSIVE STACK USAGE When matching with the pcre_exec() function, PCRE implements backtrack- - ing by making recursive calls to an internal function called match(). - In environments where the size of the stack is limited, this can se- - verely limit PCRE's operation. (The Unix environment does not usually + ing by making recursive calls to an internal function called match(). + In environments where the size of the stack is limited, this can se- + verely limit PCRE's operation. (The Unix environment does not usually suffer from this problem, but it may sometimes be necessary to increase - the maximum stack size. There is a discussion in the pcrestack docu- - mentation.) An alternative approach to recursion that uses memory from - the heap to remember data, instead of using recursive function calls, - has been implemented to work round the problem of limited stack size. + the maximum stack size. There is a discussion in the pcrestack docu- + mentation.) An alternative approach to recursion that uses memory from + the heap to remember data, instead of using recursive function calls, + has been implemented to work round the problem of limited stack size. If you want to build a version of PCRE that works this way, add --disable-stack-for-recursion - to the configure command. With this configuration, PCRE will use the - pcre_stack_malloc and pcre_stack_free variables to call memory manage- - ment functions. By default these point to malloc() and free(), but you + to the configure command. With this configuration, PCRE will use the + pcre_stack_malloc and pcre_stack_free variables to call memory manage- + ment functions. By default these point to malloc() and free(), but you can replace the pointers so that your own functions are used. - Separate functions are provided rather than using pcre_malloc and - pcre_free because the usage is very predictable: the block sizes - requested are always the same, and the blocks are always freed in - reverse order. A calling program might be able to implement optimized - functions that perform better than malloc() and free(). PCRE runs + Separate functions are provided rather than using pcre_malloc and + pcre_free because the usage is very predictable: the block sizes + requested are always the same, and the blocks are always freed in + reverse order. A calling program might be able to implement optimized + functions that perform better than malloc() and free(). PCRE runs noticeably more slowly when built in this way. This option affects only - the pcre_exec() function; it is not relevant for the the + the pcre_exec() function; it is not relevant for the the pcre_dfa_exec() function. LIMITING PCRE RESOURCE USAGE - Internally, PCRE has a function called match(), which it calls repeat- - edly (sometimes recursively) when matching a pattern with the - pcre_exec() function. By controlling the maximum number of times this - function may be called during a single matching operation, a limit can - be placed on the resources used by a single call to pcre_exec(). The - limit can be changed at run time, as described in the pcreapi documen- - tation. The default is 10 million, but this can be changed by adding a + Internally, PCRE has a function called match(), which it calls repeat- + edly (sometimes recursively) when matching a pattern with the + pcre_exec() function. By controlling the maximum number of times this + function may be called during a single matching operation, a limit can + be placed on the resources used by a single call to pcre_exec(). The + limit can be changed at run time, as described in the pcreapi documen- + tation. The default is 10 million, but this can be changed by adding a setting such as --with-match-limit=500000 - to the configure command. This setting has no effect on the + to the configure command. This setting has no effect on the pcre_dfa_exec() matching function. - In some environments it is desirable to limit the depth of recursive + In some environments it is desirable to limit the depth of recursive calls of match() more strictly than the total number of calls, in order - to restrict the maximum amount of stack (or heap, if --disable-stack- + to restrict the maximum amount of stack (or heap, if --disable-stack- for-recursion is specified) that is used. A second limit controls this; - it defaults to the value that is set for --with-match-limit, which - imposes no additional constraints. However, you can set a lower limit + it defaults to the value that is set for --with-match-limit, which + imposes no additional constraints. However, you can set a lower limit by adding, for example, --with-match-limit-recursion=10000 - to the configure command. This value can also be overridden at run + to the configure command. This value can also be overridden at run time. CREATING CHARACTER TABLES AT BUILD TIME - PCRE uses fixed tables for processing characters whose code values are - less than 256. By default, PCRE is built with a set of tables that are - distributed in the file pcre_chartables.c.dist. These tables are for + PCRE uses fixed tables for processing characters whose code values are + less than 256. By default, PCRE is built with a set of tables that are + distributed in the file pcre_chartables.c.dist. These tables are for ASCII codes only. If you add --enable-rebuild-chartables - to the configure command, the distributed tables are no longer used. - Instead, a program called dftables is compiled and run. This outputs + to the configure command, the distributed tables are no longer used. + Instead, a program called dftables is compiled and run. This outputs the source for new set of tables, created in the default locale of your C runtime system. (This method of replacing the tables does not work if - you are cross compiling, because dftables is run on the local host. If - you need to create alternative tables when cross compiling, you will + you are cross compiling, because dftables is run on the local host. If + you need to create alternative tables when cross compiling, you will have to do so "by hand".) USING EBCDIC CODE - PCRE assumes by default that it will run in an environment where the - character code is ASCII (or Unicode, which is a superset of ASCII). - This is the case for most computer operating systems. PCRE can, how- + PCRE assumes by default that it will run in an environment where the + character code is ASCII (or Unicode, which is a superset of ASCII). + This is the case for most computer operating systems. PCRE can, how- ever, be compiled to run in an EBCDIC environment by adding --enable-ebcdic to the configure command. This setting implies --enable-rebuild-charta- - bles. You should only use it if you know that you are in an EBCDIC - environment (for example, an IBM mainframe operating system). + bles. You should only use it if you know that you are in an EBCDIC + environment (for example, an IBM mainframe operating system). The + --enable-ebcdic option is incompatible with --enable-utf8. PCREGREP OPTIONS FOR COMPRESSED FILE SUPPORT @@ -578,8 +585,8 @@ AUTHOR REVISION - Last updated: 13 April 2008 - Copyright (c) 1997-2008 University of Cambridge. + Last updated: 17 March 2009 + Copyright (c) 1997-2009 University of Cambridge. ------------------------------------------------------------------------------ @@ -999,7 +1006,7 @@ MULTITHREADING pcre_malloc, pcre_free, pcre_stack_malloc, and pcre_stack_free, and the callout function pointed to by pcre_callout, are shared by all threads. - The compiled form of a regular expression is not altered during match- + The compiled form of a regular expression is not altered during match- ing, so the same compiled pattern can safely be used by several threads at once. @@ -1007,10 +1014,10 @@ MULTITHREADING SAVING PRECOMPILED PATTERNS FOR LATER USE The compiled form of a regular expression can be saved and re-used at a - later 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 - pcreprecompile documentation. However, compiling a regular expression - with one version of PCRE for use with a different version is not guar- + later 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 + pcreprecompile documentation. However, compiling a regular expression + with one version of PCRE for use with a different version is not guar- anteed to work and may cause crashes. @@ -1018,33 +1025,34 @@ CHECKING BUILD-TIME OPTIONS int pcre_config(int what, void *where); - The function pcre_config() makes it possible for a PCRE client to dis- + The function pcre_config() makes it possible for a PCRE client to dis- cover which optional features have been compiled into the PCRE library. - The pcrebuild documentation has more details about these optional fea- + The pcrebuild documentation has more details about these optional fea- tures. - The first argument for pcre_config() is an integer, specifying which + The first argument for pcre_config() is an integer, specifying which information is required; the second argument is a pointer to a variable - into which the information is placed. The following information is + into which the information is placed. The following information is available: PCRE_CONFIG_UTF8 - The output is an integer that is set to one if UTF-8 support is avail- + The output is an integer that is set to one if UTF-8 support is avail- able; otherwise it is set to zero. PCRE_CONFIG_UNICODE_PROPERTIES - The output is an integer that is set to one if support for Unicode + The output is an integer that is set to one if support for Unicode character properties is available; otherwise it is set to zero. PCRE_CONFIG_NEWLINE - The output is an integer whose value specifies the default character - sequence that is recognized as meaning "newline". The four values that + 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, -2 for ANYCRLF, - and -1 for ANY. The default should normally be the standard sequence - for your operating system. + and -1 for ANY. Though they are derived from ASCII, the same values + are returned in EBCDIC environments. The default should normally corre- + spond to the standard sequence for your operating system. PCRE_CONFIG_BSR @@ -1071,24 +1079,25 @@ CHECKING BUILD-TIME OPTIONS PCRE_CONFIG_MATCH_LIMIT - The output is an integer that gives the default limit for the number of - internal matching function calls in a pcre_exec() execution. Further - details are given with pcre_exec() below. + The output is a long integer that gives the default limit for the num- + ber of internal matching function calls in a pcre_exec() execution. + Further details are given with pcre_exec() below. PCRE_CONFIG_MATCH_LIMIT_RECURSION - The output is an integer that gives the default limit for the depth of - recursion when calling the internal matching function in a pcre_exec() - execution. Further details are given with pcre_exec() below. + The output is a long integer that gives the default limit for the depth + of recursion when calling the internal matching function in a + pcre_exec() execution. Further details are given with pcre_exec() + below. PCRE_CONFIG_STACKRECURSE - The output is an integer that is set to one if internal recursion when + The output is an integer that is set to one if internal recursion when running pcre_exec() is implemented by recursive function calls that use - the stack to remember their state. This is the usual way that PCRE is + the stack to remember their state. This is the usual way that PCRE is compiled. The output is zero if PCRE was compiled to use blocks of data - on the heap instead of recursive function calls. In this case, - pcre_stack_malloc and pcre_stack_free are called to manage memory + on the heap instead of recursive function calls. In this case, + pcre_stack_malloc and pcre_stack_free are called to manage memory blocks on the heap, thus avoiding the use of the stack. @@ -1105,55 +1114,55 @@ COMPILING A PATTERN Either of the functions pcre_compile() or pcre_compile2() can be called to compile a pattern into an internal form. The only difference between - the two interfaces is that pcre_compile2() has an additional argument, + the two interfaces is that pcre_compile2() has an additional argument, errorcodeptr, via which a numerical error code can be returned. The pattern is a C string terminated by a binary zero, and is passed in - the pattern argument. A pointer to a single block of memory that is - obtained via pcre_malloc is returned. This contains the compiled code + the pattern argument. A pointer to a single block of memory that is + obtained via pcre_malloc is returned. This contains the compiled code and related data. The pcre type is defined for the returned block; this is a typedef for a structure whose contents are not externally defined. It is up to the caller to free the memory (via pcre_free) when it is no longer required. - Although the compiled code of a PCRE regex is relocatable, that is, it + Although the compiled code of a PCRE regex is relocatable, that is, it does not depend on memory location, the complete pcre data block is not - fully relocatable, because it may contain a copy of the tableptr argu- + fully relocatable, because it may contain a copy of the tableptr argu- ment, which is an address (see below). The options argument contains various bit settings that affect the com- - pilation. It should be zero if no options are required. The available - options are described below. Some of them, in particular, those that - are compatible with Perl, can also be set and unset from within the - pattern (see the detailed description in the pcrepattern documenta- - tion). For these options, the contents of the options argument speci- - fies their initial settings at the start of compilation and execution. - The PCRE_ANCHORED and PCRE_NEWLINE_xxx options can be set at the time + pilation. It should be zero if no options are required. The available + options are described below. Some of them, in particular, those that + are compatible with Perl, can also be set and unset from within the + pattern (see the detailed description in the pcrepattern documenta- + tion). For these options, the contents of the options argument speci- + fies their initial settings at the start of compilation and execution. + The PCRE_ANCHORED and PCRE_NEWLINE_xxx options can be set at the time of matching as well as at compile time. If errptr is NULL, pcre_compile() returns NULL immediately. Otherwise, - if compilation of a pattern fails, pcre_compile() returns NULL, and + if compilation of a pattern fails, pcre_compile() returns NULL, and sets the variable pointed to by errptr to point to a textual error mes- sage. This is a static string that is part of the library. You must not try to free it. The offset from the start of the pattern to the charac- ter where the error was discovered is placed in the variable pointed to - by erroffset, which must not be NULL. If it is, an immediate error is + by erroffset, which must not be NULL. If it is, an immediate error is given. - If pcre_compile2() is used instead of pcre_compile(), and the error- - codeptr argument is not NULL, a non-zero error code number is returned - via this argument in the event of an error. This is in addition to the + If pcre_compile2() is used instead of pcre_compile(), and the error- + codeptr argument is not NULL, a non-zero error code number is returned + via this argument in the event of an error. This is in addition to the textual error message. Error codes and messages are listed below. - If the final argument, tableptr, is NULL, PCRE uses a default set of - character tables that are built when PCRE is compiled, using the - default C locale. Otherwise, tableptr must be an address that is the - result of a call to pcre_maketables(). This value is stored with the - compiled pattern, and used again by pcre_exec(), unless another table + If the final argument, tableptr, is NULL, PCRE uses a default set of + character tables that are built when PCRE is compiled, using the + default C locale. Otherwise, tableptr must be an address that is the + result of a call to pcre_maketables(). This value is stored with the + compiled pattern, and used again by pcre_exec(), unless another table pointer is passed to it. For more discussion, see the section on locale support below. - This code fragment shows a typical straightforward call to pcre_com- + This code fragment shows a typical straightforward call to pcre_com- pile(): pcre *re; @@ -1166,137 +1175,137 @@ COMPILING A PATTERN &erroffset, /* for error offset */ NULL); /* use default character tables */ - The following names for option bits are defined in the pcre.h header + The following names for option bits are defined in the pcre.h header file: PCRE_ANCHORED If this bit is set, the pattern is forced to be "anchored", that is, it - is constrained to match only at the first matching point in the string - that is being searched (the "subject string"). This effect can also be - achieved by appropriate constructs in the pattern itself, which is the + is constrained to match only at the first matching point in the string + that is being searched (the "subject string"). This effect can also be + achieved by appropriate constructs in the pattern itself, which is the only way to do it in Perl. PCRE_AUTO_CALLOUT If this bit is set, pcre_compile() automatically inserts callout items, - all with number 255, before each pattern item. For discussion of the + all with number 255, before each pattern item. For discussion of the callout facility, see the pcrecallout documentation. PCRE_BSR_ANYCRLF PCRE_BSR_UNICODE These options (which are mutually exclusive) control what the \R escape - sequence matches. The choice is either to match only CR, LF, or CRLF, + 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 set- ting an option when a compiled pattern is matched. PCRE_CASELESS - If this bit is set, letters in the pattern match both upper and lower - case letters. It is equivalent to Perl's /i option, and it can be - changed within a pattern by a (?i) option setting. In UTF-8 mode, PCRE - always understands the concept of case for characters whose values are - less than 128, so caseless matching is always possible. For characters - with higher values, the concept of case is supported if PCRE is com- - piled with Unicode property support, but not otherwise. If you want to - use caseless matching for characters 128 and above, you must ensure - that PCRE is compiled with Unicode property support as well as with + If this bit is set, letters in the pattern match both upper and lower + case letters. It is equivalent to Perl's /i option, and it can be + changed within a pattern by a (?i) option setting. In UTF-8 mode, PCRE + always understands the concept of case for characters whose values are + less than 128, so caseless matching is always possible. For characters + with higher values, the concept of case is supported if PCRE is com- + piled with Unicode property support, but not otherwise. If you want to + use caseless matching for characters 128 and above, you must ensure + that PCRE is compiled with Unicode property support as well as with UTF-8 support. PCRE_DOLLAR_ENDONLY - If this bit is set, a dollar metacharacter in the pattern matches only - at the end of the subject string. Without this option, a dollar also - matches immediately before a newline at the end of the string (but not - before any other newlines). The PCRE_DOLLAR_ENDONLY option is ignored - if PCRE_MULTILINE is set. There is no equivalent to this option in + If this bit is set, a dollar metacharacter in the pattern matches only + at the end of the subject string. Without this option, a dollar also + matches immediately before a newline at the end of the string (but not + before any other newlines). The PCRE_DOLLAR_ENDONLY option is ignored + if PCRE_MULTILINE is set. There is no equivalent to this option in Perl, and no way to set it within a pattern. PCRE_DOTALL If this bit is set, a dot metacharater in the pattern matches all char- - acters, including those that indicate newline. Without it, a dot does - not match when the current position is at a newline. This option is - equivalent to Perl's /s option, and it can be changed within a pattern - by a (?s) option setting. A negative class such as [^a] always matches + acters, including those that indicate newline. Without it, a dot does + not match when the current position is at a newline. This option is + equivalent to Perl's /s option, and it can be changed within a pattern + by a (?s) option setting. A negative class such as [^a] always matches newline characters, independent of the setting of this option. PCRE_DUPNAMES - If this bit is set, names used to identify capturing subpatterns need + If this bit is set, names used to identify capturing subpatterns need not be unique. This can be helpful for certain types of pattern when it - is known that only one instance of the named subpattern can ever be - matched. There are more details of named subpatterns below; see also + is known that only one instance of the named subpattern can ever be + matched. There are more details of named subpatterns below; see also the pcrepattern documentation. PCRE_EXTENDED - If this bit is set, whitespace data characters in the pattern are + If this bit is set, whitespace data characters in the pattern are totally ignored except when escaped or inside a character class. White- space does not include the VT character (code 11). In addition, charac- ters between an unescaped # outside a character class and the next new- - line, inclusive, are also ignored. This is equivalent to Perl's /x - option, and it can be changed within a pattern by a (?x) option set- + line, inclusive, are also ignored. This is equivalent to Perl's /x + option, and it can be changed within a pattern by a (?x) option set- ting. - This option makes it possible to include comments inside complicated - patterns. Note, however, that this applies only to data characters. - Whitespace characters may never appear within special character - sequences in a pattern, for example within the sequence (?( which + This option makes it possible to include comments inside complicated + patterns. Note, however, that this applies only to data characters. + Whitespace characters may never appear within special character + sequences in a pattern, for example within the sequence (?( which introduces a conditional subpattern. PCRE_EXTRA - This option was invented in order to turn on additional functionality - of PCRE that is incompatible with Perl, but it is currently of very - little use. When set, any backslash in a pattern that is followed by a - letter that has no special meaning causes an error, thus reserving - these combinations for future expansion. By default, as in Perl, a - backslash followed by a letter with no special meaning is treated as a - literal. (Perl can, however, be persuaded to give a warning for this.) - There are at present no other features controlled by this option. It + This option was invented in order to turn on additional functionality + of PCRE that is incompatible with Perl, but it is currently of very + little use. When set, any backslash in a pattern that is followed by a + letter that has no special meaning causes an error, thus reserving + these combinations for future expansion. By default, as in Perl, a + backslash followed by a letter with no special meaning is treated as a + literal. (Perl can, however, be persuaded to give a warning for this.) + There are at present no other features controlled by this option. It can also be set by a (?X) option setting within a pattern. PCRE_FIRSTLINE - If this option is set, an unanchored pattern is required to match - before or at the first newline in the subject string, though the + If this option is set, an unanchored pattern is required to match + before or at the first newline in the subject string, though the matched text may continue over the newline. PCRE_JAVASCRIPT_COMPAT If this option is set, PCRE's behaviour is changed in some ways so that - it is compatible with JavaScript rather than Perl. The changes are as + it is compatible with JavaScript rather than Perl. The changes are as follows: - (1) A lone closing square bracket in a pattern causes a compile-time - error, because this is illegal in JavaScript (by default it is treated + (1) A lone closing square bracket in a pattern causes a compile-time + error, because this is illegal in JavaScript (by default it is treated as a data character). Thus, the pattern AB]CD becomes illegal when this option is set. - (2) At run time, a back reference to an unset subpattern group matches - an empty string (by default this causes the current matching alterna- - tive to fail). A pattern such as (\1)(a) succeeds when this option is - set (assuming it can find an "a" in the subject), whereas it fails by + (2) At run time, a back reference to an unset subpattern group matches + an empty string (by default this causes the current matching alterna- + tive to fail). A pattern such as (\1)(a) succeeds when this option is + set (assuming it can find an "a" in the subject), whereas it fails by default, for Perl compatibility. PCRE_MULTILINE - By default, PCRE treats the subject string as consisting of a single - line of characters (even if it actually contains newlines). The "start - of line" metacharacter (^) matches only at the start of the string, - while the "end of line" metacharacter ($) matches only at the end of + By default, PCRE treats the subject string as consisting of a single + line of characters (even if it actually contains newlines). The "start + of line" metacharacter (^) matches only at the start of the string, + while the "end of line" metacharacter ($) matches only at the end of the string, or before a terminating newline (unless PCRE_DOLLAR_ENDONLY is set). This is the same as Perl. - When PCRE_MULTILINE it is set, the "start of line" and "end of line" - constructs match immediately following or immediately before internal - newlines in the subject string, respectively, as well as at the very - start and end. This is equivalent to Perl's /m option, and it can be + When PCRE_MULTILINE it is set, the "start of line" and "end of line" + constructs match immediately following or immediately before internal + newlines in the subject string, respectively, as well as at the very + start and end. This is equivalent to Perl's /m option, and it can be changed within a pattern by a (?m) option setting. If there are no new- - lines in a subject string, or no occurrences of ^ or $ in a pattern, + lines in a subject string, or no occurrences of ^ or $ in a pattern, setting PCRE_MULTILINE has no effect. PCRE_NEWLINE_CR @@ -1305,37 +1314,37 @@ COMPILING A PATTERN PCRE_NEWLINE_ANYCRLF PCRE_NEWLINE_ANY - 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_ANYCRLF specifies + 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_ANYCRLF specifies that any of the three preceding sequences should be recognized. Setting - PCRE_NEWLINE_ANY specifies that any Unicode newline sequence should be + PCRE_NEWLINE_ANY specifies that any Unicode newline sequence should be recognized. The Unicode newline sequences are the three just mentioned, - plus the single characters VT (vertical 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 + plus the single characters VT (vertical 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. - The newline setting in the options word uses three bits that are + The newline setting in the options word uses three bits that are treated as a number, giving eight possibilities. Currently only six are - used (default plus the five values above). This means that if you set - more than one newline option, the combination may or may not be sensi- + used (default plus the five values above). This means that if you set + more than one newline option, the combination may or may not be sensi- ble. For example, PCRE_NEWLINE_CR with PCRE_NEWLINE_LF is equivalent to - PCRE_NEWLINE_CRLF, but other combinations may yield unused numbers and + PCRE_NEWLINE_CRLF, but other combinations may yield unused numbers and cause an error. - 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 class is encountered. This indicates a comment that lasts - until after the next line break sequence. In other circumstances, line - break sequences are treated as literal data, except that in + 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 class is encountered. This indicates a comment that lasts + until after the next line break sequence. In other circumstances, line + break sequences are treated as literal data, except that in PCRE_EXTENDED mode, both CR and LF are treated as whitespace characters and are therefore ignored. The newline option that is set at compile time becomes the default that - is used for pcre_exec() and pcre_dfa_exec(), but it can be overridden. + is used for pcre_exec() and pcre_dfa_exec(), but it can be overridden. PCRE_NO_AUTO_CAPTURE @@ -1803,18 +1812,18 @@ MATCHING A PATTERN: THE TRADITIONAL FUNCTION const char *subject, int length, int startoffset, int options, int *ovector, int ovecsize); - The function pcre_exec() is called to match a subject string against a - compiled pattern, which is passed in the code argument. If the pattern + The function pcre_exec() is called to match a subject string against a + compiled pattern, which is passed in the code argument. If the pattern has been studied, the result of the study should be passed in the extra - argument. This function is the main matching facility of the library, + argument. This function is the main matching facility of the library, and it operates in a Perl-like manner. For specialist use there is also - an alternative matching function, which is described below in the sec- + an alternative matching function, which is described below in the sec- tion about the pcre_dfa_exec() function. - In most applications, the pattern will have been compiled (and option- - ally studied) in the same process that calls pcre_exec(). However, it + In most applications, the pattern will have been compiled (and option- + ally studied) in the same process that calls pcre_exec(). However, it is possible to save compiled patterns and study data, and then use them - later in different processes, possibly even on different hosts. For a + later in different processes, possibly even on different hosts. For a discussion about this, see the pcreprecompile documentation. Here is an example of a simple call to pcre_exec(): @@ -1833,10 +1842,10 @@ MATCHING A PATTERN: THE TRADITIONAL FUNCTION Extra data for pcre_exec() - If the extra argument is not NULL, it must point to a pcre_extra data - block. The pcre_study() function returns such a block (when it doesn't - return NULL), but you can also create one for yourself, and pass addi- - tional information in it. The pcre_extra block contains the following + If the extra argument is not NULL, it must point to a pcre_extra data + block. The pcre_study() function returns such a block (when it doesn't + return NULL), but you can also create one for yourself, and pass addi- + tional information in it. The pcre_extra block contains the following fields (not necessarily in this order): unsigned long int flags; @@ -1846,7 +1855,7 @@ MATCHING A PATTERN: THE TRADITIONAL FUNCTION void *callout_data; const unsigned char *tables; - The flags field is a bitmap that specifies which of the other fields + The flags field is a bitmap that specifies which of the other fields are set. The flag bits are: PCRE_EXTRA_STUDY_DATA @@ -1855,36 +1864,36 @@ MATCHING A PATTERN: THE TRADITIONAL FUNCTION PCRE_EXTRA_CALLOUT_DATA PCRE_EXTRA_TABLES - Other flag bits should be set to zero. The study_data field is set in - the pcre_extra block that is returned by pcre_study(), together with + Other flag bits should be set to zero. The study_data field is set in + the pcre_extra block that is returned by pcre_study(), together with the appropriate flag bit. You should not set this yourself, but you may - add to the block by setting the other fields and their corresponding + add to the block by setting the other fields and their corresponding flag bits. The match_limit field provides a means of preventing PCRE from using up - a vast amount of resources when running patterns that are not going to - match, but which have a very large number of possibilities in their - search trees. The classic example is the use of nested unlimited + a vast amount of resources when running patterns that are not going to + match, but which have a very large number of possibilities in their + search trees. The classic example is the use of nested unlimited repeats. - Internally, PCRE uses a function called match() which it calls repeat- - edly (sometimes recursively). The limit set by match_limit is imposed - on the number of times this function is called during a match, which - has the effect of limiting the amount of backtracking that can take + Internally, PCRE uses a function called match() which it calls repeat- + edly (sometimes recursively). The limit set by match_limit is imposed + on the number of times this function is called during a match, which + has the effect of limiting the amount of backtracking that can take place. For patterns that are not anchored, the count restarts from zero for each position in the subject string. - The default value for the limit can be set when PCRE is built; the - default default is 10 million, which handles all but the most extreme - cases. You can override the default by suppling pcre_exec() with a - pcre_extra block in which match_limit is set, and - PCRE_EXTRA_MATCH_LIMIT is set in the flags field. If the limit is + The default value for the limit can be set when PCRE is built; the + default default is 10 million, which handles all but the most extreme + cases. You can override the default by suppling pcre_exec() with a + pcre_extra block in which match_limit is set, and + PCRE_EXTRA_MATCH_LIMIT is set in the flags field. If the limit is exceeded, pcre_exec() returns PCRE_ERROR_MATCHLIMIT. - The match_limit_recursion field is similar to match_limit, but instead + The match_limit_recursion field is similar to match_limit, but instead of limiting the total number of times that match() is called, it limits - the depth of recursion. The recursion depth is a smaller number than - the total number of calls, because not all calls to match() are recur- + the depth of recursion. The recursion depth is a smaller number than + the total number of calls, because not all calls to match() are recur- sive. This limit is of use only if it is set smaller than match_limit. Limiting the recursion depth limits the amount of stack that can be @@ -1916,8 +1925,8 @@ MATCHING A PATTERN: THE TRADITIONAL FUNCTION The unused bits of the options argument for pcre_exec() must be zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_xxx, - PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NO_UTF8_CHECK and - PCRE_PARTIAL. + PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NO_START_OPTIMIZE, + PCRE_NO_UTF8_CHECK and PCRE_PARTIAL. PCRE_ANCHORED @@ -2011,150 +2020,161 @@ MATCHING A PATTERN: THE TRADITIONAL FUNCTION an ordinary match again. There is some code that demonstrates how to do this in the pcredemo.c sample program. + PCRE_NO_START_OPTIMIZE + + There are a number of optimizations that pcre_exec() uses at the start + of a match, in order to speed up the process. For example, if it is + known that a match must start with a specific character, it searches + the subject for that character, and fails immediately if it cannot find + it, without actually running the main matching function. When callouts + are in use, these optimizations can cause them to be skipped. This + option disables the "start-up" optimizations, causing performance to + suffer, but ensuring that the callouts do occur. + PCRE_NO_UTF8_CHECK When PCRE_UTF8 is set at compile time, the validity of the subject as a - UTF-8 string is automatically checked when pcre_exec() is subsequently - called. The value of startoffset is also checked to ensure that it - points to the start of a UTF-8 character. There is a discussion about - the validity of UTF-8 strings in the section on UTF-8 support in the - main pcre page. If an invalid UTF-8 sequence of bytes is found, - pcre_exec() returns the error PCRE_ERROR_BADUTF8. If startoffset con- + UTF-8 string is automatically checked when pcre_exec() is subsequently + called. The value of startoffset is also checked to ensure that it + points to the start of a UTF-8 character. There is a discussion about + the validity of UTF-8 strings in the section on UTF-8 support in the + main pcre page. If an invalid UTF-8 sequence of bytes is found, + pcre_exec() returns the error PCRE_ERROR_BADUTF8. If startoffset con- tains an invalid value, PCRE_ERROR_BADUTF8_OFFSET is returned. - 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 calling pcre_exec(). You might want to - do this for the second and subsequent calls to pcre_exec() if you are - making repeated calls to find all the matches in a single subject - string. However, you should be sure that the value of startoffset - points to the start of a UTF-8 character. When PCRE_NO_UTF8_CHECK is - set, the effect of passing an invalid UTF-8 string as a subject, or a - value of startoffset that does not point to the start of a UTF-8 char- + 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 calling pcre_exec(). You might want to + do this for the second and subsequent calls to pcre_exec() if you are + making repeated calls to find all the matches in a single subject + string. However, you should be sure that the value of startoffset + points to the start of a UTF-8 character. When PCRE_NO_UTF8_CHECK is + set, the effect of passing an invalid UTF-8 string as a subject, or a + value of startoffset that does not point to the start of a UTF-8 char- acter, is undefined. Your program may crash. PCRE_PARTIAL - This option turns on the partial matching feature. If the subject - string fails to match the pattern, but at some point during the match- - ing process the end of the subject was reached (that is, the subject - partially matches the pattern and the failure to match occurred only - because there were not enough subject characters), pcre_exec() returns - PCRE_ERROR_PARTIAL instead of PCRE_ERROR_NOMATCH. When PCRE_PARTIAL is - used, there are restrictions on what may appear in the pattern. These + This option turns on the partial matching feature. If the subject + string fails to match the pattern, but at some point during the match- + ing process the end of the subject was reached (that is, the subject + partially matches the pattern and the failure to match occurred only + because there were not enough subject characters), pcre_exec() returns + PCRE_ERROR_PARTIAL instead of PCRE_ERROR_NOMATCH. When PCRE_PARTIAL is + used, there are restrictions on what may appear in the pattern. These are discussed in the pcrepartial documentation. The string to be matched by pcre_exec() - The subject string is passed to pcre_exec() as a pointer in subject, a + The subject string is passed to pcre_exec() as a pointer in subject, a length (in bytes) in length, and a starting byte offset in startoffset. In UTF-8 mode, the byte offset must point to the start of a UTF-8 char- - acter. Unlike the pattern string, the subject may contain binary zero - bytes. When the starting offset is zero, the search for a match starts - at the beginning of the subject, and this is by far the most common + acter. Unlike the pattern string, the subject may contain binary zero + bytes. When the starting offset is zero, the search for a match starts + at the beginning of the subject, and this is by far the most common case. - A non-zero starting offset is useful when searching for another match - in the same subject by calling pcre_exec() again after a previous suc- - cess. Setting startoffset differs from just passing over a shortened - string and setting PCRE_NOTBOL in the case of a pattern that begins + A non-zero starting offset is useful when searching for another match + in the same subject by calling pcre_exec() again after a previous suc- + cess. Setting startoffset differs from just passing over a shortened + string and setting PCRE_NOTBOL in the case of a pattern that begins with any kind of lookbehind. For example, consider the pattern \Biss\B - which finds occurrences of "iss" in the middle of words. (\B matches - only if the current position in the subject is not a word boundary.) - When applied to the string "Mississipi" the first call to pcre_exec() - finds the first occurrence. If pcre_exec() is called again with just - the remainder of the subject, namely "issipi", it does not match, + which finds occurrences of "iss" in the middle of words. (\B matches + only if the current position in the subject is not a word boundary.) + When applied to the string "Mississipi" the first call to pcre_exec() + finds the first occurrence. If pcre_exec() is called again with just + the remainder of the subject, namely "issipi", it does not match, because \B is always false at the start of the subject, which is deemed - to be a word boundary. However, if pcre_exec() is passed the entire + to be a word boundary. However, if pcre_exec() is passed the entire string again, but with startoffset set to 4, it finds the second occur- - rence of "iss" because it is able to look behind the starting point to + rence of "iss" because it is able to look behind the starting point to discover that it is preceded by a letter. - If a non-zero starting offset is passed when the pattern is anchored, + If a non-zero starting offset is passed when the pattern is anchored, one attempt to match at the given offset is made. This can only succeed - if the pattern does not require the match to be at the start of the + if the pattern does not require the match to be at the start of the subject. How pcre_exec() returns captured substrings - In general, a pattern matches a certain portion of the subject, and in - addition, further substrings from the subject may be picked out by - parts of the pattern. Following the usage in Jeffrey Friedl's book, - this is called "capturing" in what follows, and the phrase "capturing - subpattern" is used for a fragment of a pattern that picks out a sub- - string. PCRE supports several other kinds of parenthesized subpattern + In general, a pattern matches a certain portion of the subject, and in + addition, further substrings from the subject may be picked out by + parts of the pattern. Following the usage in Jeffrey Friedl's book, + this is called "capturing" in what follows, and the phrase "capturing + subpattern" is used for a fragment of a pattern that picks out a sub- + string. PCRE supports several other kinds of parenthesized subpattern that do not cause substrings to be captured. Captured substrings are returned to the caller via a vector of integers - whose address is passed in ovector. The number of elements in the vec- - tor is passed in ovecsize, which must be a non-negative number. Note: + whose address is passed in ovector. The number of elements in the vec- + tor is passed in ovecsize, which must be a non-negative number. Note: this argument is NOT the size of ovector in bytes. - The first two-thirds of the vector is used to pass back captured sub- - strings, each substring using a pair of integers. The remaining third - of the vector is used as workspace by pcre_exec() while matching cap- - turing subpatterns, and is not available for passing back information. - The number passed in ovecsize should always be a multiple of three. If + The first two-thirds of the vector is used to pass back captured sub- + strings, each substring using a pair of integers. The remaining third + of the vector is used as workspace by pcre_exec() while matching cap- + turing subpatterns, and is not available for passing back information. + The number passed in ovecsize should always be a multiple of three. If it is not, it is rounded down. - When a match is successful, information about captured substrings is - returned in pairs of integers, starting at the beginning of ovector, - and continuing up to two-thirds of its length at the most. The first - element of each pair is set to the byte offset of the first character - in a substring, and the second is set to the byte offset of the first - character after the end of a substring. Note: these values are always + When a match is successful, information about captured substrings is + returned in pairs of integers, starting at the beginning of ovector, + and continuing up to two-thirds of its length at the most. The first + element of each pair is set to the byte offset of the first character + in a substring, and the second is set to the byte offset of the first + character after the end of a substring. Note: these values are always byte offsets, even in UTF-8 mode. They are not character counts. - The first pair of integers, ovector[0] and ovector[1], identify the - portion of the subject string matched by the entire pattern. The next - pair is used for the first capturing subpattern, and so on. The value + The first pair of integers, ovector[0] and ovector[1], identify the + portion of the subject string matched by the entire pattern. The next + pair is used for the first capturing subpattern, and so on. The value returned by pcre_exec() is one more than the highest numbered pair that - has been set. For example, if two substrings have been captured, the - returned value is 3. If there are no capturing subpatterns, the return + has been set. For example, if two substrings have been captured, the + returned value is 3. If there are no capturing subpatterns, the return value from a successful match is 1, indicating that just the first pair of offsets has been set. If a capturing subpattern is matched repeatedly, it is the last portion of the string that it matched that is returned. - If the vector is too small to hold all the captured substring offsets, + If the vector is too small to hold all the captured substring offsets, it is used as far as possible (up to two-thirds of its length), and the - function returns a value of zero. If the substring offsets are not of - interest, pcre_exec() may be called with ovector passed as NULL and - ovecsize as zero. However, if the pattern contains back references and - the ovector is not big enough to remember the related substrings, PCRE - has to get additional memory for use during matching. Thus it is usu- + function returns a value of zero. If the substring offsets are not of + interest, pcre_exec() may be called with ovector passed as NULL and + ovecsize as zero. However, if the pattern contains back references and + the ovector is not big enough to remember the related substrings, PCRE + has to get additional memory for use during matching. Thus it is usu- ally advisable to supply an ovector. - The pcre_info() function can be used to find out how many capturing - subpatterns there are in a compiled pattern. The smallest size for - ovector that will allow for n captured substrings, in addition to the + The pcre_info() function can be used to find out how many capturing + subpatterns there are in a compiled pattern. The smallest size for + ovector that will allow for n captured substrings, in addition to the offsets of the substring matched by the whole pattern, is (n+1)*3. - It is possible for capturing subpattern number n+1 to match some part + It is possible for capturing subpattern number n+1 to match some part of the subject when subpattern n has not been used at all. For example, - if the string "abc" is matched against the pattern (a|(z))(bc) the + if the string "abc" is matched against the pattern (a|(z))(bc) the return from the function is 4, and subpatterns 1 and 3 are matched, but - 2 is not. When this happens, both values in the offset pairs corre- + 2 is not. When this happens, both values in the offset pairs corre- sponding to unused subpatterns are set to -1. - Offset values that correspond to unused subpatterns at the end of the - expression are also set to -1. For example, if the string "abc" is - matched against the pattern (abc)(x(yz)?)? subpatterns 2 and 3 are not - matched. The return from the function is 2, because the highest used + Offset values that correspond to unused subpatterns at the end of the + expression are also set to -1. For example, if the string "abc" is + matched against the pattern (abc)(x(yz)?)? subpatterns 2 and 3 are not + matched. The return from the function is 2, because the highest used capturing subpattern number is 1. However, you can refer to the offsets - for the second and third capturing subpatterns if you wish (assuming + for the second and third capturing subpatterns if you wish (assuming the vector is large enough, of course). - Some convenience functions are provided for extracting the captured + Some convenience functions are provided for extracting the captured substrings as separate strings. These are described below. Error return values from pcre_exec() - If pcre_exec() fails, it returns a negative number. The following are + If pcre_exec() fails, it returns a negative number. The following are defined in the header file: PCRE_ERROR_NOMATCH (-1) @@ -2163,7 +2183,7 @@ MATCHING A PATTERN: THE TRADITIONAL FUNCTION PCRE_ERROR_NULL (-2) - Either code or subject was passed as NULL, or ovector was NULL and + Either code or subject was passed as NULL, or ovector was NULL and ovecsize was not zero. PCRE_ERROR_BADOPTION (-3) @@ -2172,74 +2192,74 @@ MATCHING A PATTERN: THE TRADITIONAL FUNCTION PCRE_ERROR_BADMAGIC (-4) - PCRE stores a 4-byte "magic number" at the start of the compiled code, + PCRE stores a 4-byte "magic number" at the start of the compiled code, to catch the case when it is passed a junk pointer and to detect when a pattern that was compiled in an environment of one endianness is run in - an environment with the other endianness. This is the error that PCRE + an environment with the other endianness. This is the error that PCRE gives when the magic number is not present. PCRE_ERROR_UNKNOWN_OPCODE (-5) While running the pattern match, an unknown item was encountered in the - compiled pattern. This error could be caused by a bug in PCRE or by + compiled pattern. This error could be caused by a bug in PCRE or by overwriting of the compiled pattern. PCRE_ERROR_NOMEMORY (-6) - If a pattern contains back references, but the ovector that is passed + If a pattern contains back references, but the ovector that is passed to pcre_exec() is not big enough to remember the referenced substrings, - PCRE gets a block of memory at the start of matching to use for this - purpose. If the call via pcre_malloc() fails, this error is given. The + PCRE gets a block of memory at the start of matching to use for this + purpose. If the call via pcre_malloc() fails, this error is given. The memory is automatically freed at the end of matching. PCRE_ERROR_NOSUBSTRING (-7) - This error is used by the pcre_copy_substring(), pcre_get_substring(), + This error is used by the pcre_copy_substring(), pcre_get_substring(), and pcre_get_substring_list() functions (see below). It is never returned by pcre_exec(). PCRE_ERROR_MATCHLIMIT (-8) - The backtracking limit, as specified by the match_limit field in a - pcre_extra structure (or defaulted) was reached. See the description + The backtracking limit, as specified by the match_limit field in a + pcre_extra structure (or defaulted) was reached. See the description above. PCRE_ERROR_CALLOUT (-9) This error is never generated by pcre_exec() itself. It is provided for - use by callout functions that want to yield a distinctive error code. + use by callout functions that want to yield a distinctive error code. See the pcrecallout documentation for details. PCRE_ERROR_BADUTF8 (-10) - A string that contains an invalid UTF-8 byte sequence was passed as a + A string that contains an invalid UTF-8 byte sequence was passed as a subject. PCRE_ERROR_BADUTF8_OFFSET (-11) The UTF-8 byte sequence that was passed as a subject was valid, but the - value of startoffset did not point to the beginning of a UTF-8 charac- + value of startoffset did not point to the beginning of a UTF-8 charac- ter. PCRE_ERROR_PARTIAL (-12) - The subject string did not match, but it did match partially. See the + The subject string did not match, but it did match partially. See the pcrepartial documentation for details of partial matching. PCRE_ERROR_BADPARTIAL (-13) - The PCRE_PARTIAL option was used with a compiled pattern containing - items that are not supported for partial matching. See the pcrepartial + The PCRE_PARTIAL option was used with a compiled pattern containing + items that are not supported for partial matching. See the pcrepartial documentation for details of partial matching. PCRE_ERROR_INTERNAL (-14) - An unexpected internal error has occurred. This error could be caused + An unexpected internal error has occurred. This error could be caused by a bug in PCRE or by overwriting of the compiled pattern. PCRE_ERROR_BADCOUNT (-15) - This error is given if the value of the ovecsize argument is negative. + This error is given if the value of the ovecsize argument is negative. PCRE_ERROR_RECURSIONLIMIT (-21) @@ -2389,53 +2409,58 @@ EXTRACTING CAPTURED SUBSTRINGS BY NAME ate. NOTE: If PCRE_DUPNAMES is set and there are duplicate names, the behaviour may not be what you want (see the next section). + Warning: If the pattern uses the "(?|" feature to set up multiple sub- + patterns with the same number, you cannot use names to distinguish + them, because names are not included in the compiled code. The matching + process uses only numbers. + DUPLICATE SUBPATTERN NAMES int pcre_get_stringtable_entries(const pcre *code, const char *name, char **first, char **last); - When a pattern is compiled with the PCRE_DUPNAMES option, names for - subpatterns are not required to be unique. Normally, patterns with - duplicate names are such that in any one match, only one of the named - subpatterns participates. An example is shown in the pcrepattern docu- + When a pattern is compiled with the PCRE_DUPNAMES option, names for + subpatterns are not required to be unique. Normally, patterns with + duplicate names are such that in any one match, only one of the named + subpatterns participates. An example is shown in the pcrepattern docu- mentation. - When duplicates are present, pcre_copy_named_substring() and - pcre_get_named_substring() return the first substring corresponding to - the given name that is set. If none are set, PCRE_ERROR_NOSUBSTRING - (-7) is returned; no data is returned. The pcre_get_stringnumber() - function returns one of the numbers that are associated with the name, + When duplicates are present, pcre_copy_named_substring() and + pcre_get_named_substring() return the first substring corresponding to + the given name that is set. If none are set, PCRE_ERROR_NOSUBSTRING + (-7) is returned; no data is returned. The pcre_get_stringnumber() + function returns one of the numbers that are associated with the name, but it is not defined which it is. - If you want to get full details of all captured substrings for a given - name, you must use the pcre_get_stringtable_entries() function. The + If you want to get full details of all captured substrings for a given + name, you must use the pcre_get_stringtable_entries() function. The first argument is the compiled pattern, and the second is the name. The - third and fourth are pointers to variables which are updated by the + third and fourth are pointers to variables which are updated by the function. After it has run, they point to the first and last entries in - the name-to-number table for the given name. The function itself - returns the length of each entry, or PCRE_ERROR_NOSUBSTRING (-7) if - there are none. The format of the table is described above in the sec- - tion entitled Information about a pattern. Given all the relevant - entries for the name, you can extract each of their numbers, and hence + the name-to-number table for the given name. The function itself + returns the length of each entry, or PCRE_ERROR_NOSUBSTRING (-7) if + there are none. The format of the table is described above in the sec- + tion entitled Information about a pattern. Given all the relevant + entries for the name, you can extract each of their numbers, and hence the captured data, if any. FINDING ALL POSSIBLE MATCHES - The traditional matching function uses a similar algorithm to Perl, + The traditional matching function uses a similar algorithm to Perl, which stops when it finds the first match, starting at a given point in - the subject. If you want to find all possible matches, or the longest - possible match, consider using the alternative matching function (see - below) instead. If you cannot use the alternative function, but still - need to find all possible matches, you can kludge it up by making use + the subject. If you want to find all possible matches, or the longest + possible match, consider using the alternative matching function (see + below) instead. If you cannot use the alternative function, but still + need to find all possible matches, you can kludge it up by making use of the callout facility, which is described in the pcrecallout documen- tation. What you have to do is to insert a callout right at the end of the pat- - tern. When your callout function is called, extract and save the cur- - rent matched substring. Then return 1, which forces pcre_exec() to - backtrack and try other alternatives. Ultimately, when it runs out of + tern. When your callout function is called, extract and save the cur- + rent matched substring. Then return 1, which forces pcre_exec() to + backtrack and try other alternatives. Ultimately, when it runs out of matches, pcre_exec() will yield PCRE_ERROR_NOMATCH. @@ -2446,25 +2471,25 @@ MATCHING A PATTERN: THE ALTERNATIVE FUNCTION int options, int *ovector, int ovecsize, int *workspace, int wscount); - The function pcre_dfa_exec() is called to match a subject string - against a compiled pattern, using a matching algorithm that scans the - subject string just once, and does not backtrack. This has different - characteristics to the normal algorithm, and is not compatible with - Perl. Some of the features of PCRE patterns are not supported. Never- - theless, there are times when this kind of matching can be useful. For + The function pcre_dfa_exec() is called to match a subject string + against a compiled pattern, using a matching algorithm that scans the + subject string just once, and does not backtrack. This has different + characteristics to the normal algorithm, and is not compatible with + Perl. Some of the features of PCRE patterns are not supported. Never- + theless, there are times when this kind of matching can be useful. For a discussion of the two matching algorithms, see the pcrematching docu- mentation. - The arguments for the pcre_dfa_exec() function are the same as for + The arguments for the pcre_dfa_exec() function are the same as for pcre_exec(), plus two extras. The ovector argument is used in a differ- - ent way, and this is described below. The other common arguments are - used in the same way as for pcre_exec(), so their description is not + ent way, and this is described below. The other common arguments are + used in the same way as for pcre_exec(), so their description is not repeated here. - The two additional arguments provide workspace for the function. The - workspace vector should contain at least 20 elements. It is used for + The two additional arguments provide workspace for the function. The + workspace vector should contain at least 20 elements. It is used for keeping track of multiple paths through the pattern tree. More - workspace will be needed for patterns and subjects where there are a + workspace will be needed for patterns and subjects where there are a lot of potential matches. Here is an example of a simple call to pcre_dfa_exec(): @@ -2486,47 +2511,47 @@ MATCHING A PATTERN: THE ALTERNATIVE FUNCTION Option bits for pcre_dfa_exec() - The unused bits of the options argument for pcre_dfa_exec() must be - zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEW- - LINE_xxx, PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NO_UTF8_CHECK, + The unused bits of the options argument for pcre_dfa_exec() must be + zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEW- + LINE_xxx, PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NO_UTF8_CHECK, PCRE_PARTIAL, PCRE_DFA_SHORTEST, and PCRE_DFA_RESTART. All but the last three of these are the same as for pcre_exec(), so their description is not repeated here. PCRE_PARTIAL - This has the same general effect as it does for pcre_exec(), but the - details are slightly different. When PCRE_PARTIAL is set for - pcre_dfa_exec(), the return code PCRE_ERROR_NOMATCH is converted into - PCRE_ERROR_PARTIAL if the end of the subject is reached, there have + This has the same general effect as it does for pcre_exec(), but the + details are slightly different. When PCRE_PARTIAL is set for + pcre_dfa_exec(), the return code PCRE_ERROR_NOMATCH is converted into + PCRE_ERROR_PARTIAL if the end of the subject is reached, there have been no complete matches, but there is still at least one matching pos- - sibility. The portion of the string that provided the partial match is + sibility. The portion of the string that provided the partial match is set as the first matching string. PCRE_DFA_SHORTEST - Setting the PCRE_DFA_SHORTEST option causes the matching algorithm to + Setting the PCRE_DFA_SHORTEST option causes the matching algorithm to stop as soon as it has found one match. Because of the way the alterna- - tive algorithm works, this is necessarily the shortest possible match + tive algorithm works, this is necessarily the shortest possible match at the first possible matching point in the subject string. PCRE_DFA_RESTART - When pcre_dfa_exec() is called with the PCRE_PARTIAL option, and - returns a partial match, it is possible to call it again, with addi- - tional subject characters, and have it continue with the same match. - The PCRE_DFA_RESTART option requests this action; when it is set, the - workspace and wscount options must reference the same vector as before - because data about the match so far is left in them after a partial - match. There is more discussion of this facility in the pcrepartial + When pcre_dfa_exec() is called with the PCRE_PARTIAL option, and + returns a partial match, it is possible to call it again, with addi- + tional subject characters, and have it continue with the same match. + The PCRE_DFA_RESTART option requests this action; when it is set, the + workspace and wscount options must reference the same vector as before + because data about the match so far is left in them after a partial + match. There is more discussion of this facility in the pcrepartial documentation. Successful returns from pcre_dfa_exec() - When pcre_dfa_exec() succeeds, it may have matched more than one sub- + When pcre_dfa_exec() succeeds, it may have matched more than one sub- string in the subject. Note, however, that all the matches from one run - of the function start at the same point in the subject. The shorter - matches are all initial substrings of the longer matches. For example, + of the function start at the same point in the subject. The shorter + matches are all initial substrings of the longer matches. For example, if the pattern <.*> @@ -2541,62 +2566,62 @@ MATCHING A PATTERN: THE ALTERNATIVE FUNCTION <something> <something else> <something> <something else> <something further> - On success, the yield of the function is a number greater than zero, - which is the number of matched substrings. The substrings themselves - are returned in ovector. Each string uses two elements; the first is - the offset to the start, and the second is the offset to the end. In - fact, all the strings have the same start offset. (Space could have - been saved by giving this only once, but it was decided to retain some - compatibility with the way pcre_exec() returns data, even though the + On success, the yield of the function is a number greater than zero, + which is the number of matched substrings. The substrings themselves + are returned in ovector. Each string uses two elements; the first is + the offset to the start, and the second is the offset to the end. In + fact, all the strings have the same start offset. (Space could have + been saved by giving this only once, but it was decided to retain some + compatibility with the way pcre_exec() returns data, even though the meaning of the strings is different.) The strings are returned in reverse order of length; that is, the long- - est matching string is given first. If there were too many matches to - fit into ovector, the yield of the function is zero, and the vector is + est matching string is given first. If there were too many matches to + fit into ovector, the yield of the function is zero, and the vector is filled with the longest matches. Error returns from pcre_dfa_exec() - The pcre_dfa_exec() function returns a negative number when it fails. - Many of the errors are the same as for pcre_exec(), and these are - described above. There are in addition the following errors that are + The pcre_dfa_exec() function returns a negative number when it fails. + Many of the errors are the same as for pcre_exec(), and these are + described above. There are in addition the following errors that are specific to pcre_dfa_exec(): PCRE_ERROR_DFA_UITEM (-16) - This return is given if pcre_dfa_exec() encounters an item in the pat- - tern that it does not support, for instance, the use of \C or a back + This return is given if pcre_dfa_exec() encounters an item in the pat- + tern that it does not support, for instance, the use of \C or a back reference. PCRE_ERROR_DFA_UCOND (-17) - This return is given if pcre_dfa_exec() encounters a condition item - that uses a back reference for the condition, or a test for recursion + This return is given if pcre_dfa_exec() encounters a condition item + that uses a back reference for the condition, or a test for recursion in a specific group. These are not supported. PCRE_ERROR_DFA_UMLIMIT (-18) - This return is given if pcre_dfa_exec() is called with an extra block + This return is given if pcre_dfa_exec() is called with an extra block that contains a setting of the match_limit field. This is not supported (it is meaningless). PCRE_ERROR_DFA_WSSIZE (-19) - This return is given if pcre_dfa_exec() runs out of space in the + This return is given if pcre_dfa_exec() runs out of space in the workspace vector. PCRE_ERROR_DFA_RECURSE (-20) - When a recursive subpattern is processed, the matching function calls - itself recursively, using private vectors for ovector and workspace. - This error is given if the output vector is not large enough. This + When a recursive subpattern is processed, the matching function calls + itself recursively, using private vectors for ovector and workspace. + This error is given if the output vector is not large enough. This should be extremely rare, as a vector of size 1000 is used. SEE ALSO - pcrebuild(3), pcrecallout(3), pcrecpp(3)(3), pcrematching(3), pcrepar- - tial(3), pcreposix(3), pcreprecompile(3), pcresample(3), pcrestack(3). + pcrebuild(3), pcrecallout(3), pcrecpp(3)(3), pcrematching(3), pcrepar- + tial(3), pcreposix(3), pcreprecompile(3), pcresample(3), pcrestack(3). AUTHOR @@ -2608,8 +2633,8 @@ AUTHOR REVISION - Last updated: 24 August 2008 - Copyright (c) 1997-2008 University of Cambridge. + Last updated: 17 March 2009 + Copyright (c) 1997-2009 University of Cambridge. ------------------------------------------------------------------------------ @@ -2660,8 +2685,8 @@ PCRE CALLOUTS MISSING CALLOUTS You should be aware that, because of optimizations in the way PCRE - matches patterns, callouts sometimes do not happen. For example, if the - pattern is + matches patterns by default, callouts sometimes do not happen. For + example, if the pattern is ab(?C4)cd @@ -2670,13 +2695,18 @@ MISSING CALLOUTS ever start, and the callout is never reached. However, with "abyd", though the result is still no match, the callout is obeyed. + You can disable these optimizations by passing the PCRE_NO_START_OPTI- + MIZE option to pcre_exec() or pcre_dfa_exec(). This slows down the + matching process, but does ensure that callouts such as the example + above are obeyed. + THE CALLOUT INTERFACE - During matching, when PCRE reaches a callout point, the external func- - tion defined by pcre_callout is called (if it is set). This applies to - both the pcre_exec() and the pcre_dfa_exec() matching functions. The - only argument to the callout function is a pointer to a pcre_callout + During matching, when PCRE reaches a callout point, the external func- + tion defined by pcre_callout is called (if it is set). This applies to + both the pcre_exec() and the pcre_dfa_exec() matching functions. The + only argument to the callout function is a pointer to a pcre_callout block. This structure contains the following fields: int version; @@ -2692,9 +2722,9 @@ THE CALLOUT INTERFACE int pattern_position; int next_item_length; - The version field is an integer containing the version number of the - block format. The initial version was 0; the current version is 1. The - version number will change again in future if additional fields are + The version field is an integer containing the version number of the + block format. The initial version was 0; the current version is 1. The + version number will change again in future if additional fields are added, but the intention is never to remove any of the existing fields. The callout_number field contains the number of the callout, as com- @@ -2779,8 +2809,8 @@ AUTHOR REVISION - Last updated: 29 May 2007 - Copyright (c) 1997-2007 University of Cambridge. + Last updated: 15 March 2009 + Copyright (c) 1997-2009 University of Cambridge. ------------------------------------------------------------------------------ @@ -3059,33 +3089,33 @@ CHARACTERS AND METACHARACTERS syntax) ] terminates the character class - The following sections describe the use of each of the metacharacters. + The following sections describe the use of each of the metacharacters. BACKSLASH The backslash character has several uses. Firstly, if it is followed by - a non-alphanumeric character, it takes away any special meaning that - character may have. This use of backslash as an escape character + a non-alphanumeric character, it takes away any special meaning that + character may have. This use of backslash as an escape character applies both inside and outside character classes. - For example, if you want to match a * character, you write \* in the - pattern. This escaping action applies whether or not the following - character would otherwise be interpreted as a metacharacter, so it is - always safe to precede a non-alphanumeric with backslash to specify - that it stands for itself. In particular, if you want to match a back- + For example, if you want to match a * character, you write \* in the + pattern. This escaping action applies whether or not the following + character would otherwise be interpreted as a metacharacter, so it is + always safe to precede a non-alphanumeric with backslash to specify + that it stands for itself. In particular, if you want to match a back- slash, you write \\. - If a pattern is compiled with the PCRE_EXTENDED option, whitespace in - the pattern (other than in a character class) and characters between a + If a pattern is compiled with the PCRE_EXTENDED option, whitespace in + the pattern (other than in a character class) and characters between a # outside a character class and the next newline are ignored. An escap- - ing backslash can be used to include a whitespace or # character as + ing backslash can be used to include a whitespace or # character as part of the pattern. - If you want to remove the special meaning from a sequence of charac- - ters, you can do so by putting them between \Q and \E. This is differ- - ent from Perl in that $ and @ are handled as literals in \Q...\E - sequences in PCRE, whereas in Perl, $ and @ cause variable interpola- + If you want to remove the special meaning from a sequence of charac- + ters, you can do so by putting them between \Q and \E. This is differ- + ent from Perl in that $ and @ are handled as literals in \Q...\E + sequences in PCRE, whereas in Perl, $ and @ cause variable interpola- tion. Note the following examples: Pattern PCRE matches Perl matches @@ -3095,16 +3125,16 @@ BACKSLASH \Qabc\$xyz\E abc\$xyz abc\$xyz \Qabc\E\$\Qxyz\E abc$xyz abc$xyz - The \Q...\E sequence is recognized both inside and outside character + The \Q...\E sequence is recognized both inside and outside character classes. Non-printing characters A second use of backslash provides a way of encoding non-printing char- - acters in patterns in a visible manner. There is no restriction on the - appearance of non-printing characters, apart from the binary zero that - terminates a pattern, but when a pattern is being prepared by text - editing, it is usually easier to use one of the following escape + acters in patterns in a visible manner. There is no restriction on the + appearance of non-printing characters, apart from the binary zero that + terminates a pattern, but when a pattern is being prepared by text + editing, it is usually easier to use one of the following escape sequences than the binary character it represents: \a alarm, that is, the BEL character (hex 07) @@ -3118,48 +3148,48 @@ BACKSLASH \xhh character with hex code hh \x{hhh..} character with hex code hhh.. - The precise effect of \cx is as follows: if x is a lower case letter, - it is converted to upper case. Then bit 6 of the character (hex 40) is - inverted. Thus \cz becomes hex 1A, but \c{ becomes hex 3B, while \c; + The precise effect of \cx is as follows: if x is a lower case letter, + it is converted to upper case. Then bit 6 of the character (hex 40) is + inverted. Thus \cz becomes hex 1A, but \c{ becomes hex 3B, while \c; becomes hex 7B. - After \x, from zero to two hexadecimal digits are read (letters can be - in upper or lower case). Any number of hexadecimal digits may appear - between \x{ and }, but the value of the character code must be less + After \x, from zero to two hexadecimal digits are read (letters can be + in upper or lower case). Any number of hexadecimal digits may appear + between \x{ and }, but the value of the character code must be less than 256 in non-UTF-8 mode, and less than 2**31 in UTF-8 mode. That is, - the maximum value in hexadecimal is 7FFFFFFF. Note that this is bigger + the maximum value in hexadecimal is 7FFFFFFF. Note that this is bigger than the largest Unicode code point, which is 10FFFF. - If characters other than hexadecimal digits appear between \x{ and }, + If characters other than hexadecimal digits appear between \x{ and }, or if there is no terminating }, this form of escape is not recognized. - Instead, the initial \x will be interpreted as a basic hexadecimal - escape, with no following digits, giving a character whose value is + Instead, the initial \x will be interpreted as a basic hexadecimal + escape, with no following digits, giving a character whose value is zero. Characters whose value is less than 256 can be defined by either of the - two syntaxes for \x. There is no difference in the way they are han- + two syntaxes for \x. There is no difference in the way they are han- dled. For example, \xdc is exactly the same as \x{dc}. - After \0 up to two further octal digits are read. If there are fewer - than two digits, just those that are present are used. Thus the + After \0 up to two further octal digits are read. If there are fewer + than two digits, just those that are present are used. Thus the sequence \0\x\07 specifies two binary zeros followed by a BEL character - (code value 7). Make sure you supply two digits after the initial zero + (code value 7). Make sure you supply two digits after the initial zero if the pattern character that follows is itself an octal digit. The handling of a backslash followed by a digit other than 0 is compli- cated. Outside a character class, PCRE reads it and any following dig- - its as a decimal number. If the number is less than 10, or if there + its as a decimal number. If the number is less than 10, or if there have been at least that many previous capturing left parentheses in the - expression, the entire sequence is taken as a back reference. A - description of how this works is given later, following the discussion + expression, the entire sequence is taken as a back reference. A + description of how this works is given later, following the discussion of parenthesized subpatterns. - Inside a character class, or if the decimal number is greater than 9 - and there have not been that many capturing subpatterns, PCRE re-reads + Inside a character class, or if the decimal number is greater than 9 + and there have not been that many capturing subpatterns, PCRE re-reads up to three octal digits following the backslash, and uses them to gen- - erate a data character. Any subsequent digits stand for themselves. In - non-UTF-8 mode, the value of a character specified in octal must be - less than \400. In UTF-8 mode, values up to \777 are permitted. For + erate a data character. Any subsequent digits stand for themselves. In + non-UTF-8 mode, the value of a character specified in octal must be + less than \400. In UTF-8 mode, values up to \777 are permitted. For example: \040 is another way of writing a space @@ -3177,30 +3207,30 @@ BACKSLASH \81 is either a back reference, or a binary zero followed by the two characters "8" and "1" - Note that octal values of 100 or greater must not be introduced by a + Note that octal values of 100 or greater must not be introduced by a leading zero, because no more than three octal digits are ever read. All the sequences that define a single character value can be used both - inside and outside character classes. In addition, inside a character - class, the sequence \b is interpreted as the backspace character (hex - 08), and the sequences \R and \X are interpreted as the characters "R" - and "X", respectively. Outside a character class, these sequences have + inside and outside character classes. In addition, inside a character + class, the sequence \b is interpreted as the backspace character (hex + 08), and the sequences \R and \X are interpreted as the characters "R" + and "X", respectively. Outside a character class, these sequences have different meanings (see below). Absolute and relative back references - The sequence \g followed by an unsigned or a negative number, option- - ally enclosed in braces, is an absolute or relative back reference. A + The sequence \g followed by an unsigned or a negative number, option- + ally enclosed in braces, is an absolute or relative back reference. A named back reference can be coded as \g{name}. Back references are dis- cussed later, following the discussion of parenthesized subpatterns. Absolute and relative subroutine calls - For compatibility with Oniguruma, the non-Perl syntax \g followed by a + For compatibility with Oniguruma, the non-Perl syntax \g followed by a name or a number enclosed either in angle brackets or single quotes, is - an alternative syntax for referencing a subpattern as a "subroutine". - Details are discussed later. Note that \g{...} (Perl syntax) and - \g<...> (Oniguruma syntax) are not synonymous. The former is a back + an alternative syntax for referencing a subpattern as a "subroutine". + Details are discussed later. Note that \g{...} (Perl syntax) and + \g<...> (Oniguruma syntax) are not synonymous. The former is a back reference; the latter is a subroutine call. Generic character types @@ -3220,28 +3250,28 @@ BACKSLASH \W any "non-word" character Each pair of escape sequences partitions the complete set of characters - into two disjoint sets. Any given character matches one, and only one, + into two disjoint sets. Any given character matches one, and only one, of each pair. These character type sequences can appear both inside and outside char- - acter classes. They each match one character of the appropriate type. - If the current matching point is at the end of the subject string, all + acter classes. They each match one character of the appropriate type. + If the current matching point is at the end of the subject string, all of them fail, since there is no character to match. - For compatibility with Perl, \s does not match the VT character (code - 11). This makes it different from the the POSIX "space" class. The \s - characters are HT (9), LF (10), FF (12), CR (13), and space (32). If + For compatibility with Perl, \s does not match the VT character (code + 11). This makes it different from the the POSIX "space" class. The \s + characters are HT (9), LF (10), FF (12), CR (13), and space (32). If "use locale;" is included in a Perl script, \s may match the VT charac- ter. In PCRE, it never does. - In UTF-8 mode, characters with values greater than 128 never match \d, + In UTF-8 mode, characters with values greater than 128 never match \d, \s, or \w, and always match \D, \S, and \W. This is true even when Uni- - code character property support is available. These sequences retain + code character property support is available. These sequences retain their original meanings from before UTF-8 support was available, mainly for efficiency reasons. The sequences \h, \H, \v, and \V are Perl 5.10 features. In contrast to - the other sequences, these do match certain high-valued codepoints in + the other sequences, these do match certain high-valued codepoints in UTF-8 mode. The horizontal space characters are: U+0009 Horizontal tab @@ -3275,41 +3305,41 @@ BACKSLASH U+2029 Paragraph separator A "word" character is an underscore or any character less than 256 that - is a letter or digit. The definition of letters and digits is con- - trolled by PCRE's low-valued character tables, and may vary if locale- - specific matching is taking place (see "Locale support" in the pcreapi - page). For example, in a French locale such as "fr_FR" in Unix-like - systems, or "french" in Windows, some character codes greater than 128 - are used for accented letters, and these are matched by \w. The use of + is a letter or digit. The definition of letters and digits is con- + trolled by PCRE's low-valued character tables, and may vary if locale- + specific matching is taking place (see "Locale support" in the pcreapi + page). For example, in a French locale such as "fr_FR" in Unix-like + systems, or "french" in Windows, some character codes greater than 128 + are used for accented letters, and these are matched by \w. The use of locales with Unicode is discouraged. Newline sequences - Outside a character class, by default, the escape sequence \R matches + Outside a character class, by default, the escape sequence \R matches any Unicode newline sequence. This is a Perl 5.10 feature. In non-UTF-8 mode \R is equivalent to the following: (?>\r\n|\n|\x0b|\f|\r|\x85) - This is an example of an "atomic group", details of which are given + This is an example of an "atomic group", details of which are given below. This particular group matches either the two-character sequence - CR followed by LF, or one of the single characters LF (linefeed, + CR followed by LF, or one of the single characters LF (linefeed, U+000A), VT (vertical tab, U+000B), FF (formfeed, U+000C), CR (carriage return, U+000D), or NEL (next line, U+0085). The two-character sequence is treated as a single unit that cannot be split. - In UTF-8 mode, two additional characters whose codepoints are greater + In UTF-8 mode, two additional characters whose codepoints are greater than 255 are added: LS (line separator, U+2028) and PS (paragraph sepa- - rator, U+2029). Unicode character property support is not needed for + rator, U+2029). Unicode character property support is not needed for these characters to be recognized. It is possible to restrict \R to match only CR, LF, or CRLF (instead of - the complete set of Unicode line endings) by setting the option + the complete set of Unicode line endings) by setting the option PCRE_BSR_ANYCRLF either at compile time or when the pattern is matched. (BSR is an abbrevation for "backslash R".) This can be made the default - when PCRE is built; if this is the case, the other behaviour can be - requested via the PCRE_BSR_UNICODE option. It is also possible to - specify these settings by starting a pattern string with one of the + when PCRE is built; if this is the case, the other behaviour can be + requested via the PCRE_BSR_UNICODE option. It is also possible to + specify these settings by starting a pattern string with one of the following sequences: (*BSR_ANYCRLF) CR, LF, or CRLF only @@ -3318,9 +3348,9 @@ BACKSLASH These override the default and the options given to pcre_compile(), but they can be overridden by options given to pcre_exec(). Note that these special settings, which are not Perl-compatible, are recognized only at - the very start of a pattern, and that they must be in upper case. If - more than one of them is present, the last one is used. They can be - combined with a change of newline convention, for example, a pattern + the very start of a pattern, and that they must be in upper case. If + more than one of them is present, the last one is used. They can be + combined with a change of newline convention, for example, a pattern can start with: (*ANY)(*BSR_ANYCRLF) @@ -3330,49 +3360,49 @@ BACKSLASH Unicode character properties When PCRE is built with Unicode character property support, three addi- - tional escape sequences that match characters with specific properties - are available. When not in UTF-8 mode, these sequences are of course - limited to testing characters whose codepoints are less than 256, but + tional escape sequences that match characters with specific properties + are available. When not in UTF-8 mode, these sequences are of course + limited to testing characters whose codepoints are less than 256, but they do work in this mode. The extra escape sequences are: \p{xx} a character with the xx property \P{xx} a character without the xx property \X an extended Unicode sequence - The property names represented by xx above are limited to the Unicode + The property names represented by xx above are limited to the Unicode script names, the general category properties, and "Any", which matches any character (including newline). Other properties such as "InMusical- - Symbols" are not currently supported by PCRE. Note that \P{Any} does + Symbols" are not currently supported by PCRE. Note that \P{Any} does not match any characters, so always causes a match failure. Sets of Unicode characters are defined as belonging to certain scripts. - A character from one of these sets can be matched using a script name. + A character from one of these sets can be matched using a script name. For example: \p{Greek} \P{Han} - Those that are not part of an identified script are lumped together as + Those that are not part of an identified script are lumped together as "Common". The current list of scripts is: Arabic, Armenian, Balinese, Bengali, Bopomofo, Braille, Buginese, - Buhid, Canadian_Aboriginal, Cherokee, Common, Coptic, Cuneiform, + Buhid, Canadian_Aboriginal, Cherokee, Common, Coptic, Cuneiform, Cypriot, Cyrillic, Deseret, Devanagari, Ethiopic, Georgian, Glagolitic, - Gothic, Greek, Gujarati, Gurmukhi, Han, Hangul, Hanunoo, Hebrew, Hira- - gana, Inherited, Kannada, Katakana, Kharoshthi, Khmer, Lao, Latin, + Gothic, Greek, Gujarati, Gurmukhi, Han, Hangul, Hanunoo, Hebrew, Hira- + gana, Inherited, Kannada, Katakana, Kharoshthi, Khmer, Lao, Latin, Limbu, Linear_B, Malayalam, Mongolian, Myanmar, New_Tai_Lue, Nko, - Ogham, Old_Italic, Old_Persian, Oriya, Osmanya, Phags_Pa, Phoenician, + Ogham, Old_Italic, Old_Persian, Oriya, Osmanya, Phags_Pa, Phoenician, Runic, Shavian, Sinhala, Syloti_Nagri, Syriac, Tagalog, Tagbanwa, Tai_Le, Tamil, Telugu, Thaana, Thai, Tibetan, Tifinagh, Ugaritic, Yi. - Each character has exactly one general category property, specified by + Each character has exactly one general category property, specified by a two-letter abbreviation. For compatibility with Perl, negation can be - specified by including a circumflex between the opening brace and the + specified by including a circumflex between the opening brace and the property name. For example, \p{^Lu} is the same as \P{Lu}. If only one letter is specified with \p or \P, it includes all the gen- - eral category properties that start with that letter. In this case, in - the absence of negation, the curly brackets in the escape sequence are + eral category properties that start with that letter. In this case, in + the absence of negation, the curly brackets in the escape sequence are optional; these two examples have the same effect: \p{L} @@ -3424,57 +3454,57 @@ BACKSLASH Zp Paragraph separator Zs Space separator - The special property L& is also supported: it matches a character that - has the Lu, Ll, or Lt property, in other words, a letter that is not + The special property L& is also supported: it matches a character that + has the Lu, Ll, or Lt property, in other words, a letter that is not classified as a modifier or "other". - The Cs (Surrogate) property applies only to characters in the range - U+D800 to U+DFFF. Such characters are not valid in UTF-8 strings (see + The Cs (Surrogate) property applies only to characters in the range + U+D800 to U+DFFF. Such characters are not valid in UTF-8 strings (see RFC 3629) and so cannot be tested by PCRE, unless UTF-8 validity check- - ing has been turned off (see the discussion of PCRE_NO_UTF8_CHECK in + ing has been turned off (see the discussion of PCRE_NO_UTF8_CHECK in the pcreapi page). - The long synonyms for these properties that Perl supports (such as - \p{Letter}) are not supported by PCRE, nor is it permitted to prefix + The long synonyms for these properties that Perl supports (such as + \p{Letter}) are not supported by PCRE, nor is it permitted to prefix any of these properties with "Is". No character that is in the Unicode table has the Cn (unassigned) prop- erty. Instead, this property is assumed for any code point that is not in the Unicode table. - Specifying caseless matching does not affect these escape sequences. + Specifying caseless matching does not affect these escape sequences. For example, \p{Lu} always matches only upper case letters. - The \X escape matches any number of Unicode characters that form an + The \X escape matches any number of Unicode characters that form an extended Unicode sequence. \X is equivalent to (?>\PM\pM*) - That is, it matches a character without the "mark" property, followed - by zero or more characters with the "mark" property, and treats the - sequence as an atomic group (see below). Characters with the "mark" - property are typically accents that affect the preceding character. - None of them have codepoints less than 256, so in non-UTF-8 mode \X + That is, it matches a character without the "mark" property, followed + by zero or more characters with the "mark" property, and treats the + sequence as an atomic group (see below). Characters with the "mark" + property are typically accents that affect the preceding character. + None of them have codepoints less than 256, so in non-UTF-8 mode \X matches any one character. - Matching characters by Unicode property is not fast, because PCRE has - to search a structure that contains data for over fifteen thousand + Matching characters by Unicode property is not fast, because PCRE has + to search a structure that contains data for over fifteen thousand characters. That is why the traditional escape sequences such as \d and \w do not use Unicode properties in PCRE. Resetting the match start The escape sequence \K, which is a Perl 5.10 feature, causes any previ- - ously matched characters not to be included in the final matched + ously matched characters not to be included in the final matched sequence. For example, the pattern: foo\Kbar - matches "foobar", but reports that it has matched "bar". This feature - is similar to a lookbehind assertion (described below). However, in - this case, the part of the subject before the real match does not have - to be of fixed length, as lookbehind assertions do. The use of \K does - not interfere with the setting of captured substrings. For example, + matches "foobar", but reports that it has matched "bar". This feature + is similar to a lookbehind assertion (described below). However, in + this case, the part of the subject before the real match does not have + to be of fixed length, as lookbehind assertions do. The use of \K does + not interfere with the setting of captured substrings. For example, when the pattern (foo)\Kbar @@ -3483,10 +3513,10 @@ BACKSLASH Simple assertions - The final use of backslash is for certain simple assertions. An asser- - tion specifies a condition that has to be met at a particular point in - a match, without consuming any characters from the subject string. The - use of subpatterns for more complicated assertions is described below. + The final use of backslash is for certain simple assertions. An asser- + tion specifies a condition that has to be met at a particular point in + a match, without consuming any characters from the subject string. The + use of subpatterns for more complicated assertions is described below. The backslashed assertions are: \b matches at a word boundary @@ -3497,41 +3527,41 @@ BACKSLASH \z matches only at the end of the subject \G matches at the first matching position in the subject - These assertions may not appear in character classes (but note that \b + These assertions may not appear in character classes (but note that \b has a different meaning, namely the backspace character, inside a char- acter class). - A word boundary is a position in the subject string where the current - character and the previous character do not both match \w or \W (i.e. - one matches \w and the other matches \W), or the start or end of the + A word boundary is a position in the subject string where the current + character and the previous character do not both match \w or \W (i.e. + one matches \w and the other matches \W), or the start or end of the string if the first or last character matches \w, respectively. - The \A, \Z, and \z assertions differ from the traditional circumflex + The \A, \Z, and \z assertions differ from the traditional circumflex and dollar (described in the next section) in that they only ever match - at the very start and end of the subject string, whatever options are - set. Thus, they are independent of multiline mode. These three asser- + at the very start and end of the subject string, whatever options are + set. Thus, they are independent of multiline mode. These three asser- tions are not affected by the PCRE_NOTBOL or PCRE_NOTEOL options, which - affect only the behaviour of the circumflex and dollar metacharacters. - However, if the startoffset argument of pcre_exec() is non-zero, indi- + affect only the behaviour of the circumflex and dollar metacharacters. + However, if the startoffset argument of pcre_exec() is non-zero, indi- cating that matching is to start at a point other than the beginning of - the subject, \A can never match. The difference between \Z and \z is + the subject, \A can never match. The difference between \Z and \z is that \Z matches before a newline at the end of the string as well as at the very end, whereas \z matches only at the end. - The \G assertion is true only when the current matching position is at - the start point of the match, as specified by the startoffset argument - of pcre_exec(). It differs from \A when the value of startoffset is - non-zero. By calling pcre_exec() multiple times with appropriate argu- + The \G assertion is true only when the current matching position is at + the start point of the match, as specified by the startoffset argument + of pcre_exec(). It differs from \A when the value of startoffset is + non-zero. By calling pcre_exec() multiple times with appropriate argu- ments, you can mimic Perl's /g option, and it is in this kind of imple- mentation where \G can be useful. - Note, however, that PCRE's interpretation of \G, as the start of the + Note, however, that PCRE's interpretation of \G, as the start of the current match, is subtly different from Perl's, which defines it as the - end of the previous match. In Perl, these can be different when the - previously matched string was empty. Because PCRE does just one match + end of the previous match. In Perl, these can be different when the + previously matched string was empty. Because PCRE does just one match at a time, it cannot reproduce this behaviour. - If all the alternatives of a pattern begin with \G, the expression is + If all the alternatives of a pattern begin with \G, the expression is anchored to the starting match position, and the "anchored" flag is set in the compiled regular expression. @@ -3539,90 +3569,90 @@ BACKSLASH CIRCUMFLEX AND DOLLAR Outside a character class, in the default matching mode, the circumflex - character is an assertion that is true only if the current matching - point is at the start of the subject string. If the startoffset argu- - ment of pcre_exec() is non-zero, circumflex can never match if the - PCRE_MULTILINE option is unset. Inside a character class, circumflex + character is an assertion that is true only if the current matching + point is at the start of the subject string. If the startoffset argu- + ment of pcre_exec() is non-zero, circumflex can never match if the + PCRE_MULTILINE option is unset. Inside a character class, circumflex has an entirely different meaning (see below). - Circumflex need not be the first character of the pattern if a number - of alternatives are involved, but it should be the first thing in each - alternative in which it appears if the pattern is ever to match that - branch. If all possible alternatives start with a circumflex, that is, - if the pattern is constrained to match only at the start of the sub- - ject, it is said to be an "anchored" pattern. (There are also other + Circumflex need not be the first character of the pattern if a number + of alternatives are involved, but it should be the first thing in each + alternative in which it appears if the pattern is ever to match that + branch. If all possible alternatives start with a circumflex, that is, + if the pattern is constrained to match only at the start of the sub- + ject, it is said to be an "anchored" pattern. (There are also other constructs that can cause a pattern to be anchored.) - A dollar character is an assertion that is true only if the current - matching point is at the end of the subject string, or immediately + A dollar character is an assertion that is true only if the current + matching point is at the end of the subject string, or immediately before a newline at the end of the string (by default). Dollar need not - be the last character of the pattern if a number of alternatives are - involved, but it should be the last item in any branch in which it + be the last character of the pattern if a number of alternatives are + involved, but it should be the last item in any branch in which it appears. Dollar has no special meaning in a character class. - The meaning of dollar can be changed so that it matches only at the - very end of the string, by setting the PCRE_DOLLAR_ENDONLY option at + The meaning of dollar can be changed so that it matches only at the + very end of the string, by setting the PCRE_DOLLAR_ENDONLY option at compile time. This does not affect the \Z assertion. The meanings of the circumflex and dollar characters are changed if the - PCRE_MULTILINE option is set. When this is the case, a circumflex - matches immediately after internal newlines as well as at the start of - the subject string. It does not match after a newline that ends the - string. A dollar matches before any newlines in the string, as well as - at the very end, when PCRE_MULTILINE is set. When newline is specified - as the two-character sequence CRLF, isolated CR and LF characters do + PCRE_MULTILINE option is set. When this is the case, a circumflex + matches immediately after internal newlines as well as at the start of + the subject string. It does not match after a newline that ends the + string. A dollar matches before any newlines in the string, as well as + at the very end, when PCRE_MULTILINE is set. When newline is specified + as the two-character sequence CRLF, isolated CR and LF characters do not indicate newlines. - For example, the pattern /^abc$/ matches the subject string "def\nabc" - (where \n represents a newline) in multiline mode, but not otherwise. - Consequently, patterns that are anchored in single line mode because - all branches start with ^ are not anchored in multiline mode, and a - match for circumflex is possible when the startoffset argument of - pcre_exec() is non-zero. The PCRE_DOLLAR_ENDONLY option is ignored if + For example, the pattern /^abc$/ matches the subject string "def\nabc" + (where \n represents a newline) in multiline mode, but not otherwise. + Consequently, patterns that are anchored in single line mode because + all branches start with ^ are not anchored in multiline mode, and a + match for circumflex is possible when the startoffset argument of + pcre_exec() is non-zero. The PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE is set. - Note that the sequences \A, \Z, and \z can be used to match the start - and end of the subject in both modes, and if all branches of a pattern - start with \A it is always anchored, whether or not PCRE_MULTILINE is + Note that the sequences \A, \Z, and \z can be used to match the start + and end of the subject in both modes, and if all branches of a pattern + start with \A it is always anchored, whether or not PCRE_MULTILINE is set. FULL STOP (PERIOD, DOT) Outside a character class, a dot in the pattern matches any one charac- - ter in the subject string except (by default) a character that signi- - fies the end of a line. In UTF-8 mode, the matched character may be + ter in the subject string except (by default) a character that signi- + fies the end of a line. In UTF-8 mode, the matched character may be more than one byte long. - When a line ending is defined as a single character, dot never matches - that character; when the two-character sequence CRLF is used, dot does - not match CR if it is immediately followed by LF, but otherwise it - matches all characters (including isolated CRs and LFs). When any Uni- - code line endings are being recognized, dot does not match CR or LF or + When a line ending is defined as a single character, dot never matches + that character; when the two-character sequence CRLF is used, dot does + not match CR if it is immediately followed by LF, but otherwise it + matches all characters (including isolated CRs and LFs). When any Uni- + code line endings are being recognized, dot does not match CR or LF or any of the other line ending characters. - The behaviour of dot with regard to newlines can be changed. If the - PCRE_DOTALL option is set, a dot matches any one character, without + The behaviour of dot with regard to newlines can be changed. If the + PCRE_DOTALL option is set, a dot matches any one character, without exception. If the two-character sequence CRLF is present in the subject string, it takes two dots to match it. - The handling of dot is entirely independent of the handling of circum- - flex and dollar, the only relationship being that they both involve + The handling of dot is entirely independent of the handling of circum- + flex and dollar, the only relationship being that they both involve newlines. Dot has no special meaning in a character class. MATCHING A SINGLE BYTE Outside a character class, the escape sequence \C matches any one byte, - both in and out of UTF-8 mode. Unlike a dot, it always matches any - line-ending characters. The feature is provided in Perl in order to - match individual bytes in UTF-8 mode. Because it breaks up UTF-8 char- - acters into individual bytes, what remains in the string may be a mal- - formed UTF-8 string. For this reason, the \C escape sequence is best + both in and out of UTF-8 mode. Unlike a dot, it always matches any + line-ending characters. The feature is provided in Perl in order to + match individual bytes in UTF-8 mode. Because it breaks up UTF-8 char- + acters into individual bytes, what remains in the string may be a mal- + formed UTF-8 string. For this reason, the \C escape sequence is best avoided. - PCRE does not allow \C to appear in lookbehind assertions (described - below), because in UTF-8 mode this would make it impossible to calcu- + PCRE does not allow \C to appear in lookbehind assertions (described + below), because in UTF-8 mode this would make it impossible to calcu- late the length of the lookbehind. @@ -3631,96 +3661,96 @@ SQUARE BRACKETS AND CHARACTER CLASSES An opening square bracket introduces a character class, terminated by a closing square bracket. A closing square bracket on its own is not spe- cial. If a closing square bracket is required as a member of the class, - it should be the first data character in the class (after an initial + it should be the first data character in the class (after an initial circumflex, if present) or escaped with a backslash. - A character class matches a single character in the subject. In UTF-8 - mode, the character may occupy more than one byte. A matched character + A character class matches a single character in the subject. In UTF-8 + mode, the character may occupy more than one byte. A matched character must be in the set of characters defined by the class, unless the first - character in the class definition is a circumflex, in which case the - subject character must not be in the set defined by the class. If a - circumflex is actually required as a member of the class, ensure it is + character in the class definition is a circumflex, in which case the + subject character must not be in the set defined by the class. If a + circumflex is actually required as a member of the class, ensure it is not the first character, or escape it with a backslash. - For example, the character class [aeiou] matches any lower case vowel, - while [^aeiou] matches any character that is not a lower case vowel. + For example, the character class [aeiou] matches any lower case vowel, + while [^aeiou] matches any character that is not a lower case vowel. Note that a circumflex is just a convenient notation for specifying the - characters that are in the class by enumerating those that are not. A - class that starts with a circumflex is not an assertion: it still con- - sumes a character from the subject string, and therefore it fails if + characters that are in the class by enumerating those that are not. A + class that starts with a circumflex is not an assertion: it still con- + sumes a character from the subject string, and therefore it fails if the current pointer is at the end of the string. - In UTF-8 mode, characters with values greater than 255 can be included - in a class as a literal string of bytes, or by using the \x{ escaping + In UTF-8 mode, characters with values greater than 255 can be included + in a class as a literal string of bytes, or by using the \x{ escaping mechanism. - When caseless matching is set, any letters in a class represent both - their upper case and lower case versions, so for example, a caseless - [aeiou] matches "A" as well as "a", and a caseless [^aeiou] does not - match "A", whereas a caseful version would. In UTF-8 mode, PCRE always - understands the concept of case for characters whose values are less - than 128, so caseless matching is always possible. For characters with - higher values, the concept of case is supported if PCRE is compiled - with Unicode property support, but not otherwise. If you want to use - caseless matching for characters 128 and above, you must ensure that - PCRE is compiled with Unicode property support as well as with UTF-8 + When caseless matching is set, any letters in a class represent both + their upper case and lower case versions, so for example, a caseless + [aeiou] matches "A" as well as "a", and a caseless [^aeiou] does not + match "A", whereas a caseful version would. In UTF-8 mode, PCRE always + understands the concept of case for characters whose values are less + than 128, so caseless matching is always possible. For characters with + higher values, the concept of case is supported if PCRE is compiled + with Unicode property support, but not otherwise. If you want to use + caseless matching for characters 128 and above, you must ensure that + PCRE is compiled with Unicode property support as well as with UTF-8 support. - Characters that might indicate line breaks are never treated in any - special way when matching character classes, whatever line-ending - sequence is in use, and whatever setting of the PCRE_DOTALL and + Characters that might indicate line breaks are never treated in any + special way when matching character classes, whatever line-ending + sequence is in use, and whatever setting of the PCRE_DOTALL and PCRE_MULTILINE options is used. A class such as [^a] always matches one of these characters. - The minus (hyphen) character can be used to specify a range of charac- - ters in a character class. For example, [d-m] matches any letter - between d and m, inclusive. If a minus character is required in a - class, it must be escaped with a backslash or appear in a position - where it cannot be interpreted as indicating a range, typically as the + The minus (hyphen) character can be used to specify a range of charac- + ters in a character class. For example, [d-m] matches any letter + between d and m, inclusive. If a minus character is required in a + class, it must be escaped with a backslash or appear in a position + where it cannot be interpreted as indicating a range, typically as the first or last character in the class. It is not possible to have the literal character "]" as the end charac- - ter of a range. A pattern such as [W-]46] is interpreted as a class of - two characters ("W" and "-") followed by a literal string "46]", so it - would match "W46]" or "-46]". However, if the "]" is escaped with a - backslash it is interpreted as the end of range, so [W-\]46] is inter- - preted as a class containing a range followed by two other characters. - The octal or hexadecimal representation of "]" can also be used to end + ter of a range. A pattern such as [W-]46] is interpreted as a class of + two characters ("W" and "-") followed by a literal string "46]", so it + would match "W46]" or "-46]". However, if the "]" is escaped with a + backslash it is interpreted as the end of range, so [W-\]46] is inter- + preted as a class containing a range followed by two other characters. + The octal or hexadecimal representation of "]" can also be used to end a range. - Ranges operate in the collating sequence of character values. They can - also be used for characters specified numerically, for example - [\000-\037]. In UTF-8 mode, ranges can include characters whose values + Ranges operate in the collating sequence of character values. They can + also be used for characters specified numerically, for example + [\000-\037]. In UTF-8 mode, ranges can include characters whose values are greater than 255, for example [\x{100}-\x{2ff}]. If a range that includes letters is used when caseless matching is set, it matches the letters in either case. For example, [W-c] is equivalent - to [][\\^_`wxyzabc], matched caselessly, and in non-UTF-8 mode, if - character tables for a French locale are in use, [\xc8-\xcb] matches - accented E characters in both cases. In UTF-8 mode, PCRE supports the - concept of case for characters with values greater than 128 only when + to [][\\^_`wxyzabc], matched caselessly, and in non-UTF-8 mode, if + character tables for a French locale are in use, [\xc8-\xcb] matches + accented E characters in both cases. In UTF-8 mode, PCRE supports the + concept of case for characters with values greater than 128 only when it is compiled with Unicode property support. - The character types \d, \D, \p, \P, \s, \S, \w, and \W may also appear - in a character class, and add the characters that they match to the + The character types \d, \D, \p, \P, \s, \S, \w, and \W may also appear + in a character class, and add the characters that they match to the class. For example, [\dABCDEF] matches any hexadecimal digit. A circum- - flex can conveniently be used with the upper case character types to - specify a more restricted set of characters than the matching lower - case type. For example, the class [^\W_] matches any letter or digit, + flex can conveniently be used with the upper case character types to + specify a more restricted set of characters than the matching lower + case type. For example, the class [^\W_] matches any letter or digit, but not underscore. - The only metacharacters that are recognized in character classes are - backslash, hyphen (only where it can be interpreted as specifying a - range), circumflex (only at the start), opening square bracket (only - when it can be interpreted as introducing a POSIX class name - see the - next section), and the terminating closing square bracket. However, + The only metacharacters that are recognized in character classes are + backslash, hyphen (only where it can be interpreted as specifying a + range), circumflex (only at the start), opening square bracket (only + when it can be interpreted as introducing a POSIX class name - see the + next section), and the terminating closing square bracket. However, escaping other non-alphanumeric characters does no harm. POSIX CHARACTER CLASSES Perl supports the POSIX notation for character classes. This uses names - enclosed by [: and :] within the enclosing square brackets. PCRE also + enclosed by [: and :] within the enclosing square brackets. PCRE also supports this notation. For example, [01[:alpha:]%] @@ -3743,18 +3773,18 @@ POSIX CHARACTER CLASSES word "word" characters (same as \w) xdigit hexadecimal digits - The "space" characters are HT (9), LF (10), VT (11), FF (12), CR (13), - and space (32). Notice that this list includes the VT character (code + The "space" characters are HT (9), LF (10), VT (11), FF (12), CR (13), + and space (32). Notice that this list includes the VT character (code 11). This makes "space" different to \s, which does not include VT (for Perl compatibility). - The name "word" is a Perl extension, and "blank" is a GNU extension - from Perl 5.8. Another Perl extension is negation, which is indicated + The name "word" is a Perl extension, and "blank" is a GNU extension + from Perl 5.8. Another Perl extension is negation, which is indicated by a ^ character after the colon. For example, [12[:^digit:]] - matches "1", "2", or any non-digit. PCRE (and Perl) also recognize the + matches "1", "2", or any non-digit. PCRE (and Perl) also recognize the POSIX syntax [.ch.] and [=ch=] where "ch" is a "collating element", but these are not supported, and an error is given if they are encountered. @@ -3774,14 +3804,14 @@ VERTICAL BAR string). The matching process tries each alternative in turn, from left to right, and the first one that succeeds is used. If the alternatives are within a subpattern (defined below), "succeeds" means matching the - rest of the main pattern as well as the alternative in the subpattern. + rest of the main pattern as well as the alternative in the subpattern. INTERNAL OPTION SETTING - The settings of the PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, and - PCRE_EXTENDED options (which are Perl-compatible) can be changed from - within the pattern by a sequence of Perl option letters enclosed + The settings of the PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, and + PCRE_EXTENDED options (which are Perl-compatible) can be changed from + within the pattern by a sequence of Perl option letters enclosed between "(?" and ")". The option letters are i for PCRE_CASELESS @@ -3791,44 +3821,44 @@ INTERNAL OPTION SETTING For example, (?im) sets caseless, multiline matching. It is also possi- ble to unset these options by preceding the letter with a hyphen, and a - combined setting and unsetting such as (?im-sx), which sets PCRE_CASE- - LESS and PCRE_MULTILINE while unsetting PCRE_DOTALL and PCRE_EXTENDED, - is also permitted. If a letter appears both before and after the + combined setting and unsetting such as (?im-sx), which sets PCRE_CASE- + LESS and PCRE_MULTILINE while unsetting PCRE_DOTALL and PCRE_EXTENDED, + is also permitted. If a letter appears both before and after the hyphen, the option is unset. - The PCRE-specific options PCRE_DUPNAMES, PCRE_UNGREEDY, and PCRE_EXTRA - can be changed in the same way as the Perl-compatible options by using + The PCRE-specific options PCRE_DUPNAMES, PCRE_UNGREEDY, and PCRE_EXTRA + can be changed in the same way as the Perl-compatible options by using the characters J, U and X respectively. - When an option change occurs at top level (that is, not inside subpat- - tern parentheses), the change applies to the remainder of the pattern + When an option change occurs at top level (that is, not inside subpat- + tern parentheses), the change applies to the remainder of the pattern that follows. If the change is placed right at the start of a pattern, PCRE extracts it into the global options (and it will therefore show up in data extracted by the pcre_fullinfo() function). - An option change within a subpattern (see below for a description of + An option change within a subpattern (see below for a description of subpatterns) affects only that part of the current pattern that follows it, so (a(?i)b)c matches abc and aBc and no other strings (assuming PCRE_CASELESS is not - used). By this means, options can be made to have different settings - in different parts of the pattern. Any changes made in one alternative - do carry on into subsequent branches within the same subpattern. For + used). By this means, options can be made to have different settings + in different parts of the pattern. Any changes made in one alternative + do carry on into subsequent branches within the same subpattern. For example, (a(?i)b|c) - matches "ab", "aB", "c", and "C", even though when matching "C" the - first branch is abandoned before the option setting. This is because - the effects of option settings happen at compile time. There would be + matches "ab", "aB", "c", and "C", even though when matching "C" the + first branch is abandoned before the option setting. This is because + the effects of option settings happen at compile time. There would be some very weird behaviour otherwise. - Note: There are other PCRE-specific options that can be set by the - application when the compile or match functions are called. In some - cases the pattern can contain special leading sequences to override - what the application has set or what has been defaulted. Details are + Note: There are other PCRE-specific options that can be set by the + application when the compile or match functions are called. In some + cases the pattern can contain special leading sequences to override + what the application has set or what has been defaulted. Details are given in the section entitled "Newline sequences" above. @@ -3841,18 +3871,18 @@ SUBPATTERNS cat(aract|erpillar|) - matches one of the words "cat", "cataract", or "caterpillar". Without - the parentheses, it would match "cataract", "erpillar" or an empty + matches one of the words "cat", "cataract", or "caterpillar". Without + the parentheses, it would match "cataract", "erpillar" or an empty string. - 2. It sets up the subpattern as a capturing subpattern. This means - that, when the whole pattern matches, that portion of the subject + 2. It sets up the subpattern as a capturing subpattern. This means + that, when the whole pattern matches, that portion of the subject string that matched the subpattern is passed back to the caller via the - ovector argument of pcre_exec(). Opening parentheses are counted from - left to right (starting from 1) to obtain numbers for the capturing + ovector argument of pcre_exec(). Opening parentheses are counted from + left to right (starting from 1) to obtain numbers for the capturing subpatterns. - For example, if the string "the red king" is matched against the pat- + For example, if the string "the red king" is matched against the pat- tern the ((red|white) (king|queen)) @@ -3860,12 +3890,12 @@ SUBPATTERNS the captured substrings are "red king", "red", and "king", and are num- bered 1, 2, and 3, respectively. - The fact that plain parentheses fulfil two functions is not always - helpful. There are often times when a grouping subpattern is required - without a capturing requirement. If an opening parenthesis is followed - by a question mark and a colon, the subpattern does not do any captur- - ing, and is not counted when computing the number of any subsequent - capturing subpatterns. For example, if the string "the white queen" is + The fact that plain parentheses fulfil two functions is not always + helpful. There are often times when a grouping subpattern is required + without a capturing requirement. If an opening parenthesis is followed + by a question mark and a colon, the subpattern does not do any captur- + ing, and is not counted when computing the number of any subsequent + capturing subpatterns. For example, if the string "the white queen" is matched against the pattern the ((?:red|white) (king|queen)) @@ -3873,80 +3903,80 @@ SUBPATTERNS the captured substrings are "white queen" and "queen", and are numbered 1 and 2. The maximum number of capturing subpatterns is 65535. - As a convenient shorthand, if any option settings are required at the - start of a non-capturing subpattern, the option letters may appear + As a convenient shorthand, if any option settings are required at the + start of a non-capturing subpattern, the option letters may appear between the "?" and the ":". Thus the two patterns (?i:saturday|sunday) (?:(?i)saturday|sunday) match exactly the same set of strings. Because alternative branches are - tried from left to right, and options are not reset until the end of - the subpattern is reached, an option setting in one branch does affect - subsequent branches, so the above patterns match "SUNDAY" as well as + tried from left to right, and options are not reset until the end of + the subpattern is reached, an option setting in one branch does affect + subsequent branches, so the above patterns match "SUNDAY" as well as "Saturday". DUPLICATE SUBPATTERN NUMBERS Perl 5.10 introduced a feature whereby each alternative in a subpattern - uses the same numbers for its capturing parentheses. Such a subpattern - starts with (?| and is itself a non-capturing subpattern. For example, + uses the same numbers for its capturing parentheses. Such a subpattern + starts with (?| and is itself a non-capturing subpattern. For example, consider this pattern: (?|(Sat)ur|(Sun))day - Because the two alternatives are inside a (?| group, both sets of cap- - turing parentheses are numbered one. Thus, when the pattern matches, - you can look at captured substring number one, whichever alternative - matched. This construct is useful when you want to capture part, but + Because the two alternatives are inside a (?| group, both sets of cap- + turing parentheses are numbered one. Thus, when the pattern matches, + you can look at captured substring number one, whichever alternative + matched. This construct is useful when you want to capture part, but not all, of one of a number of alternatives. Inside a (?| group, paren- - theses are numbered as usual, but the number is reset at the start of - each branch. The numbers of any capturing buffers that follow the sub- - pattern start after the highest number used in any branch. The follow- - ing example is taken from the Perl documentation. The numbers under- + theses are numbered as usual, but the number is reset at the start of + each branch. The numbers of any capturing buffers that follow the sub- + pattern start after the highest number used in any branch. The follow- + ing example is taken from the Perl documentation. The numbers under- neath show in which buffer the captured content will be stored. # before ---------------branch-reset----------- after / ( a ) (?| x ( y ) z | (p (q) r) | (t) u (v) ) ( z ) /x # 1 2 2 3 2 3 4 - A backreference or a recursive call to a numbered subpattern always + A backreference or a recursive call to a numbered subpattern always refers to the first one in the pattern with the given number. - An alternative approach to using this "branch reset" feature is to use + An alternative approach to using this "branch reset" feature is to use duplicate named subpatterns, as described in the next section. NAMED SUBPATTERNS - Identifying capturing parentheses by number is simple, but it can be - very hard to keep track of the numbers in complicated regular expres- - sions. Furthermore, if an expression is modified, the numbers may - change. To help with this difficulty, PCRE supports the naming of sub- + Identifying capturing parentheses by number is simple, but it can be + very hard to keep track of the numbers in complicated regular expres- + sions. Furthermore, if an expression is modified, the numbers may + change. To help with this difficulty, PCRE supports the naming of sub- patterns. This feature was not added to Perl until release 5.10. Python - had the feature earlier, and PCRE introduced it at release 4.0, using - the Python syntax. PCRE now supports both the Perl and the Python syn- + had the feature earlier, and PCRE introduced it at release 4.0, using + the Python syntax. PCRE now supports both the Perl and the Python syn- tax. - In PCRE, a subpattern can be named in one of three ways: (?<name>...) - or (?'name'...) as in Perl, or (?P<name>...) as in Python. References + In PCRE, a subpattern can be named in one of three ways: (?<name>...) + or (?'name'...) as in Perl, or (?P<name>...) as in Python. References to capturing parentheses from other parts of the pattern, such as back- - references, recursion, and conditions, can be made by name as well as + references, recursion, and conditions, can be made by name as well as by number. - Names consist of up to 32 alphanumeric characters and underscores. - Named capturing parentheses are still allocated numbers as well as - names, exactly as if the names were not present. The PCRE API provides + Names consist of up to 32 alphanumeric characters and underscores. + Named capturing parentheses are still allocated numbers as well as + names, exactly as if the names were not present. The PCRE API provides function calls for extracting the name-to-number translation table from a compiled pattern. There is also a convenience function for extracting a captured substring by name. - By default, a name must be unique within a pattern, but it is possible + By default, a name must be unique within a pattern, but it is possible to relax this constraint by setting the PCRE_DUPNAMES option at compile - time. This can be useful for patterns where only one instance of the - named parentheses can match. Suppose you want to match the name of a - weekday, either as a 3-letter abbreviation or as the full name, and in + time. This can be useful for patterns where only one instance of the + named parentheses can match. Suppose you want to match the name of a + weekday, either as a 3-letter abbreviation or as the full name, and in both cases you want to extract the abbreviation. This pattern (ignoring the line breaks) does the job: @@ -3956,22 +3986,26 @@ NAMED SUBPATTERNS (?<DN>Thu)(?:rsday)?| (?<DN>Sat)(?:urday)? - There are five capturing substrings, but only one is ever set after a + There are five capturing substrings, but only one is ever set after a match. (An alternative way of solving this problem is to use a "branch reset" subpattern, as described in the previous section.) - The convenience function for extracting the data by name returns the - substring for the first (and in this example, the only) subpattern of - that name that matched. This saves searching to find which numbered - subpattern it was. If you make a reference to a non-unique named sub- - pattern from elsewhere in the pattern, the one that corresponds to the - lowest number is used. For further details of the interfaces for han- + The convenience function for extracting the data by name returns the + substring for the first (and in this example, the only) subpattern of + that name that matched. This saves searching to find which numbered + subpattern it was. If you make a reference to a non-unique named sub- + pattern from elsewhere in the pattern, the one that corresponds to the + lowest number is used. For further details of the interfaces for han- dling named subpatterns, see the pcreapi documentation. + Warning: You cannot use different names to distinguish between two sub- + patterns with the same number (see the previous section) because PCRE + uses only the numbers when matching. + REPETITION - Repetition is specified by quantifiers, which can follow any of the + Repetition is specified by quantifiers, which can follow any of the following items: a literal data character @@ -3984,17 +4018,17 @@ REPETITION a back reference (see next section) a parenthesized subpattern (unless it is an assertion) - The general repetition quantifier specifies a minimum and maximum num- - ber of permitted matches, by giving the two numbers in curly brackets - (braces), separated by a comma. The numbers must be less than 65536, + The general repetition quantifier specifies a minimum and maximum num- + ber of permitted matches, by giving the two numbers in curly brackets + (braces), separated by a comma. The numbers must be less than 65536, and the first must be less than or equal to the second. For example: z{2,4} - matches "zz", "zzz", or "zzzz". A closing brace on its own is not a - special character. If the second number is omitted, but the comma is - present, there is no upper limit; if the second number and the comma - are both omitted, the quantifier specifies an exact number of required + matches "zz", "zzz", or "zzzz". A closing brace on its own is not a + special character. If the second number is omitted, but the comma is + present, there is no upper limit; if the second number and the comma + are both omitted, the quantifier specifies an exact number of required matches. Thus [aeiou]{3,} @@ -4003,9 +4037,9 @@ REPETITION \d{8} - matches exactly 8 digits. An opening curly bracket that appears in a - position where a quantifier is not allowed, or one that does not match - the syntax of a quantifier, is taken as a literal character. For exam- + matches exactly 8 digits. An opening curly bracket that appears in a + position where a quantifier is not allowed, or one that does not match + the syntax of a quantifier, is taken as a literal character. For exam- ple, {,6} is not a quantifier, but a literal string of four characters. In UTF-8 mode, quantifiers apply to UTF-8 characters rather than to @@ -4149,27 +4183,27 @@ ATOMIC GROUPING AND POSSESSIVE QUANTIFIERS (?>\d+)foo - This kind of parenthesis "locks up" the part of the pattern it con- - tains once it has matched, and a failure further into the pattern is - prevented from backtracking into it. Backtracking past it to previous + This kind of parenthesis "locks up" the part of the pattern it con- + tains once it has matched, and a failure further into the pattern is + prevented from backtracking into it. Backtracking past it to previous items, however, works as normal. - An alternative description is that a subpattern of this type matches - the string of characters that an identical standalone pattern would + An alternative description is that a subpattern of this type matches + the string of characters that an identical standalone pattern would match, if anchored at the current point in the subject string. Atomic grouping subpatterns are not capturing subpatterns. Simple cases such as the above example can be thought of as a maximizing repeat that - must swallow everything it can. So, while both \d+ and \d+? are pre- - pared to adjust the number of digits they match in order to make the + must swallow everything it can. So, while both \d+ and \d+? are pre- + pared to adjust the number of digits they match in order to make the rest of the pattern match, (?>\d+) can only match an entire sequence of digits. - Atomic groups in general can of course contain arbitrarily complicated - subpatterns, and can be nested. However, when the subpattern for an + Atomic groups in general can of course contain arbitrarily complicated + subpatterns, and can be nested. However, when the subpattern for an atomic group is just a single repeated item, as in the example above, a - simpler notation, called a "possessive quantifier" can be used. This - consists of an additional + character following a quantifier. Using + simpler notation, called a "possessive quantifier" can be used. This + consists of an additional + character following a quantifier. Using this notation, the previous example can be rewritten as \d++foo @@ -4179,50 +4213,50 @@ ATOMIC GROUPING AND POSSESSIVE QUANTIFIERS (abc|xyz){2,3}+ - Possessive quantifiers are always greedy; the setting of the + Possessive quantifiers are always greedy; the setting of the PCRE_UNGREEDY option is ignored. They are a convenient notation for the - simpler forms of atomic group. However, there is no difference in the - meaning of a possessive quantifier and the equivalent atomic group, - though there may be a performance difference; possessive quantifiers + simpler forms of atomic group. However, there is no difference in the + meaning of a possessive quantifier and the equivalent atomic group, + though there may be a performance difference; possessive quantifiers should be slightly faster. - The possessive quantifier syntax is an extension to the Perl 5.8 syn- - tax. Jeffrey Friedl originated the idea (and the name) in the first + The possessive quantifier syntax is an extension to the Perl 5.8 syn- + tax. Jeffrey Friedl originated the idea (and the name) in the first edition of his book. Mike McCloskey liked it, so implemented it when he - built Sun's Java package, and PCRE copied it from there. It ultimately + built Sun's Java package, and PCRE copied it from there. It ultimately found its way into Perl at release 5.10. PCRE has an optimization that automatically "possessifies" certain sim- - ple pattern constructs. For example, the sequence A+B is treated as - A++B because there is no point in backtracking into a sequence of A's + ple pattern constructs. For example, the sequence A+B is treated as + A++B because there is no point in backtracking into a sequence of A's when B must follow. - When a pattern contains an unlimited repeat inside a subpattern that - can itself be repeated an unlimited number of times, the use of an - atomic group is the only way to avoid some failing matches taking a + When a pattern contains an unlimited repeat inside a subpattern that + can itself be repeated an unlimited number of times, the use of an + atomic group is the only way to avoid some failing matches taking a very long time indeed. The pattern (\D+|<\d+>)*[!?] - matches an unlimited number of substrings that either consist of non- - digits, or digits enclosed in <>, followed by either ! or ?. When it + matches an unlimited number of substrings that either consist of non- + digits, or digits enclosed in <>, followed by either ! or ?. When it matches, it runs quickly. However, if it is applied to aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa - it takes a long time before reporting failure. This is because the - string can be divided between the internal \D+ repeat and the external - * repeat in a large number of ways, and all have to be tried. (The - example uses [!?] rather than a single character at the end, because - both PCRE and Perl have an optimization that allows for fast failure - when a single character is used. They remember the last single charac- - ter that is required for a match, and fail early if it is not present - in the string.) If the pattern is changed so that it uses an atomic + it takes a long time before reporting failure. This is because the + string can be divided between the internal \D+ repeat and the external + * repeat in a large number of ways, and all have to be tried. (The + example uses [!?] rather than a single character at the end, because + both PCRE and Perl have an optimization that allows for fast failure + when a single character is used. They remember the last single charac- + ter that is required for a match, and fail early if it is not present + in the string.) If the pattern is changed so that it uses an atomic group, like this: ((?>\D+)|<\d+>)*[!?] - sequences of non-digits cannot be broken, and failure happens quickly. + sequences of non-digits cannot be broken, and failure happens quickly. BACK REFERENCES @@ -4985,8 +5019,8 @@ AUTHOR REVISION - Last updated: 19 April 2008 - Copyright (c) 1997-2008 University of Cambridge. + Last updated: 08 March 2009 + Copyright (c) 1997-2009 University of Cambridge. ------------------------------------------------------------------------------ @@ -5514,13 +5548,13 @@ MULTI-SEGMENT MATCHING WITH pcre_dfa_exec() 0: dogsbody 1: dog - The pattern matches the words "dog" or "dogsbody". When the subject is - presented in several parts ("do" and "gsb" being the first two) the - match stops when "dog" has been found, and it is not possible to con- - tinue. On the other hand, if "dogsbody" is presented as a single + The pattern matches the words "dog" or "dogsbody". When the subject is + presented in several parts ("do" and "gsb" being the first two) the + match stops when "dog" has been found, and it is not possible to con- + tinue. On the other hand, if "dogsbody" is presented as a single string, both matches are found. - Because of this phenomenon, it does not usually make sense to end a + Because of this phenomenon, it does not usually make sense to end a pattern that is going to be matched in this way with a variable repeat. 4. Patterns that contain alternatives at the top level which do not all @@ -5867,12 +5901,12 @@ DESCRIPTION command for linking an application that uses them. Because the POSIX functions call the native ones, it is also necessary to add -lpcre. - I have implemented only those option bits that can be reasonably mapped - to PCRE native options. In addition, the option REG_EXTENDED is defined - with the value zero. This has no effect, but since programs that are - written to the POSIX interface often use it, this makes it easier to - slot in PCRE as a replacement library. Other POSIX options are not even - defined. + I have implemented only those POSIX option bits that can be reasonably + mapped to PCRE native options. In addition, the option REG_EXTENDED is + defined with the value zero. This has no effect, but since programs + that are written to the POSIX interface often use it, this makes it + easier to slot in PCRE as a replacement library. Other POSIX options + are not even defined. When PCRE is called via these functions, it is only the API that is POSIX-like in style. The syntax and semantics of the regular expres- @@ -5952,9 +5986,9 @@ COMPILING A PATTERN MATCHING NEWLINE CHARACTERS This area is not simple, because POSIX and Perl take different views of - things. It is not possible to get PCRE to obey POSIX semantics, but - then PCRE was never intended to be a POSIX engine. The following table - lists the different possibilities for matching newline characters in + things. It is not possible to get PCRE to obey POSIX semantics, but + then PCRE was never intended to be a POSIX engine. The following table + lists the different possibilities for matching newline characters in PCRE: Default Change with @@ -5976,19 +6010,19 @@ MATCHING NEWLINE CHARACTERS ^ matches \n in middle no REG_NEWLINE PCRE's behaviour is the same as Perl's, except that there is no equiva- - lent for PCRE_DOLLAR_ENDONLY in Perl. In both PCRE and Perl, there is + lent for PCRE_DOLLAR_ENDONLY in Perl. In both PCRE and Perl, there is no way to stop newline from matching [^a]. - The default POSIX newline handling can be obtained by setting - PCRE_DOTALL and PCRE_DOLLAR_ENDONLY, but there is no way to make PCRE + The default POSIX newline handling can be obtained by setting + PCRE_DOTALL and PCRE_DOLLAR_ENDONLY, but there is no way to make PCRE behave exactly as for the REG_NEWLINE action. MATCHING A PATTERN - The function regexec() is called to match a compiled pattern preg - against a given string, which is by default terminated by a zero byte - (but see REG_STARTEND below), subject to the options in eflags. These + The function regexec() is called to match a compiled pattern preg + against a given string, which is by default terminated by a zero byte + (but see REG_STARTEND below), subject to the options in eflags. These can be: REG_NOTBOL @@ -5996,6 +6030,13 @@ MATCHING A PATTERN The PCRE_NOTBOL option is set when calling the underlying PCRE matching function. + REG_NOTEMPTY + + The PCRE_NOTEMPTY option is set when calling the underlying PCRE match- + ing function. Note that REG_NOTEMPTY is not part of the POSIX standard. + However, setting this option can give more POSIX-like behaviour in some + situations. + REG_NOTEOL The PCRE_NOTEOL option is set when calling the underlying PCRE matching @@ -6058,8 +6099,8 @@ AUTHOR REVISION - Last updated: 05 April 2008 - Copyright (c) 1997-2008 University of Cambridge. + Last updated: 11 March 2009 + Copyright (c) 1997-2009 University of Cambridge. ------------------------------------------------------------------------------ @@ -6163,6 +6204,10 @@ MATCHING INTERFACE need more, consider using the more general interface pcrecpp::RE::DoMatch. See pcrecpp.h for the signature for DoMatch. + NOTE: Do not use no_arg, which is used internally to mark the end of a + list of optional arguments, as a placeholder for missing arguments, as + this can lead to segfaults. + QUOTING METACHARACTERS @@ -6396,7 +6441,7 @@ AUTHOR REVISION - Last updated: 12 November 2007 + Last updated: 17 March 2009 ------------------------------------------------------------------------------ diff --git a/doc/pcre_dfa_exec.3 b/doc/pcre_dfa_exec.3 index 0975f4d..a046276 100644 --- a/doc/pcre_dfa_exec.3 +++ b/doc/pcre_dfa_exec.3 @@ -49,7 +49,7 @@ The options are: PCRE_NOTBOL Subject is not the beginning of a line PCRE_NOTEOL Subject is not the end of a line PCRE_NOTEMPTY An empty string is not a valid match - PCRE_NO_START_OPTIMIZE Do not do "start-match" optimizations + PCRE_NO_START_OPTIMIZE Do not do "start-match" optimizations PCRE_NO_UTF8_CHECK Do not check the subject for UTF-8 validity (only relevant if PCRE_UTF8 was set at compile time) diff --git a/doc/pcre_exec.3 b/doc/pcre_exec.3 index 292fe57..21bf6da 100644 --- a/doc/pcre_exec.3 +++ b/doc/pcre_exec.3 @@ -44,7 +44,7 @@ The options are: PCRE_NOTBOL Subject is not the beginning of a line PCRE_NOTEOL Subject is not the end of a line PCRE_NOTEMPTY An empty string is not a valid match - PCRE_NO_START_OPTIMIZE Do not do "start-match" optimizations + PCRE_NO_START_OPTIMIZE Do not do "start-match" optimizations PCRE_NO_UTF8_CHECK Do not check the subject for UTF-8 validity (only relevant if PCRE_UTF8 was set at compile time) diff --git a/doc/pcreapi.3 b/doc/pcreapi.3 index 12b177b..0327a7b 100644 --- a/doc/pcreapi.3 +++ b/doc/pcreapi.3 @@ -317,7 +317,7 @@ properties is available; otherwise it is set to zero. .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, -2 for ANYCRLF, and -1 for ANY. +are: 10 for LF, 13 for CR, 3338 for CRLF, -2 for ANYCRLF, and -1 for ANY. Though they are derived from ASCII, the same values are returned in EBCDIC environments. The default should normally correspond to the standard sequence for your operating system. @@ -1329,7 +1329,7 @@ code that demonstrates how to do this in the \fIpcredemo.c\fP sample program. .sp PCRE_NO_START_OPTIMIZE .sp -There are a number of optimizations that \fBpcre_exec()\fP uses at the start of +There are a number of optimizations that \fBpcre_exec()\fP uses at the start of a match, in order to speed up the process. For example, if it is known that a match must start with a specific character, it searches the subject for that character, and fails immediately if it cannot find it, without actually running @@ -1744,8 +1744,8 @@ appropriate. \fBNOTE:\fP If PCRE_DUPNAMES is set and there are duplicate names, the behaviour may not be what you want (see the next section). .P \fBWarning:\fP If the pattern uses the "(?|" feature to set up multiple -subpatterns with the same number, you cannot use names to distinguish them, -because names are not included in the compiled code. The matching process uses +subpatterns with the same number, you cannot use names to distinguish them, +because names are not included in the compiled code. The matching process uses only numbers. . .SH "DUPLICATE SUBPATTERN NAMES" diff --git a/doc/pcrebuild.3 b/doc/pcrebuild.3 index f1bfe88..926a4af 100644 --- a/doc/pcrebuild.3 +++ b/doc/pcrebuild.3 @@ -47,10 +47,10 @@ strings as UTF-8. As well as compiling PCRE with this option, you also have have to set the PCRE_UTF8 option when you call the \fBpcre_compile()\fP function. .P -If you set --enable-utf8 when compiling in an EBCDIC environment, PCRE expects -its input to be either ASCII or UTF-8 (depending on the runtime option). It is -not possible to support both EBCDIC and UTF-8 codes in the same version of the -library. Consequently, --enable-utf8 and --enable-ebcdic are mutually +If you set --enable-utf8 when compiling in an EBCDIC environment, PCRE expects +its input to be either ASCII or UTF-8 (depending on the runtime option). It is +not possible to support both EBCDIC and UTF-8 codes in the same version of the +library. Consequently, --enable-utf8 and --enable-ebcdic are mutually exclusive. . .SH "UNICODE CHARACTER PROPERTY SUPPORT" @@ -260,7 +260,7 @@ EBCDIC environment by adding .sp to the \fBconfigure\fP command. This setting implies --enable-rebuild-chartables. You should only use it if you know that you are in -an EBCDIC environment (for example, an IBM mainframe operating system). The +an EBCDIC environment (for example, an IBM mainframe operating system). The --enable-ebcdic option is incompatible with --enable-utf8. . .SH "PCREGREP OPTIONS FOR COMPRESSED FILE SUPPORT" diff --git a/doc/pcrecallout.3 b/doc/pcrecallout.3 index 8923689..abdbaed 100644 --- a/doc/pcrecallout.3 +++ b/doc/pcrecallout.3 @@ -54,9 +54,9 @@ string is "abyz", the lack of "d" means that matching doesn't ever start, and the callout is never reached. However, with "abyd", though the result is still no match, the callout is obeyed. .P -You can disable these optimizations by passing the PCRE_NO_START_OPTIMIZE -option to \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP. This slows down the -matching process, but does ensure that callouts such as the example above are +You can disable these optimizations by passing the PCRE_NO_START_OPTIMIZE +option to \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP. This slows down the +matching process, but does ensure that callouts such as the example above are obeyed. . . diff --git a/doc/pcrecpp.3 b/doc/pcrecpp.3 index 479e318..fa8c558 100644 --- a/doc/pcrecpp.3 +++ b/doc/pcrecpp.3 @@ -96,8 +96,8 @@ If you need more, consider using the more general interface \fBpcrecpp::RE::DoMatch\fP. See \fBpcrecpp.h\fP for the signature for \fBDoMatch\fP. .P -NOTE: Do not use \fBno_arg\fP, which is used internally to mark the end of a -list of optional arguments, as a placeholder for missing arguments, as this can +NOTE: Do not use \fBno_arg\fP, which is used internally to mark the end of a +list of optional arguments, as a placeholder for missing arguments, as this can lead to segfaults. . . diff --git a/doc/pcregrep.1 b/doc/pcregrep.1 index cae383d..e0d0519 100644 --- a/doc/pcregrep.1 +++ b/doc/pcregrep.1 @@ -25,7 +25,7 @@ If you attempt to use delimiters (for example, by surrounding a pattern with slashes, as is common in Perl scripts), they are interpreted as part of the pattern. Quotes can of course be used to delimit patterns on the command line because they are interpreted by the shell, and indeed they are required if a -pattern contains white space or shell metacharacters. +pattern contains white space or shell metacharacters. .P The first argument that follows any option settings is treated as the single pattern to be matched when neither \fB-e\fP nor \fB-f\fP is present. @@ -50,7 +50,7 @@ Patterns are limited to 8K or BUFSIZ characters, whichever is the greater. BUFSIZ is defined in \fB<stdio.h>\fP. When there is more than one pattern (specified by the use of \fB-e\fP and/or \fB-f\fP), each pattern is applied to each line in the order in which they are defined, except that all the \fB-e\fP -patterns are tried before the \fB-f\fP patterns. +patterns are tried before the \fB-f\fP patterns. .P By default, as soon as one pattern matches (or fails to match when \fB-v\fP is used), no further patterns are considered. However, if \fB--colour\fP (or @@ -62,12 +62,12 @@ matches on the same line can be found. If there are multiple patterns, they are all tried on the remainder of the line, but patterns that follow the one that matched are not tried on the earlier part of the line. .P -This is the same behaviour as GNU grep, but it does mean that the order in -which multiple patterns are specified can affect the output when one of the +This is the same behaviour as GNU grep, but it does mean that the order in +which multiple patterns are specified can affect the output when one of the above options is used. .P Patterns that can match an empty string are accepted, but empty string -matches are not recognized. An example is the pattern "(super)?(man)?", in +matches are not recognized. An example is the pattern "(super)?(man)?", in which all components are optional. This pattern finds all occurrences of both "super" and "man"; the output differs from matching with "super|man" when only the matching substrings are being shown. @@ -130,8 +130,8 @@ This option specifies under what circumstances the parts of a line that matched a pattern should be coloured in the output. By default, the output is not coloured. The value (which is optional, see above) may be "never", "always", or "auto". In the latter case, colouring happens only if the standard output is -connected to a terminal. More resources are used when colouring is enabled, -because \fBpcregrep\fP has to search for all possible matches in a line, not +connected to a terminal. More resources are used when colouring is enabled, +because \fBpcregrep\fP has to search for all possible matches in a line, not just one, in order to colour them all. The colour that is used can be specified by setting the environment variable diff --git a/doc/pcregrep.txt b/doc/pcregrep.txt index 84be6f9..0163d58 100644 --- a/doc/pcregrep.txt +++ b/doc/pcregrep.txt @@ -53,17 +53,27 @@ DESCRIPTION greater. BUFSIZ is defined in <stdio.h>. When there is more than one pattern (specified by the use of -e and/or -f), each pattern is applied to each line in the order in which they are defined, except that all - the -e patterns are tried before the -f patterns. As soon as one pat- - tern matches (or fails to match when -v is used), no further patterns - are considered. - - When --only-matching, --file-offsets, or --line-offsets is used, the - output is the part of the line that matched (either shown literally, or - as an offset). In this case, scanning resumes immediately following the - match, so that further matches on the same line can be found. If there - are multiple patterns, they are all tried on the remainder of the line. - However, patterns that follow the one that matched are not tried on the - earlier part of the line. + the -e patterns are tried before the -f patterns. + + By default, as soon as one pattern matches (or fails to match when -v + is used), no further patterns are considered. However, if --colour (or + --color) is used to colour the matching substrings, or if --only-match- + ing, --file-offsets, or --line-offsets is used to output only the part + of the line that matched (either shown literally, or as an offset), + scanning resumes immediately following the match, so that further + matches on the same line can be found. If there are multiple patterns, + they are all tried on the remainder of the line, but patterns that fol- + low the one that matched are not tried on the earlier part of the line. + + This is the same behaviour as GNU grep, but it does mean that the order + in which multiple patterns are specified can affect the output when one + of the above options is used. + + Patterns that can match an empty string are accepted, but empty string + matches are not recognized. An example is the pattern "(super)?(man)?", + in which all components are optional. This pattern finds all occur- + rences of both "super" and "man"; the output differs from matching with + "super|man" when only the matching substrings are being shown. If the LC_ALL or LC_CTYPE environment variable is set, pcregrep uses the value to set a locale when calling the PCRE library. The --locale @@ -124,123 +134,128 @@ OPTIONS the same shell item, separated by an equals sign. --colour=value, --color=value - This option specifies under what circumstances the part of a + This option specifies under what circumstances the parts of a line that matched a pattern should be coloured in the output. - The value may be "never" (the default), "always", or "auto". - In the latter case, colouring happens only if the standard - output is connected to a terminal. The colour can be speci- - fied by setting the environment variable PCREGREP_COLOUR or - PCREGREP_COLOR. The value of this variable should be a string - of two numbers, separated by a semicolon. They are copied - directly into the control string for setting colour on a ter- - minal, so it is your responsibility to ensure that they make - sense. If neither of the environment variables is set, the - default is "1;31", which gives red. + By default, the output is not coloured. The value (which is + optional, see above) may be "never", "always", or "auto". In + the latter case, colouring happens only if the standard out- + put is connected to a terminal. More resources are used when + colouring is enabled, because pcregrep has to search for all + possible matches in a line, not just one, in order to colour + them all. + + The colour that is used can be specified by setting the envi- + ronment variable PCREGREP_COLOUR or PCREGREP_COLOR. The value + of this variable should be a string of two numbers, separated + by a semicolon. They are copied directly into the control + string for setting colour on a terminal, so it is your + responsibility to ensure that they make sense. If neither of + the environment variables is set, the default is "1;31", + which gives red. -D action, --devices=action If an input path is not a regular file or a directory, "action" specifies how it is to be processed. Valid values - are "read" (the default) or "skip" (silently skip the path). + are "read" (the default) or "skip" (silently skip the path). -d action, --directories=action If an input path is a directory, "action" specifies how it is - to be processed. Valid values are "read" (the default), - "recurse" (equivalent to the -r option), or "skip" (silently - skip the path). In the default case, directories are read as - if they were ordinary files. In some operating systems the - effect of reading a directory like this is an immediate end- + to be processed. Valid values are "read" (the default), + "recurse" (equivalent to the -r option), or "skip" (silently + skip the path). In the default case, directories are read as + if they were ordinary files. In some operating systems the + effect of reading a directory like this is an immediate end- of-file. -e pattern, --regex=pattern, --regexp=pattern Specify a pattern to be matched. This option can be used mul- tiple times in order to specify several patterns. It can also - be used as a way of specifying a single pattern that starts - with a hyphen. When -e is used, no argument pattern is taken - from the command line; all arguments are treated as file - names. There is an overall maximum of 100 patterns. They are - applied to each line in the order in which they are defined + be used as a way of specifying a single pattern that starts + with a hyphen. When -e is used, no argument pattern is taken + from the command line; all arguments are treated as file + names. There is an overall maximum of 100 patterns. They are + applied to each line in the order in which they are defined until one matches (or fails to match if -v is used). If -f is - used with -e, the command line patterns are matched first, - followed by the patterns from the file, independent of the - order in which these options are specified. Note that multi- + used with -e, the command line patterns are matched first, + followed by the patterns from the file, independent of the + order in which these options are specified. Note that multi- ple use of -e is not the same as a single pattern with alter- natives. For example, X|Y finds the first character in a line - that is X or Y, whereas if the two patterns are given sepa- + that is X or Y, whereas if the two patterns are given sepa- rately, pcregrep finds X if it is present, even if it follows - Y in the line. It finds Y only if there is no X in the line. - This really matters only if you are using -o to show the + Y in the line. It finds Y only if there is no X in the line. + This really matters only if you are using -o to show the part(s) of the line that matched. --exclude=pattern When pcregrep is searching the files in a directory as a con- - sequence of the -r (recursive search) option, any regular + sequence of the -r (recursive search) option, any regular files whose names match the pattern are excluded. Subdirecto- - ries are not excluded by this option; they are searched - recursively, subject to the --exclude_dir and --include_dir - options. The pattern is a PCRE regular expression, and is + ries are not excluded by this option; they are searched + recursively, subject to the --exclude_dir and --include_dir + options. The pattern is a PCRE regular expression, and is matched against the final component of the file name (not the - entire path). If a file name matches both --include and - --exclude, it is excluded. There is no short form for this + entire path). If a file name matches both --include and + --exclude, it is excluded. There is no short form for this option. --exclude_dir=pattern - When pcregrep is searching the contents of a directory as a - consequence of the -r (recursive search) option, any subdi- - rectories whose names match the pattern are excluded. (Note - that the --exclude option does not affect subdirectories.) - The pattern is a PCRE regular expression, and is matched - against the final component of the name (not the entire - path). If a subdirectory name matches both --include_dir and - --exclude_dir, it is excluded. There is no short form for + When pcregrep is searching the contents of a directory as a + consequence of the -r (recursive search) option, any subdi- + rectories whose names match the pattern are excluded. (Note + that the --exclude option does not affect subdirectories.) + The pattern is a PCRE regular expression, and is matched + against the final component of the name (not the entire + path). If a subdirectory name matches both --include_dir and + --exclude_dir, it is excluded. There is no short form for this option. -F, --fixed-strings - Interpret each pattern as a list of fixed strings, separated - by newlines, instead of as a regular expression. The -w - (match as a word) and -x (match whole line) options can be + Interpret each pattern as a list of fixed strings, separated + by newlines, instead of as a regular expression. The -w + (match as a word) and -x (match whole line) options can be used with -F. They apply to each of the fixed strings. A line is selected if any of the fixed strings are found in it (sub- ject to -w or -x, if present). -f filename, --file=filename - Read a number of patterns from the file, one per line, and - match them against each line of input. A data line is output + Read a number of patterns from the file, one per line, and + match them against each line of input. A data line is output if any of the patterns match it. The filename can be given as "-" to refer to the standard input. When -f is used, patterns - specified on the command line using -e may also be present; + specified on the command line using -e may also be present; they are tested before the file's patterns. However, no other - pattern is taken from the command line; all arguments are - treated as file names. There is an overall maximum of 100 + pattern is taken from the command line; all arguments are + treated as file names. There is an overall maximum of 100 patterns. Trailing white space is removed from each line, and - blank lines are ignored. An empty file contains no patterns - and therefore matches nothing. See also the comments about - multiple patterns versus a single pattern with alternatives + blank lines are ignored. An empty file contains no patterns + and therefore matches nothing. See also the comments about + multiple patterns versus a single pattern with alternatives in the description of -e above. --file-offsets - Instead of showing lines or parts of lines that match, show - each match as an offset from the start of the file and a - length, separated by a comma. In this mode, no context is - shown. That is, the -A, -B, and -C options are ignored. If + Instead of showing lines or parts of lines that match, show + each match as an offset from the start of the file and a + length, separated by a comma. In this mode, no context is + shown. That is, the -A, -B, and -C options are ignored. If there is more than one match in a line, each of them is shown - separately. This option is mutually exclusive with --line- + separately. This option is mutually exclusive with --line- offsets and --only-matching. -H, --with-filename - Force the inclusion of the filename at the start of output - lines when searching a single file. By default, the filename - is not shown in this case. For matching lines, the filename - is followed by a colon and a space; for context lines, a - hyphen separator is used. If a line number is also being out- - put, it follows the file name without a space. + Force the inclusion of the filename at the start of output + lines when searching a single file. By default, the filename + is not shown in this case. For matching lines, the filename + is followed by a colon; for context lines, a hyphen separator + is used. If a line number is also being output, it follows + the file name. -h, --no-filename - Suppress the output filenames when searching multiple files. - By default, filenames are shown when multiple files are - searched. For matching lines, the filename is followed by a - colon and a space; for context lines, a hyphen separator is - used. If a line number is also being output, it follows the - file name without a space. + Suppress the output filenames when searching multiple files. + By default, filenames are shown when multiple files are + searched. For matching lines, the filename is followed by a + colon; for context lines, a hyphen separator is used. If a + line number is also being output, it follows the file name. --help Output a help message, giving brief details of the command options and file type support, and then exit. @@ -346,50 +361,49 @@ OPTIONS -n, --line-number Precede each output line by its line number in the file, fol- - lowed by a colon and a space for matching lines or a hyphen - and a space for context lines. If the filename is also being - output, it precedes the line number. This option is forced if - --line-offsets is used. + lowed by a colon for matching lines or a hyphen for context + lines. If the filename is also being output, it precedes the + line number. This option is forced if --line-offsets is used. -o, --only-matching - Show only the part of the line that matched a pattern. In - this mode, no context is shown. That is, the -A, -B, and -C - options are ignored. If there is more than one match in a - line, each of them is shown separately. If -o is combined - with -v (invert the sense of the match to find non-matching - lines), no output is generated, but the return code is set + Show only the part of the line that matched a pattern. In + this mode, no context is shown. That is, the -A, -B, and -C + options are ignored. If there is more than one match in a + line, each of them is shown separately. If -o is combined + with -v (invert the sense of the match to find non-matching + lines), no output is generated, but the return code is set appropriately. This option is mutually exclusive with --file- offsets and --line-offsets. -q, --quiet Work quietly, that is, display nothing except error messages. - The exit status indicates whether or not any matches were + The exit status indicates whether or not any matches were found. -r, --recursive - If any given path is a directory, recursively scan the files - it contains, taking note of any --include and --exclude set- - tings. By default, a directory is read as a normal file; in - some operating systems this gives an immediate end-of-file. - This option is a shorthand for setting the -d option to + If any given path is a directory, recursively scan the files + it contains, taking note of any --include and --exclude set- + tings. By default, a directory is read as a normal file; in + some operating systems this gives an immediate end-of-file. + This option is a shorthand for setting the -d option to "recurse". -s, --no-messages - Suppress error messages about non-existent or unreadable - files. Such files are quietly skipped. However, the return + Suppress error messages about non-existent or unreadable + files. Such files are quietly skipped. However, the return code is still 2, even if matches were found in other files. -u, --utf-8 - Operate in UTF-8 mode. This option is available only if PCRE - has been compiled with UTF-8 support. Both patterns and sub- + Operate in UTF-8 mode. This option is available only if PCRE + has been compiled with UTF-8 support. Both patterns and sub- ject lines must be valid strings of UTF-8 characters. -V, --version - Write the version numbers of pcregrep and the PCRE library + Write the version numbers of pcregrep and the PCRE library that is being used to the standard error stream. -v, --invert-match - Invert the sense of the match, so that lines which do not + Invert the sense of the match, so that lines which do not match any of the patterns are the ones that are found. -w, --word-regex, --word-regexp @@ -397,61 +411,61 @@ OPTIONS lent to having \b at the start and end of the pattern. -x, --line-regex, --line-regexp - Force the patterns to be anchored (each must start matching - at the beginning of a line) and in addition, require them to - match entire lines. This is equivalent to having ^ and $ + Force the patterns to be anchored (each must start matching + at the beginning of a line) and in addition, require them to + match entire lines. This is equivalent to having ^ and $ characters at the start and end of each alternative branch in every pattern. ENVIRONMENT VARIABLES - The environment variables LC_ALL and LC_CTYPE are examined, in that - order, for a locale. The first one that is set is used. This can be - overridden by the --locale option. If no locale is set, the PCRE + The environment variables LC_ALL and LC_CTYPE are examined, in that + order, for a locale. The first one that is set is used. This can be + overridden by the --locale option. If no locale is set, the PCRE library's default (usually the "C" locale) is used. NEWLINES - The -N (--newline) option allows pcregrep to scan files with different - newline conventions from the default. However, the setting of this - option does not affect the way in which pcregrep writes information to - the standard error and output streams. It uses the string "\n" in C - printf() calls to indicate newlines, relying on the C I/O library to - convert this to an appropriate sequence if the output is sent to a + The -N (--newline) option allows pcregrep to scan files with different + newline conventions from the default. However, the setting of this + option does not affect the way in which pcregrep writes information to + the standard error and output streams. It uses the string "\n" in C + printf() calls to indicate newlines, relying on the C I/O library to + convert this to an appropriate sequence if the output is sent to a file. OPTIONS COMPATIBILITY The majority of short and long forms of pcregrep's options are the same - as in the GNU grep program. Any long option of the form --xxx-regexp - (GNU terminology) is also available as --xxx-regex (PCRE terminology). - However, the --locale, -M, --multiline, -u, and --utf-8 options are + as in the GNU grep program. Any long option of the form --xxx-regexp + (GNU terminology) is also available as --xxx-regex (PCRE terminology). + However, the --locale, -M, --multiline, -u, and --utf-8 options are specific to pcregrep. OPTIONS WITH DATA There are four different ways in which an option with data can be spec- - ified. If a short form option is used, the data may follow immedi- + ified. If a short form option is used, the data may follow immedi- ately, or in the next command line item. For example: -f/some/file -f /some/file - If a long form option is used, the data may appear in the same command + If a long form option is used, the data may appear in the same command line item, separated by an equals character, or (with one exception) it may appear in the next command line item. For example: --file=/some/file --file /some/file - Note, however, that if you want to supply a file name beginning with ~ - as data in a shell command, and have the shell expand ~ to a home + Note, however, that if you want to supply a file name beginning with ~ + as data in a shell command, and have the shell expand ~ to a home directory, you must separate the file name from the option, because the - shell does not treat ~ specially unless it is at the start of an item. + shell does not treat ~ specially unless it is at the start of an item. The exception to the above is the --colour (or --color) option, for which the data is optional. If this option does have data, it must be @@ -494,5 +508,5 @@ AUTHOR REVISION - Last updated: 08 March 2008 - Copyright (c) 1997-2008 University of Cambridge. + Last updated: 01 March 2009 + Copyright (c) 1997-2009 University of Cambridge. diff --git a/doc/pcreposix.3 b/doc/pcreposix.3 index 0a01c3c..d63ac03 100644 --- a/doc/pcreposix.3 +++ b/doc/pcreposix.3 @@ -167,9 +167,9 @@ The PCRE_NOTBOL option is set when calling the underlying PCRE matching function. .sp REG_NOTEMPTY -.sp +.sp The PCRE_NOTEMPTY option is set when calling the underlying PCRE matching -function. Note that REG_NOTEMPTY is not part of the POSIX standard. However, +function. Note that REG_NOTEMPTY is not part of the POSIX standard. However, setting this option can give more POSIX-like behaviour in some situations. .sp REG_NOTEOL diff --git a/doc/pcretest.1 b/doc/pcretest.1 index 56b677e..dc2f4a8 100644 --- a/doc/pcretest.1 +++ b/doc/pcretest.1 @@ -51,7 +51,7 @@ compiled pattern is given after compilation. .TP 10 \fB-M\fP Behave as if each data line contains the \eM escape sequence; this causes -PCRE to discover the minimum MATCH_LIMIT and MATCH_LIMIT_RECURSION settings by +PCRE to discover the minimum MATCH_LIMIT and MATCH_LIMIT_RECURSION settings by calling \fBpcre_exec()\fP repeatedly with different limits. .TP 10 \fB-m\fP diff --git a/doc/pcretest.txt b/doc/pcretest.txt index 43adab3..aa862eb 100644 --- a/doc/pcretest.txt +++ b/doc/pcretest.txt @@ -40,35 +40,40 @@ OPTIONS -i Behave as if each regex has the /I modifier; information about the compiled pattern is given after compilation. - -m Output the size of each compiled pattern after it has been - compiled. This is equivalent to adding /M to each regular - expression. For compatibility with earlier versions of + -M Behave as if each data line contains the \M escape sequence; + this causes PCRE to discover the minimum MATCH_LIMIT and + MATCH_LIMIT_RECURSION settings by calling pcre_exec() repeat- + edly with different limits. + + -m Output the size of each compiled pattern after it has been + compiled. This is equivalent to adding /M to each regular + expression. For compatibility with earlier versions of pcretest, -s is a synonym for -m. - -o osize Set the number of elements in the output vector that is used - when calling pcre_exec() or pcre_dfa_exec() to be osize. The - default value is 45, which is enough for 14 capturing subex- - pressions for pcre_exec() or 22 different matches for - pcre_dfa_exec(). The vector size can be changed for individ- - ual matching calls by including \O in the data line (see + -o osize Set the number of elements in the output vector that is used + when calling pcre_exec() or pcre_dfa_exec() to be osize. The + default value is 45, which is enough for 14 capturing subex- + pressions for pcre_exec() or 22 different matches for + pcre_dfa_exec(). The vector size can be changed for individ- + ual matching calls by including \O in the data line (see below). - -p Behave as if each regex has the /P modifier; the POSIX wrap- - per API is used to call PCRE. None of the other options has + -p Behave as if each regex has the /P modifier; the POSIX wrap- + per API is used to call PCRE. None of the other options has any effect when -p is set. - -q Do not output the version number of pcretest at the start of + -q Do not output the version number of pcretest at the start of execution. - -S size On Unix-like systems, set the size of the runtime stack to + -S size On Unix-like systems, set the size of the runtime stack to size megabytes. - -t Run each compile, study, and match many times with a timer, - and output resulting time per compile or match (in millisec- - onds). Do not set -m with -t, because you will then get the - size output a zillion times, and the timing will be dis- - torted. You can control the number of iterations that are - used for timing by following -t with a number (as a separate + -t Run each compile, study, and match many times with a timer, + and output resulting time per compile or match (in millisec- + onds). Do not set -m with -t, because you will then get the + size output a zillion times, and the timing will be dis- + torted. You can control the number of iterations that are + used for timing by following -t with a number (as a separate item on the command line). For example, "-t 1000" would iter- ate 1000 times. The default is to iterate 500000 times. @@ -78,73 +83,73 @@ OPTIONS DESCRIPTION - If pcretest is given two filename arguments, it reads from the first + If pcretest is given two filename arguments, it reads from the first and writes to the second. If it is given only one filename argument, it - reads from that file and writes to stdout. Otherwise, it reads from - stdin and writes to stdout, and prompts for each line of input, using + reads from that file and writes to stdout. Otherwise, it reads from + stdin and writes to stdout, and prompts for each line of input, using "re>" to prompt for regular expressions, and "data>" to prompt for data lines. - When pcretest is built, a configuration option can specify that it - should be linked with the libreadline library. When this is done, if + When pcretest is built, a configuration option can specify that it + should be linked with the libreadline library. When this is done, if the input is from a terminal, it is read using the readline() function. - This provides line-editing and history facilities. The output from the + This provides line-editing and history facilities. The output from the -help option states whether or not readline() will be used. The program handles any number of sets of input on a single input file. - Each set starts with a regular expression, and continues with any num- + Each set starts with a regular expression, and continues with any num- ber of data lines to be matched against the pattern. - Each data line is matched separately and independently. If you want to + Each data line is matched separately and independently. If you want to do multi-line matches, you have to use the \n escape sequence (or \r or \r\n, etc., depending on the newline setting) in a single line of input - to encode the newline sequences. There is no limit on the length of - data lines; the input buffer is automatically extended if it is too + to encode the newline sequences. There is no limit on the length of + data lines; the input buffer is automatically extended if it is too small. - An empty line signals the end of the data lines, at which point a new - regular expression is read. The regular expressions are given enclosed + An empty line signals the end of the data lines, at which point a new + regular expression is read. The regular expressions are given enclosed in any non-alphanumeric delimiters other than backslash, for example: /(a|bc)x+yz/ - White space before the initial delimiter is ignored. A regular expres- - sion may be continued over several input lines, in which case the new- - line characters are included within it. It is possible to include the + White space before the initial delimiter is ignored. A regular expres- + sion may be continued over several input lines, in which case the new- + line characters are included within it. It is possible to include the delimiter within the pattern by escaping it, for example /abc\/def/ - If you do so, the escape and the delimiter form part of the pattern, - but since delimiters are always non-alphanumeric, this does not affect - its interpretation. If the terminating delimiter is immediately fol- + If you do so, the escape and the delimiter form part of the pattern, + but since delimiters are always non-alphanumeric, this does not affect + its interpretation. If the terminating delimiter is immediately fol- lowed by a backslash, for example, /abc/\ - then a backslash is added to the end of the pattern. This is done to - provide a way of testing the error condition that arises if a pattern + then a backslash is added to the end of the pattern. This is done to + provide a way of testing the error condition that arises if a pattern finishes with a backslash, because /abc\/ - is interpreted as the first line of a pattern that starts with "abc/", + is interpreted as the first line of a pattern that starts with "abc/", causing pcretest to read the next line as a continuation of the regular expression. PATTERN MODIFIERS - A pattern may be followed by any number of modifiers, which are mostly - single characters. Following Perl usage, these are referred to below - as, for example, "the /i modifier", even though the delimiter of the - pattern need not always be a slash, and no slash is used when writing - modifiers. Whitespace may appear between the final pattern delimiter + A pattern may be followed by any number of modifiers, which are mostly + single characters. Following Perl usage, these are referred to below + as, for example, "the /i modifier", even though the delimiter of the + pattern need not always be a slash, and no slash is used when writing + modifiers. Whitespace may appear between the final pattern delimiter and the first modifier, and between the modifiers themselves. The /i, /m, /s, and /x modifiers set the PCRE_CASELESS, PCRE_MULTILINE, - PCRE_DOTALL, or PCRE_EXTENDED options, respectively, when pcre_com- - pile() is called. These four modifier letters have the same effect as + PCRE_DOTALL, or PCRE_EXTENDED options, respectively, when pcre_com- + pile() is called. These four modifier letters have the same effect as they do in Perl. For example: /caseless/i @@ -169,32 +174,32 @@ PATTERN MODIFIERS /<bsr_anycrlf> PCRE_BSR_ANYCRLF /<bsr_unicode> PCRE_BSR_UNICODE - Those specifying line ending sequences are literal strings as shown, - but the letters can be in either case. This example sets multiline + Those specifying line ending sequences are literal strings as shown, + but the letters can be in either case. This example sets multiline matching with CRLF as the line ending sequence: /^abc/m<crlf> - Details of the meanings of these PCRE options are given in the pcreapi + Details of the meanings of these PCRE options are given in the pcreapi documentation. Finding all matches in a string - Searching for all possible matches within each subject string can be - requested by the /g or /G modifier. After finding a match, PCRE is + Searching for all possible matches within each subject string can be + requested by the /g or /G modifier. After finding a match, PCRE is called again to search the remainder of the subject string. The differ- ence between /g and /G is that the former uses the startoffset argument - to pcre_exec() to start searching at a new point within the entire - string (which is in effect what Perl does), whereas the latter passes - over a shortened substring. This makes a difference to the matching + to pcre_exec() to start searching at a new point within the entire + string (which is in effect what Perl does), whereas the latter passes + over a shortened substring. This makes a difference to the matching process if the pattern begins with a lookbehind assertion (including \b or \B). - If any call to pcre_exec() in a /g or /G sequence matches an empty - string, the next call is done with the PCRE_NOTEMPTY and PCRE_ANCHORED - flags set in order to search for another, non-empty, match at the same - point. If this second match fails, the start offset is advanced by - one, and the normal match is retried. This imitates the way Perl han- + If any call to pcre_exec() in a /g or /G sequence matches an empty + string, the next call is done with the PCRE_NOTEMPTY and PCRE_ANCHORED + flags set in order to search for another, non-empty, match at the same + point. If this second match fails, the start offset is advanced by + one, and the normal match is retried. This imitates the way Perl han- dles such cases when using the /g modifier or the split() function. Other modifiers @@ -245,14 +250,14 @@ PATTERN MODIFIERS The /S modifier causes pcre_study() to be called after the expression has been compiled, and the results used when the expression is matched. - The /M modifier causes the size of memory block used to hold the com- + The /M modifier causes the size of memory block used to hold the com- piled pattern to be output. - The /P modifier causes pcretest to call PCRE via the POSIX wrapper API - rather than its native API. When this is done, all other modifiers - except /i, /m, and /+ are ignored. REG_ICASE is set if /i is present, - and REG_NEWLINE is set if /m is present. The wrapper functions force - PCRE_DOLLAR_ENDONLY always, and PCRE_DOTALL unless REG_NEWLINE is set. + The /P modifier causes pcretest to call PCRE via the POSIX wrapper API + rather than its native API. When this is done, all other modifiers + except /i, /m, and /+ are ignored. REG_ICASE is set if /i is present, + and REG_NEWLINE is set if /m is present. The wrapper functions force + PCRE_DOLLAR_ENDONLY always, and PCRE_DOTALL unless REG_NEWLINE is set. The /8 modifier causes pcretest to call PCRE with the PCRE_UTF8 option set. This turns on support for UTF-8 character handling in PCRE, pro- @@ -491,7 +496,7 @@ OUTPUT FROM THE ALTERNATIVE MATCHING FUNCTION 2: tan (Using the normal matching function on this data finds only "tang".) - The longest matching string is always given first (and numbered zero). + The longest matching string is always given first (and numbered zero). If /g is present on the pattern, the search for further matches resumes at the end of the longest match. For example: @@ -505,16 +510,16 @@ OUTPUT FROM THE ALTERNATIVE MATCHING FUNCTION 1: tan 0: tan - Since the matching function does not support substring capture, the - escape sequences that are concerned with captured substrings are not + Since the matching function does not support substring capture, the + escape sequences that are concerned with captured substrings are not relevant. RESTARTING AFTER A PARTIAL MATCH When the alternative matching function has given the PCRE_ERROR_PARTIAL - return, indicating that the subject partially matched the pattern, you - can restart the match with additional subject data by means of the \R + return, indicating that the subject partially matched the pattern, you + can restart the match with additional subject data by means of the \R escape sequence. For example: re> /^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$/ @@ -523,30 +528,30 @@ RESTARTING AFTER A PARTIAL MATCH data> n05\R\D 0: n05 - For further information about partial matching, see the pcrepartial + For further information about partial matching, see the pcrepartial documentation. CALLOUTS - If the pattern contains any callout requests, pcretest's callout func- - tion is called during matching. This works with both matching func- + If the pattern contains any callout requests, pcretest's callout func- + tion is called during matching. This works with both matching func- tions. By default, the called function displays the callout number, the - start and current positions in the text at the callout time, and the + start and current positions in the text at the callout time, and the next pattern item to be tested. For example, the output --->pqrabcdef 0 ^ ^ \d - indicates that callout number 0 occurred for a match attempt starting - at the fourth character of the subject string, when the pointer was at - the seventh character of the data, and when the next pattern item was - \d. Just one circumflex is output if the start and current positions + indicates that callout number 0 occurred for a match attempt starting + at the fourth character of the subject string, when the pointer was at + the seventh character of the data, and when the next pattern item was + \d. Just one circumflex is output if the start and current positions are the same. Callouts numbered 255 are assumed to be automatic callouts, inserted as - a result of the /C pattern modifier. In this case, instead of showing - the callout number, the offset in the pattern, preceded by a plus, is + a result of the /C pattern modifier. In this case, instead of showing + the callout number, the offset in the pattern, preceded by a plus, is output. For example: re> /\d?[A-E]\*/C @@ -558,24 +563,24 @@ CALLOUTS +10 ^ ^ 0: E* - The callout function in pcretest returns zero (carry on matching) by - default, but you can use a \C item in a data line (as described above) + The callout function in pcretest returns zero (carry on matching) by + default, but you can use a \C item in a data line (as described above) to change this. - Inserting callouts can be helpful when using pcretest to check compli- - cated regular expressions. For further information about callouts, see + Inserting callouts can be helpful when using pcretest to check compli- + cated regular expressions. For further information about callouts, see the pcrecallout documentation. NON-PRINTING CHARACTERS - When pcretest is outputting text in the compiled version of a pattern, - bytes other than 32-126 are always treated as non-printing characters + When pcretest is outputting text in the compiled version of a pattern, + bytes other than 32-126 are always treated as non-printing characters are are therefore shown as hex escapes. - When pcretest is outputting text that is a matched part of a subject - string, it behaves in the same way, unless a different locale has been - set for the pattern (using the /L modifier). In this case, the + When pcretest is outputting text that is a matched part of a subject + string, it behaves in the same way, unless a different locale has been + set for the pattern (using the /L modifier). In this case, the isprint() function to distinguish printing and non-printing characters. @@ -650,5 +655,5 @@ AUTHOR REVISION - Last updated: 12 April 2008 - Copyright (c) 1997-2008 University of Cambridge. + Last updated: 10 March 2009 + Copyright (c) 1997-2009 University of Cambridge. @@ -95,7 +95,7 @@ it is needed here for malloc. */ extern "C" { #endif -/* Options. Some are compile-time only, some are run-time only, and some are +/* Options. Some are compile-time only, some are run-time only, and some are both, so we keep them all distinct. */ #define PCRE_CASELESS 0x00000001 diff --git a/pcre_compile.c b/pcre_compile.c index c498fb8..cfd803d 100644 --- a/pcre_compile.c +++ b/pcre_compile.c @@ -100,50 +100,50 @@ is invalid. */ #ifndef EBCDIC /* This is the "normal" table for ASCII systems or for EBCDIC systems running -in UTF-8 mode. */ +in UTF-8 mode. */ -static const short int escapes[] = { - 0, 0, +static const short int escapes[] = { + 0, 0, + 0, 0, + 0, 0, 0, 0, - 0, 0, 0, 0, - 0, 0, CHAR_COLON, CHAR_SEMICOLON, - CHAR_LESS_THAN_SIGN, CHAR_EQUALS_SIGN, + CHAR_LESS_THAN_SIGN, CHAR_EQUALS_SIGN, CHAR_GREATER_THAN_SIGN, CHAR_QUESTION_MARK, - CHAR_COMMERCIAL_AT, -ESC_A, - -ESC_B, -ESC_C, - -ESC_D, -ESC_E, - 0, -ESC_G, - -ESC_H, 0, - 0, -ESC_K, - 0, 0, + CHAR_COMMERCIAL_AT, -ESC_A, + -ESC_B, -ESC_C, + -ESC_D, -ESC_E, + 0, -ESC_G, + -ESC_H, 0, + 0, -ESC_K, + 0, 0, 0, 0, -ESC_P, -ESC_Q, -ESC_R, -ESC_S, - 0, 0, - -ESC_V, -ESC_W, - -ESC_X, 0, - -ESC_Z, CHAR_LEFT_SQUARE_BRACKET, + 0, 0, + -ESC_V, -ESC_W, + -ESC_X, 0, + -ESC_Z, CHAR_LEFT_SQUARE_BRACKET, CHAR_BACKSLASH, CHAR_RIGHT_SQUARE_BRACKET, - CHAR_CIRCUMFLEX_ACCENT, CHAR_UNDERSCORE, + CHAR_CIRCUMFLEX_ACCENT, CHAR_UNDERSCORE, CHAR_GRAVE_ACCENT, 7, - -ESC_b, 0, - -ESC_d, ESC_e, + -ESC_b, 0, + -ESC_d, ESC_e, ESC_f, 0, -ESC_h, 0, - 0, -ESC_k, + 0, -ESC_k, 0, 0, ESC_n, 0, - -ESC_p, 0, - ESC_r, -ESC_s, + -ESC_p, 0, + ESC_r, -ESC_s, ESC_tee, 0, - -ESC_v, -ESC_w, - 0, 0, + -ESC_v, -ESC_w, + 0, 0, -ESC_z }; -#else +#else /* This is the "abnormal" table for EBCDIC systems without UTF-8 support. */ @@ -177,8 +177,8 @@ static const short int escapes[] = { /* Table of special "verbs" like (*PRUNE). This is a short table, so it is searched linearly. Put all the names into a single string, in order to reduce -the number of relocations when a shared library is dynamically linked. The -string is built from string macros so that it works in UTF-8 mode on EBCDIC +the number of relocations when a shared library is dynamically linked. The +string is built from string macros so that it works in UTF-8 mode on EBCDIC platforms. */ typedef struct verbitem { @@ -215,8 +215,8 @@ length entry. The first three must be alpha, lower, upper, as this is assumed for handling case independence. */ static const char posix_names[] = - STRING_alpha0 STRING_lower0 STRING_upper0 STRING_alnum0 - STRING_ascii0 STRING_blank0 STRING_cntrl0 STRING_digit0 + STRING_alpha0 STRING_lower0 STRING_upper0 STRING_alnum0 + STRING_ascii0 STRING_blank0 STRING_cntrl0 STRING_digit0 STRING_graph0 STRING_print0 STRING_punct0 STRING_space0 STRING_word0 STRING_xdigit; @@ -360,9 +360,9 @@ For convenience, we use the same bit definitions as in chartables: Then we can use ctype_digit and ctype_xdigit in the code. */ -#ifndef EBCDIC +#ifndef EBCDIC -/* This is the "normal" case, for ASCII systems, and EBCDIC systems running in +/* This is the "normal" case, for ASCII systems, and EBCDIC systems running in UTF-8 mode. */ static const unsigned char digitab[] = @@ -400,7 +400,7 @@ static const unsigned char digitab[] = 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, /* 240-247 */ 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00};/* 248-255 */ -#else +#else /* This is the "abnormal" case, for EBCDIC systems not running in UTF-8 mode. */ @@ -1057,7 +1057,7 @@ for (; *ptr != 0; ptr++) /* Skip over character classes; this logic must be similar to the way they are handled for real. If the first character is '^', skip it. Also, if the first few characters (either before or after ^) are \Q\E or \E we skip them - too. This makes for compatibility with Perl. Note the use of STR macros to + too. This makes for compatibility with Perl. Note the use of STR macros to encode "Q\\E" so that it works in UTF-8 on EBCDIC platforms. */ if (*ptr == CHAR_LEFT_SQUARE_BRACKET) @@ -1068,12 +1068,12 @@ for (; *ptr != 0; ptr++) int c = *(++ptr); if (c == CHAR_BACKSLASH) { - if (ptr[1] == CHAR_E) + if (ptr[1] == CHAR_E) ptr++; - else if (strncmp((const char *)ptr+1, - STR_Q STR_BACKSLASH STR_E, 3) == 0) + else if (strncmp((const char *)ptr+1, + STR_Q STR_BACKSLASH STR_E, 3) == 0) ptr += 3; - else + else break; } else if (!negate_class && c == CHAR_CIRCUMFLEX_ACCENT) @@ -1084,7 +1084,7 @@ for (; *ptr != 0; ptr++) /* If the next character is ']', it is a data character that must be skipped, except in JavaScript compatibility mode. */ - if (ptr[1] == CHAR_RIGHT_SQUARE_BRACKET && + if (ptr[1] == CHAR_RIGHT_SQUARE_BRACKET && (cd->external_options & PCRE_JAVASCRIPT_COMPAT) == 0) ptr++; @@ -1130,7 +1130,7 @@ for (; *ptr != 0; ptr++) /* We have to disambiguate (?<! and (?<= from (?<name> */ - if ((*ptr != CHAR_LESS_THAN_SIGN || ptr[1] == CHAR_EXCLAMATION_MARK || + if ((*ptr != CHAR_LESS_THAN_SIGN || ptr[1] == CHAR_EXCLAMATION_MARK || ptr[1] == CHAR_EQUALS_SIGN) && *ptr != CHAR_APOSTROPHE) continue; @@ -2173,7 +2173,7 @@ if ((options & PCRE_EXTENDED) != 0) /* If the next thing is itself optional, we have to give up. */ -if (*ptr == CHAR_ASTERISK || *ptr == CHAR_QUESTION_MARK || +if (*ptr == CHAR_ASTERISK || *ptr == CHAR_QUESTION_MARK || strncmp((char *)ptr, STR_LEFT_CURLY_BRACKET STR_0 STR_COMMA, 3) == 0) return FALSE; @@ -2639,7 +2639,7 @@ for (;; ptr++) /* Fill in length of a previous callout, except when the next thing is a quantifier. */ - is_quantifier = + is_quantifier = c == CHAR_ASTERISK || c == CHAR_PLUS || c == CHAR_QUESTION_MARK || (c == CHAR_LEFT_CURLY_BRACKET && is_counted_repeat(ptr+1)); @@ -2759,7 +2759,7 @@ for (;; ptr++) /* PCRE supports POSIX class stuff inside a class. Perl gives an error if they are encountered at the top level, so we'll do that too. */ - if ((ptr[1] == CHAR_COLON || ptr[1] == CHAR_DOT || + if ((ptr[1] == CHAR_COLON || ptr[1] == CHAR_DOT || ptr[1] == CHAR_EQUALS_SIGN) && check_posix_syntax(ptr, &tempptr)) { @@ -2777,12 +2777,12 @@ for (;; ptr++) c = *(++ptr); if (c == CHAR_BACKSLASH) { - if (ptr[1] == CHAR_E) + if (ptr[1] == CHAR_E) ptr++; - else if (strncmp((const char *)ptr+1, - STR_Q STR_BACKSLASH STR_E, 3) == 0) + else if (strncmp((const char *)ptr+1, + STR_Q STR_BACKSLASH STR_E, 3) == 0) ptr += 3; - else + else break; } else if (!negate_class && c == CHAR_CIRCUMFLEX_ACCENT) @@ -2795,7 +2795,7 @@ for (;; ptr++) that. In JS mode, [] must always fail, so generate OP_FAIL, whereas [^] must match any character, so generate OP_ALLANY. */ - if (c == CHAR_RIGHT_SQUARE_BRACKET && + if (c == CHAR_RIGHT_SQUARE_BRACKET && (cd->external_options & PCRE_JAVASCRIPT_COMPAT) != 0) { *code++ = negate_class? OP_ALLANY : OP_FAIL; @@ -2877,7 +2877,7 @@ for (;; ptr++) 5.6 and 5.8 do. */ if (c == CHAR_LEFT_SQUARE_BRACKET && - (ptr[1] == CHAR_COLON || ptr[1] == CHAR_DOT || + (ptr[1] == CHAR_COLON || ptr[1] == CHAR_DOT || ptr[1] == CHAR_EQUALS_SIGN) && check_posix_syntax(ptr, &tempptr)) { BOOL local_negate = FALSE; @@ -3227,7 +3227,7 @@ for (;; ptr++) while (*ptr == CHAR_BACKSLASH && ptr[1] == CHAR_Q) { ptr += 2; - if (*ptr == CHAR_BACKSLASH && ptr[1] == CHAR_E) + if (*ptr == CHAR_BACKSLASH && ptr[1] == CHAR_E) { ptr += 2; continue; } inescq = TRUE; break; @@ -4427,7 +4427,7 @@ we set the flag only if there is a literal "\r" or "\n" in the class. */ } namelen = ptr - name; - if ((terminator > 0 && *ptr++ != terminator) || + if ((terminator > 0 && *ptr++ != terminator) || *ptr++ != CHAR_RIGHT_PARENTHESIS) { ptr--; /* Error offset */ @@ -4626,7 +4626,7 @@ we set the flag only if there is a literal "\r" or "\n" in the class. */ /* ------------------------------------------------------------ */ case CHAR_P: /* Python-style named subpattern handling */ - if (*(++ptr) == CHAR_EQUALS_SIGN || + if (*(++ptr) == CHAR_EQUALS_SIGN || *ptr == CHAR_GREATER_THAN_SIGN) /* Reference or recursion */ { is_recurse = *ptr == CHAR_GREATER_THAN_SIGN; @@ -4645,7 +4645,7 @@ we set the flag only if there is a literal "\r" or "\n" in the class. */ DEFINE_NAME: /* Come here from (?< handling */ case CHAR_APOSTROPHE: { - terminator = (*ptr == CHAR_LESS_THAN_SIGN)? + terminator = (*ptr == CHAR_LESS_THAN_SIGN)? CHAR_GREATER_THAN_SIGN : CHAR_APOSTROPHE; name = ++ptr; @@ -5240,7 +5240,7 @@ we set the flag only if there is a literal "\r" or "\n" in the class. */ { if (-c == ESC_Q) /* Handle start of quoted string */ { - if (ptr[1] == CHAR_BACKSLASH && ptr[2] == CHAR_E) + if (ptr[1] == CHAR_BACKSLASH && ptr[2] == CHAR_E) ptr += 2; /* avoid empty string */ else inescq = TRUE; continue; @@ -5270,7 +5270,7 @@ we set the flag only if there is a literal "\r" or "\n" in the class. */ { const uschar *p; save_hwm = cd->hwm; /* Normally this is set when '(' is read */ - terminator = (*(++ptr) == CHAR_LESS_THAN_SIGN)? + terminator = (*(++ptr) == CHAR_LESS_THAN_SIGN)? CHAR_GREATER_THAN_SIGN : CHAR_APOSTROPHE; /* These two statements stop the compiler for warning about possibly @@ -5321,12 +5321,12 @@ we set the flag only if there is a literal "\r" or "\n" in the class. */ /* \k<name> or \k'name' is a back reference by name (Perl syntax). We also support \k{name} (.NET syntax) */ - if (-c == ESC_k && (ptr[1] == CHAR_LESS_THAN_SIGN || + if (-c == ESC_k && (ptr[1] == CHAR_LESS_THAN_SIGN || ptr[1] == CHAR_APOSTROPHE || ptr[1] == CHAR_LEFT_CURLY_BRACKET)) { is_recurse = FALSE; - terminator = (*(++ptr) == CHAR_LESS_THAN_SIGN)? - CHAR_GREATER_THAN_SIGN : (*ptr == CHAR_APOSTROPHE)? + terminator = (*(++ptr) == CHAR_LESS_THAN_SIGN)? + CHAR_GREATER_THAN_SIGN : (*ptr == CHAR_APOSTROPHE)? CHAR_APOSTROPHE : CHAR_RIGHT_CURLY_BRACKET; goto NAMED_REF_OR_RECURSE; } @@ -5879,7 +5879,7 @@ do { const uschar *scode = first_significant_code(code + _pcre_OP_lengths[*code], NULL, 0, FALSE); register int op = *scode; - + /* If we are at the start of a conditional assertion group, *both* the conditional assertion *and* what follows the condition must satisfy the test for start of line. Other kinds of condition fail. Note that there may be an @@ -5887,24 +5887,24 @@ do { if (op == OP_COND) { - scode += 1 + LINK_SIZE; + scode += 1 + LINK_SIZE; if (*scode == OP_CALLOUT) scode += _pcre_OP_lengths[OP_CALLOUT]; switch (*scode) { case OP_CREF: case OP_RREF: case OP_DEF: - return FALSE; - + return FALSE; + default: /* Assertion */ - if (!is_startline(scode, bracket_map, backref_map)) return FALSE; + if (!is_startline(scode, bracket_map, backref_map)) return FALSE; do scode += GET(scode, 1); while (*scode == OP_ALT); - scode += 1 + LINK_SIZE; - break; - } + scode += 1 + LINK_SIZE; + break; + } scode = first_significant_code(scode, NULL, 0, FALSE); - op = *scode; - } + op = *scode; + } /* Non-capturing brackets */ @@ -5925,8 +5925,8 @@ do { /* Other brackets */ else if (op == OP_ASSERT || op == OP_ONCE) - { - if (!is_startline(scode, bracket_map, backref_map)) return FALSE; + { + if (!is_startline(scode, bracket_map, backref_map)) return FALSE; } /* .* means "start at start or after \n" if it isn't in brackets that @@ -6141,7 +6141,7 @@ cd->ctypes = tables + ctypes_offset; /* Check for global one-time settings at the start of the pattern, and remember the offset for later. */ -while (ptr[skipatstart] == CHAR_LEFT_PARENTHESIS && +while (ptr[skipatstart] == CHAR_LEFT_PARENTHESIS && ptr[skipatstart+1] == CHAR_ASTERISK) { int newnl = 0; diff --git a/pcre_dfa_exec.c b/pcre_dfa_exec.c index c728501..d7be929 100644 --- a/pcre_dfa_exec.c +++ b/pcre_dfa_exec.c @@ -3,7 +3,7 @@ *************************************************/ /* PCRE is a library of functions to support regular expressions whose syntax -and semantics are as close as possible to those of the Perl 5 language (but see +and semantics are as close as possible to those of the Perl 5 language (but see below for why this module is different). Written by Philip Hazel @@ -2747,17 +2747,17 @@ for (;;) while (t < md->end_subject && !IS_NEWLINE(t)) t++; end_subject = t; } - + /* There are some optimizations that avoid running the match if a known starting point is not found, or if a known later character is not present. However, there is an option that disables these, for testing and for ensuring that all callouts do actually occur. */ if ((options & PCRE_NO_START_OPTIMIZE) == 0) - { - + { + /* Advance to a known first byte. */ - + if (first_byte >= 0) { if (first_byte_caseless) @@ -2765,13 +2765,13 @@ for (;;) lcc[*current_subject] != first_byte) current_subject++; else - while (current_subject < end_subject && + while (current_subject < end_subject && *current_subject != first_byte) current_subject++; } - + /* Or to just after a linebreak for a multiline match if possible */ - + else if (startline) { if (current_subject > md->start_subject + start_offset) @@ -2779,7 +2779,7 @@ for (;;) #ifdef SUPPORT_UTF8 if (utf8) { - while (current_subject < end_subject && + while (current_subject < end_subject && !WAS_NEWLINE(current_subject)) { current_subject++; @@ -2792,11 +2792,11 @@ for (;;) #endif while (current_subject < end_subject && !WAS_NEWLINE(current_subject)) current_subject++; - + /* If we have just passed a CR and the newline option is ANY or ANYCRLF, and we are now at a LF, advance the match position by one more character. */ - + if (current_subject[-1] == CHAR_CR && (md->nltype == NLTYPE_ANY || md->nltype == NLTYPE_ANYCRLF) && current_subject < end_subject && @@ -2804,9 +2804,9 @@ for (;;) current_subject++; } } - + /* Or to a non-unique first char after study */ - + else if (start_bits != NULL) { while (current_subject < end_subject) @@ -2816,7 +2816,7 @@ for (;;) else break; } } - } + } /* Restore fudged end_subject */ @@ -2836,7 +2836,7 @@ for (;;) showed up when somebody was matching /^C/ on a 32-megabyte string... so we don't do this when the string is sufficiently long. - ALSO: this processing is disabled when partial matching is requested, and can + ALSO: this processing is disabled when partial matching is requested, and can also be explicitly deactivated. */ if ((options & PCRE_NO_START_OPTIMIZE) == 0 && diff --git a/pcre_exec.c b/pcre_exec.c index 39726bc..21cc990 100644 --- a/pcre_exec.c +++ b/pcre_exec.c @@ -789,7 +789,7 @@ for (;;) case OP_SCOND: /* Because of the way auto-callout works during compile, a callout item is inserted between OP_COND and an assertion condition. */ - + if (ecode[LINK_SIZE+1] == OP_CALLOUT) { if (pcre_callout != NULL) @@ -812,9 +812,9 @@ for (;;) } ecode += _pcre_OP_lengths[OP_CALLOUT]; } - + /* Now see what the actual condition is */ - + if (ecode[LINK_SIZE+1] == OP_RREF) /* Recursion test */ { offset = GET2(ecode, LINK_SIZE + 2); /* Recursion group number*/ @@ -4716,7 +4716,7 @@ for(;;) register int *iend = iptr + resetcount; while (iptr < iend) *iptr++ = -1; } - + /* If firstline is TRUE, the start of the match is constrained to the first line of a multiline string. That is, the match must be before or at the first newline. Implement this by temporarily adjusting end_subject so that we stop @@ -4740,14 +4740,14 @@ for(;;) while (t < md->end_subject && !IS_NEWLINE(t)) t++; end_subject = t; } - + /* There are some optimizations that avoid running the match if a known starting point is not found, or if a known later character is not present. However, there is an option that disables these, for testing and for ensuring that all callouts do actually occur. */ - + if ((options & PCRE_NO_START_OPTIMIZE) == 0) - { + { /* Advance to a unique first byte if there is one. */ if (first_byte >= 0) @@ -4759,9 +4759,9 @@ for(;;) while (start_match < end_subject && *start_match != first_byte) start_match++; } - + /* Or to just after a linebreak for a multiline match */ - + else if (startline) { if (start_match > md->start_subject + start_offset) @@ -4780,11 +4780,11 @@ for(;;) #endif while (start_match < end_subject && !WAS_NEWLINE(start_match)) start_match++; - + /* If we have just passed a CR and the newline option is ANY or ANYCRLF, and we are now at a LF, advance the match position by one more character. */ - + if (start_match[-1] == CHAR_CR && (md->nltype == NLTYPE_ANY || md->nltype == NLTYPE_ANYCRLF) && start_match < end_subject && @@ -4792,9 +4792,9 @@ for(;;) start_match++; } } - + /* Or to a non-unique first byte after study */ - + else if (start_bits != NULL) { while (start_match < end_subject) @@ -4805,9 +4805,9 @@ for(;;) } } } /* Starting optimizations */ - + /* Restore fudged end_subject */ - + end_subject = save_end_subject; #ifdef DEBUG /* Sigh. Some compilers never learn. */ @@ -4830,7 +4830,7 @@ for(;;) 32-megabyte string... so we don't do this when the string is sufficiently long. - ALSO: this processing is disabled when partial matching is requested, or if + ALSO: this processing is disabled when partial matching is requested, or if disabling is explicitly requested. */ if ((options & PCRE_NO_START_OPTIMIZE) == 0 && diff --git a/pcre_internal.h b/pcre_internal.h index 4bfdf4a..5d6f5a7 100644 --- a/pcre_internal.h +++ b/pcre_internal.h @@ -51,7 +51,7 @@ functions whose names all begin with "_pcre_". */ #define DEBUG #endif -/* We do not support both EBCDIC and UTF-8 at the same time. The "configure" +/* We do not support both EBCDIC and UTF-8 at the same time. The "configure" script prevents both being selected, but not everybody uses "configure". */ #if defined EBCDIC && defined SUPPORT_UTF8 @@ -600,19 +600,19 @@ typedef int BOOL; /* If PCRE is to support UTF-8 on EBCDIC platforms, we cannot use normal character constants like '*' because the compiler would emit their EBCDIC code, -which is different from their ASCII/UTF-8 code. Instead we define macros for -the characters so that they always use the ASCII/UTF-8 code when UTF-8 support -is enabled. When UTF-8 support is not enabled, the definitions use character -literals. Both character and string versions of each character are needed, and +which is different from their ASCII/UTF-8 code. Instead we define macros for +the characters so that they always use the ASCII/UTF-8 code when UTF-8 support +is enabled. When UTF-8 support is not enabled, the definitions use character +literals. Both character and string versions of each character are needed, and there are some longer strings as well. -This means that, on EBCDIC platforms, the PCRE library can handle either +This means that, on EBCDIC platforms, the PCRE library can handle either EBCDIC, or UTF-8, but not both. To support both in the same compiled library would need different lookups depending on whether PCRE_UTF8 was set or not. This would make it impossible to use characters in switch/case statements, -which would reduce performance. For a theoretical use (which nobody has asked -for) in a minority area (EBCDIC platforms), this is not sensible. Any -application that did need both could compile two versions of the library, using +which would reduce performance. For a theoretical use (which nobody has asked +for) in a minority area (EBCDIC platforms), this is not sensible. Any +application that did need both could compile two versions of the library, using macros to give the functions distinct names. */ #ifndef SUPPORT_UTF8 diff --git a/pcre_tables.c b/pcre_tables.c index f1a8de4..6333134 100644 --- a/pcre_tables.c +++ b/pcre_tables.c @@ -110,7 +110,7 @@ table itself. Maintenance is more error-prone, but frequent changes to this data are unlikely. July 2008: There is now a script called maint/GenerateUtt.py that can be used -to generate this data instead of maintaining it entirely by hand. +to generate this data instead of maintaining it entirely by hand. The script was updated in March 2009 to generate a new EBCDIC-compliant version. Like all other character and string literals that are compared against @@ -234,7 +234,7 @@ strings to make sure that UTF-8 support works on EBCDIC platforms. */ #define STRING_Zp0 STR_Z STR_p "\0" #define STRING_Zs0 STR_Z STR_s "\0" -const char _pcre_utt_names[] = +const char _pcre_utt_names[] = STRING_Any0 STRING_Arabic0 STRING_Armenian0 @@ -646,7 +646,7 @@ class PCRECPP_EXP_DEFN RE { // regexp wasn't valid on construction. int NumberOfCapturingGroups() const; - // The default value for an argument, to indicate the end of the argument + // The default value for an argument, to indicate the end of the argument // list. This must be used only in optional argument defaults. It should NOT // be passed explicitly. Some people have tried to use it like this: // @@ -654,7 +654,7 @@ class PCRECPP_EXP_DEFN RE { // // This is a mistake, and will not work. static Arg no_arg; - + private: void Init(const string& pattern, const RE_Options* options); @@ -825,8 +825,8 @@ if (after_context > 0 && lastmatchnumber > 0) * Apply patterns to subject till one matches * *************************************************/ -/* This function is called to run through all patterns, looking for a match. It -is used multiple times for the same subject when colouring is enabled, in order +/* This function is called to run through all patterns, looking for a match. It +is used multiple times for the same subject when colouring is enabled, in order to find all possible matches. Arguments: @@ -834,11 +834,11 @@ Arguments: length the length of the subject to match offsets the offets vector to fill in mrc address of where to put the result of pcre_exec() - -Returns: TRUE if there was a match + +Returns: TRUE if there was a match FALSE if there was no match invert if there was a non-fatal error -*/ +*/ static BOOL match_patterns(char *matchptr, size_t length, int *offsets, int *mrc) @@ -992,7 +992,7 @@ while (ptr < endptr) #include <time.h> struct timeval start_time, end_time; struct timezone dummy; - int i; + int i; if (jfriedl_XT) { @@ -1018,7 +1018,7 @@ while (ptr < endptr) for (i = 0; i < jfriedl_XR; i++) - match = (pcre_exec(pattern_list[0], hints_list[0], ptr, length, 0, + match = (pcre_exec(pattern_list[0], hints_list[0], ptr, length, 0, PCRE_NOTEMPTY, offsets, OFFSET_SIZE) >= 0); if (gettimeofday(&end_time, &dummy) != 0) @@ -1038,10 +1038,10 @@ while (ptr < endptr) ONLY_MATCHING_RESTART: - /* Run through all the patterns until one matches or there is an error other + /* Run through all the patterns until one matches or there is an error other than NOMATCH. This code is in a subroutine so that it can be re-used for finding subsequent matches when colouring matched lines. */ - + match = match_patterns(matchptr, length, offsets, &mrc); /* If it's a match or a not-match (as required), do what's wanted. */ @@ -1096,7 +1096,7 @@ while (ptr < endptr) if (do_colour) fprintf(stdout, "%c[%sm", 0x1b, colour_string); fwrite(matchptr + offsets[0], 1, offsets[1] - offsets[0], stdout); if (do_colour) fprintf(stdout, "%c[00m", 0x1b); - } + } fprintf(stdout, "\n"); matchptr += offsets[1]; length -= offsets[1]; @@ -1233,19 +1233,19 @@ while (ptr < endptr) else #endif - /* We have to split the line(s) up if colouring, and search for further + /* We have to split the line(s) up if colouring, and search for further matches. */ if (do_colour) { - int last_offset = 0; + int last_offset = 0; fwrite(ptr, 1, offsets[0], stdout); fprintf(stdout, "%c[%sm", 0x1b, colour_string); fwrite(ptr + offsets[0], 1, offsets[1] - offsets[0], stdout); fprintf(stdout, "%c[00m", 0x1b); for (;;) { - last_offset += offsets[1]; + last_offset += offsets[1]; matchptr += offsets[1]; length -= offsets[1]; if (!match_patterns(matchptr, length, offsets, &mrc)) break; @@ -1257,9 +1257,9 @@ while (ptr < endptr) fwrite(ptr + last_offset, 1, (linelength + endlinelength) - last_offset, stdout); } - + /* Not colouring; no need to search for further matches */ - + else fwrite(ptr, 1, linelength + endlinelength, stdout); } @@ -1872,7 +1872,7 @@ const char *error; /* Set the default line ending value from the default in the PCRE library; "lf", "cr", "crlf", and "any" are supported. Anything else is treated as "lf". Note that the return values from pcre_config(), though derived from the ASCII -codes, are the same in EBCDIC environments, so we must use the actual values +codes, are the same in EBCDIC environments, so we must use the actual values rather than escapes such as as '\r'. */ (void)pcre_config(PCRE_CONFIG_NEWLINE, &i); @@ -875,7 +875,7 @@ while (argc > 1 && argv[op][0] == '-') else if (strcmp(argv[op], "-b") == 0) debug = 1; else if (strcmp(argv[op], "-i") == 0) showinfo = 1; else if (strcmp(argv[op], "-d") == 0) showinfo = debug = 1; - else if (strcmp(argv[op], "-M") == 0) default_find_match_limit = TRUE; + else if (strcmp(argv[op], "-M") == 0) default_find_match_limit = TRUE; #if !defined NODFA else if (strcmp(argv[op], "-dfa") == 0) all_use_dfa = 1; #endif @@ -928,7 +928,7 @@ while (argc > 1 && argv[op][0] == '-') else if (strcmp(argv[op], "-C") == 0) { int rc; - unsigned long int lrc; + unsigned long int lrc; printf("PCRE version %s\n", pcre_version()); printf("Compiled with\n"); (void)pcre_config(PCRE_CONFIG_UTF8, &rc); @@ -937,7 +937,7 @@ while (argc > 1 && argv[op][0] == '-') printf(" %sUnicode properties support\n", rc? "" : "No "); (void)pcre_config(PCRE_CONFIG_NEWLINE, &rc); /* Note that these values are always the ASCII values, even - in EBCDIC environments. CR is 13 and NL is 10. */ + in EBCDIC environments. CR is 13 and NL is 10. */ printf(" Newline sequence is %s\n", (rc == 13)? "CR" : (rc == 10)? "LF" : (rc == (13<<8 | 10))? "CRLF" : (rc == -2)? "ANYCRLF" : @@ -2011,10 +2011,10 @@ while (!done) case 'S': show_malloc = 1; continue; - + case 'Y': options |= PCRE_NO_START_OPTIMIZE; - continue; + continue; case 'Z': options |= PCRE_NOTEOL; @@ -2074,7 +2074,7 @@ while (!done) pmatch = (regmatch_t *)malloc(sizeof(regmatch_t) * use_size_offsets); if ((options & PCRE_NOTBOL) != 0) eflags |= REG_NOTBOL; if ((options & PCRE_NOTEOL) != 0) eflags |= REG_NOTEOL; - if ((options & PCRE_NOTEMPTY) != 0) eflags |= REG_NOTEMPTY; + if ((options & PCRE_NOTEMPTY) != 0) eflags |= REG_NOTEMPTY; rc = regexec(&preg, (const char *)bptr, use_size_offsets, pmatch, eflags); |