/[pcre]/code/trunk/README

Diff of /code/trunk/README

Parent Directory | Revision Log | View Patch Patch

-revision 23 by nigel,
Sat Feb 24 21:38:41 2007 UTC
+revision 27 by nigel,
Sat Feb 24 21:38:49 2007 UTC
 Line 8 
 README file for PCRE (Perl-compatible re
  * ovector is required at matching time, to provide some additional workspace. *
  * The new man page has details. This change was necessary in order to support *
  * some of the new functionality in Perl 5.005.                                *
+ *                                                                             *
+ *           IMPORTANT FOR THOSE UPGRADING FROM VERSION 2.00                   *
+ *                                                                             *
+ * Another (I hope this is the last!) change has been made to the API for the  *
+ * pcre_compile() function. An additional argument has been added to make it   *
+ * possible to pass over a pointer to character tables built in the current    *
+ * locale by pcre_maketables(). To use the default tables, this new arguement  *
+ * should be passed as NULL.                                                   *
  *******************************************************************************
  The distribution should contain the following files:
-Line 19 
 The distribution should contain the foll
+Line 27 
 The distribution should contain the foll
    Tech.Notes        notes on the encoding
    pcre.3            man page for the functions
    pcreposix.3       man page for the POSIX wrapper API
-   maketables.c      auxiliary program for building chartables.c
+   dftables.c        auxiliary program for building chartables.c
+   maketables.c      )
    study.c           ) source of
    pcre.c            )   the functions
    pcreposix.c       )
-Line 33 
 The distribution should contain the foll
+Line 42 
 The distribution should contain the foll
    testinput         test data, compatible with Perl 5.004 and 5.005
    testinput2        test data for error messages and non-Perl things
    testinput3        test data, compatible with Perl 5.005
+   testinput4        test data for locale-specific tests
    testoutput        test results corresponding to testinput
    testoutput2       test results corresponding to testinput2
-   testoutput3       test results corresponding to testinpug3
+   testoutput3       test results corresponding to testinput3
+   testoutput4       test results corresponding to testinput4
  To build PCRE, edit Makefile for your system (it is a fairly simple make file,
  and there are some comments at the top) and then run it. It builds two
-Line 61 
 widespread, these two test files may get
+Line 72 
 widespread, these two test files may get
  The second set of tests check pcre_info(), pcre_study(), 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.
  To install PCRE, copy libpcre.a to any suitable library directory (e.g.
  /usr/local/lib), pcre.h to any suitable include directory (e.g.
  /usr/local/include), and pcre.3 to any suitable man directory (e.g.
-Line 83 
 uses the POSIX API, it will have to be r
+Line 107 
 uses the POSIX API, it will have to be r
  Character tables
  ----------------
- PCRE uses four tables for manipulating and identifying characters. These are
+ PCRE uses four tables for manipulating and identifying characters. The final
- compiled from a source file called chartables.c. This is not supplied in
+ argument of the pcre_compile() function is a pointer to a block of memory
- the distribution, but is built by the program maketables (compiled from
+ containing the concatenated tables. A call to pcre_maketables() is used to
- maketables.c), which uses the ANSI C character handling functions such as
+ generate a set of tables in the current locale. However, if the final argument
- isalnum(), isalpha(), isupper(), islower(), etc. to build the table sources.
+ is passed as NULL, a set of default tables that is built into the binary is
- This means that the default C locale set in your system may affect the contents
+ used.
- of the tables. You can change the tables by editing chartables.c and then
- re-building PCRE. If you do this, you should probably also edit Makefile to
+ The source file called chartables.c contains the default set of tables. This is
- ensure that the file doesn't ever get re-generated.
+ not supplied in the distribution, but is built by the program dftables
+ (compiled from dftables.c), which uses the ANSI C character handling functions
- The first two tables pcre_lcc[] and pcre_fcc[] provide lower casing and a
+ such as isalnum(), isalpha(), isupper(), islower(), etc. to build the table
- case flipping functions, respectively. The pcre_cbits[] table consists of four
+ sources. This means that the default C locale set your system will control the
--byte bit maps which identify digits, letters, "word" characters, and white
+ contents of the tables. You can change the default tables by editing
- space, respectively. These are used when building 32-byte bit maps that
+ chartables.c and then re-building PCRE. If you do this, you should probably
- represent character classes.
+ 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 pcre_ctypes[] table has bits indicating various character types, as
+ The final 256-byte table has bits indicating various character types, as
  follows:
   white space character
-Line 138 
 same effect as they do in Perl.
+Line 167 
 same effect as they do in Perl.
  There are also some upper case options that do not match Perl options: /A, /E,
  and /X set PCRE_ANCHORED, PCRE_DOLLAR_ENDONLY, and PCRE_EXTRA respectively.
- The /D option is a PCRE debugging feature. It causes the internal form of
- compiled regular expressions to be output after compilation. The /S option
+ The /L option must be followed directly by the name of a locale, for example,
- causes pcre_study() to be called after the expression has been compiled, and
- the results used when the expression is matched.
+   /pattern/Lfr
+ For this reason, it must be the last option letter. The given locale is set,
+ pcre_maketables() is called to build a set of character tables for the locale,
+ and this is then passed to pcre_compile() when compiling the regular
+ expression. Without an /L option, NULL is passed as the tables pointer; that
+ is, /L applies only to the expression on which it appears.
+ The /I option requests that pcretest output information about the compiled
+ expression (whether it is anchored, has a fixed first character, and so on). It
+ does this by calling pcre_info() after compiling an expression, and outputting
+ the information it gets back. If the pattern is studied, the results of that
+ are also output.
+ The /D option is a PCRE debugging feature, which also assumes /I. It causes the
+ internal form of compiled regular expressions to be output after compilation.
+ The /S option causes pcre_study() to be called after the expression has been
+ compiled, and the results used when the expression is matched.
  Finally, the /P option causes pcretest to call PCRE via the POSIX wrapper API
  rather than its native API. When this is done, all other options except /i and
-Line 206 
 following flags has any effect in this c
+Line 253 
 following flags has any effect in this c
  If the option -d is given to pcretest, it is equivalent to adding /D to each
  regular expression: the internal form is output after compilation.
- If the option -i (for "information") is given to pcretest, it calls pcre_info()
+ If the option -i is given to pcretest, it is equivalent to adding /I to each
- after compiling an expression, and outputs the information it gets back. If the
+ regular expression: information about the compiled pattern is given after
- pattern is studied, the results of that are also output.
+ compilation.
  If the option -s is given to pcretest, it outputs the size of each compiled
  pattern after it has been compiled.
-Line 237 
 for pcretest, and the special upper case
+Line 284 
 for pcretest, and the special upper case
  recognizes are not used in this file. The output should be identical, apart
  from the initial identifying banner.
- The testinput2 file is not suitable for feeding to Perltest, since it does
+ The testinput2 and testinput4 files are not suitable for feeding to Perltest,
- make use of the special upper case options and escapes that pcretest uses to
+ since they do make use of the special upper case options and escapes that
- test some features of PCRE. It also contains malformed regular expressions, in
+ pcretest uses to test some features of PCRE. The first of these files also
- order to check that PCRE diagnoses them correctly.
+ contains malformed regular expressions, in order to check that PCRE diagnoses
+ them correctly.
  Philip Hazel <ph10@cam.ac.uk>
- September 1998
+ January 1999

 Legend:



Removed from v.23
 


changed lines


 
Added in v.27
 Legend:



Removed from v.23
 


changed lines


 
Added in v.27
-Removed from v.23
+Added in v.27

	ViewVC Help
Powered by ViewVC 1.1.5