/[pcre]/code/trunk/doc/pcre.txt

Diff of /code/trunk/doc/pcre.txt

Parent Directory | Revision Log | View Patch Patch

-revision 259 by ph10,
Wed Sep 19 09:52:44 2007 UTC
+revision 261 by ph10,
Fri Sep 21 08:37:48 2007 UTC
 Line 271 
 NAME
  PCRE BUILD-TIME OPTIONS
         This  document  describes  the  optional  features  of PCRE that can be
-        selected when the library is compiled. They are all selected, or  dese-
+        selected when the library is compiled. It assumes use of the  configure
-        lected, by providing options to the configure script that is run before
+        script,  where the optional features are selected or deselected by pro-
-        the make command. The complete list of  options  for  configure  (which
+        viding options to configure before running the make  command.  However,
-        includes  the  standard  ones such as the selection of the installation
+        the  same  options  can be selected in both Unix-like and non-Unix-like
-        directory) can be obtained by running
+        environments using the GUI facility of  CMakeSetup  if  you  are  using
+        CMake instead of configure to build PCRE.
+        The complete list of options for configure (which includes the standard
+        ones such as the  selection  of  the  installation  directory)  can  be
+        obtained by running
           ./configure --help
-        The following sections include  descriptions  of  options  whose  names
+        The  following  sections  include  descriptions  of options whose names
         begin with --enable or --disable. These settings specify changes to the
-        defaults for the configure command. Because of the way  that  configure
+        defaults  for  the configure command. Because of the way that configure
-        works,  --enable  and --disable always come in pairs, so the complemen-
+        works, --enable and --disable always come in pairs, so  the  complemen-
-        tary option always exists as well, but as it specifies the default,  it
+        tary  option always exists as well, but as it specifies the default, it
         is not described.
-Line 304 
 UTF-8 SUPPORT
+Line 309 
 UTF-8 SUPPORT
           --enable-utf8
-        to  the  configure  command.  Of  itself, this does not make PCRE treat
+        to the configure command. Of itself, this  does  not  make  PCRE  treat
-        strings as UTF-8. As well as compiling PCRE with this option, you  also
+        strings  as UTF-8. As well as compiling PCRE with this option, you also
-        have  have to set the PCRE_UTF8 option when you call the pcre_compile()
+        have have to set the PCRE_UTF8 option when you call the  pcre_compile()
         function.
  UNICODE CHARACTER PROPERTY SUPPORT
-        UTF-8 support allows PCRE to process character values greater than  255
+        UTF-8  support allows PCRE to process character values greater than 255
-        in  the  strings that it handles. On its own, however, it does not pro-
+        in the strings that it handles. On its own, however, it does  not  pro-
         vide any facilities for accessing the properties of such characters. If
-        you  want  to  be able to use the pattern escapes \P, \p, and \X, which
+        you want to be able to use the pattern escapes \P, \p,  and  \X,  which
         refer to Unicode character properties, you must add
           --enable-unicode-properties
-        to the configure command. This implies UTF-8 support, even if you  have
+        to  the configure command. This implies UTF-8 support, even if you have
         not explicitly requested it.
-        Including  Unicode  property  support  adds around 30K of tables to the
+        Including Unicode property support adds around 30K  of  tables  to  the
-        PCRE library. Only the general category properties such as  Lu  and  Nd
+        PCRE  library.  Only  the general category properties such as Lu and Nd
         are supported. Details are given in the pcrepattern documentation.
  CODE VALUE OF NEWLINE
-        By  default,  PCRE interprets character 10 (linefeed, LF) as indicating
+        By default, PCRE interprets character 10 (linefeed, LF)  as  indicating
-        the end of a line. This is the normal newline  character  on  Unix-like
+        the  end  of  a line. This is the normal newline character on Unix-like
         systems. You can compile PCRE to use character 13 (carriage return, CR)
         instead, by adding
           --enable-newline-is-cr
-        to the  configure  command.  There  is  also  a  --enable-newline-is-lf
+        to  the  configure  command.  There  is  also  a --enable-newline-is-lf
         option, which explicitly specifies linefeed as the newline character.
         Alternatively, you can specify that line endings are to be indicated by
-Line 349 
 CODE VALUE OF NEWLINE
+Line 354 
 CODE VALUE OF NEWLINE
           --enable-newline-is-anycrlf
-        which causes PCRE to recognize any of the three sequences  CR,  LF,  or
+        which  causes  PCRE  to recognize any of the three sequences CR, LF, or
         CRLF as indicating a line ending. Finally, a fifth option, specified by
           --enable-newline-is-any
         causes PCRE to recognize any Unicode newline sequence.
-        Whatever line ending convention is selected when PCRE is built  can  be
+        Whatever  line  ending convention is selected when PCRE is built can be
-        overridden  when  the library functions are called. At build time it is
+        overridden when the library functions are called. At build time  it  is
         conventional to use the standard for your operating system.
  WHAT \R MATCHES
-        By default, the sequence \R in a pattern matches  any  Unicode  newline
+        By  default,  the  sequence \R in a pattern matches any Unicode newline
-        sequence,  whatever  has  been selected as the line ending sequence. If
+        sequence, whatever has been selected as the line  ending  sequence.  If
         you specify
           --enable-bsr-anycrlf
-        the default is changed so that \R matches only CR, LF, or  CRLF.  What-
+        the  default  is changed so that \R matches only CR, LF, or CRLF. What-
-        ever  is selected when PCRE is built can be overridden when the library
+        ever is selected when PCRE is built can be overridden when the  library
         functions are called.
  BUILDING SHARED AND STATIC LIBRARIES
-        The PCRE building process uses libtool to build both shared and  static
+        The  PCRE building process uses libtool to build both shared and static
-        Unix  libraries by default. You can suppress one of these by adding one
+        Unix libraries by default. You can suppress one of these by adding  one
         of
           --disable-shared
-Line 389 
 BUILDING SHARED AND STATIC LIBRARIES
+Line 394 
 BUILDING SHARED AND STATIC LIBRARIES
  POSIX MALLOC USAGE
         When PCRE is called through the POSIX interface (see the pcreposix doc-
-        umentation),  additional  working  storage  is required for holding the
+        umentation), additional working storage is  required  for  holding  the
-        pointers to capturing substrings, because PCRE requires three  integers
+        pointers  to capturing substrings, because PCRE requires three integers
-        per  substring,  whereas  the POSIX interface provides only two. If the
+        per substring, whereas the POSIX interface provides only  two.  If  the
         number of expected substrings is small, the wrapper function uses space
         on the stack, because this is faster than using malloc() for each call.
         The default threshold above which the stack is no longer used is 10; it
-Line 404 
 POSIX MALLOC USAGE
+Line 409 
 POSIX MALLOC USAGE
  HANDLING VERY LARGE PATTERNS
-        Within  a  compiled  pattern,  offset values are used to point from one
+        Within a compiled pattern, offset values are used  to  point  from  one
-        part to another (for example, from an opening parenthesis to an  alter-
+        part  to another (for example, from an opening parenthesis to an alter-
-        nation  metacharacter).  By default, two-byte values are used for these
+        nation metacharacter). By default, two-byte values are used  for  these
-        offsets, leading to a maximum size for a  compiled  pattern  of  around
+        offsets,  leading  to  a  maximum size for a compiled pattern of around
-K.  This  is sufficient to handle all but the most gigantic patterns.
+K. This is sufficient to handle all but the most  gigantic  patterns.
-        Nevertheless, some people do want to process enormous patterns,  so  it
+        Nevertheless,  some  people do want to process enormous patterns, so it
-        is  possible  to compile PCRE to use three-byte or four-byte offsets by
+        is possible to compile PCRE to use three-byte or four-byte  offsets  by
         adding a setting such as
           --with-link-size=3
-        to the configure command. The value given must be 2,  3,  or  4.  Using
+        to  the  configure  command.  The value given must be 2, 3, or 4. Using
-        longer  offsets slows down the operation of PCRE because it has to load
+        longer offsets slows down the operation of PCRE because it has to  load
         additional bytes when handling them.
  AVOIDING EXCESSIVE STACK USAGE
         When matching with the pcre_exec() function, PCRE implements backtrack-
-        ing  by  making recursive calls to an internal function called match().
+        ing by making recursive calls to an internal function  called  match().
-        In environments where the size of the stack is limited,  this  can  se-
+        In  environments  where  the size of the stack is limited, this can se-
-        verely  limit  PCRE's operation. (The Unix environment does not usually
+        verely limit PCRE's operation. (The Unix environment does  not  usually
         suffer from this problem, but it may sometimes be necessary to increase
-        the  maximum  stack size.  There is a discussion in the pcrestack docu-
+        the maximum stack size.  There is a discussion in the  pcrestack  docu-
-        mentation.) An alternative approach to recursion that uses memory  from
+        mentation.)  An alternative approach to recursion that uses memory from
-        the  heap  to remember data, instead of using recursive function calls,
+        the heap to remember data, instead of using recursive  function  calls,
-        has been implemented to work round the problem of limited  stack  size.
+        has  been  implemented to work round the problem of limited stack size.
         If you want to build a version of PCRE that works this way, add
           --disable-stack-for-recursion
-        to  the  configure  command. With this configuration, PCRE will use the
+        to the configure command. With this configuration, PCRE  will  use  the
-        pcre_stack_malloc and pcre_stack_free variables to call memory  manage-
+        pcre_stack_malloc  and pcre_stack_free variables to call memory manage-
-        ment  functions. By default these point to malloc() and free(), but you
+        ment functions. By default these point to malloc() and free(), but  you
         can replace the pointers so that your own functions are used.
-        Separate functions are  provided  rather  than  using  pcre_malloc  and
+        Separate  functions  are  provided  rather  than  using pcre_malloc and
-        pcre_free  because  the  usage  is  very  predictable:  the block sizes
+        pcre_free because the  usage  is  very  predictable:  the  block  sizes
-        requested are always the same, and  the  blocks  are  always  freed  in
+        requested  are  always  the  same,  and  the blocks are always freed in
-        reverse  order.  A calling program might be able to implement optimized
+        reverse order. A calling program might be able to  implement  optimized
-        functions that perform better  than  malloc()  and  free().  PCRE  runs
+        functions  that  perform  better  than  malloc()  and free(). PCRE runs
         noticeably more slowly when built in this way. This option affects only
-        the  pcre_exec()  function;  it   is   not   relevant   for   the   the
+        the   pcre_exec()   function;   it   is   not   relevant  for  the  the
         pcre_dfa_exec() function.
  LIMITING PCRE RESOURCE USAGE
-        Internally,  PCRE has a function called match(), which it calls repeat-
+        Internally, PCRE has a function called match(), which it calls  repeat-
-        edly  (sometimes  recursively)  when  matching  a  pattern   with   the
+        edly   (sometimes   recursively)  when  matching  a  pattern  with  the
-        pcre_exec()  function.  By controlling the maximum number of times this
+        pcre_exec() function. By controlling the maximum number of  times  this
-        function may be called during a single matching operation, a limit  can
+        function  may be called during a single matching operation, a limit can
-        be  placed  on  the resources used by a single call to pcre_exec(). The
+        be placed on the resources used by a single call  to  pcre_exec().  The
-        limit can be changed at run time, as described in the pcreapi  documen-
+        limit  can be changed at run time, as described in the pcreapi documen-
-        tation.  The default is 10 million, but this can be changed by adding a
+        tation. The default is 10 million, but this can be changed by adding  a
         setting such as
           --with-match-limit=500000
-        to  the  configure  command.  This  setting  has  no  effect   on   the
+        to   the   configure  command.  This  setting  has  no  effect  on  the
         pcre_dfa_exec() matching function.
-        In  some  environments  it is desirable to limit the depth of recursive
+        In some environments it is desirable to limit the  depth  of  recursive
         calls of match() more strictly than the total number of calls, in order
-        to  restrict  the maximum amount of stack (or heap, if --disable-stack-
+        to restrict the maximum amount of stack (or heap,  if  --disable-stack-
         for-recursion is specified) that is used. A second limit controls this;
-        it  defaults  to  the  value  that is set for --with-match-limit, which
+        it defaults to the value that  is  set  for  --with-match-limit,  which
-        imposes no additional constraints. However, you can set a  lower  limit
+        imposes  no  additional constraints. However, you can set a lower limit
         by adding, for example,
           --with-match-limit-recursion=10000
-        to  the  configure  command.  This  value can also be overridden at run
+        to the configure command. This value can  also  be  overridden  at  run
         time.
  CREATING CHARACTER TABLES AT BUILD TIME
-        PCRE uses fixed tables for processing characters whose code values  are
+        PCRE  uses fixed tables for processing characters whose code values are
-        less  than 256. By default, PCRE is built with a set of tables that are
+        less than 256. By default, PCRE is built with a set of tables that  are
-        distributed in the file pcre_chartables.c.dist. These  tables  are  for
+        distributed  in  the  file pcre_chartables.c.dist. These tables are for
         ASCII codes only. If you add
           --enable-rebuild-chartables
-        to  the  configure  command, the distributed tables are no longer used.
+        to the configure command, the distributed tables are  no  longer  used.
-        Instead, a program called dftables is compiled and  run.  This  outputs
+        Instead,  a  program  called dftables is compiled and run. This outputs
         the source for new set of tables, created in the default locale of your
         C runtime system. (This method of replacing the tables does not work if
-        you  are cross compiling, because dftables is run on the local host. If
+        you are cross compiling, because dftables is run on the local host.  If
-        you need to create alternative tables when cross  compiling,  you  will
+        you  need  to  create alternative tables when cross compiling, you will
         have to do so "by hand".)
  USING EBCDIC CODE
-        PCRE  assumes  by  default that it will run in an environment where the
+        PCRE assumes by default that it will run in an  environment  where  the
-        character code is ASCII (or Unicode, which is  a  superset  of  ASCII).
+        character  code  is  ASCII  (or Unicode, which is a superset of ASCII).
-        This  is  the  case for most computer operating systems. PCRE can, how-
+        This is the case for most computer operating systems.  PCRE  can,  how-
         ever, be compiled to run in an EBCDIC environment by adding
           --enable-ebcdic
         to the configure command. This setting implies --enable-rebuild-charta-
-        bles.  You  should  only  use  it if you know that you are in an EBCDIC
+        bles. You should only use it if you know that  you  are  in  an  EBCDIC
         environment (for example, an IBM mainframe operating system).
-Line 526 
 AUTHOR
+Line 531 
 AUTHOR
  REVISION
-        Last updated: 11 September 2007
+        Last updated: 21 September 2007
         Copyright (c) 1997-2007 University of Cambridge.
  ------------------------------------------------------------------------------
-Line 5161 
 BACKTRACKING CONTROL
+Line 5166 
 BACKTRACKING CONTROL
  NEWLINE CONVENTIONS
-        These are recognized only at the very start of a pattern.
+        These  are  recognized only at the very start of the pattern or after a
+        (*BSR_...) option.
           (*CR)
           (*LF)
-Line 5172 
 NEWLINE CONVENTIONS
+Line 5178 
 NEWLINE CONVENTIONS
  WHAT \R MATCHES
-        These are recognized only at the very start of a pattern.
+        These are recognized only at the very start of the pattern or  after  a
+        (*...) option that sets the newline convention.
           (*BSR_ANYCRLF)
           (*BSR_UNICODE)
-Line 5198 
 AUTHOR
+Line 5205 
 AUTHOR
  REVISION
-        Last updated: 11 September 2007
+        Last updated: 21 September 2007
         Copyright (c) 1997-2007 University of Cambridge.
  ------------------------------------------------------------------------------

 Legend:



Removed from v.259
 


changed lines


 
Added in v.261
 Legend:



Removed from v.259
 


changed lines


 
Added in v.261
-Removed from v.259
+Added in v.261

	ViewVC Help
Powered by ViewVC 1.1.5