Parent Directory
| 
Revision Log
| 
Patch
| revision 69 by nigel, Sat Feb 24 21:40:18 2007 UTC | revision 75 by nigel, Sat Feb 24 21:40:37 2007 UTC | |
|---|---|---|
| # | Line 1 | Line 1 |
| 1 | ----------------------------------------------------------------------------- | |
| 2 | This file contains a concatenation of the PCRE man pages, converted to plain | This file contains a concatenation of the PCRE man pages, converted to plain |
| 3 | text format for ease of searching with a text editor, or for use on systems | text format for ease of searching with a text editor, or for use on systems |
| 4 | that do not have a man page processor. The small individual files that give | that do not have a man page processor. The small individual files that give |
| # | Line 5 synopses of each function in the library | Line 6 synopses of each function in the library |
| 6 | separate text files for the pcregrep and pcretest commands. | separate text files for the pcregrep and pcretest commands. |
| 7 | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| 8 | ||
| 9 | NAME | PCRE(3) PCRE(3) |
| PCRE - Perl-compatible regular expressions | ||
| 10 | ||
| DESCRIPTION | ||
| 11 | ||
| The PCRE library is a set of functions that implement regu- | ||
| lar expression pattern matching using the same syntax and | ||
| semantics as Perl, with just a few differences. The current | ||
| implementation of PCRE (release 4.x) corresponds approxi- | ||
| mately with Perl 5.8, including support for UTF-8 encoded | ||
| strings. However, this support has to be explicitly | ||
| enabled; it is not the default. | ||
| PCRE is written in C and released as a C library. However, a | ||
| number of people have written wrappers and interfaces of | ||
| various kinds. A C++ class is included in these contribu- | ||
| tions, which can be found in the Contrib directory at the | ||
| primary FTP site, which is: | ||
| ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre | ||
| Details of exactly which Perl regular expression features | ||
| are and are not supported by PCRE are given in separate | ||
| documents. See the pcrepattern and pcrecompat pages. | ||
| Some features of PCRE can be included, excluded, or changed | ||
| when the library is built. The pcre_config() function makes | ||
| it possible for a client to discover which features are | ||
| available. Documentation about building PCRE for various | ||
| operating systems can be found in the README file in the | ||
| source distribution. | ||
| 12 | ||
| 13 | NAME | |
| 14 | PCRE - Perl-compatible regular expressions | |
| 15 | ||
| 16 | USER DOCUMENTATION | INTRODUCTION |
| 17 | ||
| 18 | The user documentation for PCRE has been split up into a | The PCRE library is a set of functions that implement regular expres- |
| 19 | number of different sections. In the "man" format, each of | sion pattern matching using the same syntax and semantics as Perl, with |
| 20 | these is a separate "man page". In the HTML format, each is | just a few differences. The current implementation of PCRE (release |
| 21 | a separate page, linked from the index page. In the plain | 5.x) corresponds approximately with Perl 5.8, including support for |
| 22 | text format, all the sections are concatenated, for ease of | UTF-8 encoded strings and Unicode general category properties. However, |
| 23 | searching. The sections are as follows: | this support has to be explicitly enabled; it is not the default. |
| 24 | ||
| 25 | pcre this document | PCRE is written in C and released as a C library. A number of people |
| 26 | pcreapi details of PCRE's native API | have written wrappers and interfaces of various kinds. A C++ class is |
| 27 | pcrebuild options for building PCRE | included in these contributions, which can be found in the Contrib |
| 28 | pcrecallout details of the callout feature | directory at the primary FTP site, which is: |
| 29 | pcrecompat discussion of Perl compatibility | |
| 30 | pcregrep description of the pcregrep command | ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre |
| 31 | pcrepattern syntax and semantics of supported | |
| 32 | regular expressions | Details of exactly which Perl regular expression features are and are |
| 33 | pcreperform discussion of performance issues | not supported by PCRE are given in separate documents. See the pcrepat- |
| 34 | pcreposix the POSIX-compatible API | tern and pcrecompat pages. |
| 35 | pcresample discussion of the sample program | |
| 36 | pcretest the pcretest testing command | Some features of PCRE can be included, excluded, or changed when the |
| 37 | library is built. The pcre_config() function makes it possible for a | |
| 38 | In addition, in the "man" and HTML formats, there is a short | client to discover which features are available. The features them- |
| 39 | page for each library function, listing its arguments and | selves are described in the pcrebuild page. Documentation about build- |
| 40 | results. | ing PCRE for various operating systems can be found in the README file |
| 41 | in the source distribution. | |
| 42 | ||
| 43 | ||
| 44 | LIMITATIONS | USER DOCUMENTATION |
| 45 | ||
| 46 | There are some size limitations in PCRE but it is hoped that | The user documentation for PCRE comprises a number of different sec- |
| 47 | they will never in practice be relevant. | tions. In the "man" format, each of these is a separate "man page". In |
| 48 | the HTML format, each is a separate page, linked from the index page. | |
| 49 | In the plain text format, all the sections are concatenated, for ease | |
| 50 | of searching. The sections are as follows: | |
| 51 | ||
| 52 | pcre this document | |
| 53 | pcreapi details of PCRE's native API | |
| 54 | pcrebuild options for building PCRE | |
| 55 | pcrecallout details of the callout feature | |
| 56 | pcrecompat discussion of Perl compatibility | |
| 57 | pcregrep description of the pcregrep command | |
| 58 | pcrepartial details of the partial matching facility | |
| 59 | pcrepattern syntax and semantics of supported | |
| 60 | regular expressions | |
| 61 | pcreperform discussion of performance issues | |
| 62 | pcreposix the POSIX-compatible API | |
| 63 | pcreprecompile details of saving and re-using precompiled patterns | |
| 64 | pcresample discussion of the sample program | |
| 65 | pcretest description of the pcretest testing command | |
| 66 | ||
| 67 | The maximum length of a compiled pattern is 65539 (sic) | In addition, in the "man" and HTML formats, there is a short page for |
| 68 | bytes if PCRE is compiled with the default internal linkage | each library function, listing its arguments and results. |
| 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). | ||
| If these cases the limit is substantially larger. However, | ||
| the speed of execution will be slower. | ||
| All values in repeating quantifiers must be less than 65536. | ||
| The maximum number of capturing subpatterns is 65535. | ||
| There is no limit to the number of non-capturing subpat- | ||
| terns, but the maximum depth of nesting of all kinds of | ||
| parenthesized subpattern, including capturing subpatterns, | ||
| assertions, and other types of subpattern, is 200. | ||
| The maximum length of a subject string is the largest posi- | ||
| tive number that an integer variable can hold. However, PCRE | ||
| uses recursion to handle subpatterns and indefinite repeti- | ||
| tion. This means that the available stack space may limit | ||
| the size of a subject string that can be processed by cer- | ||
| tain patterns. | ||
| 69 | ||
| 70 | ||
| 71 | UTF-8 SUPPORT | LIMITATIONS |
| 72 | ||
| 73 | Starting at release 3.3, PCRE has had some support for char- | There are some size limitations in PCRE but it is hoped that they will |
| 74 | acter strings encoded in the UTF-8 format. For release 4.0 | never in practice be relevant. |
| this has been greatly extended to cover most common require- | ||
| ments. | ||
| 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 addi- | ||
| tional run time overhead is limited to testing the PCRE_UTF8 | ||
| flag in several places, so should not be very large. | ||
| The following comments apply when PCRE is running in UTF-8 | ||
| mode: | ||
| 1. PCRE assumes that the strings it is given contain valid | ||
| UTF-8 codes. It does not diagnose invalid UTF-8 strings. If | ||
| you pass invalid UTF-8 strings to PCRE, the results are | ||
| undefined. | ||
| 2. In a pattern, the escape sequence \x{...}, where the con- | ||
| tents of the braces is a string of hexadecimal digits, is | ||
| interpreted as a UTF-8 character whose code number is the | ||
| given hexadecimal number, for example: \x{1234}. If a non- | ||
| hexadecimal digit appears between the braces, the item is | ||
| not recognized. This escape sequence can be used either as | ||
| a literal, or within a character class. | ||
| 3. The original hexadecimal escape sequence, \xhh, matches a | ||
| two-byte UTF-8 character if the value is greater than 127. | ||
| 4. Repeat quantifiers apply to complete UTF-8 characters, | ||
| not to individual bytes, for example: \x{100}{3}. | ||
| 5. The dot metacharacter matches one UTF-8 character instead | ||
| of a single byte. | ||
| 6. 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. | ||
| 7. The character escapes \b, \B, \d, \D, \s, \S, \w, and \W | ||
| correctly test characters of any code value, but the charac- | ||
| ters that PCRE recognizes as digits, spaces, or word charac- | ||
| ters remain the same set as before, all with values less | ||
| than 256. | ||
| 8. Case-insensitive matching applies only to characters | ||
| whose values are less than 256. PCRE does not support the | ||
| notion of "case" for higher-valued characters. | ||
| 75 | ||
| 76 | 9. PCRE does not support the use of Unicode tables and pro- | The maximum length of a compiled pattern is 65539 (sic) bytes if PCRE |
| 77 | perties or the Perl escapes \p, \P, and \X. | is compiled with the default internal linkage size of 2. If you want to |
| 78 | process regular expressions that are truly enormous, you can compile | |
| 79 | PCRE with an internal linkage size of 3 or 4 (see the README file in | |
| 80 | the source distribution and the pcrebuild documentation for details). | |
| 81 | In these cases the limit is substantially larger. However, the speed | |
| 82 | of execution will be slower. | |
| 83 | ||
| 84 | All values in repeating quantifiers must be less than 65536. The maxi- | |
| 85 | mum number of capturing subpatterns is 65535. | |
| 86 | ||
| 87 | There is no limit to the number of non-capturing subpatterns, but the | |
| 88 | maximum depth of nesting of all kinds of parenthesized subpattern, | |
| 89 | including capturing subpatterns, assertions, and other types of subpat- | |
| 90 | tern, is 200. | |
| 91 | ||
| 92 | The maximum length of a subject string is the largest positive number | |
| 93 | that an integer variable can hold. However, PCRE uses recursion to han- | |
| 94 | dle subpatterns and indefinite repetition. This means that the avail- | |
| 95 | able stack space may limit the size of a subject string that can be | |
| 96 | processed by certain patterns. | |
| 97 | ||
| 98 | ||
| 99 | UTF-8 AND UNICODE PROPERTY SUPPORT | |
| 100 | ||
| 101 | From release 3.3, PCRE has had some support for character strings | |
| 102 | encoded in the UTF-8 format. For release 4.0 this was greatly extended | |
| 103 | to cover most common requirements, and in release 5.0 additional sup- | |
| 104 | port for Unicode general category properties was added. | |
| 105 | ||
| 106 | In order process UTF-8 strings, you must build PCRE to include UTF-8 | |
| 107 | support in the code, and, in addition, you must call pcre_compile() | |
| 108 | with the PCRE_UTF8 option flag. When you do this, both the pattern and | |
| 109 | any subject strings that are matched against it are treated as UTF-8 | |
| 110 | strings instead of just strings of bytes. | |
| 111 | ||
| 112 | If you compile PCRE with UTF-8 support, but do not use it at run time, | |
| 113 | the library will be a bit bigger, but the additional run time overhead | |
| 114 | is limited to testing the PCRE_UTF8 flag in several places, so should | |
| 115 | not be very large. | |
| 116 | ||
| 117 | If PCRE is built with Unicode character property support (which implies | |
| 118 | UTF-8 support), the escape sequences \p{..}, \P{..}, and \X are sup- | |
| 119 | ported. The available properties that can be tested are limited to the | |
| 120 | general category properties such as Lu for an upper case letter or Nd | |
| 121 | for a decimal number. A full list is given in the pcrepattern documen- | |
| 122 | tation. The PCRE library is increased in size by about 90K when Unicode | |
| 123 | property support is included. | |
| 124 | ||
| 125 | The following comments apply when PCRE is running in UTF-8 mode: | |
| 126 | ||
| 127 | 1. When you set the PCRE_UTF8 flag, the strings passed as patterns and | |
| 128 | subjects are checked for validity on entry to the relevant functions. | |
| 129 | If an invalid UTF-8 string is passed, an error return is given. In some | |
| 130 | situations, you may already know that your strings are valid, and | |
| 131 | therefore want to skip these checks in order to improve performance. If | |
| 132 | you set the PCRE_NO_UTF8_CHECK flag at compile time or at run time, | |
| 133 | PCRE assumes that the pattern or subject it is given (respectively) | |
| 134 | contains only valid UTF-8 codes. In this case, it does not diagnose an | |
| 135 | invalid UTF-8 string. If you pass an invalid UTF-8 string to PCRE when | |
| 136 | PCRE_NO_UTF8_CHECK is set, the results are undefined. Your program may | |
| 137 | crash. | |
| 138 | ||
| 139 | 2. In a pattern, the escape sequence \x{...}, where the contents of the | |
| 140 | braces is a string of hexadecimal digits, is interpreted as a UTF-8 | |
| 141 | character whose code number is the given hexadecimal number, for exam- | |
| 142 | ple: \x{1234}. If a non-hexadecimal digit appears between the braces, | |
| 143 | the item is not recognized. This escape sequence can be used either as | |
| 144 | a literal, or within a character class. | |
| 145 | ||
| 146 | 3. The original hexadecimal escape sequence, \xhh, matches a two-byte | |
| 147 | UTF-8 character if the value is greater than 127. | |
| 148 | ||
| 149 | 4. Repeat quantifiers apply to complete UTF-8 characters, not to indi- | |
| 150 | vidual bytes, for example: \x{100}{3}. | |
| 151 | ||
| 152 | 5. The dot metacharacter matches one UTF-8 character instead of a sin- | |
| 153 | gle byte. | |
| 154 | ||
| 155 | 6. The escape sequence \C can be used to match a single byte in UTF-8 | |
| 156 | mode, but its use can lead to some strange effects. | |
| 157 | ||
| 158 | 7. The character escapes \b, \B, \d, \D, \s, \S, \w, and \W correctly | |
| 159 | test characters of any code value, but the characters that PCRE recog- | |
| 160 | nizes as digits, spaces, or word characters remain the same set as | |
| 161 | before, all with values less than 256. This remains true even when PCRE | |
| 162 | includes Unicode property support, because to do otherwise would slow | |
| 163 | down PCRE in many common cases. If you really want to test for a wider | |
| 164 | sense of, say, "digit", you must use Unicode property tests such as | |
| 165 | \p{Nd}. | |
| 166 | ||
| 167 | 8. Similarly, characters that match the POSIX named character classes | |
| 168 | are all low-valued characters. | |
| 169 | ||
| 170 | 9. Case-insensitive matching applies only to characters whose values | |
| 171 | are less than 128, unless PCRE is built with Unicode property support. | |
| 172 | Even when Unicode property support is available, PCRE still uses its | |
| 173 | own character tables when checking the case of low-valued characters, | |
| 174 | so as not to degrade performance. The Unicode property information is | |
| 175 | used only for characters with higher values. | |
| 176 | ||
| 177 | ||
| 178 | AUTHOR | AUTHOR |
| 179 | ||
| 180 | Philip Hazel <ph10@cam.ac.uk> | Philip Hazel <ph10@cam.ac.uk> |
| 181 | University Computing Service, | University Computing Service, |
| 182 | Cambridge CB2 3QG, England. | Cambridge CB2 3QG, England. |
| 183 | Phone: +44 1223 334714 | Phone: +44 1223 334714 |
| 184 | ||
| 185 | Last updated: 04 February 2003 | Last updated: 09 September 2004 |
| 186 | Copyright (c) 1997-2003 University of Cambridge. | Copyright (c) 1997-2004 University of Cambridge. |
| 187 | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| 188 | ||
| 189 | NAME | PCRE(3) PCRE(3) |
| PCRE - Perl-compatible regular expressions | ||
| 190 | ||
| 191 | ||
| 192 | ||
| 193 | NAME | |
| 194 | PCRE - Perl-compatible regular expressions | |
| 195 | ||
| 196 | PCRE BUILD-TIME OPTIONS | PCRE BUILD-TIME OPTIONS |
| 197 | ||
| 198 | This document describes the optional features of PCRE that | This document describes the optional features of PCRE that can be |
| 199 | can be selected when the library is compiled. They are all | selected when the library is compiled. They are all selected, or dese- |
| 200 | selected, or deselected, by providing options to the config- | lected, by providing options to the configure script that is run before |
| 201 | ure script which is run before the make command. The com- | the make command. The complete list of options for configure (which |
| 202 | plete list of options for configure (which includes the | includes the standard ones such as the selection of the installation |
| 203 | standard ones such as the selection of the installation | directory) can be obtained by running |
| 204 | directory) can be obtained by running | |
| 205 | ./configure --help | |
| 206 | ./configure --help | |
| 207 | The following sections describe certain options whose names begin with | |
| 208 | The following sections describe certain options whose names | --enable or --disable. These settings specify changes to the defaults |
| 209 | begin with --enable or --disable. These settings specify | for the configure command. Because of the way that configure works, |
| 210 | changes to the defaults for the configure command. Because | --enable and --disable always come in pairs, so the complementary |
| 211 | of the way that configure works, --enable and --disable | option always exists as well, but as it specifies the default, it is |
| 212 | always come in pairs, so the complementary option always | not described. |
| exists as well, but as it specifies the default, it is not | ||
| described. | ||
| 213 | ||
| 214 | ||
| 215 | UTF-8 SUPPORT | UTF-8 SUPPORT |
| 216 | ||
| 217 | To build PCRE with support for UTF-8 character strings, add | To build PCRE with support for UTF-8 character strings, add |
| 218 | ||
| 219 | --enable-utf8 | |
| 220 | ||
| 221 | to the configure command. Of itself, this does not make PCRE treat | |
| 222 | strings as UTF-8. As well as compiling PCRE with this option, you also | |
| 223 | have have to set the PCRE_UTF8 option when you call the pcre_compile() | |
| 224 | function. | |
| 225 | ||
| --enable-utf8 | ||
| 226 | ||
| 227 | to the configure command. Of itself, this does not make PCRE | UNICODE CHARACTER PROPERTY SUPPORT |
| 228 | treat strings as UTF-8. As well as compiling PCRE with this | |
| 229 | option, you also have have to set the PCRE_UTF8 option when | UTF-8 support allows PCRE to process character values greater than 255 |
| 230 | you call the pcre_compile() function. | in the strings that it handles. On its own, however, it does not pro- |
| 231 | vide any facilities for accessing the properties of such characters. If | |
| 232 | you want to be able to use the pattern escapes \P, \p, and \X, which | |
| 233 | refer to Unicode character properties, you must add | |
| 234 | ||
| 235 | --enable-unicode-properties | |
| 236 | ||
| 237 | to the configure command. This implies UTF-8 support, even if you have | |
| 238 | not explicitly requested it. | |
| 239 | ||
| 240 | Including Unicode property support adds around 90K of tables to the | |
| 241 | PCRE library, approximately doubling its size. Only the general cate- | |
| 242 | gory properties such as Lu and Nd are supported. Details are given in | |
| 243 | the pcrepattern documentation. | |
| 244 | ||
| 245 | ||
| 246 | CODE VALUE OF NEWLINE | CODE VALUE OF NEWLINE |
| 247 | ||
| 248 | By default, PCRE treats character 10 (linefeed) as the new- | By default, PCRE treats character 10 (linefeed) as the newline charac- |
| 249 | line character. This is the normal newline character on | ter. This is the normal newline character on Unix-like systems. You can |
| 250 | Unix-like systems. You can compile PCRE to use character 13 | compile PCRE to use character 13 (carriage return) instead by adding |
| 251 | (carriage return) instead by adding | |
| 252 | --enable-newline-is-cr | |
| 253 | --enable-newline-is-cr | |
| 254 | to the configure command. For completeness there is also a --enable- | |
| 255 | to the configure command. For completeness there is also a | newline-is-lf option, which explicitly specifies linefeed as the new- |
| 256 | --enable-newline-is-lf option, which explicitly specifies | line character. |
| linefeed as the newline character. | ||
| 257 | ||
| 258 | ||
| 259 | BUILDING SHARED AND STATIC LIBRARIES | BUILDING SHARED AND STATIC LIBRARIES |
| 260 | ||
| 261 | The PCRE building process uses libtool to build both shared | The PCRE building process uses libtool to build both shared and static |
| 262 | and static Unix libraries by default. You can suppress one | Unix libraries by default. You can suppress one of these by adding one |
| 263 | of these by adding one of | of |
| 264 | ||
| 265 | --disable-shared | --disable-shared |
| 266 | --disable-static | --disable-static |
| 267 | ||
| 268 | to the configure command, as required. | to the configure command, as required. |
| 269 | ||
| 270 | ||
| 271 | POSIX MALLOC USAGE | POSIX MALLOC USAGE |
| 272 | ||
| 273 | When PCRE is called through the POSIX interface (see the | When PCRE is called through the POSIX interface (see the pcreposix doc- |
| 274 | pcreposix documentation), additional working storage is | umentation), additional working storage is required for holding the |
| 275 | required for holding the pointers to capturing substrings | pointers to capturing substrings, because PCRE requires three integers |
| 276 | because PCRE requires three integers per substring, whereas | per substring, whereas the POSIX interface provides only two. If the |
| 277 | the POSIX interface provides only two. If the number of | number of expected substrings is small, the wrapper function uses space |
| 278 | expected substrings is small, the wrapper function uses | on the stack, because this is faster than using malloc() for each call. |
| 279 | space on the stack, because this is faster than using mal- | The default threshold above which the stack is no longer used is 10; it |
| 280 | loc() for each call. The default threshold above which the | can be changed by adding a setting such as |
| stack is no longer used is 10; it can be changed by adding a | ||
| setting such as | ||
| 281 | ||
| 282 | --with-posix-malloc-threshold=20 | --with-posix-malloc-threshold=20 |
| 283 | ||
| 284 | to the configure command. | to the configure command. |
| 285 | ||
| 286 | ||
| 287 | LIMITING PCRE RESOURCE USAGE | LIMITING PCRE RESOURCE USAGE |
| 288 | ||
| 289 | Internally, PCRE has a function called match() which it | Internally, PCRE has a function called match(), which it calls repeat- |
| 290 | calls repeatedly (possibly recursively) when performing a | edly (possibly recursively) when matching a pattern. By controlling the |
| 291 | matching operation. By limiting the number of times this | maximum number of times this function may be called during a single |
| 292 | function may be called, a limit can be placed on the | matching operation, a limit can be placed on the resources used by a |
| 293 | resources used by a single call to pcre_exec(). The limit | single call to pcre_exec(). The limit can be changed at run time, as |
| 294 | can be changed at run time, as described in the pcreapi | described in the pcreapi documentation. The default is 10 million, but |
| 295 | documentation. The default is 10 million, but this can be | this can be changed by adding a setting such as |
| changed by adding a setting such as | ||
| 296 | ||
| 297 | --with-match-limit=500000 | --with-match-limit=500000 |
| 298 | ||
| 299 | to the configure command. | to the configure command. |
| 300 | ||
| 301 | ||
| 302 | HANDLING VERY LARGE PATTERNS | HANDLING VERY LARGE PATTERNS |
| 303 | ||
| 304 | Within a compiled pattern, offset values are used to point | Within a compiled pattern, offset values are used to point from one |
| 305 | from one part to another (for example, from an opening | part to another (for example, from an opening parenthesis to an alter- |
| 306 | parenthesis to an alternation metacharacter). By default | nation metacharacter). By default, two-byte values are used for these |
| 307 | two-byte values are used for these offsets, leading to a | offsets, leading to a maximum size for a compiled pattern of around |
| 308 | maximum size for a compiled pattern of around 64K. This is | 64K. This is sufficient to handle all but the most gigantic patterns. |
| 309 | sufficient to handle all but the most gigantic patterns. | Nevertheless, some people do want to process enormous patterns, so it |
| 310 | Nevertheless, some people do want to process enormous pat- | is possible to compile PCRE to use three-byte or four-byte offsets by |
| 311 | terns, so it is possible to compile PCRE to use three-byte | adding a setting such as |
| 312 | or four-byte offsets by adding a setting such as | |
| 313 | --with-link-size=3 | |
| 314 | --with-link-size=3 | |
| 315 | to the configure command. The value given must be 2, 3, or 4. Using | |
| 316 | to the configure command. The value given must be 2, 3, or | longer offsets slows down the operation of PCRE because it has to load |
| 317 | 4. Using longer offsets slows down the operation of PCRE | additional bytes when handling them. |
| 318 | because it has to load additional bytes when handling them. | |
| 319 | If you build PCRE with an increased link size, test 2 (and test 5 if | |
| 320 | If you build PCRE with an increased link size, test 2 (and | you are using UTF-8) will fail. Part of the output of these tests is a |
| 321 | test 5 if you are using UTF-8) will fail. Part of the output | representation of the compiled pattern, and this changes with the link |
| 322 | of these tests is a representation of the compiled pattern, | size. |
| 323 | and this changes with the link size. | |
| 324 | ||
| 325 | AVOIDING EXCESSIVE STACK USAGE | |
| 326 | ||
| 327 | PCRE implements backtracking while matching by making recursive calls | |
| 328 | to an internal function called match(). In environments where the size | |
| 329 | of the stack is limited, this can severely limit PCRE's operation. (The | |
| 330 | Unix environment does not usually suffer from this problem.) An alter- | |
| 331 | native approach that uses memory from the heap to remember data, | |
| 332 | instead of using recursive function calls, has been implemented to work | |
| 333 | round this problem. If you want to build a version of PCRE that works | |
| 334 | this way, add | |
| 335 | ||
| 336 | --disable-stack-for-recursion | |
| 337 | ||
| 338 | to the configure command. With this configuration, PCRE will use the | |
| 339 | pcre_stack_malloc and pcre_stack_free variables to call memory manage- | |
| 340 | ment functions. Separate functions are provided because the usage is | |
| 341 | very predictable: the block sizes requested are always the same, and | |
| 342 | the blocks are always freed in reverse order. A calling program might | |
| 343 | be able to implement optimized functions that perform better than the | |
| 344 | standard malloc() and free() functions. PCRE runs noticeably more | |
| 345 | slowly when built in this way. | |
| 346 | ||
| 347 | ||
| 348 | USING EBCDIC CODE | |
| 349 | ||
| 350 | PCRE assumes by default that it will run in an environment where the | |
| 351 | character code is ASCII (or Unicode, which is a superset of ASCII). | |
| 352 | PCRE can, however, be compiled to run in an EBCDIC environment by | |
| 353 | adding | |
| 354 | ||
| 355 | --enable-ebcdic | |
| 356 | ||
| 357 | Last updated: 21 January 2003 | to the configure command. |
| 358 | Copyright (c) 1997-2003 University of Cambridge. | |
| 359 | Last updated: 09 September 2004 | |
| 360 | Copyright (c) 1997-2004 University of Cambridge. | |
| 361 | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| 362 | ||
| 363 | PCRE(3) PCRE(3) | |
| 364 | ||
| 365 | ||
| 366 | ||
| 367 | NAME | NAME |
| 368 | PCRE - Perl-compatible regular expressions | PCRE - Perl-compatible regular expressions |
| 369 | ||
| 370 | PCRE NATIVE API | |
| 371 | ||
| 372 | #include <pcre.h> | |
| 373 | ||
| 374 | SYNOPSIS OF PCRE API | pcre *pcre_compile(const char *pattern, int options, |
| 375 | const char **errptr, int *erroffset, | |
| 376 | const unsigned char *tableptr); | |
| 377 | ||
| 378 | #include <pcre.h> | pcre_extra *pcre_study(const pcre *code, int options, |
| 379 | const char **errptr); | |
| 380 | ||
| 381 | pcre *pcre_compile(const char *pattern, int options, | int pcre_exec(const pcre *code, const pcre_extra *extra, |
| 382 | const char **errptr, int *erroffset, | const char *subject, int length, int startoffset, |
| 383 | const unsigned char *tableptr); | int options, int *ovector, int ovecsize); |
| 384 | ||
| 385 | pcre_extra *pcre_study(const pcre *code, int options, | int pcre_copy_named_substring(const pcre *code, |
| 386 | const char **errptr); | const char *subject, int *ovector, |
| 387 | int stringcount, const char *stringname, | |
| 388 | char *buffer, int buffersize); | |
| 389 | ||
| 390 | int pcre_exec(const pcre *code, const pcre_extra *extra, | int pcre_copy_substring(const char *subject, int *ovector, |
| 391 | const char *subject, int length, int startoffset, | int stringcount, int stringnumber, char *buffer, |
| 392 | int options, int *ovector, int ovecsize); | int buffersize); |
| 393 | ||
| 394 | int pcre_copy_named_substring(const pcre *code, | int pcre_get_named_substring(const pcre *code, |
| 395 | const char *subject, int *ovector, | const char *subject, int *ovector, |
| 396 | int stringcount, const char *stringname, | int stringcount, const char *stringname, |
| 397 | char *buffer, int buffersize); | const char **stringptr); |
| 398 | ||
| 399 | int pcre_copy_substring(const char *subject, int *ovector, | int pcre_get_stringnumber(const pcre *code, |
| 400 | int stringcount, int stringnumber, char *buffer, | const char *name); |
| int buffersize); | ||
| 401 | ||
| 402 | int pcre_get_named_substring(const pcre *code, | int pcre_get_substring(const char *subject, int *ovector, |
| 403 | const char *subject, int *ovector, | int stringcount, int stringnumber, |
| 404 | int stringcount, const char *stringname, | const char **stringptr); |
| const char **stringptr); | ||
| 405 | ||
| 406 | int pcre_get_stringnumber(const pcre *code, | int pcre_get_substring_list(const char *subject, |
| 407 | const char *name); | int *ovector, int stringcount, const char ***listptr); |
| 408 | ||
| 409 | int pcre_get_substring(const char *subject, int *ovector, | void pcre_free_substring(const char *stringptr); |
| int stringcount, int stringnumber, | ||
| const char **stringptr); | ||
| 410 | ||
| 411 | int pcre_get_substring_list(const char *subject, | void pcre_free_substring_list(const char **stringptr); |
| int *ovector, int stringcount, const char ***listptr); | ||
| 412 | ||
| 413 | void pcre_free_substring(const char *stringptr); | const unsigned char *pcre_maketables(void); |
| 414 | ||
| 415 | void pcre_free_substring_list(const char **stringptr); | int pcre_fullinfo(const pcre *code, const pcre_extra *extra, |
| 416 | int what, void *where); | |
| 417 | ||
| 418 | const unsigned char *pcre_maketables(void); | int pcre_info(const pcre *code, int *optptr, int *firstcharptr); |
| 419 | ||
| 420 | int pcre_fullinfo(const pcre *code, const pcre_extra *extra, | int pcre_config(int what, void *where); |
| int what, void *where); | ||
| 421 | ||
| 422 | char *pcre_version(void); | |
| 423 | ||
| 424 | int pcre_info(const pcre *code, int *optptr, *firstcharptr); | void *(*pcre_malloc)(size_t); |
| 425 | ||
| 426 | int pcre_config(int what, void *where); | void (*pcre_free)(void *); |
| 427 | ||
| 428 | char *pcre_version(void); | void *(*pcre_stack_malloc)(size_t); |
| 429 | ||
| 430 | void *(*pcre_malloc)(size_t); | void (*pcre_stack_free)(void *); |
| 431 | ||
| 432 | void (*pcre_free)(void *); | int (*pcre_callout)(pcre_callout_block *); |
| 433 | ||
| int (*pcre_callout)(pcre_callout_block *); | ||
| 434 | ||
| 435 | PCRE API OVERVIEW | |
| 436 | ||
| 437 | PCRE API | PCRE has its own native API, which is described in this document. There |
| 438 | is also a set of wrapper functions that correspond to the POSIX regular | |
| 439 | expression API. These are described in the pcreposix documentation. | |
| 440 | ||
| 441 | PCRE has its own native API, which is described in this | The native API function prototypes are defined in the header file |
| 442 | document. There is also a set of wrapper functions that | pcre.h, and on Unix systems the library itself is called libpcre. It |
| 443 | correspond to the POSIX regular expression API. These are | can normally be accessed by adding -lpcre to the command for linking an |
| 444 | described in the pcreposix documentation. | application that uses PCRE. The header file defines the macros |
| 445 | PCRE_MAJOR and PCRE_MINOR to contain the major and minor release num- | |
| 446 | bers for the library. Applications can use these to include support | |
| 447 | for different releases of PCRE. | |
| 448 | ||
| 449 | The native API function prototypes are defined in the header | The functions pcre_compile(), pcre_study(), and pcre_exec() are used |
| 450 | file pcre.h, and on Unix systems the library itself is | for compiling and matching regular expressions. A sample program that |
| 451 | called libpcre.a, so can be accessed by adding -lpcre to the | demonstrates the simplest way of using them is provided in the file |
| 452 | command for linking an application which calls it. The | called pcredemo.c in the source distribution. The pcresample documenta- |
| 453 | header file defines the macros PCRE_MAJOR and PCRE_MINOR to | tion describes how to run it. |
| contain the major and minor release numbers for the library. | ||
| Applications can use these to include support for different | ||
| releases. | ||
| 454 | ||
| 455 | The functions pcre_compile(), pcre_study(), and pcre_exec() | In addition to the main compiling and matching functions, there are |
| 456 | are used for compiling and matching regular expressions. A | convenience functions for extracting captured substrings from a matched |
| 457 | sample program that demonstrates the simplest way of using | subject string. They are: |
| them is given in the file pcredemo.c. The pcresample docu- | ||
| mentation describes how to run it. | ||
| 458 | ||
| 459 | There are convenience functions for extracting captured sub- | pcre_copy_substring() |
| 460 | strings from a matched subject string. They are: | pcre_copy_named_substring() |
| 461 | pcre_get_substring() | |
| 462 | pcre_get_named_substring() | |
| 463 | pcre_get_substring_list() | |
| 464 | pcre_get_stringnumber() | |
| 465 | ||
| 466 | pcre_copy_substring() | pcre_free_substring() and pcre_free_substring_list() are also provided, |
| 467 | pcre_copy_named_substring() | to free the memory used for extracted strings. |
| pcre_get_substring() | ||
| pcre_get_named_substring() | ||
| pcre_get_substring_list() | ||
| 468 | ||
| 469 | pcre_free_substring() and pcre_free_substring_list() are | The function pcre_maketables() is used to build a set of character |
| 470 | also provided, to free the memory used for extracted | tables in the current locale for passing to pcre_compile() or |
| 471 | strings. | pcre_exec(). This is an optional facility that is provided for spe- |
| 472 | cialist use. Most commonly, no special tables are passed, in which case | |
| 473 | internal tables that are generated when PCRE is built are used. | |
| 474 | ||
| 475 | The function pcre_maketables() is used (optionally) to build | The function pcre_fullinfo() is used to find out information about a |
| 476 | a set of character tables in the current locale for passing | compiled pattern; pcre_info() is an obsolete version that returns only |
| 477 | to pcre_compile(). | some of the available information, but is retained for backwards com- |
| 478 | patibility. The function pcre_version() returns a pointer to a string | |
| 479 | containing the version of PCRE and its date of release. | |
| 480 | ||
| 481 | The function pcre_fullinfo() is used to find out information | The global variables pcre_malloc and pcre_free initially contain the |
| 482 | about a compiled pattern; pcre_info() is an obsolete version | entry points of the standard malloc() and free() functions, respec- |
| 483 | which returns only some of the available information, but is | tively. PCRE calls the memory management functions via these variables, |
| 484 | retained for backwards compatibility. The function | so a calling program can replace them if it wishes to intercept the |
| 485 | pcre_version() returns a pointer to a string containing the | calls. This should be done before calling any PCRE functions. |
| version of PCRE and its date of release. | ||
| 486 | ||
| 487 | The global variables pcre_malloc and pcre_free initially | The global variables pcre_stack_malloc and pcre_stack_free are also |
| 488 | contain the entry points of the standard malloc() and free() | indirections to memory management functions. These special functions |
| 489 | functions respectively. PCRE calls the memory management | are used only when PCRE is compiled to use the heap for remembering |
| 490 | functions via these variables, so a calling program can | data, instead of recursive function calls. This is a non-standard way |
| 491 | replace them if it wishes to intercept the calls. This | of building PCRE, for use in environments that have limited stacks. |
| 492 | should be done before calling any PCRE functions. | Because of the greater use of memory management, it runs more slowly. |
| 493 | Separate functions are provided so that special-purpose external code | |
| 494 | can be used for this case. When used, these functions are always called | |
| 495 | in a stack-like manner (last obtained, first freed), and always for | |
| 496 | memory blocks of the same size. | |
| 497 | ||
| 498 | The global variable pcre_callout initially contains NULL. It | The global variable pcre_callout initially contains NULL. It can be set |
| 499 | can be set by the caller to a "callout" function, which PCRE | by the caller to a "callout" function, which PCRE will then call at |
| 500 | will then call at specified points during a matching opera- | specified points during a matching operation. Details are given in the |
| 501 | tion. Details are given in the pcrecallout documentation. | pcrecallout documentation. |
| 502 | ||
| 503 | ||
| 504 | MULTITHREADING | MULTITHREADING |
| 505 | ||
| 506 | The PCRE functions can be used in multi-threading applica- | The PCRE functions can be used in multi-threading applications, with |
| 507 | tions, with the proviso that the memory management functions | the proviso that the memory management functions pointed to by |
| 508 | pointed to by pcre_malloc and pcre_free, and the callout | pcre_malloc, pcre_free, pcre_stack_malloc, and pcre_stack_free, and the |
| 509 | function pointed to by pcre_callout, are shared by all | callout function pointed to by pcre_callout, are shared by all threads. |
| 510 | threads. | |
| 511 | The compiled form of a regular expression is not altered during match- | |
| 512 | The compiled form of a regular expression is not altered | ing, so the same compiled pattern can safely be used by several threads |
| 513 | during matching, so the same compiled pattern can safely be | at once. |
| 514 | used by several threads at once. | |
| 515 | ||
| 516 | SAVING PRECOMPILED PATTERNS FOR LATER USE | |
| 517 | ||
| 518 | The compiled form of a regular expression can be saved and re-used at a | |
| 519 | later time, possibly by a different program, and even on a host other | |
| 520 | than the one on which it was compiled. Details are given in the | |
| 521 | pcreprecompile documentation. | |
| 522 | ||
| 523 | ||
| 524 | CHECKING BUILD-TIME OPTIONS | CHECKING BUILD-TIME OPTIONS |
| 525 | ||
| 526 | int pcre_config(int what, void *where); | int pcre_config(int what, void *where); |
| 527 | ||
| 528 | The function pcre_config() makes it possible for a PCRE client to dis- | |
| 529 | cover which optional features have been compiled into the PCRE library. | |
| 530 | The pcrebuild documentation has more details about these optional fea- | |
| 531 | tures. | |
| 532 | ||
| 533 | The function pcre_config() makes it possible for a PCRE | The first argument for pcre_config() is an integer, specifying which |
| 534 | client to discover which optional features have been com- | information is required; the second argument is a pointer to a variable |
| 535 | piled into the PCRE library. The pcrebuild documentation has | into which the information is placed. The following information is |
| 536 | more details about these optional features. | available: |
| 537 | ||
| 538 | The first argument for pcre_config() is an integer, specify- | PCRE_CONFIG_UTF8 |
| ing which information is required; the second argument is a | ||
| pointer to a variable into which the information is placed. | ||
| The following information is available: | ||
| 539 | ||
| 540 | PCRE_CONFIG_UTF8 | The output is an integer that is set to one if UTF-8 support is avail- |
| 541 | able; otherwise it is set to zero. | |
| 542 | ||
| 543 | The output is an integer that is set to one if UTF-8 support | PCRE_CONFIG_UNICODE_PROPERTIES |
| is available; otherwise it is set to zero. | ||
| 544 | ||
| 545 | PCRE_CONFIG_NEWLINE | The output is an integer that is set to one if support for Unicode |
| 546 | character properties is available; otherwise it is set to zero. | |
| 547 | ||
| 548 | The output is an integer that is set to the value of the | PCRE_CONFIG_NEWLINE |
| code that is used for the newline character. It is either | ||
| linefeed (10) or carriage return (13), and should normally | ||
| be the standard character for your operating system. | ||
| 549 | ||
| 550 | PCRE_CONFIG_LINK_SIZE | The output is an integer that is set to the value of the code that is |
| 551 | used for the newline character. It is either linefeed (10) or carriage | |
| 552 | return (13), and should normally be the standard character for your | |
| 553 | operating system. | |
| 554 | ||
| 555 | The output is an integer that contains the number of bytes | PCRE_CONFIG_LINK_SIZE |
| used for internal linkage in compiled regular expressions. | ||
| The value is 2, 3, or 4. Larger values allow larger regular | ||
| expressions to be compiled, at the expense of slower match- | ||
| ing. The default value of 2 is sufficient for all but the | ||
| most massive patterns, since it allows the compiled pattern | ||
| to be up to 64K in size. | ||
| 556 | ||
| 557 | PCRE_CONFIG_POSIX_MALLOC_THRESHOLD | The output is an integer that contains the number of bytes used for |
| 558 | internal linkage in compiled regular expressions. The value is 2, 3, or | |
| 559 | 4. Larger values allow larger regular expressions to be compiled, at | |
| 560 | the expense of slower matching. The default value of 2 is sufficient | |
| 561 | for all but the most massive patterns, since it allows the compiled | |
| 562 | pattern to be up to 64K in size. | |
| 563 | ||
| 564 | The output is an integer that contains the threshold above | PCRE_CONFIG_POSIX_MALLOC_THRESHOLD |
| which the POSIX interface uses malloc() for output vectors. | ||
| Further details are given in the pcreposix documentation. | ||
| 565 | ||
| 566 | PCRE_CONFIG_MATCH_LIMIT | The output is an integer that contains the threshold above which the |
| 567 | POSIX interface uses malloc() for output vectors. Further details are | |
| 568 | given in the pcreposix documentation. | |
| 569 | ||
| 570 | The output is an integer that gives the default limit for | PCRE_CONFIG_MATCH_LIMIT |
| 571 | the number of internal matching function calls in a | |
| 572 | pcre_exec() execution. Further details are given with | The output is an integer that gives the default limit for the number of |
| 573 | pcre_exec() below. | internal matching function calls in a pcre_exec() execution. Further |
| 574 | details are given with pcre_exec() below. | |
| 575 | ||
| 576 | PCRE_CONFIG_STACKRECURSE | |
| 577 | ||
| 578 | The output is an integer that is set to one if internal recursion is | |
| 579 | implemented by recursive function calls that use the stack to remember | |
| 580 | their state. This is the usual way that PCRE is compiled. The output is | |
| 581 | zero if PCRE was compiled to use blocks of data on the heap instead of | |
| 582 | recursive function calls. In this case, pcre_stack_malloc and | |
| 583 | pcre_stack_free are called to manage memory blocks on the heap, thus | |
| 584 | avoiding the use of the stack. | |
| 585 | ||
| 586 | ||
| 587 | COMPILING A PATTERN | COMPILING A PATTERN |
| 588 | ||
| 589 | pcre *pcre_compile(const char *pattern, int options, | pcre *pcre_compile(const char *pattern, int options, |
| 590 | const char **errptr, int *erroffset, | const char **errptr, int *erroffset, |
| 591 | const unsigned char *tableptr); | const unsigned char *tableptr); |
| 592 | ||
| 593 | The function pcre_compile() is called to compile a pattern | The function pcre_compile() is called to compile a pattern into an |
| 594 | into an internal form. The pattern is a C string terminated | internal form. The pattern is a C string terminated by a binary zero, |
| 595 | by a binary zero, and is passed in the argument pattern. A | and is passed in the pattern argument. A pointer to a single block of |
| 596 | pointer to a single block of memory that is obtained via | memory that is obtained via pcre_malloc is returned. This contains the |
| 597 | pcre_malloc is returned. This contains the compiled code and | compiled code and related data. The pcre type is defined for the |
| 598 | related data. The pcre type is defined for the returned | returned block; this is a typedef for a structure whose contents are |
| 599 | block; this is a typedef for a structure whose contents are | not externally defined. It is up to the caller to free the memory when |
| 600 | not externally defined. It is up to the caller to free the | it is no longer required. |
| 601 | memory when it is no longer required. | |
| 602 | Although the compiled code of a PCRE regex is relocatable, that is, it | |
| 603 | Although the compiled code of a PCRE regex is relocatable, | does not depend on memory location, the complete pcre data block is not |
| 604 | that is, it does not depend on memory location, the complete | fully relocatable, because it may contain a copy of the tableptr argu- |
| 605 | pcre data block is not fully relocatable, because it con- | ment, which is an address (see below). |
| 606 | tains a copy of the tableptr argument, which is an address | |
| 607 | (see below). | The options argument contains independent bits that affect the compila- |
| 608 | The options argument contains independent bits that affect | tion. It should be zero if no options are required. The available |
| 609 | the compilation. It should be zero if no options are | options are described below. Some of them, in particular, those that |
| 610 | required. Some of the options, in particular, those that are | are compatible with Perl, can also be set and unset from within the |
| 611 | compatible with Perl, can also be set and unset from within | pattern (see the detailed description in the pcrepattern documenta- |
| 612 | the pattern (see the detailed description of regular expres- | tion). For these options, the contents of the options argument speci- |
| 613 | sions in the pcrepattern documentation). For these options, | fies their initial settings at the start of compilation and execution. |
| 614 | the contents of the options argument specifies their initial | The PCRE_ANCHORED option can be set at the time of matching as well as |
| 615 | settings at the start of compilation and execution. The | at compile time. |
| 616 | PCRE_ANCHORED option can be set at the time of matching as | |
| 617 | well as at compile time. | If errptr is NULL, pcre_compile() returns NULL immediately. Otherwise, |
| 618 | if compilation of a pattern fails, pcre_compile() returns NULL, and | |
| 619 | If errptr is NULL, pcre_compile() returns NULL immediately. | sets the variable pointed to by errptr to point to a textual error mes- |
| 620 | Otherwise, if compilation of a pattern fails, pcre_compile() | sage. The offset from the start of the pattern to the character where |
| 621 | returns NULL, and sets the variable pointed to by errptr to | the error was discovered is placed in the variable pointed to by |
| 622 | point to a textual error message. The offset from the start | erroffset, which must not be NULL. If it is, an immediate error is |
| 623 | of the pattern to the character where the error was | given. |
| 624 | discovered is placed in the variable pointed to by | |
| 625 | erroffset, which must not be NULL. If it is, an immediate | If the final argument, tableptr, is NULL, PCRE uses a default set of |
| 626 | error is given. | character tables that are built when PCRE is compiled, using the |
| 627 | default C locale. Otherwise, tableptr must be an address that is the | |
| 628 | If the final argument, tableptr, is NULL, PCRE uses a | result of a call to pcre_maketables(). This value is stored with the |
| 629 | default set of character tables which are built when it is | compiled pattern, and used again by pcre_exec(), unless another table |
| 630 | compiled, using the default C locale. Otherwise, tableptr | pointer is passed to it. For more discussion, see the section on locale |
| 631 | must be the result of a call to pcre_maketables(). See the | support below. |
| 632 | section on locale support below. | |
| 633 | This code fragment shows a typical straightforward call to pcre_com- | |
| 634 | This code fragment shows a typical straightforward call to | pile(): |
| 635 | pcre_compile(): | |
| 636 | pcre *re; | |
| 637 | pcre *re; | const char *error; |
| 638 | const char *error; | int erroffset; |
| 639 | int erroffset; | re = pcre_compile( |
| 640 | re = pcre_compile( | "^A.*Z", /* the pattern */ |
| 641 | "^A.*Z", /* the pattern */ | 0, /* default options */ |
| 642 | 0, /* default options */ | &error, /* for error message */ |
| 643 | &error, /* for error message */ | &erroffset, /* for error offset */ |
| 644 | &erroffset, /* for error offset */ | NULL); /* use default character tables */ |
| 645 | NULL); /* use default character tables */ | |
| 646 | The following names for option bits are defined in the pcre.h header | |
| 647 | The following option bits are defined: | file: |
| 648 | ||
| 649 | PCRE_ANCHORED | PCRE_ANCHORED |
| 650 | ||
| 651 | If this bit is set, the pattern is forced to be "anchored", | If this bit is set, the pattern is forced to be "anchored", that is, it |
| 652 | that is, it is constrained to match only at the first match- | is constrained to match only at the first matching point in the string |
| 653 | ing point in the string which is being searched (the "sub- | that is being searched (the "subject string"). This effect can also be |
| 654 | ject string"). This effect can also be achieved by appropri- | achieved by appropriate constructs in the pattern itself, which is the |
| 655 | ate constructs in the pattern itself, which is the only way | only way to do it in Perl. |
| 656 | to do it in Perl. | |
| 657 | PCRE_AUTO_CALLOUT | |
| 658 | PCRE_CASELESS | |
| 659 | If this bit is set, pcre_compile() automatically inserts callout items, | |
| 660 | If this bit is set, letters in the pattern match both upper | all with number 255, before each pattern item. For discussion of the |
| 661 | and lower case letters. It is equivalent to Perl's /i | callout facility, see the pcrecallout documentation. |
| 662 | option, and it can be changed within a pattern by a (?i) | |
| 663 | option setting. | PCRE_CASELESS |
| 664 | ||
| 665 | PCRE_DOLLAR_ENDONLY | If this bit is set, letters in the pattern match both upper and lower |
| 666 | case letters. It is equivalent to Perl's /i option, and it can be | |
| 667 | If this bit is set, a dollar metacharacter in the pattern | changed within a pattern by a (?i) option setting. When running in |
| 668 | matches only at the end of the subject string. Without this | UTF-8 mode, case support for high-valued characters is available only |
| 669 | option, a dollar also matches immediately before the final | when PCRE is built with Unicode character property support. |
| 670 | character if it is a newline (but not before any other new- | |
| 671 | lines). The PCRE_DOLLAR_ENDONLY option is ignored if | PCRE_DOLLAR_ENDONLY |
| 672 | PCRE_MULTILINE is set. There is no equivalent to this option | |
| 673 | in Perl, and no way to set it within a pattern. | If this bit is set, a dollar metacharacter in the pattern matches only |
| 674 | at the end of the subject string. Without this option, a dollar also | |
| 675 | PCRE_DOTALL | matches immediately before the final character if it is a newline (but |
| 676 | not before any other newlines). The PCRE_DOLLAR_ENDONLY option is | |
| 677 | If this bit is set, a dot metacharater in the pattern | ignored if PCRE_MULTILINE is set. There is no equivalent to this option |
| 678 | matches all characters, including newlines. Without it, new- | in Perl, and no way to set it within a pattern. |
| 679 | lines are excluded. This option is equivalent to Perl's /s | |
| 680 | option, and it can be changed within a pattern by a (?s) | PCRE_DOTALL |
| 681 | option setting. A negative class such as [^a] always matches | |
| 682 | a newline character, independent of the setting of this | If this bit is set, a dot metacharater in the pattern matches all char- |
| 683 | option. | acters, including newlines. Without it, newlines are excluded. This |
| 684 | option is equivalent to Perl's /s option, and it can be changed within | |
| 685 | PCRE_EXTENDED | a pattern by a (?s) option setting. A negative class such as [^a] |
| 686 | always matches a newline character, independent of the setting of this | |
| 687 | If this bit is set, whitespace data characters in the pat- | option. |
| 688 | tern are totally ignored except when escaped or inside a | |
| 689 | character class. Whitespace does not include the VT charac- | PCRE_EXTENDED |
| 690 | ter (code 11). In addition, characters between an unescaped | |
| 691 | # outside a character class and the next newline character, | If this bit is set, whitespace data characters in the pattern are |
| 692 | inclusive, are also ignored. This is equivalent to Perl's /x | totally ignored except when escaped or inside a character class. |
| 693 | option, and it can be changed within a pattern by a (?x) | Whitespace does not include the VT character (code 11). In addition, |
| 694 | option setting. | characters between an unescaped # outside a character class and the |
| 695 | next newline character, inclusive, are also ignored. This is equivalent | |
| 696 | This option makes it possible to include comments inside | to Perl's /x option, and it can be changed within a pattern by a (?x) |
| 697 | complicated patterns. Note, however, that this applies only | option setting. |
| 698 | to data characters. Whitespace characters may never appear | |
| 699 | within special character sequences in a pattern, for example | This option makes it possible to include comments inside complicated |
| 700 | within the sequence (?( which introduces a conditional sub- | patterns. Note, however, that this applies only to data characters. |
| 701 | pattern. | Whitespace characters may never appear within special character |
| 702 | sequences in a pattern, for example within the sequence (?( which | |
| 703 | PCRE_EXTRA | introduces a conditional subpattern. |
| 704 | ||
| 705 | This option was invented in order to turn on additional | PCRE_EXTRA |
| 706 | functionality of PCRE that is incompatible with Perl, but it | |
| 707 | is currently of very little use. When set, any backslash in | This option was invented in order to turn on additional functionality |
| 708 | a pattern that is followed by a letter that has no special | of PCRE that is incompatible with Perl, but it is currently of very |
| 709 | meaning causes an error, thus reserving these combinations | little use. When set, any backslash in a pattern that is followed by a |
| 710 | for future expansion. By default, as in Perl, a backslash | letter that has no special meaning causes an error, thus reserving |
| 711 | followed by a letter with no special meaning is treated as a | these combinations for future expansion. By default, as in Perl, a |
| 712 | literal. There are at present no other features controlled | backslash followed by a letter with no special meaning is treated as a |
| 713 | by this option. It can also be set by a (?X) option setting | literal. There are at present no other features controlled by this |
| 714 | within a pattern. | option. It can also be set by a (?X) option setting within a pattern. |
| 715 | ||
| 716 | PCRE_MULTILINE | PCRE_MULTILINE |
| 717 | ||
| 718 | By default, PCRE treats the subject string as consisting of | By default, PCRE treats the subject string as consisting of a single |
| 719 | a single "line" of characters (even if it actually contains | line of characters (even if it actually contains newlines). The "start |
| 720 | several newlines). The "start of line" metacharacter (^) | of line" metacharacter (^) matches only at the start of the string, |
| 721 | matches only at the start of the string, while the "end of | while the "end of line" metacharacter ($) matches only at the end of |
| 722 | line" metacharacter ($) matches only at the end of the | the string, or before a terminating newline (unless PCRE_DOLLAR_ENDONLY |
| 723 | string, or before a terminating newline (unless | is set). This is the same as Perl. |
| 724 | PCRE_DOLLAR_ENDONLY is set). This is the same as Perl. | |
| 725 | When PCRE_MULTILINE it is set, the "start of line" and "end of line" | |
| 726 | When PCRE_MULTILINE it is set, the "start of line" and "end | constructs match immediately following or immediately before any new- |
| 727 | of line" constructs match immediately following or immedi- | line in the subject string, respectively, as well as at the very start |
| 728 | ately before any newline in the subject string, respec- | and end. This is equivalent to Perl's /m option, and it can be changed |
| 729 | tively, as well as at the very start and end. This is | within a pattern by a (?m) option setting. If there are no "\n" charac- |
| 730 | equivalent to Perl's /m option, and it can be changed within | ters in a subject string, or no occurrences of ^ or $ in a pattern, |
| 731 | a pattern by a (?m) option setting. If there are no "\n" | setting PCRE_MULTILINE has no effect. |
| 732 | characters in a subject string, or no occurrences of ^ or $ | |
| 733 | in a pattern, setting PCRE_MULTILINE has no effect. | PCRE_NO_AUTO_CAPTURE |
| 734 | ||
| 735 | PCRE_NO_AUTO_CAPTURE | If this option is set, it disables the use of numbered capturing paren- |
| 736 | theses in the pattern. Any opening parenthesis that is not followed by | |
| 737 | If this option is set, it disables the use of numbered cap- | ? behaves as if it were followed by ?: but named parentheses can still |
| 738 | turing parentheses in the pattern. Any opening parenthesis | be used for capturing (and they acquire numbers in the usual way). |
| 739 | that is not followed by ? behaves as if it were followed by | There is no equivalent of this option in Perl. |
| 740 | ?: but named parentheses can still be used for capturing | |
| 741 | (and they acquire numbers in the usual way). There is no | PCRE_UNGREEDY |
| 742 | equivalent of this option in Perl. | |
| 743 | This option inverts the "greediness" of the quantifiers so that they | |
| 744 | PCRE_UNGREEDY | are not greedy by default, but become greedy if followed by "?". It is |
| 745 | not compatible with Perl. It can also be set by a (?U) option setting | |
| 746 | This option inverts the "greediness" of the quantifiers so | within the pattern. |
| 747 | that they are not greedy by default, but become greedy if | |
| 748 | followed by "?". It is not compatible with Perl. It can also | PCRE_UTF8 |
| 749 | be set by a (?U) option setting within the pattern. | |
| 750 | This option causes PCRE to regard both the pattern and the subject as | |
| 751 | PCRE_UTF8 | strings of UTF-8 characters instead of single-byte character strings. |
| 752 | However, it is available only when PCRE is built to include UTF-8 sup- | |
| 753 | This option causes PCRE to regard both the pattern and the | port. If not, the use of this option provokes an error. Details of how |
| 754 | subject as strings of UTF-8 characters instead of single- | this option changes the behaviour of PCRE are given in the section on |
| 755 | byte character strings. However, it is available only if | UTF-8 support in the main pcre page. |
| 756 | PCRE has been built to include UTF-8 support. If not, the | |
| 757 | use of this option provokes an error. Details of how this | PCRE_NO_UTF8_CHECK |
| 758 | option changes the behaviour of PCRE are given in the sec- | |
| 759 | tion on UTF-8 support in the main pcre page. | When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 string is |
| 760 | automatically checked. If an invalid UTF-8 sequence of bytes is found, | |
| 761 | pcre_compile() returns an error. If you already know that your pattern | |
| 762 | is valid, and you want to skip this check for performance reasons, you | |
| 763 | can set the PCRE_NO_UTF8_CHECK option. When it is set, the effect of | |
| 764 | passing an invalid UTF-8 string as a pattern is undefined. It may cause | |
| 765 | your program to crash. Note that this option can also be passed to | |
| 766 | pcre_exec(), to suppress the UTF-8 validity checking of subject | |
| 767 | strings. | |
| 768 | ||
| 769 | ||
| 770 | STUDYING A PATTERN | STUDYING A PATTERN |
| 771 | ||
| 772 | pcre_extra *pcre_study(const pcre *code, int options, | pcre_extra *pcre_study(const pcre *code, int options, |
| 773 | const char **errptr); | const char **errptr); |
| 774 | ||
| 775 | When a pattern is going to be used several times, it is | If a compiled pattern is going to be used several times, it is worth |
| 776 | worth spending more time analyzing it in order to speed up | spending more time analyzing it in order to speed up the time taken for |
| 777 | the time taken for matching. The function pcre_study() takes | matching. The function pcre_study() takes a pointer to a compiled pat- |
| 778 | a pointer to a compiled pattern as its first argument. If | tern as its first argument. If studying the pattern produces additional |
| 779 | studing the pattern produces additional information that | information that will help speed up matching, pcre_study() returns a |
| 780 | will help speed up matching, pcre_study() returns a pointer | pointer to a pcre_extra block, in which the study_data field points to |
| 781 | to a pcre_extra block, in which the study_data field points | the results of the study. |
| 782 | to the results of the study. | |
| 783 | The returned value from pcre_study() can be passed directly to | |
| 784 | The returned value from a pcre_study() can be passed | pcre_exec(). However, a pcre_extra block also contains other fields |
| 785 | directly to pcre_exec(). However, the pcre_extra block also | that can be set by the caller before the block is passed; these are |
| 786 | contains other fields that can be set by the caller before | described below in the section on matching a pattern. |
| 787 | the block is passed; these are described below. If studying | |
| 788 | the pattern does not produce any additional information, | If studying the pattern does not produce any additional information, |
| 789 | pcre_study() returns NULL. In that circumstance, if the cal- | pcre_study() returns NULL. In that circumstance, if the calling program |
| 790 | ling program wants to pass some of the other fields to | wants to pass any of the other fields to pcre_exec(), it must set up |
| 791 | pcre_exec(), it must set up its own pcre_extra block. | its own pcre_extra block. |
| 792 | ||
| 793 | The second argument contains option bits. At present, no | The second argument of pcre_study() contains option bits. At present, |
| 794 | options are defined for pcre_study(), and this argument | no options are defined, and this argument should always be zero. |
| 795 | should always be zero. | |
| 796 | The third argument for pcre_study() is a pointer for an error message. | |
| 797 | The third argument for pcre_study() is a pointer for an | If studying succeeds (even if no data is returned), the variable it |
| 798 | error message. If studying succeeds (even if no data is | points to is set to NULL. Otherwise it points to a textual error mes- |
| 799 | returned), the variable it points to is set to NULL. Other- | sage. You should therefore test the error pointer for NULL after call- |
| 800 | wise it points to a textual error message. You should there- | ing pcre_study(), to be sure that it has run successfully. |
| 801 | fore test the error pointer for NULL after calling | |
| 802 | pcre_study(), to be sure that it has run successfully. | This is a typical call to pcre_study(): |
| 803 | ||
| 804 | This is a typical call to pcre_study(): | pcre_extra *pe; |
| 805 | pe = pcre_study( | |
| 806 | pcre_extra *pe; | re, /* result of pcre_compile() */ |
| 807 | pe = pcre_study( | 0, /* no options exist */ |
| 808 | re, /* result of pcre_compile() */ | &error); /* set to NULL or points to a message */ |
| 809 | 0, /* no options exist */ | |
| 810 | &error); /* set to NULL or points to a message */ | At present, studying a pattern is useful only for non-anchored patterns |
| 811 | that do not have a single fixed starting character. A bitmap of possi- | |
| 812 | At present, studying a pattern is useful only for non- | ble starting bytes is created. |
| anchored patterns that do not have a single fixed starting | ||
| character. A bitmap of possible starting characters is | ||
| created. | ||
| 813 | ||
| 814 | ||
| 815 | LOCALE SUPPORT | LOCALE SUPPORT |
| 816 | ||
| 817 | PCRE handles caseless matching, and determines whether char- | PCRE handles caseless matching, and determines whether characters are |
| 818 | acters are letters, digits, or whatever, by reference to a | letters, digits, or whatever, by reference to a set of tables, indexed |
| 819 | set of tables. When running in UTF-8 mode, this applies only | by character value. (When running in UTF-8 mode, this applies only to |
| 820 | to characters with codes less than 256. The library contains | characters with codes less than 128. Higher-valued codes never match |
| 821 | a default set of tables that is created in the default C | escapes such as \w or \d, but can be tested with \p if PCRE is built |
| 822 | locale when PCRE is compiled. This is used when the final | with Unicode character property support.) |
| 823 | argument of pcre_compile() is NULL, and is sufficient for | |
| 824 | many applications. | An internal set of tables is created in the default C locale when PCRE |
| 825 | is built. This is used when the final argument of pcre_compile() is | |
| 826 | An alternative set of tables can, however, be supplied. Such | NULL, and is sufficient for many applications. An alternative set of |
| 827 | tables are built by calling the pcre_maketables() function, | tables can, however, be supplied. These may be created in a different |
| 828 | which has no arguments, in the relevant locale. The result | locale from the default. As more and more applications change to using |
| 829 | can then be passed to pcre_compile() as often as necessary. | Unicode, the need for this locale support is expected to die away. |
| 830 | For example, to build and use tables that are appropriate | |
| 831 | for the French locale (where accented characters with codes | External tables are built by calling the pcre_maketables() function, |
| 832 | greater than 128 are treated as letters), the following code | which has no arguments, in the relevant locale. The result can then be |
| 833 | could be used: | passed to pcre_compile() or pcre_exec() as often as necessary. For |
| 834 | example, to build and use tables that are appropriate for the French | |
| 835 | setlocale(LC_CTYPE, "fr"); | locale (where accented characters with values greater than 128 are |
| 836 | tables = pcre_maketables(); | treated as letters), the following code could be used: |
| 837 | re = pcre_compile(..., tables); | |
| 838 | setlocale(LC_CTYPE, "fr_FR"); | |
| 839 | The tables are built in memory that is obtained via | tables = pcre_maketables(); |
| 840 | pcre_malloc. The pointer that is passed to pcre_compile is | re = pcre_compile(..., tables); |
| 841 | saved with the compiled pattern, and the same tables are | |
| 842 | used via this pointer by pcre_study() and pcre_exec(). Thus, | When pcre_maketables() runs, the tables are built in memory that is |
| 843 | for any single pattern, compilation, studying and matching | obtained via pcre_malloc. It is the caller's responsibility to ensure |
| 844 | all happen in the same locale, but different patterns can be | that the memory containing the tables remains available for as long as |
| 845 | compiled in different locales. It is the caller's responsi- | it is needed. |
| 846 | bility to ensure that the memory containing the tables | |
| 847 | remains available for as long as it is needed. | The pointer that is passed to pcre_compile() is saved with the compiled |
| 848 | pattern, and the same tables are used via this pointer by pcre_study() | |
| 849 | and normally also by pcre_exec(). Thus, by default, for any single pat- | |
| 850 | tern, compilation, studying and matching all happen in the same locale, | |
| 851 | but different patterns can be compiled in different locales. | |
| 852 | ||
| 853 | It is possible to pass a table pointer or NULL (indicating the use of | |
| 854 | the internal tables) to pcre_exec(). Although not intended for this | |
| 855 | purpose, this facility could be used to match a pattern in a different | |
| 856 | locale from the one in which it was compiled. Passing table pointers at | |
| 857 | run time is discussed below in the section on matching a pattern. | |
| 858 | ||
| 859 | ||
| 860 | INFORMATION ABOUT A PATTERN | INFORMATION ABOUT A PATTERN |
| 861 | ||
| 862 | int pcre_fullinfo(const pcre *code, const pcre_extra *extra, | int pcre_fullinfo(const pcre *code, const pcre_extra *extra, |
| 863 | int what, void *where); | int what, void *where); |
| 864 | ||
| 865 | The pcre_fullinfo() function returns information about a | The pcre_fullinfo() function returns information about a compiled pat- |
| 866 | compiled pattern. It replaces the obsolete pcre_info() func- | tern. It replaces the obsolete pcre_info() function, which is neverthe- |
| 867 | tion, which is nevertheless retained for backwards compabil- | less retained for backwards compability (and is documented below). |
| 868 | ity (and is documented below). | |
| 869 | The first argument for pcre_fullinfo() is a pointer to the compiled | |
| 870 | The first argument for pcre_fullinfo() is a pointer to the | pattern. The second argument is the result of pcre_study(), or NULL if |
| 871 | compiled pattern. The second argument is the result of | the pattern was not studied. The third argument specifies which piece |
| 872 | pcre_study(), or NULL if the pattern was not studied. The | of information is required, and the fourth argument is a pointer to a |
| 873 | third argument specifies which piece of information is | variable to receive the data. The yield of the function is zero for |
| 874 | required, and the fourth argument is a pointer to a variable | success, or one of the following negative numbers: |
| 875 | to receive the data. The yield of the function is zero for | |
| 876 | success, or one of the following negative numbers: | PCRE_ERROR_NULL the argument code was NULL |
| 877 | the argument where was NULL | |
| 878 | PCRE_ERROR_NULL the argument code was NULL | PCRE_ERROR_BADMAGIC the "magic number" was not found |
| 879 | the argument where was NULL | PCRE_ERROR_BADOPTION the value of what was invalid |
| 880 | PCRE_ERROR_BADMAGIC the "magic number" was not found | |
| 881 | PCRE_ERROR_BADOPTION the value of what was invalid | The "magic number" is placed at the start of each compiled pattern as |
| 882 | an simple check against passing an arbitrary memory pointer. Here is a | |
| 883 | Here is a typical call of pcre_fullinfo(), to obtain the | typical call of pcre_fullinfo(), to obtain the length of the compiled |
| 884 | length of the compiled pattern: | pattern: |
| 885 | ||
| 886 | int rc; | int rc; |
| 887 | unsigned long int length; | unsigned long int length; |
| 888 | rc = pcre_fullinfo( | rc = pcre_fullinfo( |
| 889 | re, /* result of pcre_compile() */ | re, /* result of pcre_compile() */ |
| 890 | pe, /* result of pcre_study(), or NULL */ | pe, /* result of pcre_study(), or NULL */ |
| 891 | PCRE_INFO_SIZE, /* what is required */ | PCRE_INFO_SIZE, /* what is required */ |
| 892 | &length); /* where to put the data */ | &length); /* where to put the data */ |
| 893 | ||
| 894 | The possible values for the third argument are defined in | The possible values for the third argument are defined in pcre.h, and |
| 895 | pcre.h, and are as follows: | are as follows: |
| 896 | ||
| 897 | PCRE_INFO_BACKREFMAX | PCRE_INFO_BACKREFMAX |
| 898 | ||
| 899 | Return the number of the highest back reference in the pat- | Return the number of the highest back reference in the pattern. The |
| 900 | tern. The fourth argument should point to an int variable. | fourth argument should point to an int variable. Zero is returned if |
| 901 | Zero is returned if there are no back references. | there are no back references. |
| 902 | ||
| 903 | PCRE_INFO_CAPTURECOUNT | PCRE_INFO_CAPTURECOUNT |
| 904 | ||
| 905 | Return the number of capturing subpatterns in the pattern. | Return the number of capturing subpatterns in the pattern. The fourth |
| 906 | The fourth argument should point to an int variable. | argument should point to an int variable. |
| 907 | ||
| 908 | PCRE_INFO_FIRSTBYTE | PCRE_INFO_DEFAULTTABLES |
| 909 | ||
| 910 | Return information about the first byte of any matched | Return a pointer to the internal default character tables within PCRE. |
| 911 | string, for a non-anchored pattern. (This option used to be | The fourth argument should point to an unsigned char * variable. This |
| 912 | called PCRE_INFO_FIRSTCHAR; the old name is still recognized | information call is provided for internal use by the pcre_study() func- |
| 913 | for backwards compatibility.) | tion. External callers can cause PCRE to use its internal tables by |
| 914 | passing a NULL table pointer. | |
| 915 | If there is a fixed first byte, e.g. from a pattern such as | |
| 916 | (cat|cow|coyote), it is returned in the integer pointed to | PCRE_INFO_FIRSTBYTE |
| 917 | by where. Otherwise, if either | |
| 918 | Return information about the first byte of any matched string, for a | |
| 919 | (a) the pattern was compiled with the PCRE_MULTILINE option, | non-anchored pattern. (This option used to be called |
| 920 | and every branch starts with "^", or | PCRE_INFO_FIRSTCHAR; the old name is still recognized for backwards |
| 921 | compatibility.) | |
| 922 | (b) every branch of the pattern starts with ".*" and | |
| 923 | PCRE_DOTALL is not set (if it were set, the pattern would be | If there is a fixed first byte, for example, from a pattern such as |
| 924 | anchored), | (cat|cow|coyote), it is returned in the integer pointed to by where. |
| 925 | Otherwise, if either | |
| 926 | -1 is returned, indicating that the pattern matches only at | |
| 927 | the start of a subject string or after any newline within | (a) the pattern was compiled with the PCRE_MULTILINE option, and every |
| 928 | the string. Otherwise -2 is returned. For anchored patterns, | branch starts with "^", or |
| 929 | -2 is returned. | |
| 930 | (b) every branch of the pattern starts with ".*" and PCRE_DOTALL is not | |
| 931 | PCRE_INFO_FIRSTTABLE | set (if it were set, the pattern would be anchored), |
| 932 | ||
| 933 | If the pattern was studied, and this resulted in the con- | -1 is returned, indicating that the pattern matches only at the start |
| 934 | struction of a 256-bit table indicating a fixed set of bytes | of a subject string or after any newline within the string. Otherwise |
| 935 | for the first byte in any matching string, a pointer to the | -2 is returned. For anchored patterns, -2 is returned. |
| 936 | table is returned. Otherwise NULL is returned. The fourth | |
| 937 | argument should point to an unsigned char * variable. | PCRE_INFO_FIRSTTABLE |
| 938 | ||
| 939 | PCRE_INFO_LASTLITERAL | If the pattern was studied, and this resulted in the construction of a |
| 940 | 256-bit table indicating a fixed set of bytes for the first byte in any | |
| 941 | Return the value of the rightmost literal byte that must | matching string, a pointer to the table is returned. Otherwise NULL is |
| 942 | exist in any matched string, other than at its start, if | returned. The fourth argument should point to an unsigned char * vari- |
| 943 | such a byte has been recorded. The fourth argument should | able. |
| 944 | point to an int variable. If there is no such byte, -1 is | |
| 945 | returned. For anchored patterns, a last literal byte is | PCRE_INFO_LASTLITERAL |
| 946 | recorded only if it follows something of variable length. | |
| 947 | For example, for the pattern /^a\d+z\d+/ the returned value | Return the value of the rightmost literal byte that must exist in any |
| 948 | is "z", but for /^a\dz\d/ the returned value is -1. | matched string, other than at its start, if such a byte has been |
| 949 | recorded. The fourth argument should point to an int variable. If there | |
| 950 | PCRE_INFO_NAMECOUNT | is no such byte, -1 is returned. For anchored patterns, a last literal |
| 951 | PCRE_INFO_NAMEENTRYSIZE | byte is recorded only if it follows something of variable length. For |
| 952 | PCRE_INFO_NAMETABLE | example, for the pattern /^a\d+z\d+/ the returned value is "z", but for |
| 953 | /^a\dz\d/ the returned value is -1. | |
| 954 | PCRE supports the use of named as well as numbered capturing | |
| 955 | parentheses. The names are just an additional way of identi- | PCRE_INFO_NAMECOUNT |
| 956 | fying the parentheses, which still acquire a number. A | PCRE_INFO_NAMEENTRYSIZE |
| 957 | caller that wants to extract data from a named subpattern | PCRE_INFO_NAMETABLE |
| 958 | must convert the name to a number in order to access the | |
| 959 | correct pointers in the output vector (described with | PCRE supports the use of named as well as numbered capturing parenthe- |
| 960 | pcre_exec() below). In order to do this, it must first use | ses. The names are just an additional way of identifying the parenthe- |
| 961 | these three values to obtain the name-to-number mapping | ses, which still acquire numbers. A convenience function called |
| 962 | table for the pattern. | pcre_get_named_substring() is provided for extracting an individual |
| 963 | captured substring by name. It is also possible to extract the data | |
| 964 | The map consists of a number of fixed-size entries. | directly, by first converting the name to a number in order to access |
| 965 | PCRE_INFO_NAMECOUNT gives the number of entries, and | the correct pointers in the output vector (described with pcre_exec() |
| 966 | PCRE_INFO_NAMEENTRYSIZE gives the size of each entry; both | below). To do the conversion, you need to use the name-to-number map, |
| 967 | of these return an int value. The entry size depends on the | which is described by these three values. |
| 968 | length of the longest name. PCRE_INFO_NAMETABLE returns a | |
| 969 | pointer to the first entry of the table (a pointer to char). | The map consists of a number of fixed-size entries. PCRE_INFO_NAMECOUNT |
| 970 | The first two bytes of each entry are the number of the cap- | gives the number of entries, and PCRE_INFO_NAMEENTRYSIZE gives the size |
| 971 | turing parenthesis, most significant byte first. The rest of | of each entry; both of these return an int value. The entry size |
| 972 | the entry is the corresponding name, zero terminated. The | depends on the length of the longest name. PCRE_INFO_NAMETABLE returns |
| 973 | names are in alphabetical order. For example, consider the | a pointer to the first entry of the table (a pointer to char). The |
| 974 | following pattern (assume PCRE_EXTENDED is set, so white | first two bytes of each entry are the number of the capturing parenthe- |
| 975 | space - including newlines - is ignored): | sis, most significant byte first. The rest of the entry is the corre- |
| 976 | sponding name, zero terminated. The names are in alphabetical order. | |
| 977 | (?P<date> (?P<year>(\d\d)?\d\d) - | For example, consider the following pattern (assume PCRE_EXTENDED is |
| 978 | (?P<month>\d\d) - (?P<day>\d\d) ) | set, so white space - including newlines - is ignored): |
| 979 | ||
| 980 | There are four named subpatterns, so the table has four | (?P<date> (?P<year>(\d\d)?\d\d) - |
| 981 | entries, and each entry in the table is eight bytes long. | (?P<month>\d\d) - (?P<day>\d\d) ) |
| 982 | The table is as follows, with non-printing bytes shows in | |
| 983 | hex, and undefined bytes shown as ??: | There are four named subpatterns, so the table has four entries, and |
| 984 | each entry in the table is eight bytes long. The table is as follows, | |
| 985 | 00 01 d a t e 00 ?? | with non-printing bytes shows in hexadecimal, and undefined bytes shown |
| 986 | 00 05 d a y 00 ?? ?? | as ??: |
| 987 | 00 04 m o n t h 00 | |
| 988 | 00 02 y e a r 00 ?? | 00 01 d a t e 00 ?? |
| 989 | 00 05 d a y 00 ?? ?? | |
| 990 | When writing code to extract data from named subpatterns, | 00 04 m o n t h 00 |
| 991 | remember that the length of each entry may be different for | 00 02 y e a r 00 ?? |
| 992 | each compiled pattern. | |
| 993 | When writing code to extract data from named subpatterns using the | |
| 994 | PCRE_INFO_OPTIONS | name-to-number map, remember that the length of each entry is likely to |
| 995 | be different for each compiled pattern. | |
| 996 | Return a copy of the options with which the pattern was com- | |
| 997 | piled. The fourth argument should point to an unsigned long | PCRE_INFO_OPTIONS |
| 998 | int variable. These option bits are those specified in the | |
| 999 | call to pcre_compile(), modified by any top-level option | Return a copy of the options with which the pattern was compiled. The |
| 1000 | settings within the pattern itself. | fourth argument should point to an unsigned long int variable. These |
| 1001 | option bits are those specified in the call to pcre_compile(), modified | |
| 1002 | A pattern is automatically anchored by PCRE if all of its | by any top-level option settings within the pattern itself. |
| 1003 | top-level alternatives begin with one of the following: | |
| 1004 | A pattern is automatically anchored by PCRE if all of its top-level | |
| 1005 | ^ unless PCRE_MULTILINE is set | alternatives begin with one of the following: |
| 1006 | \A always | |
| 1007 | \G always | ^ unless PCRE_MULTILINE is set |
| 1008 | .* if PCRE_DOTALL is set and there are no back | \A always |
| 1009 | references to the subpattern in which .* appears | \G always |
| 1010 | .* if PCRE_DOTALL is set and there are no back | |
| 1011 | For such patterns, the PCRE_ANCHORED bit is set in the | references to the subpattern in which .* appears |
| 1012 | options returned by pcre_fullinfo(). | |
| 1013 | For such patterns, the PCRE_ANCHORED bit is set in the options returned | |
| 1014 | PCRE_INFO_SIZE | by pcre_fullinfo(). |
| 1015 | ||
| 1016 | Return the size of the compiled pattern, that is, the value | PCRE_INFO_SIZE |
| 1017 | that was passed as the argument to pcre_malloc() when PCRE | |
| 1018 | was getting memory in which to place the compiled data. The | Return the size of the compiled pattern, that is, the value that was |
| 1019 | fourth argument should point to a size_t variable. | passed as the argument to pcre_malloc() when PCRE was getting memory in |
| 1020 | which to place the compiled data. The fourth argument should point to a | |
| 1021 | PCRE_INFO_STUDYSIZE | size_t variable. |
| 1022 | ||
| 1023 | Returns the size of the data block pointed to by the | PCRE_INFO_STUDYSIZE |
| 1024 | study_data field in a pcre_extra block. That is, it is the | |
| 1025 | value that was passed to pcre_malloc() when PCRE was getting | Return the size of the data block pointed to by the study_data field in |
| 1026 | memory into which to place the data created by pcre_study(). | a pcre_extra block. That is, it is the value that was passed to |
| 1027 | The fourth argument should point to a size_t variable. | pcre_malloc() when PCRE was getting memory into which to place the data |
| 1028 | created by pcre_study(). The fourth argument should point to a size_t | |
| 1029 | variable. | |
| 1030 | ||
| 1031 | ||
| 1032 | OBSOLETE INFO FUNCTION | OBSOLETE INFO FUNCTION |
| 1033 | ||
| 1034 | int pcre_info(const pcre *code, int *optptr, *firstcharptr); | int pcre_info(const pcre *code, int *optptr, int *firstcharptr); |
| 1035 | ||
| 1036 | The pcre_info() function is now obsolete because its inter- | The pcre_info() function is now obsolete because its interface is too |
| 1037 | face is too restrictive to return all the available data | restrictive to return all the available data about a compiled pattern. |
| 1038 | about a compiled pattern. New programs should use | New programs should use pcre_fullinfo() instead. The yield of |
| 1039 | pcre_fullinfo() instead. The yield of pcre_info() is the | pcre_info() is the number of capturing subpatterns, or one of the fol- |
| 1040 | number of capturing subpatterns, or one of the following | lowing negative numbers: |
| 1041 | negative numbers: | |
| 1042 | PCRE_ERROR_NULL the argument code was NULL | |
| 1043 | PCRE_ERROR_NULL the argument code was NULL | PCRE_ERROR_BADMAGIC the "magic number" was not found |
| 1044 | PCRE_ERROR_BADMAGIC the "magic number" was not found | |
| 1045 | If the optptr argument is not NULL, a copy of the options with which | |
| 1046 | If the optptr argument is not NULL, a copy of the options | the pattern was compiled is placed in the integer it points to (see |
| 1047 | with which the pattern was compiled is placed in the integer | PCRE_INFO_OPTIONS above). |
| 1048 | it points to (see PCRE_INFO_OPTIONS above). | |
| 1049 | If the pattern is not anchored and the firstcharptr argument is not | |
| 1050 | If the pattern is not anchored and the firstcharptr argument | NULL, it is used to pass back information about the first character of |
| 1051 | is not NULL, it is used to pass back information about the | any matched string (see PCRE_INFO_FIRSTBYTE above). |
| first character of any matched string (see | ||
| PCRE_INFO_FIRSTBYTE above). | ||
| 1052 | ||
| 1053 | ||
| 1054 | MATCHING A PATTERN | MATCHING A PATTERN |
| 1055 | ||
| 1056 | int pcre_exec(const pcre *code, const pcre_extra *extra, | int pcre_exec(const pcre *code, const pcre_extra *extra, |
| 1057 | const char *subject, int length, int startoffset, | const char *subject, int length, int startoffset, |
| 1058 | int options, int *ovector, int ovecsize); | int options, int *ovector, int ovecsize); |
| 1059 | ||
| 1060 | The function pcre_exec() is called to match a subject string | The function pcre_exec() is called to match a subject string against a |
| 1061 | against a pre-compiled pattern, which is passed in the code | compiled pattern, which is passed in the code argument. If the pattern |
| 1062 | argument. If the pattern has been studied, the result of the | has been studied, the result of the study should be passed in the extra |
| 1063 | study should be passed in the extra argument. | argument. |
| 1064 | ||
| 1065 | Here is an example of a simple call to pcre_exec(): | In most applications, the pattern will have been compiled (and option- |
| 1066 | ally studied) in the same process that calls pcre_exec(). However, it | |
| 1067 | int rc; | is possible to save compiled patterns and study data, and then use them |
| 1068 | int ovector[30]; | later in different processes, possibly even on different hosts. For a |
| 1069 | rc = pcre_exec( | discussion about this, see the pcreprecompile documentation. |
| 1070 | re, /* result of pcre_compile() */ | |
| 1071 | NULL, /* we didn't study the pattern */ | Here is an example of a simple call to pcre_exec(): |
| 1072 | "some string", /* the subject string */ | |
| 1073 | 11, /* the length of the subject string */ | int rc; |
| 1074 | 0, /* start at offset 0 in the subject */ | int ovector[30]; |
| 1075 | 0, /* default options */ | rc = pcre_exec( |
| 1076 | ovector, /* vector for substring information */ | re, /* result of pcre_compile() */ |
| 1077 | 30); /* number of elements in the vector */ | NULL, /* we didn't study the pattern */ |
| 1078 | "some string", /* the subject string */ | |
| 1079 | If the extra argument is not NULL, it must point to a | 11, /* the length of the subject string */ |
| 1080 | pcre_extra data block. The pcre_study() function returns | 0, /* start at offset 0 in the subject */ |
| 1081 | such a block (when it doesn't return NULL), but you can also | 0, /* default options */ |
| 1082 | create one for yourself, and pass additional information in | ovector, /* vector of integers for substring information */ |
| 1083 | it. The fields in the block are as follows: | 30); /* number of elements in the vector (NOT size in |
| 1084 | bytes) */ | |
| 1085 | unsigned long int flags; | |
| 1086 | void *study_data; | Extra data for pcre_exec() |
| 1087 | unsigned long int match_limit; | |
| 1088 | void *callout_data; | If the extra argument is not NULL, it must point to a pcre_extra data |
| 1089 | block. The pcre_study() function returns such a block (when it doesn't | |
| 1090 | The flags field is a bitmap that specifies which of the | return NULL), but you can also create one for yourself, and pass addi- |
| 1091 | other fields are set. The flag bits are: | tional information in it. The fields in a pcre_extra block are as fol- |
| 1092 | lows: | |
| 1093 | PCRE_EXTRA_STUDY_DATA | |
| 1094 | PCRE_EXTRA_MATCH_LIMIT | unsigned long int flags; |
| 1095 | PCRE_EXTRA_CALLOUT_DATA | void *study_data; |
| 1096 | unsigned long int match_limit; | |
| 1097 | Other flag bits should be set to zero. The study_data field | void *callout_data; |
| 1098 | is set in the pcre_extra block that is returned by | const unsigned char *tables; |
| 1099 | pcre_study(), together with the appropriate flag bit. You | |
| 1100 | should not set this yourself, but you can add to the block | The flags field is a bitmap that specifies which of the other fields |
| 1101 | by setting the other fields. | are set. The flag bits are: |
| 1102 | ||
| 1103 | The match_limit field provides a means of preventing PCRE | PCRE_EXTRA_STUDY_DATA |
| 1104 | from using up a vast amount of resources when running pat- | PCRE_EXTRA_MATCH_LIMIT |
| 1105 | terns that are not going to match, but which have a very | PCRE_EXTRA_CALLOUT_DATA |
| 1106 | large number of possibilities in their search trees. The | PCRE_EXTRA_TABLES |
| 1107 | classic example is the use of nested unlimited repeats. | |
| 1108 | Internally, PCRE uses a function called match() which it | Other flag bits should be set to zero. The study_data field is set in |
| 1109 | calls repeatedly (sometimes recursively). The limit is | the pcre_extra block that is returned by pcre_study(), together with |
| 1110 | imposed on the number of times this function is called dur- | the appropriate flag bit. You should not set this yourself, but you may |
| 1111 | ing a match, which has the effect of limiting the amount of | add to the block by setting the other fields and their corresponding |
| 1112 | recursion and backtracking that can take place. For patterns | flag bits. |
| 1113 | that are not anchored, the count starts from zero for each | |
| 1114 | position in the subject string. | The match_limit field provides a means of preventing PCRE from using up |
| 1115 | a vast amount of resources when running patterns that are not going to | |
| 1116 | The default limit for the library can be set when PCRE is | match, but which have a very large number of possibilities in their |
| 1117 | built; the default default is 10 million, which handles all | search trees. The classic example is the use of nested unlimited |
| 1118 | but the most extreme cases. You can reduce the default by | repeats. |
| 1119 | suppling pcre_exec() with a pcre_extra block in which | |
| 1120 | match_limit is set to a smaller value, and | Internally, PCRE uses a function called match() which it calls repeat- |
| 1121 | PCRE_EXTRA_MATCH_LIMIT is set in the flags field. If the | edly (sometimes recursively). The limit is imposed on the number of |
| 1122 | limit is exceeded, pcre_exec() returns | times this function is called during a match, which has the effect of |
| 1123 | PCRE_ERROR_MATCHLIMIT. | limiting the amount of recursion and backtracking that can take place. |
| 1124 | For patterns that are not anchored, the count starts from zero for each | |
| 1125 | The pcre_callout field is used in conjunction with the "cal- | position in the subject string. |
| 1126 | lout" feature, which is described in the pcrecallout docu- | |
| 1127 | mentation. | The default limit for the library can be set when PCRE is built; the |
| 1128 | default default is 10 million, which handles all but the most extreme | |
| 1129 | The PCRE_ANCHORED option can be passed in the options argu- | cases. You can reduce the default by suppling pcre_exec() with a |
| 1130 | ment, whose unused bits must be zero. This limits | pcre_extra block in which match_limit is set to a smaller value, and |
| 1131 | pcre_exec() to matching at the first matching position. How- | PCRE_EXTRA_MATCH_LIMIT is set in the flags field. If the limit is |
| 1132 | ever, if a pattern was compiled with PCRE_ANCHORED, or | exceeded, pcre_exec() returns PCRE_ERROR_MATCHLIMIT. |
| 1133 | turned out to be anchored by virtue of its contents, it can- | |
| 1134 | not be made unachored at matching time. | The pcre_callout field is used in conjunction with the "callout" fea- |
| 1135 | ture, which is described in the pcrecallout documentation. | |
| 1136 | There are also three further options that can be set only at | |
| 1137 | matching time: | The tables field is used to pass a character tables pointer to |
| 1138 | pcre_exec(); this overrides the value that is stored with the compiled | |
| 1139 | PCRE_NOTBOL | pattern. A non-NULL value is stored with the compiled pattern only if |
| 1140 | custom tables were supplied to pcre_compile() via its tableptr argu- | |
| 1141 | The first character of the string is not the beginning of a | ment. If NULL is passed to pcre_exec() using this mechanism, it forces |
| 1142 | line, so the circumflex metacharacter should not match | PCRE's internal tables to be used. This facility is helpful when re- |
| 1143 | before it. Setting this without PCRE_MULTILINE (at compile | using patterns that have been saved after compiling with an external |
| 1144 | time) causes circumflex never to match. | set of tables, because the external tables might be at a different |
| 1145 | address when pcre_exec() is called. See the pcreprecompile documenta- | |
| 1146 | PCRE_NOTEOL | tion for a discussion of saving compiled patterns for later use. |
| 1147 | ||
| 1148 | The end of the string is not the end of a line, so the dol- | Option bits for pcre_exec() |
| 1149 | lar metacharacter should not match it nor (except in multi- | |
| 1150 | line mode) a newline immediately before it. Setting this | The unused bits of the options argument for pcre_exec() must be zero. |
| 1151 | without PCRE_MULTILINE (at compile time) causes dollar never | The only bits that may be set are PCRE_ANCHORED, PCRE_NOTBOL, |
| 1152 | to match. | PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NO_UTF8_CHECK and PCRE_PARTIAL. |
| 1153 | ||
| 1154 | PCRE_NOTEMPTY | PCRE_ANCHORED |
| 1155 | ||
| 1156 | An empty string is not considered to be a valid match if | The PCRE_ANCHORED option limits pcre_exec() to matching at the first |
| 1157 | this option is set. If there are alternatives in the pat- | matching position. If a pattern was compiled with PCRE_ANCHORED, or |
| 1158 | tern, they are tried. If all the alternatives match the | turned out to be anchored by virtue of its contents, it cannot be made |
| 1159 | empty string, the entire match fails. For example, if the | unachored at matching time. |
| 1160 | pattern | |
| 1161 | PCRE_NOTBOL | |
| 1162 | a?b? | |
| 1163 | This option specifies that first character of the subject string is not | |
| 1164 | is applied to a string not beginning with "a" or "b", it | the beginning of a line, so the circumflex metacharacter should not |
| 1165 | matches the empty string at the start of the subject. With | match before it. Setting this without PCRE_MULTILINE (at compile time) |
| 1166 | PCRE_NOTEMPTY set, this match is not valid, so PCRE searches | causes circumflex never to match. This option affects only the |
| 1167 | further into the string for occurrences of "a" or "b". | behaviour of the circumflex metacharacter. It does not affect \A. |
| 1168 | ||
| 1169 | Perl has no direct equivalent of PCRE_NOTEMPTY, but it does | PCRE_NOTEOL |
| 1170 | make a special case of a pattern match of the empty string | |
| 1171 | within its split() function, and when using the /g modifier. | This option specifies that the end of the subject string is not the end |
| 1172 | It is possible to emulate Perl's behaviour after matching a | of a line, so the dollar metacharacter should not match it nor (except |
| 1173 | null string by first trying the match again at the same | in multiline mode) a newline immediately before it. Setting this with- |
| 1174 | offset with PCRE_NOTEMPTY set, and then if that fails by | out PCRE_MULTILINE (at compile time) causes dollar never to match. This |
| 1175 | advancing the starting offset (see below) and trying an | option affects only the behaviour of the dollar metacharacter. It does |
| 1176 | ordinary match again. | not affect \Z or \z. |
| 1177 | ||
| 1178 | The subject string is passed to pcre_exec() as a pointer in | PCRE_NOTEMPTY |
| 1179 | subject, a length in length, and a starting offset in star- | |
| 1180 | toffset. Unlike the pattern string, the subject may contain | An empty string is not considered to be a valid match if this option is |
| 1181 | binary zero bytes. When the starting offset is zero, the | set. If there are alternatives in the pattern, they are tried. If all |
| 1182 | search for a match starts at the beginning of the subject, | the alternatives match the empty string, the entire match fails. For |
| 1183 | and this is by far the most common case. | example, if the pattern |
| 1184 | ||
| 1185 | If the pattern was compiled with the PCRE_UTF8 option, the | a?b? |
| 1186 | subject must be a sequence of bytes that is a valid UTF-8 | |
| 1187 | string. If an invalid UTF-8 string is passed, PCRE's | is applied to a string not beginning with "a" or "b", it matches the |
| 1188 | behaviour is not defined. | empty string at the start of the subject. With PCRE_NOTEMPTY set, this |
| 1189 | match is not valid, so PCRE searches further into the string for occur- | |
| 1190 | A non-zero starting offset is useful when searching for | rences of "a" or "b". |
| 1191 | another match in the same subject by calling pcre_exec() | |
| 1192 | again after a previous success. Setting startoffset differs | Perl has no direct equivalent of PCRE_NOTEMPTY, but it does make a spe- |
| 1193 | from just passing over a shortened string and setting | cial case of a pattern match of the empty string within its split() |
| 1194 | PCRE_NOTBOL in the case of a pattern that begins with any | function, and when using the /g modifier. It is possible to emulate |
| 1195 | kind of lookbehind. For example, consider the pattern | Perl's behaviour after matching a null string by first trying the match |
| 1196 | again at the same offset with PCRE_NOTEMPTY and PCRE_ANCHORED, and then | |
| 1197 | \Biss\B | if that fails by advancing the starting offset (see below) and trying |
| 1198 | an ordinary match again. There is some code that demonstrates how to do | |
| 1199 | which finds occurrences of "iss" in the middle of words. (\B | this in the pcredemo.c sample program. |
| 1200 | matches only if the current position in the subject is not a | |
| 1201 | word boundary.) When applied to the string "Mississipi" the | PCRE_NO_UTF8_CHECK |
| 1202 | first call to pcre_exec() finds the first occurrence. If | |
| 1203 | pcre_exec() is called again with just the remainder of the | When PCRE_UTF8 is set at compile time, the validity of the subject as a |
| 1204 | subject, namely "issipi", it does not match, because \B is | UTF-8 string is automatically checked when pcre_exec() is subsequently |
| 1205 | always false at the start of the subject, which is deemed to | called. The value of startoffset is also checked to ensure that it |
| 1206 | be a word boundary. However, if pcre_exec() is passed the | points to the start of a UTF-8 character. If an invalid UTF-8 sequence |
| 1207 | entire string again, but with startoffset set to 4, it finds | of bytes is found, pcre_exec() returns the error PCRE_ERROR_BADUTF8. If |
| 1208 | the second occurrence of "iss" because it is able to look | startoffset contains an invalid value, PCRE_ERROR_BADUTF8_OFFSET is |
| 1209 | behind the starting point to discover that it is preceded by | returned. |
| 1210 | a letter. | |
| 1211 | If you already know that your subject is valid, and you want to skip | |
| 1212 | If a non-zero starting offset is passed when the pattern is | these checks for performance reasons, you can set the |
| 1213 | anchored, one attempt to match at the given offset is tried. | PCRE_NO_UTF8_CHECK option when calling pcre_exec(). You might want to |
| 1214 | This can only succeed if the pattern does not require the | do this for the second and subsequent calls to pcre_exec() if you are |
| 1215 | match to be at the start of the subject. | making repeated calls to find all the matches in a single subject |
| 1216 | string. However, you should be sure that the value of startoffset | |
| 1217 | In general, a pattern matches a certain portion of the sub- | points to the start of a UTF-8 character. When PCRE_NO_UTF8_CHECK is |
| 1218 | ject, and in addition, further substrings from the subject | set, the effect of passing an invalid UTF-8 string as a subject, or a |
| 1219 | may be picked out by parts of the pattern. Following the | value of startoffset that does not point to the start of a UTF-8 char- |
| 1220 | usage in Jeffrey Friedl's book, this is called "capturing" | acter, is undefined. Your program may crash. |
| 1221 | in what follows, and the phrase "capturing subpattern" is | |
| 1222 | used for a fragment of a pattern that picks out a substring. | PCRE_PARTIAL |
| 1223 | PCRE supports several other kinds of parenthesized subpat- | |
| 1224 | tern that do not cause substrings to be captured. | This option turns on the partial matching feature. If the subject |
| 1225 | string fails to match the pattern, but at some point during the match- | |
| 1226 | Captured substrings are returned to the caller via a vector | ing process the end of the subject was reached (that is, the subject |
| 1227 | of integer offsets whose address is passed in ovector. The | partially matches the pattern and the failure to match occurred only |
| 1228 | number of elements in the vector is passed in ovecsize. The | because there were not enough subject characters), pcre_exec() returns |
| 1229 | first two-thirds of the vector is used to pass back captured | PCRE_ERROR_PARTIAL instead of PCRE_ERROR_NOMATCH. When PCRE_PARTIAL is |
| 1230 | substrings, each substring using a pair of integers. The | used, there are restrictions on what may appear in the pattern. These |
| 1231 | remaining third of the vector is used as workspace by | are discussed in the pcrepartial documentation. |
| 1232 | pcre_exec() while matching capturing subpatterns, and is not | |
| 1233 | available for passing back information. The length passed in | The string to be matched by pcre_exec() |
| 1234 | ovecsize should always be a multiple of three. If it is not, | |
| 1235 | it is rounded down. | The subject string is passed to pcre_exec() as a pointer in subject, a |
| 1236 | length in length, and a starting byte offset in startoffset. In UTF-8 | |
| 1237 | When a match has been successful, information about captured | mode, the byte offset must point to the start of a UTF-8 character. |
| 1238 | substrings is returned in pairs of integers, starting at the | Unlike the pattern string, the subject may contain binary zero bytes. |
| 1239 | beginning of ovector, and continuing up to two-thirds of its | When the starting offset is zero, the search for a match starts at the |
| 1240 | length at the most. The first element of a pair is set to | beginning of the subject, and this is by far the most common case. |
| 1241 | the offset of the first character in a substring, and the | |
| 1242 | second is set to the offset of the first character after the | A non-zero starting offset is useful when searching for another match |
| 1243 | end of a substring. The first pair, ovector[0] and ovec- | in the same subject by calling pcre_exec() again after a previous suc- |
| 1244 | tor[1], identify the portion of the subject string matched | cess. Setting startoffset differs from just passing over a shortened |
| 1245 | by the entire pattern. The next pair is used for the first | string and setting PCRE_NOTBOL in the case of a pattern that begins |
| 1246 | capturing subpattern, and so on. The value returned by | with any kind of lookbehind. For example, consider the pattern |
| 1247 | pcre_exec() is the number of pairs that have been set. If | |
| 1248 | there are no capturing subpatterns, the return value from a | \Biss\B |
| 1249 | successful match is 1, indicating that just the first pair | |
| 1250 | of offsets has been set. | which finds occurrences of "iss" in the middle of words. (\B matches |
| 1251 | only if the current position in the subject is not a word boundary.) | |
| 1252 | Some convenience functions are provided for extracting the | When applied to the string "Mississipi" the first call to pcre_exec() |
| 1253 | captured substrings as separate strings. These are described | finds the first occurrence. If pcre_exec() is called again with just |
| 1254 | in the following section. | the remainder of the subject, namely "issipi", it does not match, |
| 1255 | because \B is always false at the start of the subject, which is deemed | |
| 1256 | It is possible for an capturing subpattern number n+1 to | to be a word boundary. However, if pcre_exec() is passed the entire |
| 1257 | match some part of the subject when subpattern n has not | string again, but with startoffset set to 4, it finds the second occur- |
| 1258 | been used at all. For example, if the string "abc" is | rence of "iss" because it is able to look behind the starting point to |
| 1259 | matched against the pattern (a|(z))(bc) subpatterns 1 and 3 | discover that it is preceded by a letter. |
| 1260 | are matched, but 2 is not. When this happens, both offset | |
| 1261 | values corresponding to the unused subpattern are set to -1. | If a non-zero starting offset is passed when the pattern is anchored, |
| 1262 | one attempt to match at the given offset is made. This can only succeed | |
| 1263 | If a capturing subpattern is matched repeatedly, it is the | if the pattern does not require the match to be at the start of the |
| 1264 | last portion of the string that it matched that gets | subject. |
| 1265 | returned. | |
| 1266 | How pcre_exec() returns captured substrings | |
| 1267 | If the vector is too small to hold all the captured sub- | |
| 1268 | strings, it is used as far as possible (up to two-thirds of | In general, a pattern matches a certain portion of the subject, and in |
| 1269 | its length), and the function returns a value of zero. In | addition, further substrings from the subject may be picked out by |
| 1270 | particular, if the substring offsets are not of interest, | parts of the pattern. Following the usage in Jeffrey Friedl's book, |
| 1271 | pcre_exec() may be called with ovector passed as NULL and | this is called "capturing" in what follows, and the phrase "capturing |
| 1272 | ovecsize as zero. However, if the pattern contains back | subpattern" is used for a fragment of a pattern that picks out a sub- |
| 1273 | references and the ovector isn't big enough to remember the | string. PCRE supports several other kinds of parenthesized subpattern |
| 1274 | related substrings, PCRE has to get additional memory for | that do not cause substrings to be captured. |
| 1275 | use during matching. Thus it is usually advisable to supply | |
| 1276 | an ovector. | Captured substrings are returned to the caller via a vector of integer |
| 1277 | offsets whose address is passed in ovector. The number of elements in | |
| 1278 | Note that pcre_info() can be used to find out how many cap- | the vector is passed in ovecsize, which must be a non-negative number. |
| 1279 | turing subpatterns there are in a compiled pattern. The | Note: this argument is NOT the size of ovector in bytes. |
| 1280 | smallest size for ovector that will allow for n captured | |
| 1281 | substrings, in addition to the offsets of the substring | The first two-thirds of the vector is used to pass back captured sub- |
| 1282 | matched by the whole pattern, is (n+1)*3. | strings, each substring using a pair of integers. The remaining third |
| 1283 | of the vector is used as workspace by pcre_exec() while matching cap- | |
| 1284 | If pcre_exec() fails, it returns a negative number. The fol- | turing subpatterns, and is not available for passing back information. |
| 1285 | lowing are defined in the header file: | The length passed in ovecsize should always be a multiple of three. If |
| 1286 | it is not, it is rounded down. | |
| 1287 | PCRE_ERROR_NOMATCH (-1) | |
| 1288 | When a match is successful, information about captured substrings is | |
| 1289 | The subject string did not match the pattern. | returned in pairs of integers, starting at the beginning of ovector, |
| 1290 | and continuing up to two-thirds of its length at the most. The first | |
| 1291 | PCRE_ERROR_NULL (-2) | element of a pair is set to the offset of the first character in a sub- |
| 1292 | string, and the second is set to the offset of the first character | |
| 1293 | Either code or subject was passed as NULL, or ovector was | after the end of a substring. The first pair, ovector[0] and ovec- |
| 1294 | NULL and ovecsize was not zero. | tor[1], identify the portion of the subject string matched by the |
| 1295 | entire pattern. The next pair is used for the first capturing subpat- | |
| 1296 | PCRE_ERROR_BADOPTION (-3) | tern, and so on. The value returned by pcre_exec() is the number of |
| 1297 | pairs that have been set. If there are no capturing subpatterns, the | |
| 1298 | An unrecognized bit was set in the options argument. | return value from a successful match is 1, indicating that just the |
| 1299 | first pair of offsets has been set. | |
| 1300 | PCRE_ERROR_BADMAGIC (-4) | |
| 1301 | Some convenience functions are provided for extracting the captured | |
| 1302 | PCRE stores a 4-byte "magic number" at the start of the com- | substrings as separate strings. These are described in the following |
| 1303 | piled code, to catch the case when it is passed a junk | section. |
| 1304 | pointer. This is the error it gives when the magic number | |
| 1305 | isn't present. | It is possible for an capturing subpattern number n+1 to match some |
| 1306 | part of the subject when subpattern n has not been used at all. For | |
| 1307 | PCRE_ERROR_UNKNOWN_NODE (-5) | example, if the string "abc" is matched against the pattern (a|(z))(bc) |
| 1308 | subpatterns 1 and 3 are matched, but 2 is not. When this happens, both | |
| 1309 | While running the pattern match, an unknown item was encoun- | offset values corresponding to the unused subpattern are set to -1. |
| 1310 | tered in the compiled pattern. This error could be caused by | |
| 1311 | a bug in PCRE or by overwriting of the compiled pattern. | If a capturing subpattern is matched repeatedly, it is the last portion |
| 1312 | of the string that it matched that is returned. | |
| 1313 | PCRE_ERROR_NOMEMORY (-6) | |
| 1314 | If the vector is too small to hold all the captured substring offsets, | |
| 1315 | If a pattern contains back references, but the ovector that | it is used as far as possible (up to two-thirds of its length), and the |
| 1316 | is passed to pcre_exec() is not big enough to remember the | function returns a value of zero. In particular, if the substring off- |
| 1317 | referenced substrings, PCRE gets a block of memory at the | sets are not of interest, pcre_exec() may be called with ovector passed |
| 1318 | start of matching to use for this purpose. If the call via | as NULL and ovecsize as zero. However, if the pattern contains back |
| 1319 | pcre_malloc() fails, this error is given. The memory is | references and the ovector is not big enough to remember the related |
| 1320 | freed at the end of matching. | substrings, PCRE has to get additional memory for use during matching. |
| 1321 | Thus it is usually advisable to supply an ovector. | |
| 1322 | PCRE_ERROR_NOSUBSTRING (-7) | |
| 1323 | Note that pcre_info() can be used to find out how many capturing sub- | |
| 1324 | This error is used by the pcre_copy_substring(), | patterns there are in a compiled pattern. The smallest size for ovector |
| 1325 | pcre_get_substring(), and pcre_get_substring_list() func- | that will allow for n captured substrings, in addition to the offsets |
| 1326 | tions (see below). It is never returned by pcre_exec(). | of the substring matched by the whole pattern, is (n+1)*3. |
| 1327 | ||
| 1328 | PCRE_ERROR_MATCHLIMIT (-8) | Return values from pcre_exec() |
| 1329 | ||
| 1330 | The recursion and backtracking limit, as specified by the | If pcre_exec() fails, it returns a negative number. The following are |
| 1331 | match_limit field in a pcre_extra structure (or defaulted) | defined in the header file: |
| 1332 | was reached. See the description above. | |
| 1333 | PCRE_ERROR_NOMATCH (-1) | |
| 1334 | PCRE_ERROR_CALLOUT (-9) | |
| 1335 | The subject string did not match the pattern. | |
| 1336 | This error is never generated by pcre_exec() itself. It is | |
| 1337 | provided for use by callout functions that want to yield a | PCRE_ERROR_NULL (-2) |
| 1338 | distinctive error code. See the pcrecallout documentation | |
| 1339 | for details. | Either code or subject was passed as NULL, or ovector was NULL and |
| 1340 | ovecsize was not zero. | |
| 1341 | ||
| 1342 | PCRE_ERROR_BADOPTION (-3) | |
| 1343 | ||
| 1344 | An unrecognized bit was set in the options argument. | |
| 1345 | ||
| 1346 | PCRE_ERROR_BADMAGIC (-4) | |
| 1347 | ||
| 1348 | PCRE stores a 4-byte "magic number" at the start of the compiled code, | |
| 1349 | to catch the case when it is passed a junk pointer and to detect when a | |
| 1350 | pattern that was compiled in an environment of one endianness is run in | |
| 1351 | an environment with the other endianness. This is the error that PCRE | |
| 1352 | gives when the magic number is not present. | |
| 1353 | ||
| 1354 | PCRE_ERROR_UNKNOWN_NODE (-5) | |
| 1355 | ||
| 1356 | While running the pattern match, an unknown item was encountered in the | |
| 1357 | compiled pattern. This error could be caused by a bug in PCRE or by | |
| 1358 | overwriting of the compiled pattern. | |
| 1359 | ||
| 1360 | PCRE_ERROR_NOMEMORY (-6) | |
| 1361 | ||
| 1362 | If a pattern contains back references, but the ovector that is passed | |
| 1363 | to pcre_exec() is not big enough to remember the referenced substrings, | |
| 1364 | PCRE gets a block of memory at the start of matching to use for this | |
| 1365 | purpose. If the call via pcre_malloc() fails, this error is given. The | |
| 1366 | memory is automatically freed at the end of matching. | |
| 1367 | ||
| 1368 | PCRE_ERROR_NOSUBSTRING (-7) | |
| 1369 | ||
| 1370 | This error is used by the pcre_copy_substring(), pcre_get_substring(), | |
| 1371 | and pcre_get_substring_list() functions (see below). It is never | |
| 1372 | returned by pcre_exec(). | |
| 1373 | ||
| 1374 | PCRE_ERROR_MATCHLIMIT (-8) | |
| 1375 | ||
| 1376 | The recursion and backtracking limit, as specified by the match_limit | |
| 1377 | field in a pcre_extra structure (or defaulted) was reached. See the | |
| 1378 | description above. | |
| 1379 | ||
| 1380 | PCRE_ERROR_CALLOUT (-9) | |
| 1381 | ||
| 1382 | This error is never generated by pcre_exec() itself. It is provided for | |
| 1383 | use by callout functions that want to yield a distinctive error code. | |
| 1384 | See the pcrecallout documentation for details. | |
| 1385 | ||
| 1386 | PCRE_ERROR_BADUTF8 (-10) | |
| 1387 | ||
| 1388 | A string that contains an invalid UTF-8 byte sequence was passed as a | |
| 1389 | subject. | |
| 1390 | ||
| 1391 | PCRE_ERROR_BADUTF8_OFFSET (-11) | |
| 1392 | ||
| 1393 | The UTF-8 byte sequence that was passed as a subject was valid, but the | |
| 1394 | value of startoffset did not point to the beginning of a UTF-8 charac- | |
| 1395 | ter. | |
| 1396 | ||
| 1397 | PCRE_ERROR_PARTIAL (-12) | |
| 1398 | ||
| 1399 | The subject string did not match, but it did match partially. See the | |
| 1400 | pcrepartial documentation for details of partial matching. | |
| 1401 | ||
| 1402 | PCRE_ERROR_BAD_PARTIAL (-13) | |
| 1403 | ||
| 1404 | The PCRE_PARTIAL option was used with a compiled pattern containing | |
| 1405 | items that are not supported for partial matching. See the pcrepartial | |
| 1406 | documentation for details of partial matching. | |
| 1407 | ||
| 1408 | PCRE_ERROR_INTERNAL (-14) | |
| 1409 | ||
| 1410 | An unexpected internal error has occurred. This error could be caused | |
| 1411 | by a bug in PCRE or by overwriting of the compiled pattern. | |
| 1412 | ||
| 1413 | PCRE_ERROR_BADCOUNT (-15) | |
| 1414 | ||
| 1415 | This error is given if the value of the ovecsize argument is negative. | |
| 1416 | ||
| 1417 | ||
| 1418 | EXTRACTING CAPTURED SUBSTRINGS BY NUMBER | EXTRACTING CAPTURED SUBSTRINGS BY NUMBER |
| 1419 | ||
| 1420 | int pcre_copy_substring(const char *subject, int *ovector, | int pcre_copy_substring(const char *subject, int *ovector, |
| 1421 | int stringcount, int stringnumber, char *buffer, | int stringcount, int stringnumber, char *buffer, |
| 1422 | int buffersize); | int buffersize); |
| 1423 | ||
| 1424 | int pcre_get_substring(const char *subject, int *ovector, | int pcre_get_substring(const char *subject, int *ovector, |
| 1425 | int stringcount, int stringnumber, | int stringcount, int stringnumber, |
| 1426 | const char **stringptr); | const char **stringptr); |
| 1427 | ||
| 1428 | int pcre_get_substring_list(const char *subject, | int pcre_get_substring_list(const char *subject, |
| 1429 | int *ovector, int stringcount, const char ***listptr); | int *ovector, int stringcount, const char ***listptr); |
| 1430 | ||
| 1431 | Captured substrings can be accessed directly by using the | Captured substrings can be accessed directly by using the offsets |
| 1432 | offsets returned by pcre_exec() in ovector. For convenience, | returned by pcre_exec() in ovector. For convenience, the functions |
| 1433 | the functions pcre_copy_substring(), pcre_get_substring(), | pcre_copy_substring(), pcre_get_substring(), and pcre_get_sub- |
| 1434 | and pcre_get_substring_list() are provided for extracting | string_list() are provided for extracting captured substrings as new, |
| 1435 | captured substrings as new, separate, zero-terminated | separate, zero-terminated strings. These functions identify substrings |
| 1436 | strings. These functions identify substrings by number. The | by number. The next section describes functions for extracting named |
| 1437 | next section describes functions for extracting named sub- | substrings. A substring that contains a binary zero is correctly |
| 1438 | strings. A substring that contains a binary zero is | extracted and has a further zero added on the end, but the result is |
| 1439 | correctly extracted and has a further zero added on the end, | not, of course, a C string. |
| 1440 | but the result is not, of course, a C string. | |
| 1441 | The first three arguments are the same for all three of these func- | |
| 1442 | The first three arguments are the same for all three of | tions: subject is the subject string that has just been successfully |
| 1443 | these functions: subject is the subject string which has | matched, ovector is a pointer to the vector of integer offsets that was |
| 1444 | just been successfully matched, ovector is a pointer to the | passed to pcre_exec(), and stringcount is the number of substrings that |
| 1445 | vector of integer offsets that was passed to pcre_exec(), | were captured by the match, including the substring that matched the |
| 1446 | and stringcount is the number of substrings that were cap- | entire regular expression. This is the value returned by pcre_exec() if |
| 1447 | tured by the match, including the substring that matched the | it is greater than zero. If pcre_exec() returned zero, indicating that |
| 1448 | entire regular expression. This is the value returned by | it ran out of space in ovector, the value passed as stringcount should |
| 1449 | pcre_exec if it is greater than zero. If pcre_exec() | be the number of elements in the vector divided by three. |
| 1450 | returned zero, indicating that it ran out of space in ovec- | |
| 1451 | tor, the value passed as stringcount should be the size of | The functions pcre_copy_substring() and pcre_get_substring() extract a |
| 1452 | the vector divided by three. | single substring, whose number is given as stringnumber. A value of |
| 1453 | zero extracts the substring that matched the entire pattern, whereas | |
| 1454 | The functions pcre_copy_substring() and pcre_get_substring() | higher values extract the captured substrings. For pcre_copy_sub- |
| 1455 | extract a single substring, whose number is given as string- | string(), the string is placed in buffer, whose length is given by |
| 1456 | number. A value of zero extracts the substring that matched | buffersize, while for pcre_get_substring() a new block of memory is |
| 1457 | the entire pattern, while higher values extract the captured | obtained via pcre_malloc, and its address is returned via stringptr. |
| 1458 | substrings. For pcre_copy_substring(), the string is placed | The yield of the function is the length of the string, not including |
| 1459 | in buffer, whose length is given by buffersize, while for | the terminating zero, or one of |
| 1460 | pcre_get_substring() a new block of memory is obtained via | |
| 1461 | pcre_malloc, and its address is returned via stringptr. The | PCRE_ERROR_NOMEMORY (-6) |
| 1462 | yield of the function is the length of the string, not | |
| 1463 | including the terminating zero, or one of | The buffer was too small for pcre_copy_substring(), or the attempt to |
| 1464 | get memory failed for pcre_get_substring(). | |
| 1465 | PCRE_ERROR_NOMEMORY (-6) | |
| 1466 | PCRE_ERROR_NOSUBSTRING (-7) | |
| 1467 | The buffer was too small for pcre_copy_substring(), or the | |
| 1468 | attempt to get memory failed for pcre_get_substring(). | There is no substring whose number is stringnumber. |
| 1469 | ||
| 1470 | PCRE_ERROR_NOSUBSTRING (-7) | The pcre_get_substring_list() function extracts all available sub- |
| 1471 | strings and builds a list of pointers to them. All this is done in a | |
| 1472 | There is no substring whose number is stringnumber. | single block of memory that is obtained via pcre_malloc. The address of |
| 1473 | the memory block is returned via listptr, which is also the start of | |
| 1474 | The pcre_get_substring_list() function extracts all avail- | the list of string pointers. The end of the list is marked by a NULL |
| 1475 | able substrings and builds a list of pointers to them. All | pointer. The yield of the function is zero if all went well, or |
| 1476 | this is done in a single block of memory which is obtained | |
| 1477 | via pcre_malloc. The address of the memory block is returned | PCRE_ERROR_NOMEMORY (-6) |
| 1478 | via listptr, which is also the start of the list of string | |
| 1479 | pointers. The end of the list is marked by a NULL pointer. | if the attempt to get the memory block failed. |
| 1480 | The yield of the function is zero if all went well, or | |
| 1481 | When any of these functions encounter a substring that is unset, which | |
| 1482 | PCRE_ERROR_NOMEMORY (-6) | can happen when capturing subpattern number n+1 matches some part of |
| 1483 | the subject, but subpattern n has not been used at all, they return an | |
| 1484 | if the attempt to get the memory block failed. | empty string. This can be distinguished from a genuine zero-length sub- |
| 1485 | string by inspecting the appropriate offset in ovector, which is nega- | |
| 1486 | When any of these functions encounter a substring that is | tive for unset substrings. |
| 1487 | unset, which can happen when capturing subpattern number n+1 | |
| 1488 | matches some part of the subject, but subpattern n has not | The two convenience functions pcre_free_substring() and pcre_free_sub- |
| 1489 | been used at all, they return an empty string. This can be | string_list() can be used to free the memory returned by a previous |
| 1490 | distinguished from a genuine zero-length substring by | call of pcre_get_substring() or pcre_get_substring_list(), respec- |
| 1491 | inspecting the appropriate offset in ovector, which is nega- | tively. They do nothing more than call the function pointed to by |
| 1492 | tive for unset substrings. | pcre_free, which of course could be called directly from a C program. |
| 1493 | However, PCRE is used in some situations where it is linked via a spe- | |
| 1494 | The two convenience functions pcre_free_substring() and | cial interface to another programming language which cannot use |
| 1495 | pcre_free_substring_list() can be used to free the memory | pcre_free directly; it is for these cases that the functions are |
| 1496 | returned by a previous call of pcre_get_substring() or | provided. |
| pcre_get_substring_list(), respectively. They do nothing | ||
| more than call the function pointed to by pcre_free, which | ||
| of course could be called directly from a C program. How- | ||
| ever, PCRE is used in some situations where it is linked via | ||
| a special interface to another programming language which | ||
| cannot use pcre_free directly; it is for these cases that | ||
| the functions are provided. | ||
| 1497 | ||
| 1498 | ||
| 1499 | EXTRACTING CAPTURED SUBSTRINGS BY NAME | EXTRACTING CAPTURED SUBSTRINGS BY NAME |
| 1500 | ||
| 1501 | int pcre_copy_named_substring(const pcre *code, | int pcre_get_stringnumber(const pcre *code, |
| 1502 | const char *subject, int *ovector, | const char *name); |
| 1503 | int stringcount, const char *stringname, | |
| 1504 | char *buffer, int buffersize); | int pcre_copy_named_substring(const pcre *code, |
| 1505 | const char *subject, int *ovector, | |
| 1506 | int pcre_get_stringnumber(const pcre *code, | int stringcount, const char *stringname, |
| 1507 | const char *name); | char *buffer, int buffersize); |
| 1508 | ||
| 1509 | int pcre_get_named_substring(const pcre *code, | int pcre_get_named_substring(const pcre *code, |
| 1510 | const char *subject, int *ovector, | const char *subject, int *ovector, |
| 1511 | int stringcount, const char *stringname, | int stringcount, const char *stringname, |
| 1512 | const char **stringptr); | const char **stringptr); |
| 1513 | ||
| 1514 | To extract a substring by name, you first have to find asso- | To extract a substring by name, you first have to find associated num- |
| 1515 | ciated number. This can be done by calling | ber. For example, for this pattern |
| 1516 | pcre_get_stringnumber(). The first argument is the compiled | |
| 1517 | pattern, and the second is the name. For example, for this | (a+)b(?<xxx>\d+)... |
| 1518 | pattern | |
| 1519 | the number of the subpattern called "xxx" is 2. You can find the number | |
| 1520 | ab(?<xxx>\d+)... | from the name by calling pcre_get_stringnumber(). The first argument is |
| 1521 | the compiled pattern, and the second is the name. The yield of the | |
| 1522 | the number of the subpattern called "xxx" is 1. Given the | function is the subpattern number, or PCRE_ERROR_NOSUBSTRING (-7) if |
| 1523 | number, you can then extract the substring directly, or use | there is no subpattern of that name. |
| 1524 | one of the functions described in the previous section. For | |
| 1525 | convenience, there are also two functions that do the whole | Given the number, you can extract the substring directly, or use one of |
| 1526 | job. | the functions described in the previous section. For convenience, there |
| 1527 | are also two functions that do the whole job. | |
| 1528 | Most of the arguments of pcre_copy_named_substring() and | |
| 1529 | pcre_get_named_substring() are the same as those for the | Most of the arguments of pcre_copy_named_substring() and |
| 1530 | functions that extract by number, and so are not re- | pcre_get_named_substring() are the same as those for the similarly |
| 1531 | described here. There are just two differences. | named functions that extract by number. As these are described in the |
| 1532 | previous section, they are not re-described here. There are just two | |
| 1533 | First, instead of a substring number, a substring name is | differences: |
| 1534 | given. Second, there is an extra argument, given at the | |
| 1535 | start, which is a pointer to the compiled pattern. This is | First, instead of a substring number, a substring name is given. Sec- |
| 1536 | needed in order to gain access to the name-to-number trans- | ond, there is an extra argument, given at the start, which is a pointer |
| 1537 | lation table. | to the compiled pattern. This is needed in order to gain access to the |
| 1538 | name-to-number translation table. | |
| 1539 | These functions call pcre_get_stringnumber(), and if it | |
| 1540 | succeeds, they then call pcre_copy_substring() or | These functions call pcre_get_stringnumber(), and if it succeeds, they |
| 1541 | pcre_get_substring(), as appropriate. | then call pcre_copy_substring() or pcre_get_substring(), as appropri- |
| 1542 | ate. | |
| 1543 | ||
| 1544 | Last updated: 03 February 2003 | Last updated: 09 September 2004 |
| 1545 | Copyright (c) 1997-2003 University of Cambridge. | Copyright (c) 1997-2004 University of Cambridge. |
| 1546 | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| 1547 | ||
| 1548 | NAME | PCRE(3) PCRE(3) |
| PCRE - Perl-compatible regular expressions | ||
| 1549 | ||
| 1550 | ||
| PCRE CALLOUTS | ||
| 1551 | ||
| 1552 | int (*pcre_callout)(pcre_callout_block *); | NAME |
| 1553 | PCRE - Perl-compatible regular expressions | |
| 1554 | ||
| 1555 | PCRE CALLOUTS | |
| 1556 | ||
| 1557 | PCRE provides a feature called "callout", which is a means | int (*pcre_callout)(pcre_callout_block *); |
| of temporarily passing control to the caller of PCRE in the | ||
| middle of pattern matching. The caller of PCRE provides an | ||
| external function by putting its entry point in the global | ||
| variable pcre_callout. By default, this variable contains | ||
| NULL, which disables all calling out. | ||
| Within a regular expression, (?C) indicates the points at | ||
| which the external function is to be called. Different cal- | ||
| lout points can be identified by putting a number less than | ||
| 256 after the letter C. The default value is zero. For | ||
| example, this pattern has two callout points: | ||
| (?C1)9abc(?C2)def | ||
| During matching, when PCRE reaches a callout point (and | ||
| pcre_callout is set), the external function is called. Its | ||
| only argument is a pointer to a pcre_callout block. This | ||
| contains the following variables: | ||
| int version; | ||
| int callout_number; | ||
| int *offset_vector; | ||
| const char *subject; | ||
| int subject_length; | ||
| int start_match; | ||
| int current_position; | ||
| int capture_top; | ||
| int capture_last; | ||
| void *callout_data; | ||
| The version field is an integer containing the version | ||
| number of the block format. The current version is zero. The | ||
| version number may change 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 compiled into the pattern (that is, the number after ?C). | ||
| The offset_vector field is a pointer to the vector of | ||
| offsets that was passed by the caller to pcre_exec(). The | ||
| contents can be inspected in order to extract substrings | ||
| that have been matched so far, in the same way as for | ||
| extracting substrings after a match has completed. | ||
| The subject and subject_length fields contain copies the | ||
| values that were passed to pcre_exec(). | ||
| The start_match field contains the offset within the subject | ||
| at which the current match attempt started. If the pattern | ||
| is not anchored, the callout function may be called several | ||
| times for different starting points. | ||
| The current_position field contains the offset within the | ||
| subject of the current match pointer. | ||
| The capture_top field contains the number of the highest | ||
| captured substring so far. | ||
| The capture_last field contains the number of the most | ||
| recently captured substring. | ||
| The callout_data field contains a value that is passed to | ||
| pcre_exec() by the caller specifically so that it can be | ||
| passed back in callouts. It is passed in the pcre_callout | ||
| field of the pcre_extra data structure. If no such data was | ||
| passed, the value of callout_data in a pcre_callout block is | ||
| NULL. There is a description of the pcre_extra structure in | ||
| the pcreapi documentation. | ||
| 1558 | ||
| 1559 | PCRE provides a feature called "callout", which is a means of temporar- | |
| 1560 | ily passing control to the caller of PCRE in the middle of pattern | |
| 1561 | matching. The caller of PCRE provides an external function by putting | |
| 1562 | its entry point in the global variable pcre_callout. By default, this | |
| 1563 | variable contains NULL, which disables all calling out. | |
| 1564 | ||
| 1565 | Within a regular expression, (?C) indicates the points at which the | |
| 1566 | external function is to be called. Different callout points can be | |
| 1567 | identified by putting a number less than 256 after the letter C. The | |
| 1568 | default value is zero. For example, this pattern has two callout | |
| 1569 | points: | |
| 1570 | ||
| 1571 | (?C1)eabc(?C2)def | |
| 1572 | ||
| 1573 | If the PCRE_AUTO_CALLOUT option bit is set when pcre_compile() is | |
| 1574 | called, PCRE automatically inserts callouts, all with number 255, | |
| 1575 | before each item in the pattern. For example, if PCRE_AUTO_CALLOUT is | |
| 1576 | used with the pattern | |
| 1577 | ||
| 1578 | A(\d{2}|--) | |
| 1579 | ||
| 1580 | it is processed as if it were | |
| 1581 | ||
| 1582 | (?C255)A(?C255)((?C255)\d{2}(?C255)|(?C255)-(?C255)-(?C255))(?C255) | |
| 1583 | ||
| 1584 | Notice that there is a callout before and after each parenthesis and | |
| 1585 | alternation bar. Automatic callouts can be used for tracking the | |
| 1586 | progress of pattern matching. The pcretest command has an option that | |
| 1587 | sets automatic callouts; when it is used, the output indicates how the | |
| 1588 | pattern is matched. This is useful information when you are trying to | |
| 1589 | optimize the performance of a particular pattern. | |
| 1590 | ||
| 1591 | ||
| 1592 | MISSING CALLOUTS | |
| 1593 | ||
| 1594 | You should be aware that, because of optimizations in the way PCRE | |
| 1595 | matches patterns, callouts sometimes do not happen. For example, if the | |
| 1596 | pattern is | |
| 1597 | ||
| 1598 | ab(?C4)cd | |
| 1599 | ||
| 1600 | PCRE knows that any matching string must contain the letter "d". If the | |
| 1601 | subject string is "abyz", the lack of "d" means that matching doesn't | |
| 1602 | ever start, and the callout is never reached. However, with "abyd", | |
| 1603 | though the result is still no match, the callout is obeyed. | |
| 1604 | ||
| 1605 | ||
| 1606 | THE CALLOUT INTERFACE | |
| 1607 | ||
| 1608 | During matching, when PCRE reaches a callout point, the external func- | |
| 1609 | tion defined by pcre_callout is called (if it is set). The only argu- | |
| 1610 | ment is a pointer to a pcre_callout block. This structure contains the | |
| 1611 | following fields: | |
| 1612 | ||
| 1613 | int version; | |
| 1614 | int callout_number; | |
| 1615 | int *offset_vector; | |
| 1616 | const char *subject; | |
| 1617 | int subject_length; | |
| 1618 | int start_match; | |
| 1619 | int current_position; | |
| 1620 | int capture_top; | |
| 1621 | int capture_last; | |
| 1622 | void *callout_data; | |
| 1623 | int pattern_position; | |
| 1624 | int next_item_length; | |
| 1625 | ||
| 1626 | The version field is an integer containing the version number of the | |
| 1627 | block format. The initial version was 0; the current version is 1. The | |
| 1628 | version number will change again in future if additional fields are | |
| 1629 | added, but the intention is never to remove any of the existing fields. | |
| 1630 | ||
| 1631 | The callout_number field contains the number of the callout, as com- | |
| 1632 | piled into the pattern (that is, the number after ?C for manual call- | |
| 1633 | outs, and 255 for automatically generated callouts). | |
| 1634 | ||
| 1635 | The offset_vector field is a pointer to the vector of offsets that was | |
| 1636 | passed by the caller to pcre_exec(). The contents can be inspected in | |
| 1637 | order to extract substrings that have been matched so far, in the same | |
| 1638 | way as for extracting substrings after a match has completed. | |
| 1639 | ||
| 1640 | The subject and subject_length fields contain copies of the values that | |
| 1641 | were passed to pcre_exec(). | |
| 1642 | ||
| 1643 | The start_match field contains the offset within the subject at which | |
| 1644 | the current match attempt started. If the pattern is not anchored, the | |
| 1645 | callout function may be called several times from the same point in the | |
| 1646 | pattern for different starting points in the subject. | |
| 1647 | ||
| 1648 | The current_position field contains the offset within the subject of | |
| 1649 | the current match pointer. | |
| 1650 | ||
| 1651 | The capture_top field contains one more than the number of the highest | |
| 1652 | numbered captured substring so far. If no substrings have been cap- | |
| 1653 | tured, the value of capture_top is one. | |
| 1654 | ||
| 1655 | The capture_last field contains the number of the most recently cap- | |
| 1656 | tured substring. If no substrings have been captured, its value is -1. | |
| 1657 | ||
| 1658 | The callout_data field contains a value that is passed to pcre_exec() | |
| 1659 | by the caller specifically so that it can be passed back in callouts. | |
| 1660 | It is passed in the pcre_callout field of the pcre_extra data struc- | |
| 1661 | ture. If no such data was passed, the value of callout_data in a | |
| 1662 | pcre_callout block is NULL. There is a description of the pcre_extra | |
| 1663 | structure in the pcreapi documentation. | |
| 1664 | ||
| 1665 | The pattern_position field is present from version 1 of the pcre_call- | |
| 1666 | out structure. It contains the offset to the next item to be matched in | |
| 1667 | the pattern string. | |
| 1668 | ||
| 1669 | The next_item_length field is present from version 1 of the pcre_call- | |
| 1670 | out structure. It contains the length of the next item to be matched in | |
| 1671 | the pattern string. When the callout immediately precedes an alterna- | |
| 1672 | tion bar, a closing parenthesis, or the end of the pattern, the length | |
| 1673 | is zero. When the callout precedes an opening parenthesis, the length | |
| 1674 | is that of the entire subpattern. | |
| 1675 | ||
| 1676 | The pattern_position and next_item_length fields are intended to help | |
| 1677 | in distinguishing between different automatic callouts, which all have | |
| 1678 | the same callout number. However, they are set for all callouts. | |
| 1679 | ||
| 1680 | ||
| 1681 | RETURN VALUES | RETURN VALUES |
| 1682 | ||
| 1683 | The callout function returns an integer. If the value is | The external callout function returns an integer to PCRE. If the value |
| 1684 | zero, matching proceeds as normal. If the value is greater | is zero, matching proceeds as normal. If the value is greater than |
| 1685 | than zero, matching fails at the current point, but back- | zero, matching fails at the current point, but backtracking to test |
| 1686 | tracking to test other possibilities goes ahead, just as if | other matching possibilities goes ahead, just as if a lookahead asser- |
| 1687 | a lookahead assertion had failed. If the value is less than | tion had failed. If the value is less than zero, the match is aban- |
| 1688 | zero, the match is abandoned, and pcre_exec() returns the | doned, and pcre_exec() returns the negative value. |
| 1689 | value. | |
| 1690 | Negative values should normally be chosen from the set of | |
| 1691 | Negative values should normally be chosen from the set of | PCRE_ERROR_xxx values. In particular, PCRE_ERROR_NOMATCH forces a stan- |
| 1692 | PCRE_ERROR_xxx values. In particular, PCRE_ERROR_NOMATCH | dard "no match" failure. The error number PCRE_ERROR_CALLOUT is |
| 1693 | forces a standard "no match" failure. The error number | reserved for use by callout functions; it will never be used by PCRE |
| 1694 | PCRE_ERROR_CALLOUT is reserved for use by callout functions; | itself. |
| it will never be used by PCRE itself. | ||
| 1695 | ||
| 1696 | Last updated: 21 January 2003 | Last updated: 09 September 2004 |
| 1697 | Copyright (c) 1997-2003 University of Cambridge. | Copyright (c) 1997-2004 University of Cambridge. |
| 1698 | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| 1699 | ||
| 1700 | PCRE(3) PCRE(3) | |
| 1701 | ||
| 1702 | ||
| 1703 | ||
| 1704 | NAME | NAME |
| 1705 | PCRE - Perl-compatible regular expressions | PCRE - Perl-compatible regular expressions |
| 1706 | ||
| 1707 | DIFFERENCES BETWEEN PCRE AND PERL | |
| 1708 | ||
| 1709 | This document describes the differences in the ways that PCRE and Perl | |
| 1710 | handle regular expressions. The differences described here are with | |
| 1711 | respect to Perl 5.8. | |
| 1712 | ||
| 1713 | 1. PCRE does not have full UTF-8 support. Details of what it does have | |
| 1714 | are given in the section on UTF-8 support in the main pcre page. | |
| 1715 | ||
| 1716 | 2. PCRE does not allow repeat quantifiers on lookahead assertions. Perl | |
| 1717 | permits them, but they do not mean what you might think. For example, | |
| 1718 | (?!a){3} does not assert that the next three characters are not "a". It | |
| 1719 | just asserts that the next character is not "a" three times. | |
| 1720 | ||
| 1721 | 3. Capturing subpatterns that occur inside negative lookahead asser- | |
| 1722 | tions are counted, but their entries in the offsets vector are never | |
| 1723 | set. Perl sets its numerical variables from any such patterns that are | |
| 1724 | matched before the assertion fails to match something (thereby succeed- | |
| 1725 | ing), but only if the negative lookahead assertion contains just one | |
| 1726 | branch. | |
| 1727 | ||
| 1728 | 4. Though binary zero characters are supported in the subject string, | |
| 1729 | they are not allowed in a pattern string because it is passed as a nor- | |
| 1730 | mal C string, terminated by zero. The escape sequence \0 can be used in | |
| 1731 | the pattern to represent a binary zero. | |
| 1732 | ||
| 1733 | 5. The following Perl escape sequences are not supported: \l, \u, \L, | |
| 1734 | \U, and \N. In fact these are implemented by Perl's general string-han- | |
| 1735 | dling and are not part of its pattern matching engine. If any of these | |
| 1736 | are encountered by PCRE, an error is generated. | |
| 1737 | ||
| 1738 | 6. The Perl escape sequences \p, \P, and \X are supported only if PCRE | |
| 1739 | is built with Unicode character property support. The properties that | |
| 1740 | can be tested with \p and \P are limited to the general category prop- | |
| 1741 | erties such as Lu and Nd. | |
| 1742 | ||
| 1743 | 7. PCRE does support the \Q...\E escape for quoting substrings. Charac- | |
| 1744 | ters in between are treated as literals. This is slightly different | |
| 1745 | from Perl in that $ and @ are also handled as literals inside the | |
| 1746 | quotes. In Perl, they cause variable interpolation (but of course PCRE | |
| 1747 | does not have variables). Note the following examples: | |
| 1748 | ||
| 1749 | Pattern PCRE matches Perl matches | |
| 1750 | ||
| 1751 | \Qabc$xyz\E abc$xyz abc followed by the | |
| 1752 | contents of $xyz | |
| 1753 | \Qabc\$xyz\E abc\$xyz abc\$xyz | |
| 1754 | \Qabc\E\$\Qxyz\E abc$xyz abc$xyz | |
| 1755 | ||
| 1756 | The \Q...\E sequence is recognized both inside and outside character | |
| 1757 | classes. | |
| 1758 | ||
| 1759 | 8. Fairly obviously, PCRE does not support the (?{code}) and (?p{code}) | |
| 1760 | constructions. However, there is support for recursive patterns using | |
| 1761 | the non-Perl items (?R), (?number), and (?P>name). Also, the PCRE | |
| 1762 | "callout" feature allows an external function to be called during pat- | |
| 1763 | tern matching. See the pcrecallout documentation for details. | |
| 1764 | ||
| 1765 | 9. There are some differences that are concerned with the settings of | |
| 1766 | captured strings when part of a pattern is repeated. For example, | |
| 1767 | matching "aba" against the pattern /^(a(b)?)+$/ in Perl leaves $2 | |
| 1768 | unset, but in PCRE it is set to "b". | |
| 1769 | ||
| 1770 | 10. PCRE provides some extensions to the Perl regular expression facil- | |
| 1771 | ities: | |
| 1772 | ||
| 1773 | (a) Although lookbehind assertions must match fixed length strings, | |
| 1774 | each alternative branch of a lookbehind assertion can match a different | |
| 1775 | length of string. Perl requires them all to have the same length. | |
| 1776 | ||
| 1777 | (b) If PCRE_DOLLAR_ENDONLY is set and PCRE_MULTILINE is not set, the $ | |
| 1778 | meta-character matches only at the very end of the string. | |
| 1779 | ||
| 1780 | (c) If PCRE_EXTRA is set, a backslash followed by a letter with no spe- | |
| 1781 | cial meaning is faulted. | |
| 1782 | ||
| 1783 | (d) If PCRE_UNGREEDY is set, the greediness of the repetition quanti- | |
| 1784 | fiers is inverted, that is, by default they are not greedy, but if fol- | |
| 1785 | lowed by a question mark they are. | |
| 1786 | ||
| 1787 | (e) PCRE_ANCHORED can be used at matching time to force a pattern to be | |
| 1788 | tried only at the first matching position in the subject string. | |
| 1789 | ||
| 1790 | (f) The PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, and PCRE_NO_AUTO_CAP- | |
| 1791 | TURE options for pcre_exec() have no Perl equivalents. | |
| 1792 | ||
| 1793 | DIFFERENCES FROM PERL | (g) The (?R), (?number), and (?P>name) constructs allows for recursive |
| 1794 | pattern matching (Perl can do this using the (?p{code}) construct, | |
| 1795 | which PCRE cannot support.) | |
| 1796 | ||
| 1797 | This document describes the differences in the ways that | (h) PCRE supports named capturing substrings, using the Python syntax. |
| PCRE and Perl handle regular expressions. The differences | ||
| described here are with respect to Perl 5.8. | ||
| 1. PCRE does not allow repeat quantifiers on lookahead | ||
| assertions. Perl permits them, but they do not mean what you | ||
| might think. For example, (?!a){3} does not assert that the | ||
| next three characters are not "a". It just asserts that the | ||
| next character is not "a" three times. | ||
| 2. Capturing subpatterns that occur inside negative looka- | ||
| head assertions are counted, but their entries in the | ||
| offsets vector are never set. Perl sets its numerical vari- | ||
| ables from any such patterns that are matched before the | ||
| assertion fails to match something (thereby succeeding), but | ||
| only if the negative lookahead assertion contains just one | ||
| branch. | ||
| 3. Though binary zero characters are supported in the sub- | ||
| ject string, they are not allowed in a pattern string | ||
| because it is passed as a normal C string, terminated by | ||
| zero. The escape sequence "\0" can be used in the pattern to | ||
| represent a binary zero. | ||
| 4. The following Perl escape sequences are not supported: | ||
| \l, \u, \L, \U, \P, \p, and \X. In fact these are imple- | ||
| mented by Perl's general string-handling and are not part of | ||
| its pattern matching engine. If any of these are encountered | ||
| by PCRE, an error is generated. | ||
| 5. PCRE does support the \Q...\E escape for quoting sub- | ||
| strings. Characters in between are treated as literals. This | ||
| is slightly different from Perl in that $ and @ are also | ||
| handled as literals inside the quotes. In Perl, they cause | ||
| variable interpolation (but of course PCRE does not have | ||
| variables). Note the following examples: | ||
| Pattern PCRE matches Perl matches | ||
| \Qabc$xyz\E abc$xyz abc followed by the | ||
| contents of $xyz | ||
| \Qabc\$xyz\E abc\$xyz abc\$xyz | ||
| \Qabc\E\$\Qxyz\E abc$xyz abc$xyz | ||
| In PCRE, the \Q...\E mechanism is not recognized inside a | ||
| character class. | ||
| 8. Fairly obviously, PCRE does not support the (?{code}) and | ||
| (?p{code}) constructions. However, there is some experimen- | ||
| tal support for recursive patterns using the non-Perl items | ||
| (?R), (?number) and (?P>name). Also, the PCRE "callout" | ||
| feature allows an external function to be called during pat- | ||
| tern matching. | ||
| 9. There are some differences that are concerned with the | ||
| settings of captured strings when part of a pattern is | ||
| repeated. For example, matching "aba" against the pattern | ||
| /^(a(b)?)+$/ in Perl leaves $2 unset, but in PCRE it is set | ||
| to "b". | ||
| 10. PCRE provides some extensions to the Perl regular | ||
| expression facilities: | ||
| (a) Although lookbehind assertions must match fixed length | ||
| strings, each alternative branch of a lookbehind assertion | ||
| can match a different length of string. Perl requires them | ||
| all to have the same length. | ||
| (b) If PCRE_DOLLAR_ENDONLY is set and PCRE_MULTILINE is not | ||
| set, the $ meta-character matches only at the very end of | ||
| the string. | ||
| (c) If PCRE_EXTRA is set, a backslash followed by a letter | ||
| with no special meaning is faulted. | ||
| (d) If PCRE_UNGREEDY is set, the greediness of the repeti- | ||
| tion quantifiers is inverted, that is, by default they are | ||
| not greedy, but if followed by a question mark they are. | ||
| (e) PCRE_ANCHORED can be used to force a pattern to be tried | ||
| only at the first matching position in the subject string. | ||
| (f) The PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, and | ||
| PCRE_NO_AUTO_CAPTURE options for pcre_exec() have no Perl | ||
| equivalents. | ||
| (g) The (?R), (?number), and (?P>name) constructs allows for | ||
| recursive pattern matching (Perl can do this using the | ||
| (?p{code}) construct, which PCRE cannot support.) | ||
| (h) PCRE supports named capturing substrings, using the | ||
| Python syntax. | ||
| (i) PCRE supports the possessive quantifier "++" syntax, | ||
| taken from Sun's Java package. | ||
| 1798 | ||
| 1799 | (j) The (R) condition, for testing recursion, is a PCRE | (i) PCRE supports the possessive quantifier "++" syntax, taken from |
| 1800 | extension. | Sun's Java package. |
| 1801 | ||
| 1802 | (k) The callout facility is PCRE-specific. | (j) The (R) condition, for testing recursion, is a PCRE extension. |
| 1803 | ||
| 1804 | Last updated: 03 February 2003 | (k) The callout facility is PCRE-specific. |
| 1805 | Copyright (c) 1997-2003 University of Cambridge. | |
| 1806 | (l) The partial matching facility is PCRE-specific. | |
| 1807 | ||
| 1808 | (m) Patterns compiled by PCRE can be saved and re-used at a later time, | |
| 1809 | even on different hosts that have the other endianness. | |
| 1810 | ||
| 1811 | Last updated: 09 September 2004 | |
| 1812 | Copyright (c) 1997-2004 University of Cambridge. | |
| 1813 | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| 1814 | ||
| 1815 | NAME | PCRE(3) PCRE(3) |
| 1816 | PCRE - Perl-compatible regular expressions | |
| 1817 | ||
| 1818 | ||
| 1819 | NAME | |
| 1820 | PCRE - Perl-compatible regular expressions | |
| 1821 | ||
| 1822 | PCRE REGULAR EXPRESSION DETAILS | PCRE REGULAR EXPRESSION DETAILS |
| 1823 | ||
| 1824 | The syntax and semantics of the regular expressions sup- | The syntax and semantics of the regular expressions supported by PCRE |
| 1825 | ported by PCRE are described below. Regular expressions are | are described below. Regular expressions are also described in the Perl |
| 1826 | also described in the Perl documentation and in a number of | documentation and in a number of books, some of which have copious |
| 1827 | other books, some of which have copious examples. Jeffrey | examples. Jeffrey Friedl's "Mastering Regular Expressions", published |
| 1828 | Friedl's "Mastering Regular Expressions", published by | by O'Reilly, covers regular expressions in great detail. This descrip- |
| 1829 | O'Reilly, covers them in great detail. The description here | tion of PCRE's regular expressions is intended as reference material. |
| 1830 | is intended as reference documentation. | |
| 1831 | The original operation of PCRE was on strings of one-byte characters. | |
| 1832 | The basic operation of PCRE is on strings of bytes. However, | However, there is now also support for UTF-8 character strings. To use |
| 1833 | there is also support for UTF-8 character strings. To use | this, you must build PCRE to include UTF-8 support, and then call |
| 1834 | this support you must build PCRE to include UTF-8 support, | pcre_compile() with the PCRE_UTF8 option. How this affects pattern |
| 1835 | and then call pcre_compile() with the PCRE_UTF8 option. How | matching is mentioned in several places below. There is also a summary |
| 1836 | this affects the pattern matching is mentioned in several | of UTF-8 features in the section on UTF-8 support in the main pcre |
| 1837 | places below. There is also a summary of UTF-8 features in | page. |
| 1838 | the section on UTF-8 support in the main pcre page. | |
| 1839 | A regular expression is a pattern that is matched against a subject | |
| 1840 | A regular expression is a pattern that is matched against a | string from left to right. Most characters stand for themselves in a |
| 1841 | subject string from left to right. Most characters stand for | pattern, and match the corresponding characters in the subject. As a |
| 1842 | themselves in a pattern, and match the corresponding charac- | trivial example, the pattern |
| 1843 | ters in the subject. As a trivial example, the pattern | |
| 1844 | The quick brown fox | |
| 1845 | The quick brown fox | |
| 1846 | matches a portion of a subject string that is identical to itself. The | |
| 1847 | matches a portion of a subject string that is identical to | power of regular expressions comes from the ability to include alterna- |
| 1848 | itself. The power of regular expressions comes from the | tives and repetitions in the pattern. These are encoded in the pattern |
| 1849 | ability to include alternatives and repetitions in the pat- | by the use of metacharacters, which do not stand for themselves but |
| 1850 | tern. These are encoded in the pattern by the use of meta- | instead are interpreted in some special way. |
| 1851 | characters, which do not stand for themselves but instead | |
| 1852 | are interpreted in some special way. | There are two different sets of metacharacters: those that are recog- |
| 1853 | nized anywhere in the pattern except within square brackets, and those | |
| 1854 | There are two different sets of meta-characters: those that | that are recognized in square brackets. Outside square brackets, the |
| 1855 | are recognized anywhere in the pattern except within square | metacharacters are as follows: |
| 1856 | brackets, and those that are recognized in square brackets. | |
| 1857 | Outside square brackets, the meta-characters are as follows: | \ general escape character with several uses |
| 1858 | ^ assert start of string (or line, in multiline mode) | |
| 1859 | \ general escape character with several uses | $ assert end of string (or line, in multiline mode) |
| 1860 | ^ assert start of string (or line, in multiline mode) | . match any character except newline (by default) |
| 1861 | $ assert end of string (or line, in multiline mode) | [ start character class definition |
| 1862 | . match any character except newline (by default) | | start of alternative branch |
| 1863 | [ start character class definition | ( start subpattern |
| 1864 | | start of alternative branch | ) end subpattern |
| 1865 | ( start subpattern | ? extends the meaning of ( |
| 1866 | ) end subpattern | also 0 or 1 quantifier |
| 1867 | ? extends the meaning of ( | also quantifier minimizer |
| 1868 | also 0 or 1 quantifier | * 0 or more quantifier |
| 1869 | also quantifier minimizer | + 1 or more quantifier |
| 1870 | * 0 or more quantifier | also "possessive quantifier" |
| 1871 | + 1 or more quantifier | { start min/max quantifier |
| 1872 | also "possessive quantifier" | |
| 1873 | { start min/max quantifier | Part of a pattern that is in square brackets is called a "character |
| 1874 | class". In a character class the only metacharacters are: | |
| 1875 | Part of a pattern that is in square brackets is called a | |
| 1876 | "character class". In a character class the only meta- | \ general escape character |
| 1877 | characters are: | ^ negate the class, but only if the first character |
| 1878 | - indicates character range | |
| 1879 | \ general escape character | [ POSIX character class (only if followed by POSIX |
| 1880 | ^ negate the class, but only if the first character | syntax) |
| 1881 | - indicates character range | ] terminates the character class |
| [ POSIX character class (only if followed by POSIX | ||
| syntax) | ||
| ] terminates the character class | ||
| 1882 | ||
| 1883 | The following sections describe the use of each of the | The following sections describe the use of each of the metacharacters. |
| meta-characters. | ||
| 1884 | ||
| 1885 | ||
| 1886 | BACKSLASH | BACKSLASH |
| 1887 | ||
| 1888 | The backslash character has several uses. Firstly, if it is | The backslash character has several uses. Firstly, if it is followed by |
| 1889 | followed by a non-alphameric character, it takes away any | a non-alphanumeric character, it takes away any special meaning that |
| 1890 | special meaning that character may have. This use of | character may have. This use of backslash as an escape character |
| 1891 | backslash as an escape character applies both inside and | applies both inside and outside character classes. |
| 1892 | outside character classes. | |
| 1893 | For example, if you want to match a * character, you write \* in the | |
| 1894 | For example, if you want to match a * character, you write | pattern. This escaping action applies whether or not the following |
| 1895 | \* in the pattern. This escaping action applies whether or | character would otherwise be interpreted as a metacharacter, so it is |
| 1896 | not the following character would otherwise be interpreted | always safe to precede a non-alphanumeric with backslash to specify |
| 1897 | as a meta-character, so it is always safe to precede a non- | that it stands for itself. In particular, if you want to match a back- |
| 1898 | alphameric with backslash to specify that it stands for | slash, you write \\. |
| 1899 | itself. In particular, if you want to match a backslash, you | |
| 1900 | write \\. | If a pattern is compiled with the PCRE_EXTENDED option, whitespace in |
| 1901 | the pattern (other than in a character class) and characters between a | |
| 1902 | If a pattern is compiled with the PCRE_EXTENDED option, whi- | # outside a character class and the next newline character are ignored. |
| 1903 | tespace in the pattern (other than in a character class) and | An escaping backslash can be used to include a whitespace or # charac- |
| 1904 | characters between a # outside a character class and the | ter as part of the pattern. |
| 1905 | next newline character are ignored. An escaping backslash | |
| 1906 | can be used to include a whitespace or # character as part | If you want to remove the special meaning from a sequence of charac- |
| 1907 | of the pattern. | ters, you can do so by putting them between \Q and \E. This is differ- |
| 1908 | ent from Perl in that $ and @ are handled as literals in \Q...\E | |
| 1909 | If you want to remove the special meaning from a sequence of | sequences in PCRE, whereas in Perl, $ and @ cause variable interpola- |
| 1910 | characters, you can do so by putting them between \Q and \E. | tion. Note the following examples: |
| 1911 | This is different from Perl in that $ and @ are handled as | |
| 1912 | literals in \Q...\E sequences in PCRE, whereas in Perl, $ | Pattern PCRE matches Perl matches |
| 1913 | and @ cause variable interpolation. Note the following exam- | |
| 1914 | ples: | \Qabc$xyz\E abc$xyz abc followed by the |
| 1915 | contents of $xyz | |
| 1916 | Pattern PCRE matches Perl matches | \Qabc\$xyz\E abc\$xyz abc\$xyz |
| 1917 | \Qabc\E\$\Qxyz\E abc$xyz abc$xyz | |
| 1918 | \Qabc$xyz\E abc$xyz abc followed by the | |
| 1919 | The \Q...\E sequence is recognized both inside and outside character | |
| 1920 | contents of $xyz | classes. |
| 1921 | \Qabc\$xyz\E abc\$xyz abc\$xyz | |
| 1922 | \Qabc\E\$\Qxyz\E abc$xyz abc$xyz | Non-printing characters |
| 1923 | ||
| 1924 | The \Q...\E sequence is recognized both inside and outside | A second use of backslash provides a way of encoding non-printing char- |
| 1925 | character classes. | acters in patterns in a visible manner. There is no restriction on the |
| 1926 | appearance of non-printing characters, apart from the binary zero that | |
| 1927 | A second use of backslash provides a way of encoding non- | terminates a pattern, but when a pattern is being prepared by text |
| 1928 | printing characters in patterns in a visible manner. There | editing, it is usually easier to use one of the following escape |
| 1929 | is no restriction on the appearance of non-printing charac- | sequences than the binary character it represents: |
| 1930 | ters, apart from the binary zero that terminates a pattern, | |
| 1931 | but when a pattern is being prepared by text editing, it is | \a alarm, that is, the BEL character (hex 07) |
| 1932 | usually easier to use one of the following escape sequences | \cx "control-x", where x is any character |
| 1933 | than the binary character it represents: | \e escape (hex 1B) |
| 1934 | \f formfeed (hex 0C) | |
| 1935 | \a alarm, that is, the BEL character (hex 07) | \n newline (hex 0A) |
| 1936 | \cx "control-x", where x is any character | \r carriage return (hex 0D) |
| 1937 | \e escape (hex 1B) | \t tab (hex 09) |
| 1938 | \f formfeed (hex 0C) | \ddd character with octal code ddd, or backreference |
| 1939 | \n newline (hex 0A) | \xhh character with hex code hh |
| 1940 | \r carriage return (hex 0D) | \x{hhh..} character with hex code hhh... (UTF-8 mode only) |
| 1941 | \t tab (hex 09) | |
| 1942 | \ddd character with octal code ddd, or backreference | The precise effect of \cx is as follows: if x is a lower case letter, |
| 1943 | \xhh character with hex code hh | it is converted to upper case. Then bit 6 of the character (hex 40) is |
| 1944 | \x{hhh..} character with hex code hhh... (UTF-8 mode only) | inverted. Thus \cz becomes hex 1A, but \c{ becomes hex 3B, while \c; |
| 1945 | becomes hex 7B. | |
| 1946 | The precise effect of \cx is as follows: if x is a lower | |
| 1947 | case letter, it is converted to upper case. Then bit 6 of | After \x, from zero to two hexadecimal digits are read (letters can be |
| 1948 | the character (hex 40) is inverted. Thus \cz becomes hex | in upper or lower case). In UTF-8 mode, any number of hexadecimal dig- |
| 1949 | 1A, but \c{ becomes hex 3B, while \c; becomes hex 7B. | its may appear between \x{ and }, but the value of the character code |
| 1950 | must be less than 2**31 (that is, the maximum hexadecimal value is | |
| 1951 | After \x, from zero to two hexadecimal digits are read | 7FFFFFFF). If characters other than hexadecimal digits appear between |
| 1952 | (letters can be in upper or lower case). In UTF-8 mode, any | \x{ and }, or if there is no terminating }, this form of escape is not |
| 1953 | number of hexadecimal digits may appear between \x{ and }, | recognized. Instead, the initial \x will be interpreted as a basic hex- |
| 1954 | but the value of the character code must be less than 2**31 | adecimal escape, with no following digits, giving a character whose |
| 1955 | (that is, the maximum hexadecimal value is 7FFFFFFF). If | value is zero. |
| 1956 | characters other than hexadecimal digits appear between \x{ | |
| 1957 | and }, or if there is no terminating }, this form of escape | Characters whose value is less than 256 can be defined by either of the |
| 1958 | is not recognized. Instead, the initial \x will be inter- | two syntaxes for \x when PCRE is in UTF-8 mode. There is no difference |
| 1959 | preted as a basic hexadecimal escape, with no following | in the way they are handled. For example, \xdc is exactly the same as |
| 1960 | digits, giving a byte whose value is zero. | \x{dc}. |
| 1961 | ||
| 1962 | Characters whose value is less than 256 can be defined by | After \0 up to two further octal digits are read. In both cases, if |
| 1963 | either of the two syntaxes for \x when PCRE is in UTF-8 | there are fewer than two digits, just those that are present are used. |
| 1964 | mode. There is no difference in the way they are handled. | Thus the sequence \0\x\07 specifies two binary zeros followed by a BEL |
| 1965 | For example, \xdc is exactly the same as \x{dc}. | character (code value 7). Make sure you supply two digits after the |
| 1966 | initial zero if the pattern character that follows is itself an octal | |
| 1967 | After \0 up to two further octal digits are read. In both | digit. |
| 1968 | cases, if there are fewer than two digits, just those that | |
| 1969 | are present are used. Thus the sequence \0\x\07 specifies | The handling of a backslash followed by a digit other than 0 is compli- |
| 1970 | two binary zeros followed by a BEL character (code value 7). | cated. Outside a character class, PCRE reads it and any following dig- |
| 1971 | Make sure you supply two digits after the initial zero if | its as a decimal number. If the number is less than 10, or if there |
| 1972 | the character that follows is itself an octal digit. | have been at least that many previous capturing left parentheses in the |
| 1973 | expression, the entire sequence is taken as a back reference. A | |
| 1974 | The handling of a backslash followed by a digit other than 0 | description of how this works is given later, following the discussion |
| 1975 | is complicated. Outside a character class, PCRE reads it | of parenthesized subpatterns. |
| 1976 | and any following digits as a decimal number. If the number | |
| 1977 | is less than 10, or if there have been at least that many | Inside a character class, or if the decimal number is greater than 9 |
| 1978 | previous capturing left parentheses in the expression, the | and there have not been that many capturing subpatterns, PCRE re-reads |
| 1979 | entire sequence is taken as a back reference. A description | up to three octal digits following the backslash, and generates a sin- |
| 1980 | of how this works is given later, following the discussion | gle byte from the least significant 8 bits of the value. Any subsequent |
| 1981 | of parenthesized subpatterns. | digits stand for themselves. For example: |
| 1982 | ||
| 1983 | Inside a character class, or if the decimal number is | \040 is another way of writing a space |
| 1984 | greater than 9 and there have not been that many capturing | \40 is the same, provided there are fewer than 40 |
| 1985 | subpatterns, PCRE re-reads up to three octal digits follow- | previous capturing subpatterns |
| 1986 | ing the backslash, and generates a single byte from the | \7 is always a back reference |
| 1987 | least significant 8 bits of the value. Any subsequent digits | \11 might be a back reference, or another way of |
| 1988 | stand for themselves. For example: | writing a tab |
| 1989 | \011 is always a tab | |
| 1990 | \040 is another way of writing a space | \0113 is a tab followed by the character "3" |
| 1991 | \40 is the same, provided there are fewer than 40 | \113 might be a back reference, otherwise the |
| 1992 | previous capturing subpatterns | character with octal code 113 |
| 1993 | \7 is always a back reference | \377 might be a back reference, otherwise |
| 1994 | \11 might be a back reference, or another way of | the byte consisting entirely of 1 bits |
| 1995 | writing a tab | \81 is either a back reference, or a binary zero |
| 1996 | \011 is always a tab | followed by the two characters "8" and "1" |
| 1997 | \0113 is a tab followed by the character "3" | |
| 1998 | \113 might be a back reference, otherwise the | Note that octal values of 100 or greater must not be introduced by a |
| 1999 | character with octal code 113 | leading zero, because no more than three octal digits are ever read. |
| 2000 | \377 might be a back reference, otherwise | |
| 2001 | the byte consisting entirely of 1 bits | All the sequences that define a single byte value or a single UTF-8 |
| 2002 | \81 is either a back reference, or a binary zero | character (in UTF-8 mode) can be used both inside and outside character |
| 2003 | followed by the two characters "8" and "1" | classes. In addition, inside a character class, the sequence \b is |
| 2004 | interpreted as the backspace character (hex 08), and the sequence \X is | |
| 2005 | Note that octal values of 100 or greater must not be intro- | interpreted as the character "X". Outside a character class, these |
| 2006 | duced by a leading zero, because no more than three octal | sequences have different meanings (see below). |
| 2007 | digits are ever read. | |
| 2008 | Generic character types | |
| 2009 | All the sequences that define a single byte value or a sin- | |
| 2010 | gle UTF-8 character (in UTF-8 mode) can be used both inside | The third use of backslash is for specifying generic character types. |
| 2011 | and outside character classes. In addition, inside a charac- | The following are always recognized: |
| 2012 | ter class, the sequence \b is interpreted as the backspace | |
| 2013 | character (hex 08). Outside a character class it has a dif- | \d any decimal digit |
| 2014 | ferent meaning (see below). | \D any character that is not a decimal digit |
| 2015 | \s any whitespace character | |
| 2016 | The third use of backslash is for specifying generic charac- | \S any character that is not a whitespace character |
| 2017 | ter types: | \w any "word" character |
| 2018 | \W any "non-word" character | |
| 2019 | \d any decimal digit | |
| 2020 | \D any character that is not a decimal digit | Each pair of escape sequences partitions the complete set of characters |
| 2021 | \s any whitespace character | into two disjoint sets. Any given character matches one, and only one, |
| 2022 | \S any character that is not a whitespace character | of each pair. |
| 2023 | \w any "word" character | |
| 2024 | W any "non-word" character | These character type sequences can appear both inside and outside char- |
| 2025 | acter classes. They each match one character of the appropriate type. | |
| 2026 | Each pair of escape sequences partitions the complete set of | If the current matching point is at the end of the subject string, all |
| 2027 | characters into two disjoint sets. Any given character | of them fail, since there is no character to match. |
| 2028 | matches one, and only one, of each pair. | |
| 2029 | For compatibility with Perl, \s does not match the VT character (code | |
| 2030 | In UTF-8 mode, characters with values greater than 255 never | 11). This makes it different from the the POSIX "space" class. The \s |
| 2031 | match \d, \s, or \w, and always match \D, \S, and \W. | characters are HT (9), LF (10), FF (12), CR (13), and space (32). |
| 2032 | ||
| 2033 | For compatibility with Perl, \s does not match the VT char- | A "word" character is an underscore or any character less than 256 that |
| 2034 | acter (code 11). This makes it different from the the POSIX | is a letter or digit. The definition of letters and digits is con- |
| 2035 | "space" class. The \s characters are HT (9), LF (10), FF | trolled by PCRE's low-valued character tables, and may vary if locale- |
| 2036 | (12), CR (13), and space (32). | specific matching is taking place (see "Locale support" in the pcreapi |
| 2037 | page). For example, in the "fr_FR" (French) locale, some character | |
| 2038 | A "word" character is any letter or digit or the underscore | codes greater than 128 are used for accented letters, and these are |
| 2039 | character, that is, any character which can be part of a | matched by \w. |
| 2040 | Perl "word". The definition of letters and digits is con- | |
| 2041 | trolled by PCRE's character tables, and may vary if locale- | In UTF-8 mode, characters with values greater than 128 never match \d, |
| 2042 | specific matching is taking place (see "Locale support" in | \s, or \w, and always match \D, \S, and \W. This is true even when Uni- |
| 2043 | the pcreapi page). For example, in the "fr" (French) locale, | code character property support is available. |
| 2044 | some character codes greater than 128 are used for accented | |
| 2045 | letters, and these are matched by \w. | Unicode character properties |
| 2046 | ||
| 2047 | These character type sequences can appear both inside and | When PCRE is built with Unicode character property support, three addi- |
| 2048 | outside character classes. They each match one character of | tional escape sequences to match generic character types are available |
| 2049 | the appropriate type. If the current matching point is at | when UTF-8 mode is selected. They are: |
| 2050 | the end of the subject string, all of them fail, since there | |
| 2051 | is no character to match. | \p{xx} a character with the xx property |
| 2052 | \P{xx} a character without the xx property | |
| 2053 | The fourth use of backslash is for certain simple asser- | \X an extended Unicode sequence |
| 2054 | tions. An assertion specifies a condition that has to be met | |
| 2055 | at a particular point in a match, without consuming any | The property names represented by xx above are limited to the Unicode |
| 2056 | characters from the subject string. The use of subpatterns | general category properties. Each character has exactly one such prop- |
| 2057 | for more complicated assertions is described below. The | erty, specified by a two-letter abbreviation. For compatibility with |
| 2058 | backslashed assertions are | Perl, negation can be specified by including a circumflex between the |
| 2059 | opening brace and the property name. For example, \p{^Lu} is the same | |
| 2060 | \b matches at a word boundary | as \P{Lu}. |
| 2061 | \B matches when not at a word boundary | |
| 2062 | \A matches at start of subject | If only one letter is specified with \p or \P, it includes all the |
| 2063 | \Z matches at end of subject or before newline at end | properties that start with that letter. In this case, in the absence of |
| 2064 | \z matches at end of subject | negation, the curly brackets in the escape sequence are optional; these |
| 2065 | \G matches at first matching position in subject | two examples have the same effect: |
| 2066 | ||
| 2067 | These assertions may not appear in character classes (but | \p{L} |
| 2068 | note that \b has a different meaning, namely the backspace | \pL |
| 2069 | character, inside a character class). | |
| 2070 | The following property codes are supported: | |
| 2071 | A word boundary is a position in the subject string where | |
| 2072 | the current character and the previous character do not both | C Other |
| 2073 | match \w or \W (i.e. one matches \w and the other matches | Cc Control |
| 2074 | \W), or the start or end of the string if the first or last | Cf Format |
| 2075 | character matches \w, respectively. | Cn Unassigned |
| 2076 | The \A, \Z, and \z assertions differ from the traditional | Co Private use |
| 2077 | circumflex and dollar (described below) in that they only | Cs Surrogate |
| 2078 | ever match at the very start and end of the subject string, | |
| 2079 | whatever options are set. Thus, they are independent of mul- | L Letter |
| 2080 | tiline mode. | Ll Lower case letter |
| 2081 | Lm Modifier letter | |
| 2082 | They are not affected by the PCRE_NOTBOL or PCRE_NOTEOL | Lo Other letter |
| 2083 | options. If the startoffset argument of pcre_exec() is non- | Lt Title case letter |
| 2084 | zero, indicating that matching is to start at a point other | Lu Upper case letter |
| 2085 | than the beginning of the subject, \A can never match. The | |
| 2086 | difference between \Z and \z is that \Z matches before a | M Mark |
| 2087 | newline that is the last character of the string as well as | Mc Spacing mark |
| 2088 | at the end of the string, whereas \z matches only at the | Me Enclosing mark |
| 2089 | end. | Mn Non-spacing mark |
| 2090 | ||
| 2091 | The \G assertion is true only when the current matching | N Number |
| 2092 | position is at the start point of the match, as specified by | Nd Decimal number |
| 2093 | the startoffset argument of pcre_exec(). It differs from \A | Nl Letter number |
| 2094 | when the value of startoffset is non-zero. By calling | No Other number |
| 2095 | pcre_exec() multiple times with appropriate arguments, you | |
| 2096 | can mimic Perl's /g option, and it is in this kind of imple- | P Punctuation |
| 2097 | mentation where \G can be useful. | Pc Connector punctuation |
| 2098 | Pd Dash punctuation | |
| 2099 | Note, however, that PCRE's interpretation of \G, as the | Pe Close punctuation |
| 2100 | start of the current match, is subtly different from Perl's, | Pf Final punctuation |
| 2101 | which defines it as the end of the previous match. In Perl, | Pi Initial punctuation |
| 2102 | these can be different when the previously matched string | Po Other punctuation |
| 2103 | was empty. Because PCRE does just one match at a time, it | Ps Open punctuation |
| 2104 | cannot reproduce this behaviour. | |
| 2105 | S Symbol | |
| 2106 | If all the alternatives of a pattern begin with \G, the | Sc Currency symbol |
| 2107 | expression is anchored to the starting match position, and | Sk Modifier symbol |
| 2108 | the "anchored" flag is set in the compiled regular expres- | Sm Mathematical symbol |
| 2109 | sion. | So Other symbol |
| 2110 | ||
| 2111 | Z Separator | |
| 2112 | Zl Line separator | |
| 2113 | Zp Paragraph separator | |
| 2114 | Zs Space separator | |
| 2115 | ||
| 2116 | Extended properties such as "Greek" or "InMusicalSymbols" are not sup- | |
| 2117 | ported by PCRE. | |
| 2118 | ||
| 2119 | Specifying caseless matching does not affect these escape sequences. | |
| 2120 | For example, \p{Lu} always matches only upper case letters. | |
| 2121 | ||
| 2122 | The \X escape matches any number of Unicode characters that form an | |
| 2123 | extended Unicode sequence. \X is equivalent to | |
| 2124 | ||
| 2125 | (?>\PM\pM*) | |
| 2126 | ||
| 2127 | That is, it matches a character without the "mark" property, followed | |
| 2128 | by zero or more characters with the "mark" property, and treats the | |
| 2129 | sequence as an atomic group (see below). Characters with the "mark" | |
| 2130 | property are typically accents that affect the preceding character. | |
| 2131 | ||
| 2132 | Matching characters by Unicode property is not fast, because PCRE has | |
| 2133 | to search a structure that contains data for over fifteen thousand | |
| 2134 | characters. That is why the traditional escape sequences such as \d and | |
| 2135 | \w do not use Unicode properties in PCRE. | |
| 2136 | ||
| 2137 | Simple assertions | |
| 2138 | ||
| 2139 | The fourth use of backslash is for certain simple assertions. An asser- | |
| 2140 | tion specifies a condition that has to be met at a particular point in | |
| 2141 | a match, without consuming any characters from the subject string. The | |
| 2142 | use of subpatterns for more complicated assertions is described below. | |
| 2143 | The backslashed assertions are: | |
| 2144 | ||
| 2145 | \b matches at a word boundary | |
| 2146 | \B matches when not at a word boundary | |
| 2147 | \A matches at start of subject | |
| 2148 | \Z matches at end of subject or before newline at end | |
| 2149 | \z matches at end of subject | |
| 2150 | \G matches at first matching position in subject | |
| 2151 | ||
| 2152 | These assertions may not appear in character classes (but note that \b | |
| 2153 | has a different meaning, namely the backspace character, inside a char- | |
| 2154 | acter class). | |
| 2155 | ||
| 2156 | A word boundary is a position in the subject string where the current | |
| 2157 | character and the previous character do not both match \w or \W (i.e. | |
| 2158 | one matches \w and the other matches \W), or the start or end of the | |
| 2159 | string if the first or last character matches \w, respectively. | |
| 2160 | ||
| 2161 | The \A, \Z, and \z assertions differ from the traditional circumflex | |
| 2162 | and dollar (described in the next section) in that they only ever match | |
| 2163 | at the very start and end of the subject string, whatever options are | |
| 2164 | set. Thus, they are independent of multiline mode. These three asser- | |
| 2165 | tions are not affected by the PCRE_NOTBOL or PCRE_NOTEOL options, which | |
| 2166 | affect only the behaviour of the circumflex and dollar metacharacters. | |
| 2167 | However, if the startoffset argument of pcre_exec() is non-zero, indi- | |
| 2168 | cating that matching is to start at a point other than the beginning of | |
| 2169 | the subject, \A can never match. The difference between \Z and \z is | |
| 2170 | that \Z matches before a newline that is the last character of the | |
| 2171 | string as well as at the end of the string, whereas \z matches only at | |
| 2172 | the end. | |
| 2173 | ||
| 2174 | The \G assertion is true only when the current matching position is at | |
| 2175 | the start point of the match, as specified by the startoffset argument | |
| 2176 | of pcre_exec(). It differs from \A when the value of startoffset is | |
| 2177 | non-zero. By calling pcre_exec() multiple times with appropriate argu- | |
| 2178 | ments, you can mimic Perl's /g option, and it is in this kind of imple- | |
| 2179 | mentation where \G can be useful. | |
| 2180 | ||
| 2181 | Note, however, that PCRE's interpretation of \G, as the start of the | |
| 2182 | current match, is subtly different from Perl's, which defines it as the | |
| 2183 | end of the previous match. In Perl, these can be different when the | |
| 2184 | previously matched string was empty. Because PCRE does just one match | |
| 2185 | at a time, it cannot reproduce this behaviour. | |
| 2186 | ||
| 2187 | If all the alternatives of a pattern begin with \G, the expression is | |
| 2188 | anchored to the starting match position, and the "anchored" flag is set | |
| 2189 | in the compiled regular expression. | |
| 2190 | ||
| 2191 | ||
| 2192 | CIRCUMFLEX AND DOLLAR | CIRCUMFLEX AND DOLLAR |
| 2193 | ||
| 2194 | Outside a character class, in the default matching mode, the | Outside a character class, in the default matching mode, the circumflex |
| 2195 | circumflex character is an assertion which is true only if | character is an assertion that is true only if the current matching |
| 2196 | the current matching point is at the start of the subject | point is at the start of the subject string. If the startoffset argu- |
| 2197 | string. If the startoffset argument of pcre_exec() is non- | ment of pcre_exec() is non-zero, circumflex can never match if the |
| 2198 | zero, circumflex can never match if the PCRE_MULTILINE | PCRE_MULTILINE option is unset. Inside a character class, circumflex |
| 2199 | option is unset. Inside a character class, circumflex has an | has an entirely different meaning (see below). |
| 2200 | entirely different meaning (see below). | |
| 2201 | Circumflex need not be the first character of the pattern if a number | |
| 2202 | Circumflex need not be the first character of the pattern if | of alternatives are involved, but it should be the first thing in each |
| 2203 | a number of alternatives are involved, but it should be the | alternative in which it appears if the pattern is ever to match that |
| 2204 | first thing in each alternative in which it appears if the | branch. If all possible alternatives start with a circumflex, that is, |
| 2205 | pattern is ever to match that branch. If all possible alter- | if the pattern is constrained to match only at the start of the sub- |
| 2206 | natives start with a circumflex, that is, if the pattern is | ject, it is said to be an "anchored" pattern. (There are also other |
| 2207 | constrained to match only at the start of the subject, it is | constructs that can cause a pattern to be anchored.) |
| 2208 | said to be an "anchored" pattern. (There are also other con- | |
| 2209 | structs that can cause a pattern to be anchored.) | A dollar character is an assertion that is true only if the current |
| 2210 | matching point is at the end of the subject string, or immediately | |
| 2211 | A dollar character is an assertion which is true only if the | before a newline character that is the last character in the string (by |
| 2212 | current matching point is at the end of the subject string, | default). Dollar need not be the last character of the pattern if a |
| 2213 | or immediately before a newline character that is the last | number of alternatives are involved, but it should be the last item in |
| 2214 | character in the string (by default). Dollar need not be the | any branch in which it appears. Dollar has no special meaning in a |
| 2215 | last character of the pattern if a number of alternatives | character class. |
| 2216 | are involved, but it should be the last item in any branch | |
| 2217 | in which it appears. Dollar has no special meaning in a | The meaning of dollar can be changed so that it matches only at the |
| 2218 | character class. | very end of the string, by setting the PCRE_DOLLAR_ENDONLY option at |
| 2219 | compile time. This does not affect the \Z assertion. | |
| 2220 | The meaning of dollar can be changed so that it matches only | |
| 2221 | at the very end of the string, by setting the | The meanings of the circumflex and dollar characters are changed if the |
| 2222 | PCRE_DOLLAR_ENDONLY option at compile time. This does not | PCRE_MULTILINE option is set. When this is the case, they match immedi- |
| 2223 | affect the \Z assertion. | ately after and immediately before an internal newline character, |
| 2224 | respectively, in addition to matching at the start and end of the sub- | |
| 2225 | The meanings of the circumflex and dollar characters are | ject string. For example, the pattern /^abc$/ matches the subject |
| 2226 | changed if the PCRE_MULTILINE option is set. When this is | string "def\nabc" (where \n represents a newline character) in multi- |
| 2227 | the case, they match immediately after and immediately | line mode, but not otherwise. Consequently, patterns that are anchored |
| 2228 | before an internal newline character, respectively, in addi- | in single line mode because all branches start with ^ are not anchored |
| 2229 | tion to matching at the start and end of the subject string. | in multiline mode, and a match for circumflex is possible when the |
| 2230 | For example, the pattern /^abc$/ matches the subject string | startoffset argument of pcre_exec() is non-zero. The PCRE_DOL- |
| 2231 | "def\nabc" in multiline mode, but not otherwise. Conse- | LAR_ENDONLY option is ignored if PCRE_MULTILINE is set. |
| 2232 | quently, patterns that are anchored in single line mode | |
| 2233 | because all branches start with ^ are not anchored in multi- | Note that the sequences \A, \Z, and \z can be used to match the start |
| 2234 | line mode, and a match for circumflex is possible when the | and end of the subject in both modes, and if all branches of a pattern |
| 2235 | startoffset argument of pcre_exec() is non-zero. The | start with \A it is always anchored, whether PCRE_MULTILINE is set or |
| 2236 | PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE is | not. |
| 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 PCRE_MULTILINE is set or not. | ||
| 2237 | ||
| 2238 | ||
| 2239 | FULL STOP (PERIOD, DOT) | FULL STOP (PERIOD, DOT) |
| 2240 | ||
| 2241 | Outside a character class, a dot in the pattern matches any | Outside a character class, a dot in the pattern matches any one charac- |
| 2242 | one character in the subject, including a non-printing char- | ter in the subject, including a non-printing character, but not (by |
| 2243 | acter, but not (by default) newline. In UTF-8 mode, a dot | default) newline. In UTF-8 mode, a dot matches any UTF-8 character, |
| 2244 | matches any UTF-8 character, which might be more than one | which might be more than one byte long, except (by default) newline. If |
| 2245 | byte long, except (by default) for newline. If the | the PCRE_DOTALL option is set, dots match newlines as well. The han- |
| 2246 | PCRE_DOTALL option is set, dots match newlines as well. The | dling of dot is entirely independent of the handling of circumflex and |
| 2247 | handling of dot is entirely independent of the handling of | dollar, the only relationship being that they both involve newline |
| 2248 | circumflex and dollar, the only relationship being that they | characters. Dot has no special meaning in a character class. |
| both involve newline characters. Dot has no special meaning | ||
| in a character class. | ||
| 2249 | ||
| 2250 | ||
| 2251 | MATCHING A SINGLE BYTE | MATCHING A SINGLE BYTE |
| 2252 | ||
| 2253 | Outside a character class, the escape sequence \C matches | Outside a character class, the escape sequence \C matches any one byte, |
| 2254 | any one byte, both in and out of UTF-8 mode. Unlike a dot, | both in and out of UTF-8 mode. Unlike a dot, it can match a newline. |
| 2255 | it always matches a newline. The feature is provided in Perl | The feature is provided in Perl in order to match individual bytes in |
| 2256 | in order to match individual bytes in UTF-8 mode. Because | UTF-8 mode. Because it breaks up UTF-8 characters into individual |
| 2257 | it breaks up UTF-8 characters into individual bytes, what | bytes, what remains in the string may be a malformed UTF-8 string. For |
| 2258 | remains in the string may be a malformed UTF-8 string. For | this reason, the \C escape sequence is best avoided. |
| 2259 | this reason it is best avoided. | |
| 2260 | PCRE does not allow \C to appear in lookbehind assertions (described | |
| 2261 | PCRE does not allow \C to appear in lookbehind assertions | below), because in UTF-8 mode this would make it impossible to calcu- |
| 2262 | (see below), because in UTF-8 mode it makes it impossible to | late the length of the lookbehind. |
| 2263 | calculate the length of the lookbehind. | |
| 2264 | ||
| 2265 | SQUARE BRACKETS AND CHARACTER CLASSES | |
| 2266 | SQUARE BRACKETS | |
| 2267 | An opening square bracket introduces a character class, terminated by a | |
| 2268 | An opening square bracket introduces a character class, ter- | closing square bracket. A closing square bracket on its own is not spe- |
| 2269 | minated by a closing square bracket. A closing square | cial. If a closing square bracket is required as a member of the class, |
| 2270 | bracket on its own is not special. If a closing square | it should be the first data character in the class (after an initial |
| 2271 | bracket is required as a member of the class, it should be | circumflex, if present) or escaped with a backslash. |
| 2272 | the first data character in the class (after an initial cir- | |
| 2273 | cumflex, if present) or escaped with a backslash. | A character class matches a single character in the subject. In UTF-8 |
| 2274 | mode, the character may occupy more than one byte. A matched character | |
| 2275 | A character class matches a single character in the subject. | must be in the set of characters defined by the class, unless the first |
| 2276 | In UTF-8 mode, the character may occupy more than one byte. | character in the class definition is a circumflex, in which case the |
| 2277 | A matched character must be in the set of characters defined | subject character must not be in the set defined by the class. If a |
| 2278 | by the class, unless the first character in the class defin- | circumflex is actually required as a member of the class, ensure it is |
| 2279 | ition is a circumflex, in which case the subject character | not the first character, or escape it with a backslash. |
| 2280 | must not be in the set defined by the class. If a circumflex | |
| 2281 | is actually required as a member of the class, ensure it is | For example, the character class [aeiou] matches any lower case vowel, |
| 2282 | not the first character, or escape it with a backslash. | while [^aeiou] matches any character that is not a lower case vowel. |
| 2283 | Note that a circumflex is just a convenient notation for specifying the | |
| 2284 | For example, the character class [aeiou] matches any lower | characters that are in the class by enumerating those that are not. A |
| 2285 | case vowel, while [^aeiou] matches any character that is not | class that starts with a circumflex is not an assertion: it still con- |
| 2286 | a lower case vowel. Note that a circumflex is just a con- | sumes a character from the subject string, and therefore it fails if |
| 2287 | venient notation for specifying the characters which are in | the current pointer is at the end of the string. |
| 2288 | the class by enumerating those that are not. It is not an | |
| 2289 | assertion: it still consumes a character from the subject | In UTF-8 mode, characters with values greater than 255 can be included |
| 2290 | string, and fails if the current pointer is at the end of | in a class as a literal string of bytes, or by using the \x{ escaping |
| 2291 | the string. | mechanism. |
| 2292 | ||
| 2293 | In UTF-8 mode, characters with values greater than 255 can | When caseless matching is set, any letters in a class represent both |
| 2294 | be included in a class as a literal string of bytes, or by | their upper case and lower case versions, so for example, a caseless |
| 2295 | using the \x{ escaping mechanism. | [aeiou] matches "A" as well as "a", and a caseless [^aeiou] does not |
| 2296 | match "A", whereas a caseful version would. When running in UTF-8 mode, | |
| 2297 | When caseless matching is set, any letters in a class | PCRE supports the concept of case for characters with values greater |
| 2298 | represent both their upper case and lower case versions, so | than 128 only when it is compiled with Unicode property support. |
| 2299 | for example, a caseless [aeiou] matches "A" as well as "a", | |
| 2300 | and a caseless [^aeiou] does not match "A", whereas a case- | The newline character is never treated in any special way in character |
| 2301 | ful version would. PCRE does not support the concept of case | classes, whatever the setting of the PCRE_DOTALL or PCRE_MULTILINE |
| 2302 | for characters with values greater than 255. | options is. A class such as [^a] will always match a newline. |
| 2303 | The newline character is never treated in any special way in | |
| 2304 | character classes, whatever the setting of the PCRE_DOTALL | The minus (hyphen) character can be used to specify a range of charac- |
| 2305 | or PCRE_MULTILINE options is. A class such as [^a] will | ters in a character class. For example, [d-m] matches any letter |
| 2306 | always match a newline. | between d and m, inclusive. If a minus character is required in a |
| 2307 | class, it must be escaped with a backslash or appear in a position | |
| 2308 | The minus (hyphen) character can be used to specify a range | where it cannot be interpreted as indicating a range, typically as the |
| 2309 | of characters in a character class. For example, [d-m] | first or last character in the class. |
| 2310 | matches any letter between d and m, inclusive. If a minus | |
| 2311 | character is required in a class, it must be escaped with a | It is not possible to have the literal character "]" as the end charac- |
| 2312 | backslash or appear in a position where it cannot be inter- | ter of a range. A pattern such as [W-]46] is interpreted as a class of |
| 2313 | preted as indicating a range, typically as the first or last | two characters ("W" and "-") followed by a literal string "46]", so it |
| 2314 | character in the class. | would match "W46]" or "-46]". However, if the "]" is escaped with a |
| 2315 | backslash it is interpreted as the end of range, so [W-\]46] is inter- | |
| 2316 | It is not possible to have the literal character "]" as the | preted as a class containing a range followed by two other characters. |
| 2317 | end character of a range. A pattern such as [W-]46] is | The octal or hexadecimal representation of "]" can also be used to end |
| 2318 | interpreted as a class of two characters ("W" and "-") fol- | a range. |
| 2319 | lowed by a literal string "46]", so it would match "W46]" or | |
| 2320 | "-46]". However, if the "]" is escaped with a backslash it | Ranges operate in the collating sequence of character values. They can |
| 2321 | is interpreted as the end of range, so [W-\]46] is inter- | also be used for characters specified numerically, for example |
| 2322 | preted as a single class containing a range followed by two | [\000-\037]. In UTF-8 mode, ranges can include characters whose values |
| 2323 | separate characters. The octal or hexadecimal representation | are greater than 255, for example [\x{100}-\x{2ff}]. |
| 2324 | of "]" can also be used to end a range. | |
| 2325 | If a range that includes letters is used when caseless matching is set, | |
| 2326 | Ranges operate in the collating sequence of character | it matches the letters in either case. For example, [W-c] is equivalent |
| 2327 | values. They can also be used for characters specified | to [][\\^_`wxyzabc], matched caselessly, and in non-UTF-8 mode, if |
| 2328 | numerically, for example [\000-\037]. In UTF-8 mode, ranges | character tables for the "fr_FR" locale are in use, [\xc8-\xcb] matches |
| 2329 | can include characters whose values are greater than 255, | accented E characters in both cases. In UTF-8 mode, PCRE supports the |
| 2330 | for example [\x{100}-\x{2ff}]. | concept of case for characters with values greater than 128 only when |
| 2331 | it is compiled with Unicode property support. | |
| 2332 | If a range that includes letters is used when caseless | |
| 2333 | matching is set, it matches the letters in either case. For | The character types \d, \D, \p, \P, \s, \S, \w, and \W may also appear |
| 2334 | example, [W-c] is equivalent to [][\^_`wxyzabc], matched | in a character class, and add the characters that they match to the |
| 2335 | caselessly, and if character tables for the "fr" locale are | class. For example, [\dABCDEF] matches any hexadecimal digit. A circum- |
| 2336 | in use, [\xc8-\xcb] matches accented E characters in both | flex can conveniently be used with the upper case character types to |
| 2337 | cases. | specify a more restricted set of characters than the matching lower |
| 2338 | case type. For example, the class [^\W_] matches any letter or digit, | |
| 2339 | The character types \d, \D, \s, \S, \w, and \W may also | but not underscore. |
| 2340 | appear in a character class, and add the characters that | |
| 2341 | they match to the class. For example, [\dABCDEF] matches any | The only metacharacters that are recognized in character classes are |
| 2342 | hexadecimal digit. A circumflex can conveniently be used | backslash, hyphen (only where it can be interpreted as specifying a |
| 2343 | with the upper case character types to specify a more res- | range), circumflex (only at the start), opening square bracket (only |
| 2344 | tricted set of characters than the matching lower case type. | when it can be interpreted as introducing a POSIX class name - see the |
| 2345 | For example, the class [^\W_] matches any letter or digit, | next section), and the terminating closing square bracket. However, |
| 2346 | but not underscore. | escaping other non-alphanumeric characters does no harm. |
| All non-alphameric characters other than \, -, ^ (at the | ||
| start) and the terminating ] are non-special in character | ||
| classes, but it does no harm if they are escaped. | ||
| 2347 | ||
| 2348 | ||
| 2349 | POSIX CHARACTER CLASSES | POSIX CHARACTER CLASSES |
| 2350 | ||
| 2351 | Perl supports the POSIX notation for character classes, | Perl supports the POSIX notation for character classes. This uses names |
| 2352 | which uses names enclosed by [: and :] within the enclosing | enclosed by [: and :] within the enclosing square brackets. PCRE also |
| 2353 | square brackets. PCRE also supports this notation. For exam- | supports this notation. For example, |
| 2354 | ple, | |
| 2355 | [01[:alpha:]%] | |
| 2356 | [01[:alpha:]%] | |
| 2357 | matches "0", "1", any alphabetic character, or "%". The supported class | |
| 2358 | matches "0", "1", any alphabetic character, or "%". The sup- | names are |
| 2359 | ported class names are | |
| 2360 | alnum letters and digits | |
| 2361 | alnum letters and digits | alpha letters |
| 2362 | alpha letters | ascii character codes 0 - 127 |
| 2363 | ascii character codes 0 - 127 | blank space or tab only |
| 2364 | blank space or tab only | cntrl control characters |
| 2365 | cntrl control characters | digit decimal digits (same as \d) |
| 2366 | digit decimal digits (same as \d) | graph printing characters, excluding space |
| 2367 | graph printing characters, excluding space | lower lower case letters |
| 2368 | lower lower case letters | print printing characters, including space |
| 2369 | print printing characters, including space | punct printing characters, excluding letters and digits |
| 2370 | punct printing characters, excluding letters and digits | space white space (not quite the same as \s) |
| 2371 | space white space (not quite the same as \s) | upper upper case letters |
| 2372 | upper upper case letters | word "word" characters (same as \w) |
| 2373 | word "word" characters (same as \w) | xdigit hexadecimal digits |
| 2374 | xdigit hexadecimal digits | |
| 2375 | The "space" characters are HT (9), LF (10), VT (11), FF (12), CR (13), | |
| 2376 | The "space" characters are HT (9), LF (10), VT (11), FF | and space (32). Notice that this list includes the VT character (code |
| 2377 | (12), CR (13), and space (32). Notice that this list | 11). This makes "space" different to \s, which does not include VT (for |
| 2378 | includes the VT character (code 11). This makes "space" dif- | Perl compatibility). |
| 2379 | ferent to \s, which does not include VT (for Perl compati- | |
| 2380 | bility). | The name "word" is a Perl extension, and "blank" is a GNU extension |
| 2381 | from Perl 5.8. Another Perl extension is negation, which is indicated | |
| 2382 | The name "word" is a Perl extension, and "blank" is a GNU | by a ^ character after the colon. For example, |
| 2383 | extension from Perl 5.8. Another Perl extension is negation, | |
| 2384 | which is indicated by a ^ character after the colon. For | [12[:^digit:]] |
| 2385 | example, | |
| 2386 | matches "1", "2", or any non-digit. PCRE (and Perl) also recognize the | |
| 2387 | [12[:^digit:]] | POSIX syntax [.ch.] and [=ch=] where "ch" is a "collating element", but |
| 2388 | these are not supported, and an error is given if they are encountered. | |
| 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. | ||
| 2389 | ||
| 2390 | In UTF-8 mode, characters with values greater than 255 do | In UTF-8 mode, characters with values greater than 128 do not match any |
| 2391 | not match any of the POSIX character classes. | of the POSIX character classes. |
| 2392 | ||
| 2393 | ||
| 2394 | VERTICAL BAR | VERTICAL BAR |
| 2395 | ||
| 2396 | Vertical bar characters are used to separate alternative | Vertical bar characters are used to separate alternative patterns. For |
| 2397 | patterns. For example, the pattern | example, the pattern |
| 2398 | ||
| 2399 | gilbert|sullivan | gilbert|sullivan |
| 2400 | ||
| 2401 | matches either "gilbert" or "sullivan". Any number of alter- | matches either "gilbert" or "sullivan". Any number of alternatives may |
| 2402 | natives may appear, and an empty alternative is permitted | appear, and an empty alternative is permitted (matching the empty |
| 2403 | (matching the empty string). The matching process tries | string). The matching process tries each alternative in turn, from |
| 2404 | each alternative in turn, from left to right, and the first | left to right, and the first one that succeeds is used. If the alterna- |
| 2405 | one that succeeds is used. If the alternatives are within a | tives are within a subpattern (defined below), "succeeds" means match- |
| 2406 | subpattern (defined below), "succeeds" means matching the | ing the rest of the main pattern as well as the alternative in the sub- |
| 2407 | rest of the main pattern as well as the alternative in the | pattern. |
| subpattern. | ||
| 2408 | ||
| 2409 | ||
| 2410 | INTERNAL OPTION SETTING | INTERNAL OPTION SETTING |
| 2411 | ||
| 2412 | The settings of the PCRE_CASELESS, PCRE_MULTILINE, | The settings of the PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, and |
| 2413 | PCRE_DOTALL, and PCRE_EXTENDED options can be changed from | PCRE_EXTENDED options can be changed from within the pattern by a |
| 2414 | within the pattern by a sequence of Perl option letters | sequence of Perl option letters enclosed between "(?" and ")". The |
| 2415 | enclosed between "(?" and ")". The option letters are | option letters are |
| 2416 | ||
| 2417 | i for PCRE_CASELESS | i for PCRE_CASELESS |
| 2418 | m for PCRE_MULTILINE | m for PCRE_MULTILINE |
| 2419 | s for PCRE_DOTALL | s for PCRE_DOTALL |
| 2420 | x for PCRE_EXTENDED | x for PCRE_EXTENDED |
| 2421 | ||
| 2422 | For example, (?im) sets caseless, multiline matching. It is | For example, (?im) sets caseless, multiline matching. It is also possi- |
| 2423 | also possible to unset these options by preceding the letter | ble to unset these options by preceding the letter with a hyphen, and a |
| 2424 | with a hyphen, and a combined setting and unsetting such as | combined setting and unsetting such as (?im-sx), which sets PCRE_CASE- |
| 2425 | (?im-sx), which sets PCRE_CASELESS and PCRE_MULTILINE while | LESS and PCRE_MULTILINE while unsetting PCRE_DOTALL and PCRE_EXTENDED, |
| 2426 | unsetting PCRE_DOTALL and PCRE_EXTENDED, is also permitted. | is also permitted. If a letter appears both before and after the |
| 2427 | If a letter appears both before and after the hyphen, the | hyphen, the option is unset. |
| 2428 | option is unset. | |
| 2429 | When an option change occurs at top level (that is, not inside subpat- | |
| 2430 | When an option change occurs at top level (that is, not | tern parentheses), the change applies to the remainder of the pattern |
| 2431 | inside subpattern parentheses), the change applies to the | that follows. If the change is placed right at the start of a pattern, |
| 2432 | remainder of the pattern that follows. If the change is | PCRE extracts it into the global options (and it will therefore show up |
| 2433 | placed right at the start of a pattern, PCRE extracts it | in data extracted by the pcre_fullinfo() function). |
| 2434 | into the global options (and it will therefore show up in | |
| 2435 | data extracted by the pcre_fullinfo() function). | An option change within a subpattern affects only that part of the cur- |
| 2436 | rent pattern that follows it, so | |
| 2437 | An option change within a subpattern affects only that part | |
| 2438 | of the current pattern that follows it, so | (a(?i)b)c |
| 2439 | ||
| 2440 | (a(?i)b)c | matches abc and aBc and no other strings (assuming PCRE_CASELESS is not |
| 2441 | used). By this means, options can be made to have different settings | |
| 2442 | matches abc and aBc and no other strings (assuming | in different parts of the pattern. Any changes made in one alternative |
| 2443 | PCRE_CASELESS is not used). By this means, options can be | do carry on into subsequent branches within the same subpattern. For |
| 2444 | made to have different settings in different parts of the | example, |
| 2445 | pattern. Any changes made in one alternative do carry on | |
| 2446 | into subsequent branches within the same subpattern. For | (a(?i)b|c) |
| 2447 | example, | |
| 2448 | matches "ab", "aB", "c", and "C", even though when matching "C" the | |
| 2449 | (a(?i)b|c) | first branch is abandoned before the option setting. This is because |
| 2450 | the effects of option settings happen at compile time. There would be | |
| 2451 | matches "ab", "aB", "c", and "C", even though when matching | some very weird behaviour otherwise. |
| 2452 | "C" the first branch is abandoned before the option setting. | |
| 2453 | This is because the effects of option settings happen at | The PCRE-specific options PCRE_UNGREEDY and PCRE_EXTRA can be changed |
| 2454 | compile time. There would be some very weird behaviour oth- | in the same way as the Perl-compatible options by using the characters |
| 2455 | erwise. | U and X respectively. The (?X) flag setting is special in that it must |
| 2456 | always occur earlier in the pattern than any of the additional features | |
| 2457 | The PCRE-specific options PCRE_UNGREEDY and PCRE_EXTRA can | it turns on, even when it is at top level. It is best to put it at the |
| 2458 | be changed in the same way as the Perl-compatible options by | start. |
| using the characters U and X respectively. The (?X) flag | ||
| setting is special in that it must always occur earlier in | ||
| the pattern than any of the additional features it turns on, | ||
| even when it is at top level. It is best put at the start. | ||
| 2459 | ||
| 2460 | ||
| 2461 | SUBPATTERNS | SUBPATTERNS |
| 2462 | ||
| 2463 | Subpatterns are delimited by parentheses (round brackets), | Subpatterns are delimited by parentheses (round brackets), which can be |
| 2464 | which can be nested. Marking part of a pattern as a subpat- | nested. Turning part of a pattern into a subpattern does two things: |
| 2465 | tern does two things: | |
| 2466 | 1. It localizes a set of alternatives. For example, the pattern | |
| 2467 | 1. It localizes a set of alternatives. For example, the pat- | |
| 2468 | tern | cat(aract|erpillar|) |
| 2469 | ||
| 2470 | cat(aract|erpillar|) | matches one of the words "cat", "cataract", or "caterpillar". Without |
| 2471 | the parentheses, it would match "cataract", "erpillar" or the empty | |
| 2472 | matches one of the words "cat", "cataract", or "caterpil- | string. |
| 2473 | lar". Without the parentheses, it would match "cataract", | |
| 2474 | "erpillar" or the empty string. | 2. It sets up the subpattern as a capturing subpattern. This means |
| 2475 | that, when the whole pattern matches, that portion of the subject | |
| 2476 | 2. It sets up the subpattern as a capturing subpattern (as | string that matched the subpattern is passed back to the caller via the |
| 2477 | defined above). When the whole pattern matches, that por- | ovector argument of pcre_exec(). Opening parentheses are counted from |
| 2478 | tion of the subject string that matched the subpattern is | left to right (starting from 1) to obtain numbers for the capturing |
| 2479 | passed back to the caller via the ovector argument of | subpatterns. |
| 2480 | pcre_exec(). Opening parentheses are counted from left to | |
| 2481 | right (starting from 1) to obtain the numbers of the captur- | For example, if the string "the red king" is matched against the pat- |
| 2482 | ing subpatterns. | tern |
| 2483 | ||
| 2484 | For example, if the string "the red king" is matched against | the ((red|white) (king|queen)) |
| 2485 | the pattern | |
| 2486 | the captured substrings are "red king", "red", and "king", and are num- | |
| 2487 | the ((red|white) (king|queen)) | bered 1, 2, and 3, respectively. |
| 2488 | ||
| 2489 | the captured substrings are "red king", "red", and "king", | The fact that plain parentheses fulfil two functions is not always |
| 2490 | and are numbered 1, 2, and 3, respectively. | helpful. There are often times when a grouping subpattern is required |
| 2491 | without a capturing requirement. If an opening parenthesis is followed | |
| 2492 | The fact that plain parentheses fulfil two functions is not | by a question mark and a colon, the subpattern does not do any captur- |
| 2493 | always helpful. There are often times when a grouping sub- | ing, and is not counted when computing the number of any subsequent |
| 2494 | pattern is required without a capturing requirement. If an | capturing subpatterns. For example, if the string "the white queen" is |
| 2495 | opening parenthesis is followed by a question mark and a | matched against the pattern |
| 2496 | colon, the subpattern does not do any capturing, and is not | |
| 2497 | counted when computing the number of any subsequent captur- | the ((?:red|white) (king|queen)) |
| 2498 | ing subpatterns. For example, if the string "the white | |
| 2499 | queen" is matched against the pattern | the captured substrings are "white queen" and "queen", and are numbered |
| 2500 | 1 and 2. The maximum number of capturing subpatterns is 65535, and the | |
| 2501 | the ((?:red|white) (king|queen)) | maximum depth of nesting of all subpatterns, both capturing and non- |
| 2502 | capturing, is 200. | |
| 2503 | the captured substrings are "white queen" and "queen", and | |
| 2504 | are numbered 1 and 2. The maximum number of capturing sub- | As a convenient shorthand, if any option settings are required at the |
| 2505 | patterns is 65535, and the maximum depth of nesting of all | start of a non-capturing subpattern, the option letters may appear |
| 2506 | subpatterns, both capturing and non-capturing, is 200. | between the "?" and the ":". Thus the two patterns |
| 2507 | ||
| 2508 | As a convenient shorthand, if any option settings are | (?i:saturday|sunday) |
| 2509 | required at the start of a non-capturing subpattern, the | (?:(?i)saturday|sunday) |
| 2510 | option letters may appear between the "?" and the ":". Thus | |
| 2511 | the two patterns | match exactly the same set of strings. Because alternative branches are |
| 2512 | tried from left to right, and options are not reset until the end of | |
| 2513 | (?i:saturday|sunday) | the subpattern is reached, an option setting in one branch does affect |
| 2514 | (?:(?i)saturday|sunday) | subsequent branches, so the above patterns match "SUNDAY" as well as |
| 2515 | "Saturday". | |
| 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 "Saturday". | ||
| 2516 | ||
| 2517 | ||
| 2518 | NAMED SUBPATTERNS | NAMED SUBPATTERNS |
| 2519 | ||
| 2520 | Identifying capturing parentheses by number is simple, but | Identifying capturing parentheses by number is simple, but it can be |
| 2521 | it can be very hard to keep track of the numbers in compli- | very hard to keep track of the numbers in complicated regular expres- |
| 2522 | cated regular expressions. Furthermore, if an expression is | sions. Furthermore, if an expression is modified, the numbers may |
| 2523 | modified, the numbers may change. To help with the diffi- | change. To help with this difficulty, PCRE supports the naming of sub- |
| 2524 | culty, PCRE supports the naming of subpatterns, something | patterns, something that Perl does not provide. The Python syntax |
| 2525 | that Perl does not provide. The Python syntax (?P<name>...) | (?P<name>...) is used. Names consist of alphanumeric characters and |
| 2526 | is used. Names consist of alphanumeric characters and under- | underscores, and must be unique within a pattern. |
| 2527 | scores, and must be unique within a pattern. | |
| 2528 | Named capturing parentheses are still allocated numbers as well as | |
| 2529 | Named capturing parentheses are still allocated numbers as | names. The PCRE API provides function calls for extracting the name-to- |
| 2530 | well as names. The PCRE API provides function calls for | number translation table from a compiled pattern. There is also a con- |
| 2531 | extracting the name-to-number translation table from a com- | venience function for extracting a captured substring by name. For fur- |
| 2532 | piled pattern. For further details see the pcreapi documen- | ther details see the pcreapi documentation. |
| tation. | ||
| 2533 | ||
| 2534 | ||
| 2535 | REPETITION | REPETITION |
| 2536 | ||
| 2537 | Repetition is specified by quantifiers, which can follow any | Repetition is specified by quantifiers, which can follow any of the |
| 2538 | of the following items: | following items: |
| 2539 | ||
| 2540 | a literal data character | |
| 2541 | the . metacharacter | |
| 2542 | the \C escape sequence | |
| 2543 | the \X escape sequence (in UTF-8 mode with Unicode properties) | |
| 2544 | an escape such as \d that matches a single character | |
| 2545 | a character class | |
| 2546 | a back reference (see next section) | |
| 2547 | a parenthesized subpattern (unless it is an assertion) | |
| 2548 | ||
| 2549 | The general repetition quantifier specifies a minimum and maximum num- | |
| 2550 | ber of permitted matches, by giving the two numbers in curly brackets | |
| 2551 | (braces), separated by a comma. The numbers must be less than 65536, | |
| 2552 | and the first must be less than or equal to the second. For example: | |
| 2553 | ||
| 2554 | z{2,4} | |
| 2555 | ||
| 2556 | matches "zz", "zzz", or "zzzz". A closing brace on its own is not a | |
| 2557 | special character. If the second number is omitted, but the comma is | |
| 2558 | present, there is no upper limit; if the second number and the comma | |
| 2559 | are both omitted, the quantifier specifies an exact number of required | |
| 2560 | matches. Thus | |
| 2561 | ||
| 2562 | [aeiou]{3,} | |
| 2563 | ||
| 2564 | matches at least 3 successive vowels, but may match many more, while | |
| 2565 | ||
| 2566 | \d{8} | |
| 2567 | ||
| 2568 | matches exactly 8 digits. An opening curly bracket that appears in a | |
| 2569 | position where a quantifier is not allowed, or one that does not match | |
| 2570 | the syntax of a quantifier, is taken as a literal character. For exam- | |
| 2571 | ple, {,6} is not a quantifier, but a literal string of four characters. | |
| 2572 | ||
| 2573 | In UTF-8 mode, quantifiers apply to UTF-8 characters rather than to | |
| 2574 | individual bytes. Thus, for example, \x{100}{2} matches two UTF-8 char- | |
| 2575 | acters, each of which is represented by a two-byte sequence. Similarly, | |
| 2576 | when Unicode property support is available, \X{3} matches three Unicode | |
| 2577 | extended sequences, each of which may be several bytes long (and they | |
| 2578 | may be of different lengths). | |
| 2579 | ||
| 2580 | The quantifier {0} is permitted, causing the expression to behave as if | |
| 2581 | the previous item and the quantifier were not present. | |
| 2582 | ||
| 2583 | a literal data character | For convenience (and historical compatibility) the three most common |
| 2584 | the . metacharacter | quantifiers have single-character abbreviations: |
| the \C escape sequence | ||
| escapes such as \d that match single characters | ||
| a character class | ||
| a back reference (see next section) | ||
| a parenthesized subpattern (unless it is an assertion) | ||
| The general repetition quantifier specifies a minimum and | ||
| maximum number 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. Thus | ||
| [aeiou]{3,} | ||
| matches at least 3 successive vowels, but may match many | ||
| more, while | ||
| \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 example, {,6} is not a quantif- | ||
| ier, but a literal string of four characters. | ||
| In UTF-8 mode, quantifiers apply to UTF-8 characters rather | ||
| than to individual bytes. Thus, for example, \x{100}{2} | ||
| matches two UTF-8 characters, each of which is represented | ||
| by a two-byte sequence. | ||
| The quantifier {0} is permitted, causing the expression to | ||
| behave as if the previous item and the quantifier were not | ||
| present. | ||
| For convenience (and historical compatibility) the three | ||
| most common quantifiers have single-character abbreviations: | ||
| * is equivalent to {0,} | ||
| + is equivalent to {1,} | ||
| ? is equivalent to {0,1} | ||
| It is possible to construct infinite loops by following a | ||
| subpattern that can match no characters with a quantifier | ||
| that has no upper limit, for example: | ||
| (a?)* | ||
| Earlier versions of Perl and PCRE used to give an error at | ||
| compile time for such patterns. However, because there are | ||
| cases where this can be useful, such patterns are now | ||
| accepted, but if any repetition of the subpattern does in | ||
| fact match no characters, the loop is forcibly broken. | ||
| By default, the quantifiers are "greedy", that is, they | ||
| match as much as possible (up to the maximum number of per- | ||
| mitted times), without causing the rest of the pattern to | ||
| fail. The classic example of where this gives problems is in | ||
| trying to match comments in C programs. These appear between | ||
| the sequences /* and */ and within the sequence, individual | ||
| * and / characters may appear. An attempt to match C com- | ||
| ments by applying the pattern | ||
| /\*.*\*/ | ||
| to the string | ||
| /* first command */ not comment /* second comment */ | ||
| fails, because it matches the entire string owing to the | ||
| greediness of the .* item. | ||
| However, if a quantifier is followed by a question mark, it | ||
| ceases to be greedy, and instead matches the minimum number | ||
| of times possible, so the pattern | ||
| /\*.*?\*/ | ||
| does the right thing with the C comments. The meaning of the | ||
| various quantifiers is not otherwise changed, just the pre- | ||
| ferred number of matches. Do not confuse this use of ques- | ||
| tion mark with its use as a quantifier in its own right. | ||
| Because it has two uses, it can sometimes appear doubled, as | ||
| in | ||
| \d??\d | ||
| which matches one digit by preference, but can match two if | ||
| that is the only way the rest of the pattern matches. | ||
| If the PCRE_UNGREEDY option is set (an option which is not | ||
| available in Perl), the quantifiers are not greedy by | ||
| default, but individual ones can be made greedy by following | ||
| them with a question mark. In other words, it inverts the | ||
| default behaviour. | ||
| When a parenthesized subpattern is quantified with a minimum | ||
| repeat count that is greater than 1 or with a limited max- | ||
| imum, more store is required for the compiled pattern, in | ||
| proportion to the size of the minimum or maximum. | ||
| If a pattern starts with .* or .{0,} and the PCRE_DOTALL | ||
| option (equivalent to Perl's /s) is set, thus allowing the . | ||
| to match newlines, the pattern is implicitly anchored, | ||
| because whatever follows will be tried against every charac- | ||
| ter position in the subject string, so there is no point in | ||
| retrying the overall match at any position after the first. | ||
| PCRE normally treats such a pattern as though it were pre- | ||
| ceded by \A. | ||
| In cases where it is known that the subject string contains | ||
| no newlines, it is worth setting PCRE_DOTALL in order to | ||
| obtain this optimization, or alternatively using ^ to indi- | ||
| cate anchoring explicitly. | ||
| However, there is one situation where the optimization can- | ||
| not be used. When .* is inside capturing parentheses that | ||
| are the subject of a backreference elsewhere in the pattern, | ||
| a match at the start may fail, and a later one succeed. Con- | ||
| sider, for example: | ||
| (.*)abc\1 | ||
| If the subject is "xyz123abc123" the match point is the | ||
| fourth character. For this reason, such a pattern is not | ||
| implicitly anchored. | ||
| When a capturing subpattern is repeated, the value captured | ||
| is the substring that matched the final iteration. For exam- | ||
| ple, after | ||
| (tweedle[dume]{3}\s*)+ | ||
| has matched "tweedledum tweedledee" the value of the cap- | ||
| tured substring is "tweedledee". However, if there are | ||
| nested capturing subpatterns, the corresponding captured | ||
| values may have been set in previous iterations. For exam- | ||
| ple, after | ||
| 2585 | ||
| 2586 | /(a|(b))+/ | * is equivalent to {0,} |
| 2587 | + is equivalent to {1,} | |
| 2588 | ? is equivalent to {0,1} | |
| 2589 | ||
| 2590 | matches "aba" the value of the second captured substring is | It is possible to construct infinite loops by following a subpattern |
| 2591 | "b". | that can match no characters with a quantifier that has no upper limit, |
| 2592 | for example: | |
| 2593 | ||
| 2594 | (a?)* | |
| 2595 | ||
| 2596 | Earlier versions of Perl and PCRE used to give an error at compile time | |
| 2597 | for such patterns. However, because there are cases where this can be | |
| 2598 | useful, such patterns are now accepted, but if any repetition of the | |
| 2599 | subpattern does in fact match no characters, the loop is forcibly bro- | |
| 2600 | ken. | |
| 2601 | ||
| 2602 | By default, the quantifiers are "greedy", that is, they match as much | |
| 2603 | as possible (up to the maximum number of permitted times), without | |
| 2604 | causing the rest of the pattern to fail. The classic example of where | |
| 2605 | this gives problems is in trying to match comments in C programs. These | |
| 2606 | appear between /* and */ and within the comment, individual * and / | |
| 2607 | characters may appear. An attempt to match C comments by applying the | |
| 2608 | pattern | |
| 2609 | ||
| 2610 | /\*.*\*/ | |
| 2611 | ||
| 2612 | to the string | |
| 2613 | ||
| 2614 | /* first comment */ not comment /* second comment */ | |
| 2615 | ||
| 2616 | fails, because it matches the entire string owing to the greediness of | |
| 2617 | the .* item. | |
| 2618 | ||
| 2619 | However, if a quantifier is followed by a question mark, it ceases to | |
| 2620 | be greedy, and instead matches the minimum number of times possible, so | |
| 2621 | the pattern | |
| 2622 | ||
| 2623 | /\*.*?\*/ | |
| 2624 | ||
| 2625 | does the right thing with the C comments. The meaning of the various | |
| 2626 | quantifiers is not otherwise changed, just the preferred number of | |
| 2627 | matches. Do not confuse this use of question mark with its use as a | |
| 2628 | quantifier in its own right. Because it has two uses, it can sometimes | |
| 2629 | appear doubled, as in | |
| 2630 | ||
| 2631 | \d??\d | |
| 2632 | ||
| 2633 | which matches one digit by preference, but can match two if that is the | |
| 2634 | only way the rest of the pattern matches. | |
| 2635 | ||
| 2636 | If the PCRE_UNGREEDY option is set (an option which is not available in | |
| 2637 | Perl), the quantifiers are not greedy by default, but individual ones | |
| 2638 | can be made greedy by following them with a question mark. In other | |
| 2639 | words, it inverts the default behaviour. | |
| 2640 | ||
| 2641 | When a parenthesized subpattern is quantified with a minimum repeat | |
| 2642 | count that is greater than 1 or with a limited maximum, more memory is | |
| 2643 | required for the compiled pattern, in proportion to the size of the | |
| 2644 | minimum or maximum. | |
| 2645 | ||
| 2646 | If a pattern starts with .* or .{0,} and the PCRE_DOTALL option (equiv- | |
| 2647 | alent to Perl's /s) is set, thus allowing the . to match newlines, the | |
| 2648 | pattern is implicitly anchored, because whatever follows will be tried | |
| 2649 | against every character position in the subject string, so there is no | |
| 2650 | point in retrying the overall match at any position after the first. | |
| 2651 | PCRE normally treats such a pattern as though it were preceded by \A. | |
| 2652 | ||
| 2653 | In cases where it is known that the subject string contains no new- | |
| 2654 | lines, it is worth setting PCRE_DOTALL in order to obtain this opti- | |
| 2655 | mization, or alternatively using ^ to indicate anchoring explicitly. | |
| 2656 | ||
| 2657 | However, there is one situation where the optimization cannot be used. | |
| 2658 | When .* is inside capturing parentheses that are the subject of a | |
| 2659 | backreference elsewhere in the pattern, a match at the start may fail, | |
| 2660 | and a later one succeed. Consider, for example: | |
| 2661 | ||