/[pcre]/code/trunk/doc/pcre.3
ViewVC logotype

Contents of /code/trunk/doc/pcre.3

Parent Directory Parent Directory | Revision Log Revision Log


Revision 954 - (hide annotations) (download)
Sat Mar 31 18:09:26 2012 UTC (2 years, 8 months ago) by ph10
File size: 6304 byte(s)
Add date and PCRE version to .TH macros of all man pages.

1 ph10 954 .TH PCRE 3 "10 January 2012" "PCRE 8.30"
2 nigel 41 .SH NAME
3 nigel 63 PCRE - Perl-compatible regular expressions
4 nigel 75 .SH INTRODUCTION
5 nigel 63 .rs
6     .sp
7 nigel 41 The PCRE library is a set of functions that implement regular expression
8 nigel 63 pattern matching using the same syntax and semantics as Perl, with just a few
9 ph10 456 differences. Some features that appeared in Python and PCRE before they
10     appeared in Perl are also available using the Python syntax, there is some
11     support for one or two .NET and Oniguruma syntax items, and there is an option
12     for requesting some minor changes that give better JavaScript compatibility.
13 nigel 75 .P
14 ph10 903 Starting with release 8.30, it is possible to compile two separate PCRE
15 ph10 846 libraries: the original, which supports 8-bit character strings (including
16     UTF-8 strings), and a second library that supports 16-bit character strings
17     (including UTF-16 strings). The build process allows either one or both to be
18 ph10 903 built. The majority of the work to make this possible was done by Zoltan
19 ph10 846 Herczeg.
20     .P
21     The two libraries contain identical sets of functions, except that the names in
22     the 16-bit library start with \fBpcre16_\fP instead of \fBpcre_\fP. To avoid
23     over-complication and reduce the documentation maintenance load, most of the
24     documentation describes the 8-bit library, with the differences for the 16-bit
25     library described separately in the
26     .\" HREF
27     \fBpcre16\fP
28     .\"
29 ph10 903 page. References to functions or structures of the form \fIpcre[16]_xxx\fP
30     should be read as meaning "\fIpcre_xxx\fP when using the 8-bit library and
31 ph10 861 \fIpcre16_xxx\fP when using the 16-bit library".
32 ph10 846 .P
33 ph10 572 The current implementation of PCRE corresponds approximately with Perl 5.12,
34 ph10 846 including support for UTF-8/16 encoded strings and Unicode general category
35     properties. However, UTF-8/16 and Unicode support has to be explicitly enabled;
36     it is not the default. The Unicode tables correspond to Unicode release 6.0.0.
37 nigel 93 .P
38     In addition to the Perl-compatible matching function, PCRE contains an
39 ph10 456 alternative function that matches the same compiled patterns in a different
40     way. In certain circumstances, the alternative function has some advantages.
41     For a discussion of the two matching algorithms, see the
42 nigel 77 .\" HREF
43     \fBpcrematching\fP
44     .\"
45     page.
46     .P
47 nigel 75 PCRE is written in C and released as a C library. A number of people have
48 nigel 77 written wrappers and interfaces of various kinds. In particular, Google Inc.
49 ph10 846 have provided a comprehensive C++ wrapper for the 8-bit library. This is now
50     included as part of the PCRE distribution. The
51 nigel 77 .\" HREF
52     \fBpcrecpp\fP
53     .\"
54     page has details of this interface. Other people's contributions can be found
55 ph10 583 in the \fIContrib\fP directory at the primary FTP site, which is:
56 nigel 75 .sp
57 nigel 63 .\" HTML <a href="ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre">
58     .\" </a>
59     ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre
60 nigel 75 .P
61 nigel 63 Details of exactly which Perl regular expression features are and are not
62     supported by PCRE are given in separate documents. See the
63     .\" HREF
64 ph10 583 \fBpcrepattern\fP
65 nigel 63 .\"
66     and
67     .\" HREF
68 ph10 583 \fBpcrecompat\fP
69 nigel 63 .\"
70 ph10 208 pages. There is a syntax summary in the
71     .\" HREF
72 ph10 583 \fBpcresyntax\fP
73 ph10 208 .\"
74     page.
75 nigel 75 .P
76 nigel 63 Some features of PCRE can be included, excluded, or changed when the library is
77     built. The
78     .\" HREF
79 ph10 583 \fBpcre_config()\fP
80 nigel 63 .\"
81     function makes it possible for a client to discover which features are
82 nigel 75 available. The features themselves are described in the
83     .\" HREF
84     \fBpcrebuild\fP
85     .\"
86     page. Documentation about building PCRE for various operating systems can be
87 ph10 456 found in the \fBREADME\fP and \fBNON-UNIX-USE\fP files in the source
88     distribution.
89 nigel 77 .P
90 ph10 846 The libraries contains a number of undocumented internal functions and data
91 nigel 77 tables that are used by more than one of the exported external functions, but
92     which are not intended for use by external callers. Their names all begin with
93 ph10 846 "_pcre_" or "_pcre16_", which hopefully will not provoke any name clashes. In
94     some environments, it is possible to control which external symbols are
95     exported when a shared library is built, and in these cases the undocumented
96     symbols are not exported.
97 nigel 75 .
98     .
99     .SH "USER DOCUMENTATION"
100 nigel 63 .rs
101     .sp
102 nigel 75 The user documentation for PCRE comprises a number of different sections. In
103     the "man" format, each of these is a separate "man page". In the HTML format,
104     each is a separate page, linked from the index page. In the plain text format,
105 ph10 429 all the sections, except the \fBpcredemo\fP section, are concatenated, for ease
106     of searching. The sections are as follows:
107 nigel 75 .sp
108 nigel 63 pcre this document
109 ph10 903 pcre16 details of the 16-bit library
110 ph10 153 pcre-config show PCRE installation configuration information
111 nigel 77 pcreapi details of PCRE's native C API
112 nigel 63 pcrebuild options for building PCRE
113     pcrecallout details of the callout feature
114     pcrecompat discussion of Perl compatibility
115 ph10 846 pcrecpp details of the C++ wrapper for the 8-bit library
116 ph10 429 pcredemo a demonstration C program that uses PCRE
117 ph10 846 pcregrep description of the \fBpcregrep\fP command (8-bit only)
118 ph10 691 pcrejit discussion of the just-in-time optimization support
119     pcrelimits details of size and other limits
120 nigel 77 pcrematching discussion of the two matching algorithms
121 nigel 75 pcrepartial details of the partial matching facility
122     .\" JOIN
123 nigel 63 pcrepattern syntax and semantics of supported
124     regular expressions
125     pcreperform discussion of performance issues
126 ph10 846 pcreposix the POSIX-compatible C API for the 8-bit library
127 nigel 75 pcreprecompile details of saving and re-using precompiled patterns
128 ph10 429 pcresample discussion of the pcredemo program
129 nigel 91 pcrestack discussion of stack usage
130 ph10 456 pcresyntax quick syntax reference
131 nigel 75 pcretest description of the \fBpcretest\fP testing command
132 ph10 846 pcreunicode discussion of Unicode and UTF-8/16 support
133 nigel 75 .sp
134 nigel 63 In addition, in the "man" and HTML formats, there is a short page for each
135 ph10 846 8-bit C library function, listing its arguments and results.
136 nigel 75 .
137     .
138 nigel 41 .SH AUTHOR
139 nigel 63 .rs
140     .sp
141 ph10 99 .nf
142 nigel 77 Philip Hazel
143 ph10 99 University Computing Service
144 nigel 93 Cambridge CB2 3QH, England.
145 ph10 99 .fi
146 nigel 77 .P
147     Putting an actual email address here seems to have been a spam magnet, so I've
148 ph10 153 taken it away. If you want to email me, use my two initials, followed by the
149     two digits 10, at the domain cam.ac.uk.
150 ph10 99 .
151     .
152     .SH REVISION
153     .rs
154 nigel 75 .sp
155 ph10 99 .nf
156 ph10 861 Last updated: 10 January 2012
157 ph10 846 Copyright (c) 1997-2012 University of Cambridge.
158 ph10 99 .fi

Properties

Name Value
svn:eol-style native
svn:keywords "Author Date Id Revision Url"

webmaster@exim.org
ViewVC Help
Powered by ViewVC 1.1.12