/[pcre]/code/trunk/doc/pcreapi.3
ViewVC logotype

Diff of /code/trunk/doc/pcreapi.3

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 461 by ph10, Mon Oct 5 10:59:35 2009 UTC revision 545 by ph10, Wed Jun 16 10:51:15 2010 UTC
# Line 132  an application that uses PCRE. The heade Line 132  an application that uses PCRE. The heade
132  and PCRE_MINOR to contain the major and minor release numbers for the library.  and PCRE_MINOR to contain the major and minor release numbers for the library.
133  Applications can use these to include support for different releases of PCRE.  Applications can use these to include support for different releases of PCRE.
134  .P  .P
135    In a Windows environment, if you want to statically link an application program
136    against a non-dll \fBpcre.a\fP file, you must define PCRE_STATIC before
137    including \fBpcre.h\fP or \fBpcrecpp.h\fP, because otherwise the
138    \fBpcre_malloc()\fP and \fBpcre_free()\fP exported functions will be declared
139    \fB__declspec(dllimport)\fP, with unwanted results.
140    .P
141  The functions \fBpcre_compile()\fP, \fBpcre_compile2()\fP, \fBpcre_study()\fP,  The functions \fBpcre_compile()\fP, \fBpcre_compile2()\fP, \fBpcre_study()\fP,
142  and \fBpcre_exec()\fP are used for compiling and matching regular expressions  and \fBpcre_exec()\fP are used for compiling and matching regular expressions
143  in a Perl-compatible manner. A sample program that demonstrates the simplest  in a Perl-compatible manner. A sample program that demonstrates the simplest
# Line 553  set, any backslash in a pattern that is Line 559  set, any backslash in a pattern that is
559  special meaning causes an error, thus reserving these combinations for future  special meaning causes an error, thus reserving these combinations for future
560  expansion. By default, as in Perl, a backslash followed by a letter with no  expansion. By default, as in Perl, a backslash followed by a letter with no
561  special meaning is treated as a literal. (Perl can, however, be persuaded to  special meaning is treated as a literal. (Perl can, however, be persuaded to
562  give a warning for this.) There are at present no other features controlled by  give an error for this, by running it with the -w option.) There are at present
563  this option. It can also be set by a (?X) option setting within a pattern.  no other features controlled by this option. It can also be set by a (?X)
564    option setting within a pattern.
565  .sp  .sp
566    PCRE_FIRSTLINE    PCRE_FIRSTLINE
567  .sp  .sp
# Line 635  were followed by ?: but named parenthese Line 642  were followed by ?: but named parenthese
642  they acquire numbers in the usual way). There is no equivalent of this option  they acquire numbers in the usual way). There is no equivalent of this option
643  in Perl.  in Perl.
644  .sp  .sp
645      PCRE_UCP
646    .sp
647    This option changes the way PCRE processes \eb, \ed, \es, \ew, and some of the
648    POSIX character classes. By default, only ASCII characters are recognized, but
649    if PCRE_UCP is set, Unicode properties are used instead to classify characters.
650    More details are given in the section on
651    .\" HTML <a href="pcre.html#genericchartypes">
652    .\" </a>
653    generic character types
654    .\"
655    in the
656    .\" HREF
657    \fBpcrepattern\fP
658    .\"
659    page. If you set PCRE_UCP, matching one of the items it affects takes much
660    longer. The option is available only if PCRE has been compiled with Unicode
661    property support.
662    .sp
663    PCRE_UNGREEDY    PCRE_UNGREEDY
664  .sp  .sp
665  This option inverts the "greediness" of the quantifiers so that they are not  This option inverts the "greediness" of the quantifiers so that they are not
# Line 747  out of use. To avoid confusion, they hav Line 772  out of use. To avoid confusion, they hav
772    57  \eg is not followed by a braced, angle-bracketed, or quoted    57  \eg is not followed by a braced, angle-bracketed, or quoted
773          name/number or by a plain number          name/number or by a plain number
774    58  a numbered reference must not be zero    58  a numbered reference must not be zero
775    59  (*VERB) with an argument is not supported    59  an argument is not allowed for (*ACCEPT), (*FAIL), or (*COMMIT)
776    60  (*VERB) not recognized    60  (*VERB) not recognized
777    61  number is too big    61  number is too big
778    62  subpattern name expected    62  subpattern name expected
779    63  digit expected after (?+    63  digit expected after (?+
780    64  ] is an invalid data character in JavaScript compatibility mode    64  ] is an invalid data character in JavaScript compatibility mode
781      65  different names for subpatterns of the same number are not allowed
782      66  (*MARK) must have an argument
783      67  this version of PCRE is not compiled with PCRE_UCP support
784  .sp  .sp
785  The numbers 32 and 10000 in errors 48 and 49 are defaults; different values may  The numbers 32 and 10000 in errors 48 and 49 are defaults; different values may
786  be used if the limits were changed when PCRE was built.  be used if the limits were changed when PCRE was built.
# Line 827  matching. Line 855  matching.
855  PCRE handles caseless matching, and determines whether characters are letters,  PCRE handles caseless matching, and determines whether characters are letters,
856  digits, or whatever, by reference to a set of tables, indexed by character  digits, or whatever, by reference to a set of tables, indexed by character
857  value. When running in UTF-8 mode, this applies only to characters with codes  value. When running in UTF-8 mode, this applies only to characters with codes
858  less than 128. Higher-valued codes never match escapes such as \ew or \ed, but  less than 128. By default, higher-valued codes never match escapes such as \ew
859  can be tested with \ep if PCRE is built with Unicode character property  or \ed, but they can be tested with \ep if PCRE is built with Unicode character
860  support. The use of locales with Unicode is discouraged. If you are handling  property support. Alternatively, the PCRE_UCP option can be set at compile
861  characters with codes greater than 128, you should either use UTF-8 and  time; this causes \ew and friends to use Unicode property support instead of
862  Unicode, or use locales, but not try to mix the two.  built-in tables. The use of locales with Unicode is discouraged. If you are
863    handling characters with codes greater than 128, you should either use UTF-8
864    and Unicode, or use locales, but not try to mix the two.
865  .P  .P
866  PCRE contains an internal set of tables that are used when the final argument  PCRE contains an internal set of tables that are used when the final argument
867  of \fBpcre_compile()\fP is NULL. These are sufficient for many applications.  of \fBpcre_compile()\fP is NULL. These are sufficient for many applications.
# Line 1210  fields (not necessarily in this order): Line 1240  fields (not necessarily in this order):
1240    unsigned long int \fImatch_limit_recursion\fP;    unsigned long int \fImatch_limit_recursion\fP;
1241    void *\fIcallout_data\fP;    void *\fIcallout_data\fP;
1242    const unsigned char *\fItables\fP;    const unsigned char *\fItables\fP;
1243      unsigned char **\fImark\fP;
1244  .sp  .sp
1245  The \fIflags\fP field is a bitmap that specifies which of the other fields  The \fIflags\fP field is a bitmap that specifies which of the other fields
1246  are set. The flag bits are:  are set. The flag bits are:
# Line 1219  are set. The flag bits are: Line 1250  are set. The flag bits are:
1250    PCRE_EXTRA_MATCH_LIMIT_RECURSION    PCRE_EXTRA_MATCH_LIMIT_RECURSION
1251    PCRE_EXTRA_CALLOUT_DATA    PCRE_EXTRA_CALLOUT_DATA
1252    PCRE_EXTRA_TABLES    PCRE_EXTRA_TABLES
1253      PCRE_EXTRA_MARK
1254  .sp  .sp
1255  Other flag bits should be set to zero. The \fIstudy_data\fP field is set in the  Other flag bits should be set to zero. The \fIstudy_data\fP field is set in the
1256  \fBpcre_extra\fP block that is returned by \fBpcre_study()\fP, together with  \fBpcre_extra\fP block that is returned by \fBpcre_study()\fP, together with
# Line 1281  called. See the Line 1313  called. See the
1313  \fBpcreprecompile\fP  \fBpcreprecompile\fP
1314  .\"  .\"
1315  documentation for a discussion of saving compiled patterns for later use.  documentation for a discussion of saving compiled patterns for later use.
1316    .P
1317    If PCRE_EXTRA_MARK is set in the \fIflags\fP field, the \fImark\fP field must
1318    be set to point to a \fBchar *\fP variable. If the pattern contains any
1319    backtracking control verbs such as (*MARK:NAME), and the execution ends up with
1320    a name to pass back, a pointer to the name string (zero terminated) is placed
1321    in the variable pointed to by the \fImark\fP field. The names are within the
1322    compiled pattern; if you wish to retain such a name you must copy it before
1323    freeing the memory of a compiled pattern. If there is no name to pass back, the
1324    variable pointed to by the \fImark\fP field set to NULL. For details of the
1325    backtracking control verbs, see the section entitled
1326    .\" HTML <a href="pcrepattern#backtrackcontrol">
1327    .\" </a>
1328    "Backtracking control"
1329    .\"
1330    in the
1331    .\" HREF
1332    \fBpcrepattern\fP
1333    .\"
1334    documentation.
1335    .
1336  .  .
1337  .\" HTML <a name="execoptions"></a>  .\" HTML <a name="execoptions"></a>
1338  .SS "Option bits for \fBpcre_exec()\fP"  .SS "Option bits for \fBpcre_exec()\fP"
# Line 1391  sample program. Line 1443  sample program.
1443    PCRE_NO_START_OPTIMIZE    PCRE_NO_START_OPTIMIZE
1444  .sp  .sp
1445  There are a number of optimizations that \fBpcre_exec()\fP uses at the start of  There are a number of optimizations that \fBpcre_exec()\fP uses at the start of
1446  a match, in order to speed up the process. For example, if it is known that a  a match, in order to speed up the process. For example, if it is known that an
1447  match must start with a specific character, it searches the subject for that  unanchored match must start with a specific character, it searches the subject
1448  character, and fails immediately if it cannot find it, without actually running  for that character, and fails immediately if it cannot find it, without
1449  the main matching function. When callouts are in use, these optimizations can  actually running the main matching function. This means that a special item
1450  cause them to be skipped. This option disables the "start-up" optimizations,  such as (*COMMIT) at the start of a pattern is not considered until after a
1451  causing performance to suffer, but ensuring that the callouts do occur.  suitable starting point for the match has been found. When callouts are in use,
1452    these "start-up" optimizations can cause them to be skipped if the pattern is
1453    never actually used. The PCRE_NO_START_OPTIMIZE option disables the start-up
1454    optimizations, causing performance to suffer, but ensuring that the callouts do
1455    occur, and that items such as (*COMMIT) are considered at every possible
1456    starting position in the subject string.
1457  .sp  .sp
1458    PCRE_NO_UTF8_CHECK    PCRE_NO_UTF8_CHECK
1459  .sp  .sp
# Line 1591  If a pattern contains back references, b Line 1648  If a pattern contains back references, b
1648  gets a block of memory at the start of matching to use for this purpose. If the  gets a block of memory at the start of matching to use for this purpose. If the
1649  call via \fBpcre_malloc()\fP fails, this error is given. The memory is  call via \fBpcre_malloc()\fP fails, this error is given. The memory is
1650  automatically freed at the end of matching.  automatically freed at the end of matching.
1651    .P
1652    This error is also given if \fBpcre_stack_malloc()\fP fails in
1653    \fBpcre_exec()\fP. This can happen only when PCRE has been compiled with
1654    \fB--disable-stack-for-recursion\fP.
1655  .sp  .sp
1656    PCRE_ERROR_NOSUBSTRING    (-7)    PCRE_ERROR_NOSUBSTRING    (-7)
1657  .sp  .sp
# Line 1939  Here is an example of a simple call to \ Line 2000  Here is an example of a simple call to \
2000  The unused bits of the \fIoptions\fP argument for \fBpcre_dfa_exec()\fP must be  The unused bits of the \fIoptions\fP argument for \fBpcre_dfa_exec()\fP must be
2001  zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_\fIxxx\fP,  zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_\fIxxx\fP,
2002  PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NOTEMPTY_ATSTART,  PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NOTEMPTY_ATSTART,
2003  PCRE_NO_UTF8_CHECK, PCRE_PARTIAL_HARD, PCRE_PARTIAL_SOFT, PCRE_DFA_SHORTEST,  PCRE_NO_UTF8_CHECK, PCRE_BSR_ANYCRLF, PCRE_BSR_UNICODE, PCRE_NO_START_OPTIMIZE,
2004  and PCRE_DFA_RESTART. All but the last four of these are exactly the same as  PCRE_PARTIAL_HARD, PCRE_PARTIAL_SOFT, PCRE_DFA_SHORTEST, and PCRE_DFA_RESTART.
2005  for \fBpcre_exec()\fP, so their description is not repeated here.  All but the last four of these are exactly the same as for \fBpcre_exec()\fP,
2006    so their description is not repeated here.
2007  .sp  .sp
2008    PCRE_PARTIAL_HARD    PCRE_PARTIAL_HARD
2009    PCRE_PARTIAL_SOFT    PCRE_PARTIAL_SOFT
# Line 2075  Cambridge CB2 3QH, England. Line 2137  Cambridge CB2 3QH, England.
2137  .rs  .rs
2138  .sp  .sp
2139  .nf  .nf
2140  Last updated: 03 October 2009  Last updated: 15 June 2010
2141  Copyright (c) 1997-2009 University of Cambridge.  Copyright (c) 1997-2010 University of Cambridge.
2142  .fi  .fi

Legend:
Removed from v.461  
changed lines
  Added in v.545

  ViewVC Help
Powered by ViewVC 1.1.5