version 1.1.1.2, 2012/02/21 23:50:25
|
version 1.1.1.4, 2013/07/22 08:25:56
|
Line 1
|
Line 1
|
.TH PCRECALLOUT 3 | .TH PCRECALLOUT 3 "03 March 2013" "PCRE 8.33" |
.SH NAME |
.SH NAME |
PCRE - Perl-compatible regular expressions |
PCRE - Perl-compatible regular expressions |
.SH "PCRE CALLOUTS" | .SH SYNOPSIS |
.rs |
.rs |
.sp |
.sp |
|
.B #include <pcre.h> |
|
.PP |
|
.SM |
.B int (*pcre_callout)(pcre_callout_block *); |
.B int (*pcre_callout)(pcre_callout_block *); |
.PP |
.PP |
.B int (*pcre16_callout)(pcre16_callout_block *); |
.B int (*pcre16_callout)(pcre16_callout_block *); |
.PP |
.PP |
|
.B int (*pcre32_callout)(pcre32_callout_block *); |
|
. |
|
.SH DESCRIPTION |
|
.rs |
|
.sp |
PCRE provides a feature called "callout", which is a means of temporarily |
PCRE provides a feature called "callout", which is a means of temporarily |
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 |
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 |
global variable \fIpcre_callout\fP (\fIpcre16_callout\fP for the 16-bit |
global variable \fIpcre_callout\fP (\fIpcre16_callout\fP for the 16-bit |
library). By default, this variable contains NULL, which disables all calling | library, \fIpcre32_callout\fP for the 32-bit library). By default, this |
out. | variable contains NULL, which disables all calling out. |
.P |
.P |
Within a regular expression, (?C) indicates the points at which the external |
Within a regular expression, (?C) indicates the points at which the external |
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 33 it is processed as if it were
|
Line 41 it is processed as if it were
|
(?C255)A(?C255)((?C255)\ed{2}(?C255)|(?C255)-(?C255)-(?C255))(?C255) |
(?C255)A(?C255)((?C255)\ed{2}(?C255)|(?C255)-(?C255)-(?C255))(?C255) |
.sp |
.sp |
Notice that there is a callout before and after each parenthesis and |
Notice that there is a callout before and after each parenthesis and |
alternation bar. Automatic callouts can be used for tracking the progress of | alternation bar. If the pattern contains a conditional group whose condition is |
pattern matching. The | an assertion, an automatic callout is inserted immediately before the |
| condition. Such a callout may also be inserted explicitly, for example: |
| .sp |
| (?(?C9)(?=a)ab|de) |
| .sp |
| This applies only to assertion conditions (because they are themselves |
| independent groups). |
| .P |
| Automatic callouts can be used for tracking the progress of pattern matching. |
| The |
.\" HREF |
.\" HREF |
\fBpcretest\fP |
\fBpcretest\fP |
.\" |
.\" |
command has an option that sets automatic callouts; when it is used, the output |
command has an option that sets automatic callouts; when it is used, the output |
indicates how the pattern is matched. This is useful information when you are |
indicates how the pattern is matched. This is useful information when you are |
trying to optimize the performance of a particular pattern. |
trying to optimize the performance of a particular pattern. |
.P |
|
The use of callouts in a pattern makes it ineligible for optimization by the |
|
just-in-time compiler. Studying such a pattern with the PCRE_STUDY_JIT_COMPILE |
|
option always fails. |
|
. |
. |
. |
. |
.SH "MISSING CALLOUTS" |
.SH "MISSING CALLOUTS" |
Line 76 callouts such as the example above are obeyed.
|
Line 89 callouts such as the example above are obeyed.
|
.rs |
.rs |
.sp |
.sp |
During matching, when PCRE reaches a callout point, the external function |
During matching, when PCRE reaches a callout point, the external function |
defined by \fIpcre_callout\fP or \fIpcre16_callout\fP is called (if it is set). | defined by \fIpcre_callout\fP or \fIpcre[16|32]_callout\fP is called |
This applies to both normal and DFA matching. The only argument to the callout | (if it is set). This applies to both normal and DFA matching. The only |
function is a pointer to a \fBpcre_callout\fP or \fBpcre16_callout\fP block. | argument to the callout function is a pointer to a \fBpcre_callout\fP |
| or \fBpcre[16|32]_callout\fP block. |
These structures contains the following fields: |
These structures contains the following fields: |
.sp |
.sp |
int \fIversion\fP; |
int \fIversion\fP; |
Line 86 These structures contains the following fields:
|
Line 100 These structures contains the following fields:
|
int *\fIoffset_vector\fP; |
int *\fIoffset_vector\fP; |
const char *\fIsubject\fP; (8-bit version) |
const char *\fIsubject\fP; (8-bit version) |
PCRE_SPTR16 \fIsubject\fP; (16-bit version) |
PCRE_SPTR16 \fIsubject\fP; (16-bit version) |
|
PCRE_SPTR32 \fIsubject\fP; (32-bit version) |
int \fIsubject_length\fP; |
int \fIsubject_length\fP; |
int \fIstart_match\fP; |
int \fIstart_match\fP; |
int \fIcurrent_position\fP; |
int \fIcurrent_position\fP; |
Line 96 These structures contains the following fields:
|
Line 111 These structures contains the following fields:
|
int \fInext_item_length\fP; |
int \fInext_item_length\fP; |
const unsigned char *\fImark\fP; (8-bit version) |
const unsigned char *\fImark\fP; (8-bit version) |
const PCRE_UCHAR16 *\fImark\fP; (16-bit version) |
const PCRE_UCHAR16 *\fImark\fP; (16-bit version) |
|
const PCRE_UCHAR32 *\fImark\fP; (32-bit version) |
.sp |
.sp |
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 |
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 108 automatically generated callouts).
|
Line 124 automatically generated callouts).
|
.P |
.P |
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 |
passed by the caller to the matching function. When \fBpcre_exec()\fP or |
passed by the caller to the matching function. When \fBpcre_exec()\fP or |
\fBpcre16_exec()\fP is used, the contents can be inspected, in order to extract | \fBpcre[16|32]_exec()\fP is used, the contents can be inspected, in order to |
substrings that have been matched so far, in the same way as for extracting | extract substrings that have been matched so far, in the same way as for |
substrings after a match has completed. For the DFA matching functions, this | extracting substrings after a match has completed. For the DFA matching |
field is not useful. | functions, this field is not useful. |
.P |
.P |
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 |
that were passed to the matching function. |
that were passed to the matching function. |
Line 126 in the subject.
|
Line 142 in the subject.
|
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 |
current match pointer. |
current match pointer. |
.P |
.P |
When the \fBpcre_exec()\fP or \fBpcre16_exec()\fP is used, the | When the \fBpcre_exec()\fP or \fBpcre[16|32]_exec()\fP is used, the |
\fIcapture_top\fP field contains one more than the number of the highest |
\fIcapture_top\fP field contains one more than the number of the highest |
numbered captured substring so far. If no substrings have been captured, the |
numbered captured substring so far. If no substrings have been captured, the |
value of \fIcapture_top\fP is one. This is always the case when the DFA |
value of \fIcapture_top\fP is one. This is always the case when the DFA |
functions are used, because they do not support captured substrings. |
functions are used, because they do not support captured substrings. |
.P |
.P |
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 |
substring. If no substrings have been captured, its value is -1. This is always | substring. However, when a recursion exits, the value reverts to what it was |
the case for the DFA matching functions. | outside the recursion, as do the values of all captured substrings. If no |
| substrings have been captured, the value of \fIcapture_last\fP is -1. This is |
| always the case for the DFA matching functions. |
.P |
.P |
The \fIcallout_data\fP field contains a value that is passed to a matching |
The \fIcallout_data\fP field contains a value that is passed to a matching |
function specifically so that it can be passed back in callouts. It is passed |
function specifically so that it can be passed back in callouts. It is passed |
in the \fIcallout_data\fP field of a \fBpcre_extra\fP or \fBpcre16_extra\fP | in the \fIcallout_data\fP field of a \fBpcre_extra\fP or \fBpcre[16|32]_extra\fP |
data structure. If no such data was passed, the value of \fIcallout_data\fP in |
data structure. If no such data was passed, the value of \fIcallout_data\fP in |
a callout block is NULL. There is a description of the \fBpcre_extra\fP |
a callout block is NULL. There is a description of the \fBpcre_extra\fP |
structure in the |
structure in the |
Line 162 help in distinguishing between different automatic cal
|
Line 180 help in distinguishing between different automatic cal
|
same callout number. However, they are set for all callouts. |
same callout number. However, they are set for all callouts. |
.P |
.P |
The \fImark\fP field is present from version 2 of the callout structure. In |
The \fImark\fP field is present from version 2 of the callout structure. In |
callouts from \fBpcre_exec()\fP or \fBpcre16_exec()\fP it contains a pointer to | callouts from \fBpcre_exec()\fP or \fBpcre[16|32]_exec()\fP it contains a |
the zero-terminated name of the most recently passed (*MARK), (*PRUNE), or | pointer to the zero-terminated name of the most recently passed (*MARK), |
(*THEN) item in the match, or NULL if no such items have been passed. Instances | (*PRUNE), or (*THEN) item in the match, or NULL if no such items have been |
of (*PRUNE) or (*THEN) without a name do not obliterate a previous (*MARK). In | passed. Instances of (*PRUNE) or (*THEN) without a name do not obliterate a |
callouts from the DFA matching functions this field always contains NULL. | previous (*MARK). In callouts from the DFA matching functions this field always |
| contains NULL. |
. |
. |
. |
. |
.SH "RETURN VALUES" |
.SH "RETURN VALUES" |
Line 198 Cambridge CB2 3QH, England.
|
Line 217 Cambridge CB2 3QH, England.
|
.rs |
.rs |
.sp |
.sp |
.nf |
.nf |
Last updated: 08 Janurary 2012 | Last updated: 03 March 2013 |
Copyright (c) 1997-2012 University of Cambridge. | Copyright (c) 1997-2013 University of Cambridge. |
.fi |
.fi |