+++ /dev/null
-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.
-
-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. 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.
-
-
-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.
-
-If you want to make use of the experimential, incomplete support for UTF-8
-character strings in PCRE, you must add --enable-utf8 to the "configure"
-command. Without it, the code for handling UTF-8 is not included in the
-library. (Even when included, it still has to be enabled by an option at run
-time.)
-
-The "configure" script builds four 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.
-. RunTest is a script for running tests
-
-Once "configure" has run, you can run "make". It builds two libraries called
-libpcre and libpcreposix, a test program called pcretest, and the pcregrep
-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 pcregrep are
-built to use these uninstalled libraries by means of wrapper scripts. When you
-use "make install" to install shared libraries, pcregrep and pcretest are
-automatically re-built to use the newly installed libraries. However, only
-pcregrep 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", "make check", or "make test".) 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 (or
-higher) is widespread, these two test files may get amalgamated.
-
-The second set of tests check pcre_fullinfo(), 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. It also uses the debugging flag to check some of the internals of
-pcre_compile().
-
-If you build PCRE with a locale setting that is not the standard C locale, the
-character tables may be different (see next paragraph). In some cases, this may
-cause failures in the second set of tests. For example, in a locale where the
-isprint() function yields TRUE for characters in the range 128-255, the use of
-[:isascii:] inside a character class defines a different set of characters, and
-this shows up in this test as a difference in the compiled code, which is being
-listed for checking. Where the comparison test output contains [\x00-\x7f] the
-test will contain [\x00-\xff], and similarly in some other cases. This is not a
-bug in PCRE.
-
-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.
-
-The fifth test checks the experimental, incomplete UTF-8 support. It is not run
-automatically unless PCRE is built with UTF-8 support. This file can be fed
-directly to the perltest8 script, which requires Perl 5.6 or higher. The sixth
-file tests internal UTF-8 features of PCRE that are not relevant to Perl.
-
-
-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.in template for 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/pcregrep.1 man page source for the pcregrep utility
- doc/pcregrep.html HTML version
- doc/pcregrep.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
- perltest8 Perl test program for UTF-8 tests
- pcregrep.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/testinput5 test data for UTF-8 tests compatible with Perl 5.6
- testdata/testinput6 test data for other UTF-8 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
- testdata/testoutput5 test results corresponding to testinput5
- testdata/testoutput6 test results corresponding to testinput6
-
-(C) Auxiliary files for Win32 DLL
-
- dll.mk
- pcre.def
-
-Philip Hazel <ph10@cam.ac.uk>
-August 2000
projects / privoxy.git / blobdiff