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

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

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

revision 857 by ph10, Wed Dec 28 17:16:11 2011 UTC revision 858 by ph10, Sun Jan 8 17:55:38 2012 UTC
# Line 6  PCRE - Perl-compatible regular expressio Line 6  PCRE - Perl-compatible regular expressio
6  .sp  .sp
7  .B int (*pcre_callout)(pcre_callout_block *);  .B int (*pcre_callout)(pcre_callout_block *);
8  .PP  .PP
9    .B int (*pcre16_callout)(pcre16_callout_block *);
10    .PP
11  PCRE provides a feature called "callout", which is a means of temporarily  PCRE provides a feature called "callout", which is a means of temporarily
12  passing control to the caller of PCRE in the middle of pattern matching. The  passing control to the caller of PCRE in the middle of pattern matching. The
13  caller of PCRE provides an external function by putting its entry point in the  caller of PCRE provides an external function by putting its entry point in the
14  global variable \fIpcre_callout\fP. By default, this variable contains NULL,  global variable \fIpcre_callout\fP (\fIpcre16_callout\fP for the 16-bit
15  which disables all calling out.  library). By default, this variable contains NULL, which disables all calling
16    out.
17  .P  .P
18  Within a regular expression, (?C) indicates the points at which the external  Within a regular expression, (?C) indicates the points at which the external
19  function is to be called. Different callout points can be identified by putting  function is to be called. Different callout points can be identified by putting
# Line 19  For example, this pattern has two callou Line 22  For example, this pattern has two callou
22  .sp  .sp
23    (?C1)abc(?C2)def    (?C1)abc(?C2)def
24  .sp  .sp
25  If the PCRE_AUTO_CALLOUT option bit is set when \fBpcre_compile()\fP or  If the PCRE_AUTO_CALLOUT option bit is set when a pattern is compiled, PCRE
26  \fBpcre_compile2()\fP is called, PCRE automatically inserts callouts, all with  automatically inserts callouts, all with number 255, before each item in the
27  number 255, before each item in the pattern. For example, if PCRE_AUTO_CALLOUT  pattern. For example, if PCRE_AUTO_CALLOUT is used with the pattern
 is used with the pattern  
28  .sp  .sp
29    A(\ed{2}|--)    A(\ed{2}|--)
30  .sp  .sp
# Line 65  if the subject is not long enough, or, f Line 67  if the subject is not long enough, or, f
67  been scanned far enough.  been scanned far enough.
68  .P  .P
69  You can disable these optimizations by passing the PCRE_NO_START_OPTIMIZE  You can disable these optimizations by passing the PCRE_NO_START_OPTIMIZE
70  option to \fBpcre_compile()\fP, \fBpcre_exec()\fP, or \fBpcre_dfa_exec()\fP,  option to the matching function, or by starting the pattern with
71  or by starting the pattern with (*NO_START_OPT). This slows down the matching  (*NO_START_OPT). This slows down the matching process, but does ensure that
72  process, but does ensure that callouts such as the example above are obeyed.  callouts such as the example above are obeyed.
73  .  .
74  .  .
75  .SH "THE CALLOUT INTERFACE"  .SH "THE CALLOUT INTERFACE"
76  .rs  .rs
77  .sp  .sp
78  During matching, when PCRE reaches a callout point, the external function  During matching, when PCRE reaches a callout point, the external function
79  defined by \fIpcre_callout\fP is called (if it is set). This applies to both  defined by \fIpcre_callout\fP or \fIpcre16_callout\fP is called (if it is set).
80  the \fBpcre_exec()\fP and the \fBpcre_dfa_exec()\fP matching functions. The  This applies to both normal and DFA matching. The only argument to the callout
81  only argument to the callout function is a pointer to a \fBpcre_callout\fP  function is a pointer to a \fBpcre_callout\fP or \fBpcre16_callout\fP block.
82  block. This structure contains the following fields:  These structures contains the following fields:
83  .sp  .sp
84    int         \fIversion\fP;    int           \fIversion\fP;
85    int         \fIcallout_number\fP;    int           \fIcallout_number\fP;
86    int        *\fIoffset_vector\fP;    int          *\fIoffset_vector\fP;
87    const char *\fIsubject\fP;    const char   *\fIsubject\fP;           (8-bit version)
88    int         \fIsubject_length\fP;    PCRE_SPTR16   \fIsubject\fP;           (16-bit version)
89    int         \fIstart_match\fP;    int           \fIsubject_length\fP;
90    int         \fIcurrent_position\fP;    int           \fIstart_match\fP;
91    int         \fIcapture_top\fP;    int           \fIcurrent_position\fP;
92    int         \fIcapture_last\fP;    int           \fIcapture_top\fP;
93    void       *\fIcallout_data\fP;    int           \fIcapture_last\fP;
94    int         \fIpattern_position\fP;    void         *\fIcallout_data\fP;
95    int         \fInext_item_length\fP;    int           \fIpattern_position\fP;
96    const unsigned char *\fImark\fP;    int           \fInext_item_length\fP;
97      const unsigned char *\fImark\fP;       (8-bit version)
98      const PCRE_SCHAR16  *\fImark\fP;       (16-bit version)
99  .sp  .sp
100  The \fIversion\fP field is an integer containing the version number of the  The \fIversion\fP field is an integer containing the version number of the
101  block format. The initial version was 0; the current version is 2. The version  block format. The initial version was 0; the current version is 2. The version
# Line 103  into the pattern (that is, the number af Line 107  into the pattern (that is, the number af
107  automatically generated callouts).  automatically generated callouts).
108  .P  .P
109  The \fIoffset_vector\fP field is a pointer to the vector of offsets that was  The \fIoffset_vector\fP field is a pointer to the vector of offsets that was
110  passed by the caller to \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP. When  passed by the caller to the matching function. When \fBpcre_exec()\fP or
111  \fBpcre_exec()\fP is used, the contents can be inspected in order to extract  \fBpcre16_exec()\fP is used, the contents can be inspected, in order to extract
112  substrings that have been matched so far, in the same way as for extracting  substrings that have been matched so far, in the same way as for extracting
113  substrings after a match has completed. For \fBpcre_dfa_exec()\fP this field is  substrings after a match has completed. For the DFA matching functions, this
114  not useful.  field is not useful.
115  .P  .P
116  The \fIsubject\fP and \fIsubject_length\fP fields contain copies of the values  The \fIsubject\fP and \fIsubject_length\fP fields contain copies of the values
117  that were passed to \fBpcre_exec()\fP.  that were passed to the matching function.
118  .P  .P
119  The \fIstart_match\fP field normally contains the offset within the subject at  The \fIstart_match\fP field normally contains the offset within the subject at
120  which the current match attempt started. However, if the escape sequence \eK  which the current match attempt started. However, if the escape sequence \eK
# Line 122  in the subject. Line 126  in the subject.
126  The \fIcurrent_position\fP field contains the offset within the subject of the  The \fIcurrent_position\fP field contains the offset within the subject of the
127  current match pointer.  current match pointer.
128  .P  .P
129  When the \fBpcre_exec()\fP function is used, the \fIcapture_top\fP field  When the \fBpcre_exec()\fP or \fBpcre16_exec()\fP is used, the
130  contains one more than the number of the highest numbered captured substring so  \fIcapture_top\fP field contains one more than the number of the highest
131  far. If no substrings have been captured, the value of \fIcapture_top\fP is  numbered captured substring so far. If no substrings have been captured, the
132  one. This is always the case when \fBpcre_dfa_exec()\fP is used, because it  value of \fIcapture_top\fP is one. This is always the case when the DFA
133  does not support captured substrings.  functions are used, because they do not support captured substrings.
134  .P  .P
135  The \fIcapture_last\fP field contains the number of the most recently captured  The \fIcapture_last\fP field contains the number of the most recently captured
136  substring. If no substrings have been captured, its value is -1. This is always  substring. If no substrings have been captured, its value is -1. This is always
137  the case when \fBpcre_dfa_exec()\fP is used.  the case for the DFA matching functions.
138  .P  .P
139  The \fIcallout_data\fP field contains a value that is passed to  The \fIcallout_data\fP field contains a value that is passed to a matching
140  \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP specifically so that it can be  function specifically so that it can be passed back in callouts. It is passed
141  passed back in callouts. It is passed in the \fIpcre_callout\fP field of the  in the \fIcallout_data\fP field of a \fBpcre_extra\fP or \fBpcre16_extra\fP
142  \fBpcre_extra\fP data structure. If no such data was passed, the value of  data structure. If no such data was passed, the value of \fIcallout_data\fP in
143  \fIcallout_data\fP in a \fBpcre_callout\fP block is NULL. There is a  a callout block is NULL. There is a description of the \fBpcre_extra\fP
144  description of the \fBpcre_extra\fP structure in the  structure in the
145  .\" HREF  .\" HREF
146  \fBpcreapi\fP  \fBpcreapi\fP
147  .\"  .\"
148  documentation.  documentation.
149  .P  .P
150  The \fIpattern_position\fP field is present from version 1 of the  The \fIpattern_position\fP field is present from version 1 of the callout
151  \fIpcre_callout\fP structure. It contains the offset to the next item to be  structure. It contains the offset to the next item to be matched in the pattern
152  matched in the pattern string.  string.
153  .P  .P
154  The \fInext_item_length\fP field is present from version 1 of the  The \fInext_item_length\fP field is present from version 1 of the callout
155  \fIpcre_callout\fP structure. It contains the length of the next item to be  structure. It contains the length of the next item to be matched in the pattern
156  matched in the pattern string. When the callout immediately precedes an  string. When the callout immediately precedes an alternation bar, a closing
157  alternation bar, a closing parenthesis, or the end of the pattern, the length  parenthesis, or the end of the pattern, the length is zero. When the callout
158  is zero. When the callout precedes an opening parenthesis, the length is that  precedes an opening parenthesis, the length is that of the entire subpattern.
 of the entire subpattern.  
159  .P  .P
160  The \fIpattern_position\fP and \fInext_item_length\fP fields are intended to  The \fIpattern_position\fP and \fInext_item_length\fP fields are intended to
161  help in distinguishing between different automatic callouts, which all have the  help in distinguishing between different automatic callouts, which all have the
162  same callout number. However, they are set for all callouts.  same callout number. However, they are set for all callouts.
163  .P  .P
164  The \fImark\fP field is present from version 2 of the \fIpcre_callout\fP  The \fImark\fP field is present from version 2 of the callout structure. In
165  structure. In callouts from \fBpcre_exec()\fP it contains a pointer to the  callouts from \fBpcre_exec()\fP or \fBpcre16_exec()\fP it contains a pointer to
166  zero-terminated name of the most recently passed (*MARK), (*PRUNE), or (*THEN)  the zero-terminated name of the most recently passed (*MARK), (*PRUNE), or
167  item in the match, or NULL if no such items have been passed. Instances of  (*THEN) item in the match, or NULL if no such items have been passed. Instances
168  (*PRUNE) or (*THEN) without a name do not obliterate a previous (*MARK). In  of (*PRUNE) or (*THEN) without a name do not obliterate a previous (*MARK). In
169  callouts from \fBpcre_dfa_exec()\fP this field always contains NULL.  callouts from the DFA matching functions this field always contains NULL.
170  .  .
171  .  .
172  .SH "RETURN VALUES"  .SH "RETURN VALUES"
# Line 173  The external callout function returns an Line 176  The external callout function returns an
176  matching proceeds as normal. If the value is greater than zero, matching fails  matching proceeds as normal. If the value is greater than zero, matching fails
177  at the current point, but the testing of other matching possibilities goes  at the current point, but the testing of other matching possibilities goes
178  ahead, just as if a lookahead assertion had failed. If the value is less than  ahead, just as if a lookahead assertion had failed. If the value is less than
179  zero, the match is abandoned, and \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP  zero, the match is abandoned, the matching function returns the negative value.
 returns the negative value.  
180  .P  .P
181  Negative values should normally be chosen from the set of PCRE_ERROR_xxx  Negative values should normally be chosen from the set of PCRE_ERROR_xxx
182  values. In particular, PCRE_ERROR_NOMATCH forces a standard "no match" failure.  values. In particular, PCRE_ERROR_NOMATCH forces a standard "no match" failure.
# Line 196  Cambridge CB2 3QH, England. Line 198  Cambridge CB2 3QH, England.
198  .rs  .rs
199  .sp  .sp
200  .nf  .nf
201  Last updated: 30 November 2011  Last updated: 08 Janurary 2012
202  Copyright (c) 1997-2011 University of Cambridge.  Copyright (c) 1997-2012 University of Cambridge.
203  .fi  .fi

Legend:
Removed from v.857  
changed lines
  Added in v.858

  ViewVC Help
Powered by ViewVC 1.1.5