mirror of
https://github.com/php/php-src.git
synced 2024-10-07 09:46:10 +00:00
240 lines
10 KiB
Plaintext
240 lines
10 KiB
Plaintext
|
README file for PCRE (Perl-compatible regular expression library)
|
||
|
-----------------------------------------------------------------
|
||
|
|
||
|
The latest release of PCRE is always available from
|
||
|
|
||
|
ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/pcre-xxx.tar.gz
|
||
|
|
||
|
Please read the NEWS file if you are upgrading from a previous release.
|
||
|
|
||
|
|
||
|
Building PCRE on a Unix system
|
||
|
------------------------------
|
||
|
|
||
|
To build PCRE on a Unix system, run the "configure" command in the PCRE
|
||
|
distribution directory. This is a standard GNU "autoconf" configuration script,
|
||
|
for which generic instructions are supplied in INSTALL. On many systems just
|
||
|
running "./configure" is sufficient, but the usual methods of changing standard
|
||
|
defaults are available. For example
|
||
|
|
||
|
CFLAGS='-O2 -Wall' ./configure --prefix=/opt/local
|
||
|
|
||
|
specifies that the C compiler should be run with the flags '-O2 -Wall' instead
|
||
|
of the default, and that "make install" should install PCRE under /opt/local
|
||
|
instead of the default /usr/local. The "configure" script builds thre files:
|
||
|
|
||
|
. Makefile is built by copying Makefile.in and making substitutions.
|
||
|
. config.h is built by copying config.in and making substitutions.
|
||
|
. pcre-config is built by copying pcre-config.in and making substitutions.
|
||
|
|
||
|
Once "configure" has run, you can run "make". It builds two libraries called
|
||
|
libpcre and libpcreposix, a test program called pcretest, and the pgrep
|
||
|
command. You can use "make install" to copy these, and the public header file
|
||
|
pcre.h, to appropriate live directories on your system, in the normal way.
|
||
|
|
||
|
Running "make install" also installs the command pcre-config, which can be used
|
||
|
to recall information about the PCRE configuration and installation. For
|
||
|
example,
|
||
|
|
||
|
pcre-config --version
|
||
|
|
||
|
prints the version number, and
|
||
|
|
||
|
pcre-config --libs
|
||
|
|
||
|
outputs information about where the library is installed. This command can be
|
||
|
included in makefiles for programs that use PCRE, saving the programmer from
|
||
|
having to remember too many details.
|
||
|
|
||
|
|
||
|
Shared libraries on Unix systems
|
||
|
--------------------------------
|
||
|
|
||
|
The default distribution builds PCRE as two shared libraries. This support is
|
||
|
new and experimental and may not work on all systems. It relies on the
|
||
|
"libtool" scripts - these are distributed with PCRE. It should build a
|
||
|
"libtool" script and use this to compile and link shared libraries, which are
|
||
|
placed in a subdirectory called .libs. The programs pcretest and pgrep are
|
||
|
built to use these uninstalled libraries by means of wrapper scripts. When you
|
||
|
use "make install" to install shared libraries, pgrep and pcretest are
|
||
|
automatically re-built to use the newly installed libraries. However, only
|
||
|
pgrep is installed, as pcretest is really just a test program.
|
||
|
|
||
|
To build PCRE using static libraries you must use --disable-shared when
|
||
|
configuring it. For example
|
||
|
|
||
|
./configure --prefix=/usr/gnu --disable-shared
|
||
|
|
||
|
Then run "make" in the usual way.
|
||
|
|
||
|
|
||
|
Building on non-Unix systems
|
||
|
----------------------------
|
||
|
|
||
|
For a non-Unix system, read the comments in the file NON-UNIX-USE. PCRE has
|
||
|
been compiled on Windows systems and on Macintoshes, but I don't know the
|
||
|
details because I don't use those systems. It should be straightforward to
|
||
|
build PCRE on any system that has a Standard C compiler, because it uses only
|
||
|
Standard C functions.
|
||
|
|
||
|
|
||
|
Testing PCRE
|
||
|
------------
|
||
|
|
||
|
To test PCRE on a Unix system, run the RunTest script in the pcre directory.
|
||
|
(This can also be run by "make runtest" or "make check".) For other systems,
|
||
|
see the instruction in NON-UNIX-USE.
|
||
|
|
||
|
The script runs the pcretest test program (which is documented in
|
||
|
doc/pcretest.txt) on each of the testinput files (in the testdata directory) in
|
||
|
turn, and compares the output with the contents of the corresponding testoutput
|
||
|
file. A file called testtry is used to hold the output from pcretest. To run
|
||
|
pcretest on just one of the test files, give its number as an argument to
|
||
|
RunTest, for example:
|
||
|
|
||
|
RunTest 3
|
||
|
|
||
|
The first and third test files can also be fed directly into the perltest
|
||
|
script to check that Perl gives the same results. The third file requires the
|
||
|
additional features of release 5.005, which is why it is kept separate from the
|
||
|
main test input, which needs only Perl 5.004. In the long run, when 5.005 is
|
||
|
widespread, these two test files may get amalgamated.
|
||
|
|
||
|
The second set of tests check pcre_info(), pcre_study(), pcre_copy_substring(),
|
||
|
pcre_get_substring(), pcre_get_substring_list(), error detection and run-time
|
||
|
flags that are specific to PCRE, as well as the POSIX wrapper API.
|
||
|
|
||
|
The fourth set of tests checks pcre_maketables(), the facility for building a
|
||
|
set of character tables for a specific locale and using them instead of the
|
||
|
default tables. The tests make use of the "fr" (French) locale. Before running
|
||
|
the test, the script checks for the presence of this locale by running the
|
||
|
"locale" command. If that command fails, or if it doesn't include "fr" in the
|
||
|
list of available locales, the fourth test cannot be run, and a comment is
|
||
|
output to say why. If running this test produces instances of the error
|
||
|
|
||
|
** Failed to set locale "fr"
|
||
|
|
||
|
in the comparison output, it means that locale is not available on your system,
|
||
|
despite being listed by "locale". This does not mean that PCRE is broken.
|
||
|
|
||
|
PCRE has its own native API, but a set of "wrapper" functions that are based on
|
||
|
the POSIX API are also supplied in the library libpcreposix.a. Note that this
|
||
|
just provides a POSIX calling interface to PCRE: the regular expressions
|
||
|
themselves still follow Perl syntax and semantics. The header file
|
||
|
for the POSIX-style functions is called pcreposix.h. The official POSIX name is
|
||
|
regex.h, but I didn't want to risk possible problems with existing files of
|
||
|
that name by distributing it that way. To use it with an existing program that
|
||
|
uses the POSIX API, it will have to be renamed or pointed at by a link.
|
||
|
|
||
|
|
||
|
Character tables
|
||
|
----------------
|
||
|
|
||
|
PCRE uses four tables for manipulating and identifying characters. The final
|
||
|
argument of the pcre_compile() function is a pointer to a block of memory
|
||
|
containing the concatenated tables. A call to pcre_maketables() can be used to
|
||
|
generate a set of tables in the current locale. If the final argument for
|
||
|
pcre_compile() is passed as NULL, a set of default tables that is built into
|
||
|
the binary is used.
|
||
|
|
||
|
The source file called chartables.c contains the default set of tables. This is
|
||
|
not supplied in the distribution, but is built by the program dftables
|
||
|
(compiled from dftables.c), which uses the ANSI C character handling functions
|
||
|
such as isalnum(), isalpha(), isupper(), islower(), etc. to build the table
|
||
|
sources. This means that the default C locale which is set for your system will
|
||
|
control the contents of these default tables. You can change the default tables
|
||
|
by editing chartables.c and then re-building PCRE. If you do this, you should
|
||
|
probably also edit Makefile to ensure that the file doesn't ever get
|
||
|
re-generated.
|
||
|
|
||
|
The first two 256-byte tables provide lower casing and case flipping functions,
|
||
|
respectively. The next table consists of three 32-byte bit maps which identify
|
||
|
digits, "word" characters, and white space, respectively. These are used when
|
||
|
building 32-byte bit maps that represent character classes.
|
||
|
|
||
|
The final 256-byte table has bits indicating various character types, as
|
||
|
follows:
|
||
|
|
||
|
1 white space character
|
||
|
2 letter
|
||
|
4 decimal digit
|
||
|
8 hexadecimal digit
|
||
|
16 alphanumeric or '_'
|
||
|
128 regular expression metacharacter or binary zero
|
||
|
|
||
|
You should not alter the set of characters that contain the 128 bit, as that
|
||
|
will cause PCRE to malfunction.
|
||
|
|
||
|
|
||
|
Manifest
|
||
|
--------
|
||
|
|
||
|
The distribution should contain the following files:
|
||
|
|
||
|
(A) The actual source files of the PCRE library functions and their
|
||
|
headers:
|
||
|
|
||
|
dftables.c auxiliary program for building chartables.c
|
||
|
get.c )
|
||
|
maketables.c )
|
||
|
study.c ) source of
|
||
|
pcre.c ) the functions
|
||
|
pcreposix.c )
|
||
|
pcre.in "source" for the header for the external API; pcre.h
|
||
|
is built from this by "configure"
|
||
|
pcreposix.h header for the external POSIX wrapper API
|
||
|
internal.h header for internal use
|
||
|
config.in template for config.h, which is built by configure
|
||
|
|
||
|
(B) Auxiliary files:
|
||
|
|
||
|
AUTHORS information about the author of PCRE
|
||
|
ChangeLog log of changes to the code
|
||
|
INSTALL generic installation instructions
|
||
|
LICENCE conditions for the use of PCRE
|
||
|
COPYING the same, using GNU's standard name
|
||
|
Makefile.in template for Unix Makefile, which is built by configure
|
||
|
NEWS important changes in this release
|
||
|
NON-UNIX-USE notes on building PCRE on non-Unix systems
|
||
|
README this file
|
||
|
RunTest a Unix shell script for running tests
|
||
|
config.guess ) files used by libtool,
|
||
|
config.sub ) used only when building a shared library
|
||
|
configure a configuring shell script (built by autoconf)
|
||
|
configure.in the autoconf input used to build configure
|
||
|
doc/Tech.Notes notes on the encoding
|
||
|
doc/pcre.3 man page source for the PCRE functions
|
||
|
doc/pcre.html HTML version
|
||
|
doc/pcre.txt plain text version
|
||
|
doc/pcreposix.3 man page source for the POSIX wrapper API
|
||
|
doc/pcreposix.html HTML version
|
||
|
doc/pcreposix.txt plain text version
|
||
|
doc/pcretest.txt documentation of test program
|
||
|
doc/perltest.txt documentation of Perl test program
|
||
|
doc/pgrep.1 man page source for the pgrep utility
|
||
|
doc/pgrep.html HTML version
|
||
|
doc/pgrep.txt plain text version
|
||
|
install-sh a shell script for installing files
|
||
|
ltconfig ) files used to build "libtool",
|
||
|
ltmain.sh ) used only when building a shared library
|
||
|
pcretest.c test program
|
||
|
perltest Perl test program
|
||
|
pgrep.c source of a grep utility that uses PCRE
|
||
|
pcre-config.in source of script which retains PCRE information
|
||
|
testdata/testinput1 test data, compatible with Perl 5.004 and 5.005
|
||
|
testdata/testinput2 test data for error messages and non-Perl things
|
||
|
testdata/testinput3 test data, compatible with Perl 5.005
|
||
|
testdata/testinput4 test data for locale-specific tests
|
||
|
testdata/testoutput1 test results corresponding to testinput1
|
||
|
testdata/testoutput2 test results corresponding to testinput2
|
||
|
testdata/testoutput3 test results corresponding to testinput3
|
||
|
testdata/testoutput4 test results corresponding to testinput4
|
||
|
|
||
|
(C) Auxiliary files for Win32 DLL
|
||
|
|
||
|
dll.mk
|
||
|
pcre.def
|
||
|
|
||
|
Philip Hazel <ph10@cam.ac.uk>
|
||
|
February 2000
|