/[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 75 by nigel, Sat Feb 24 21:40:37 2007 UTC revision 77 by nigel, Sat Feb 24 21:40:45 2007 UTC
# Line 58  no match, the callout is obeyed. Line 58  no match, the callout is obeyed.
58  .rs  .rs
59  .sp  .sp
60  During matching, when PCRE reaches a callout point, the external function  During matching, when PCRE reaches a callout point, the external function
61  defined by \fIpcre_callout\fP is called (if it is set). The only argument is a  defined by \fIpcre_callout\fP is called (if it is set). This applies to both
62  pointer to a \fBpcre_callout\fP block. This structure contains the following  the \fBpcre_exec()\fP and the \fBpcre_dfa_exec()\fP matching functions. The
63  fields:  only argument to the callout function is a pointer to a \fBpcre_callout\fP
64    block. This structure contains the following fields:
65  .sp  .sp
66    int          \fIversion\fP;    int          \fIversion\fP;
67    int          \fIcallout_number\fP;    int          \fIcallout_number\fP;
# Line 85  into the pattern (that is, the number af Line 86  into the pattern (that is, the number af
86  automatically generated callouts).  automatically generated callouts).
87  .P  .P
88  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
89  passed by the caller to \fBpcre_exec()\fP. The contents can be inspected in  passed by the caller to \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP. When
90  order to extract substrings that have been matched so far, in the same way as  \fBpcre_exec()\fP is used, the contents can be inspected in order to extract
91  for extracting substrings after a match has completed.  substrings that have been matched so far, in the same way as for extracting
92    substrings after a match has completed. For \fBpcre_dfa_exec()\fP this field is
93    not useful.
94  .P  .P
95  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
96  that were passed to \fBpcre_exec()\fP.  that were passed to \fBpcre_exec()\fP.
# Line 100  different starting points in the subject Line 103  different starting points in the subject
103  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
104  current match pointer.  current match pointer.
105  .P  .P
106  The \fIcapture_top\fP field contains one more than the number of the highest  When the \fBpcre_exec()\fP function is used, the \fIcapture_top\fP field
107  numbered captured substring so far. If no substrings have been captured,  contains one more than the number of the highest numbered captured substring so
108  the value of \fIcapture_top\fP is one.  far. If no substrings have been captured, the value of \fIcapture_top\fP is
109    one. This is always the case when \fBpcre_dfa_exec()\fP is used, because it
110    does not support captured substrings.
111  .P  .P
112  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
113  substring. If no substrings have been captured, its value is -1.  substring. If no substrings have been captured, its value is -1. This is always
114    the case when \fBpcre_dfa_exec()\fP is used.
115  .P  .P
116  The \fIcallout_data\fP field contains a value that is passed to  The \fIcallout_data\fP field contains a value that is passed to
117  \fBpcre_exec()\fP by the caller specifically so that it can be passed back in  \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP specifically so that it can be
118  callouts. It is passed in the \fIpcre_callout\fP field of the \fBpcre_extra\fP  passed back in callouts. It is passed in the \fIpcre_callout\fP field of the
119  data structure. If no such data was passed, the value of \fIcallout_data\fP in  \fBpcre_extra\fP data structure. If no such data was passed, the value of
120  a \fBpcre_callout\fP block is NULL. There is a description of the  \fIcallout_data\fP in a \fBpcre_callout\fP block is NULL. There is a
121  \fBpcre_extra\fP structure in the  description of the \fBpcre_extra\fP structure in the
122  .\" HREF  .\" HREF
123  \fBpcreapi\fP  \fBpcreapi\fP
124  .\"  .\"
# Line 139  same callout number. However, they are s Line 145  same callout number. However, they are s
145  .sp  .sp
146  The external callout function returns an integer to PCRE. If the value is zero,  The external callout function returns an integer to PCRE. If the value is zero,
147  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
148  at the current point, but backtracking to test other matching possibilities  at the current point, but the testing of other matching possibilities goes
149  goes ahead, just as if a lookahead assertion had failed. If the value is less  ahead, just as if a lookahead assertion had failed. If the value is less than
150  than zero, the match is abandoned, and \fBpcre_exec()\fP returns the negative  zero, the match is abandoned, and \fBpcre_exec()\fP (or \fBpcre_dfa_exec()\fP)
151  value.  returns the negative value.
152  .P  .P
153  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
154  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 150  The error number PCRE_ERROR_CALLOUT is r Line 156  The error number PCRE_ERROR_CALLOUT is r
156  it will never be used by PCRE itself.  it will never be used by PCRE itself.
157  .P  .P
158  .in 0  .in 0
159  Last updated: 09 September 2004  Last updated: 28 February 2005
160  .br  .br
161  Copyright (c) 1997-2004 University of Cambridge.  Copyright (c) 1997-2005 University of Cambridge.

Legend:
Removed from v.75  
changed lines
  Added in v.77

  ViewVC Help
Powered by ViewVC 1.1.5