diff options
Diffstat (limited to 'srclib/pcre/doc/pcre.3')
| -rw-r--r-- | srclib/pcre/doc/pcre.3 | 204 |
1 files changed, 0 insertions, 204 deletions
diff --git a/srclib/pcre/doc/pcre.3 b/srclib/pcre/doc/pcre.3 deleted file mode 100644 index 54b0c3359b..0000000000 --- a/srclib/pcre/doc/pcre.3 +++ /dev/null @@ -1,204 +0,0 @@ -.TH PCRE 3 -.SH NAME -PCRE - Perl-compatible regular expressions -.SH INTRODUCTION -.rs -.sp -The PCRE library is a set of functions that implement regular expression -pattern matching using the same syntax and semantics as Perl, with just a few -differences. The current implementation of PCRE (release 5.x) corresponds -approximately with Perl 5.8, including support for UTF-8 encoded strings and -Unicode general category properties. However, this support has to be explicitly -enabled; it is not the default. -.P -PCRE is written in C and released as a C library. A number of people have -written wrappers and interfaces of various kinds. A C++ class is included in -these contributions, which can be found in the \fIContrib\fR directory at the -primary FTP site, which is: -.sp -.\" HTML <a href="ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre"> -.\" </a> -ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre -.P -Details of exactly which Perl regular expression features are and are not -supported by PCRE are given in separate documents. See the -.\" HREF -\fBpcrepattern\fR -.\" -and -.\" HREF -\fBpcrecompat\fR -.\" -pages. -.P -Some features of PCRE can be included, excluded, or changed when the library is -built. The -.\" HREF -\fBpcre_config()\fR -.\" -function makes it possible for a client to discover which features are -available. The features themselves are described in the -.\" HREF -\fBpcrebuild\fP -.\" -page. Documentation about building PCRE for various operating systems can be -found in the \fBREADME\fP file in the source distribution. -. -. -.SH "USER DOCUMENTATION" -.rs -.sp -The user documentation for PCRE comprises a number of different sections. In -the "man" format, each of these is a separate "man page". In the HTML format, -each is a separate page, linked from the index page. In the plain text format, -all the sections are concatenated, for ease of searching. The sections are as -follows: -.sp - pcre this document - pcreapi details of PCRE's native API - pcrebuild options for building PCRE - pcrecallout details of the callout feature - pcrecompat discussion of Perl compatibility - pcregrep description of the \fBpcregrep\fP command - pcrepartial details of the partial matching facility -.\" JOIN - pcrepattern syntax and semantics of supported - regular expressions - pcreperform discussion of performance issues - pcreposix the POSIX-compatible API - pcreprecompile details of saving and re-using precompiled patterns - pcresample discussion of the sample program - pcretest description of the \fBpcretest\fP testing command -.sp -In addition, in the "man" and HTML formats, there is a short page for each -library function, listing its arguments and results. -. -. -.SH LIMITATIONS -.rs -.sp -There are some size limitations in PCRE but it is hoped that they will never in -practice be relevant. -.P -The maximum length of a compiled pattern is 65539 (sic) bytes if PCRE is -compiled with the default internal linkage size of 2. If you want to process -regular expressions that are truly enormous, you can compile PCRE with an -internal linkage size of 3 or 4 (see the \fBREADME\fP file in the source -distribution and the -.\" HREF -\fBpcrebuild\fP -.\" -documentation for details). In these cases the limit is substantially larger. -However, the speed of execution will be slower. -.P -All values in repeating quantifiers must be less than 65536. -The maximum number of capturing subpatterns is 65535. -.P -There is no limit to the number of non-capturing subpatterns, but the maximum -depth of nesting of all kinds of parenthesized subpattern, including capturing -subpatterns, assertions, and other types of subpattern, is 200. -.P -The maximum length of a subject string is the largest positive number that an -integer variable can hold. However, PCRE uses recursion to handle subpatterns -and indefinite repetition. This means that the available stack space may limit -the size of a subject string that can be processed by certain patterns. -.sp -.\" HTML <a name="utf8support"></a> -. -. -.SH "UTF-8 AND UNICODE PROPERTY SUPPORT" -.rs -.sp -From release 3.3, PCRE has had some support for character strings encoded in -the UTF-8 format. For release 4.0 this was greatly extended to cover most -common requirements, and in release 5.0 additional support for Unicode general -category properties was added. -.P -In order process UTF-8 strings, you must build PCRE to include UTF-8 support in -the code, and, in addition, you must call -.\" HREF -\fBpcre_compile()\fP -.\" -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. -.P -If you compile PCRE with UTF-8 support, but do not use it at run time, the -library will be a bit bigger, but the additional run time overhead is limited -to testing the PCRE_UTF8 flag in several places, so should not be very large. -.P -If PCRE is built with Unicode character property support (which implies UTF-8 -support), the escape sequences \ep{..}, \eP{..}, and \eX are supported. -The available properties that can be tested are limited to the general -category properties such as Lu for an upper case letter or Nd for a decimal -number. A full list is given in the -.\" HREF -\fBpcrepattern\fP -.\" -documentation. The PCRE library is increased in size by about 90K when Unicode -property support is included. -.P -The following comments apply when PCRE is running in UTF-8 mode: -.P -1. When you set the PCRE_UTF8 flag, the strings passed as patterns and subjects -are checked for validity on entry to the relevant functions. If an invalid -UTF-8 string is passed, an error return is given. In some situations, you may -already know that your strings are valid, and therefore want to skip these -checks in order to improve performance. If you set the PCRE_NO_UTF8_CHECK flag -at compile time or at run time, PCRE assumes that the pattern or subject it -is given (respectively) contains only valid UTF-8 codes. In this case, it does -not diagnose an invalid UTF-8 string. If you pass an invalid UTF-8 string to -PCRE when PCRE_NO_UTF8_CHECK is set, the results are undefined. Your program -may crash. -.P -2. In a pattern, the escape sequence \ex{...}, where the contents 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: \ex{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. -.P -3. The original hexadecimal escape sequence, \exhh, matches a two-byte UTF-8 -character if the value is greater than 127. -.P -4. Repeat quantifiers apply to complete UTF-8 characters, not to individual -bytes, for example: \ex{100}{3}. -.P -5. The dot metacharacter matches one UTF-8 character instead of a single byte. -.P -6. The escape sequence \eC can be used to match a single byte in UTF-8 mode, -but its use can lead to some strange effects. -.P -7. The character escapes \eb, \eB, \ed, \eD, \es, \eS, \ew, and \eW correctly -test characters of any code value, but the characters that PCRE recognizes as -digits, spaces, or word characters remain the same set as before, all with -values less than 256. This remains true even when PCRE includes Unicode -property support, because to do otherwise would slow down PCRE in many common -cases. If you really want to test for a wider sense of, say, "digit", you -must use Unicode property tests such as \ep{Nd}. -.P -8. Similarly, characters that match the POSIX named character classes are all -low-valued characters. -.P -9. Case-insensitive matching applies only to characters whose values are less -than 128, unless PCRE is built with Unicode property support. Even when Unicode -property support is available, PCRE still uses its own character tables when -checking the case of low-valued characters, so as not to degrade performance. -The Unicode property information is used only for characters with higher -values. -. -.SH AUTHOR -.rs -.sp -Philip Hazel <ph10@cam.ac.uk> -.br -University Computing Service, -.br -Cambridge CB2 3QG, England. -.br -Phone: +44 1223 334714 -.sp -.in 0 -Last updated: 09 September 2004 -.br -Copyright (c) 1997-2004 University of Cambridge. |