diff options
author | ph10 <ph10@6239d852-aaf2-0410-a92c-79f79f948069> | 2014-09-28 17:39:28 +0000 |
---|---|---|
committer | ph10 <ph10@6239d852-aaf2-0410-a92c-79f79f948069> | 2014-09-28 17:39:28 +0000 |
commit | f30ff3deb77413a8059cfe06dc6db30047e8dcde (patch) | |
tree | 73e5c69fb89a5edfc680ae9b23b8f819058e7c6d /doc/html/pcre2.html | |
parent | 8ad769e3db843fd70ad105d2af2205a94c3b521e (diff) | |
download | pcre2-f30ff3deb77413a8059cfe06dc6db30047e8dcde.tar.gz |
More draft documentation.
git-svn-id: svn://vcs.exim.org/pcre2/code/trunk@82 6239d852-aaf2-0410-a92c-79f79f948069
Diffstat (limited to 'doc/html/pcre2.html')
-rw-r--r-- | doc/html/pcre2.html | 182 |
1 files changed, 182 insertions, 0 deletions
diff --git a/doc/html/pcre2.html b/doc/html/pcre2.html new file mode 100644 index 0000000..f8672b8 --- /dev/null +++ b/doc/html/pcre2.html @@ -0,0 +1,182 @@ +<html> +<head> +<title>pcre2 specification</title> +</head> +<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB"> +<h1>pcre2 man page</h1> +<p> +Return to the <a href="index.html">PCRE2 index page</a>. +</p> +<p> +This page is part of the PCRE2 HTML documentation. It was generated +automatically from the original man page. If there is any nonsense in it, +please consult the man page, in case the conversion went wrong. +<br> +<ul> +<li><a name="TOC1" href="#SEC1">INTRODUCTION</a> +<li><a name="TOC2" href="#SEC2">SECURITY CONSIDERATIONS</a> +<li><a name="TOC3" href="#SEC3">USER DOCUMENTATION</a> +<li><a name="TOC4" href="#SEC4">AUTHOR</a> +<li><a name="TOC5" href="#SEC5">REVISION</a> +</ul> +<br><a name="SEC1" href="#TOC1">INTRODUCTION</a><br> +<P> +PCRE2 is the name used for a revised API for the PCRE library, which is a set +of functions, written in C, that implement regular expression pattern matching +using the same syntax and semantics as Perl, with just a few differences. Some +features that appeared in Python and the original PCRE before they appeared in +Perl are also available using the Python syntax, there is some support for one +or two .NET and Oniguruma syntax items, and there are options for requesting +some minor changes that give better ECMAScript (aka JavaScript) compatibility. +</P> +<P> +The source code for PCRE2 can be compiled to support 8-bit, 16-bit, or 32-bit +code units, which means that up to three separate libraries may be installed. +The original work to extend PCRE to 16-bit and 32-bit code units was done by +Zoltan Herczeg and Christian Persch, respectively. In all three cases, strings +can be interpreted either as one character per code unit, or as UTF-encoded +Unicode, with support for Unicode general category properties. Unicode is +optional at build time, and must be enabled explicitly at run time. The version +of Unicode in use can be discovered by running +<pre> + pcre2test -C +</PRE> +</P> +<P> +The three libraries contain identical sets of functions, with names ending in +_8, _16, or _32, respectively (for example, <b>pcre2_compile_8()</b>). However, +by defining PCRE2_CODE_UNIT_WIDTH to be 8, 16, or 32, a program that uses just +one code unit width can be written using generic names such as +<b>pcre2_compile()</b>, and the documentation is written assuming that this is +the case. +</P> +<P> +In addition to the Perl-compatible matching function, PCRE2 contains an +alternative function that matches the same compiled patterns in a different +way. In certain circumstances, the alternative function has some advantages. +For a discussion of the two matching algorithms, see the +<a href="pcre2matching.html"><b>pcre2matching</b></a> +page. +</P> +<P> +Details of exactly which Perl regular expression features are and are not +supported by PCRE2 are given in separate documents. See the +<a href="pcre2pattern.html"><b>pcre2pattern</b></a> +and +<a href="pcre2compat.html"><b>pcre2compat</b></a> +pages. There is a syntax summary in the +<a href="pcre2syntax.html"><b>pcre2syntax</b></a> +page. +</P> +<P> +Some features of PCRE2 can be included, excluded, or changed when the library +is built. The +<a href="pcre2_config.html"><b>pcre2_config()</b></a> +function makes it possible for a client to discover which features are +available. The features themselves are described in the +<a href="pcre2build.html"><b>pcre2build</b></a> +page. Documentation about building PCRE2 for various operating systems can be +found in the +<a href="README.txt"><b>README</b></a> +and +<a href="NON-AUTOTOOLS-BUILD.txt"><b>NON-AUTOTOOLS_BUILD</b></a> +files in the source distribution. +</P> +<P> +The libraries contains a number of undocumented internal functions and data +tables that are used by more than one of the exported external functions, but +which are not intended for use by external callers. Their names all begin with +"_pcre2", which hopefully will not provoke any name clashes. In some +environments, it is possible to control which external symbols are exported +when a shared library is built, and in these cases the undocumented symbols are +not exported. +</P> +<br><a name="SEC2" href="#TOC1">SECURITY CONSIDERATIONS</a><br> +<P> +If you are using PCRE2 in a non-UTF application that permits users to supply +arbitrary patterns for compilation, you should be aware of a feature that +allows users to turn on UTF support from within a pattern, provided that PCRE2 +was built with Unicode support. For example, an 8-bit pattern that begins with +"(*UTF)" turns on UTF-8 mode, which interprets patterns and subjects as strings +of UTF-8 code units instead of individual 8-bit characters. This causes both +the pattern and any data against which it is matched to be checked for UTF-8 +validity. If the data string is very long, such a check might use sufficiently +many resources as to cause your application to lose performance. +</P> +<P> +One way of guarding against this possibility is to use the +<b>pcre2_pattern_info()</b> function to check the compiled pattern's options for +UTF. Alternatively, you can set the PCRE2_NEVER_UTF option at compile time. +This causes an compile time error if a pattern contains a UTF-setting sequence. +</P> +<P> +If your application is one that supports UTF, be aware that validity checking +can take time. If the same data string is to be matched many times, you can use +the PCRE2_NO_UTF_CHECK option for the second and subsequent matches to avoid +running redundant checks. +</P> +<P> +Another way that performance can be hit is by running a pattern that has a very +large search tree against a string that will never match. Nested unlimited +repeats in a pattern are a common example. PCRE2 provides some protection +against this: see the <b>pcre2_set_match_limit()</b> function in the +<a href="pcre2api.html"><b>pcre2api</b></a> +page. +</P> +<br><a name="SEC3" href="#TOC1">USER DOCUMENTATION</a><br> +<P> +The user documentation for PCRE2 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, +the descriptions of the <b>pcre2grep</b> and <b>pcre2test</b> programs are in +files called <b>pcre2grep.txt</b> and <b>pcre2test.txt</b>, respectively. The +remaining sections, except for the <b>pcre2demo</b> section (which is a program +listing), and the short pages for individual functions, are concatenated in +<b>pcre2.txt</b>, for ease of searching. The sections are as follows: +<pre> + pcre2 this document FIXME CHECK THIS LIST + pcre2-config show PCRE2 installation configuration information + pcre2api details of PCRE2's native C API + pcre2build building PCRE2 + pcre2callout details of the callout feature + pcre2compat discussion of Perl compatibility + pcre2demo a demonstration C program that uses PCRE2 + pcre2grep description of the <b>pcre2grep</b> command (8-bit only) + pcre2jit discussion of the just-in-time optimization support + pcre2limits details of size and other limits + pcre2matching discussion of the two matching algorithms + pcre2partial details of the partial matching facility + pcre2pattern syntax and semantics of supported regular expressions + pcre2perform discussion of performance issues + pcre2posix the POSIX-compatible C API for the 8-bit library + pcre2sample discussion of the pcre2demo program + pcre2stack discussion of stack usage + pcre2syntax quick syntax reference + pcre2test description of the <b>pcre2test</b> testing command + pcre2unicode discussion of Unicode and UTF support +</pre> +In the "man" and HTML formats, there is also a short page for each C library +function, listing its arguments and results. +</P> +<br><a name="SEC4" href="#TOC1">AUTHOR</a><br> +<P> +Philip Hazel +<br> +University Computing Service +<br> +Cambridge CB2 3QH, England. +<br> +</P> +<P> +Putting an actual email address here is a spam magnet. If you want to email me, +use my two initials, followed by the two digits 10, at the domain cam.ac.uk. +</P> +<br><a name="SEC5" href="#TOC1">REVISION</a><br> +<P> +Last updated: 28 September 2014 +<br> +Copyright © 1997-2014 University of Cambridge. +<br> +<p> +Return to the <a href="index.html">PCRE2 index page</a>. +</p> |