diff options
| author | Gluzskiy Alexandr <sss123next@gmail.com> | 2010-02-15 05:51:01 +0300 |
|---|---|---|
| committer | Gluzskiy Alexandr <sss123next@gmail.com> | 2010-02-15 05:51:01 +0300 |
| commit | 7fd9fe181150f166a098eaf4e006f878c28cb770 (patch) | |
| tree | 093af9d26a08e6bac60112a9c5f2f870ddef0fe8 /Utilities/PCRE/man/html/pcrecallout.3.html | |
| parent | 6f32ef233b95d78efb905c97081193a2a454590e (diff) | |
sort
Diffstat (limited to 'Utilities/PCRE/man/html/pcrecallout.3.html')
| -rw-r--r-- | Utilities/PCRE/man/html/pcrecallout.3.html | 148 |
1 files changed, 148 insertions, 0 deletions
diff --git a/Utilities/PCRE/man/html/pcrecallout.3.html b/Utilities/PCRE/man/html/pcrecallout.3.html new file mode 100644 index 0000000..83e61b2 --- /dev/null +++ b/Utilities/PCRE/man/html/pcrecallout.3.html @@ -0,0 +1,148 @@ +<!-- manual page source format generated by PolyglotMan v3.2, -->
+<!-- available at http://polyglotman.sourceforge.net/ -->
+
+<html>
+<head>
+<title>PCRE(3) manual page</title>
+</head>
+<body bgcolor='white'>
+<a href='#toc'>Table of Contents</a><p>
+
+<h2><a name='sect0' href='#toc0'>Name</a></h2>
+PCRE - Perl-compatible regular expressions
+<h2><a name='sect1' href='#toc1'>Pcre Callouts</a></h2>
+ <p>
+<b>int (*pcre_callout)(pcre_callout_block
+*);</b> <p>
+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 caller of PCRE provides an external function by putting its entry point
+in the global variable <i>pcre_callout</i>. By default, this variable contains
+NULL, which disables all calling out. <p>
+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 a number less than 256 after
+the letter C. The default value is zero. For example, this pattern has two
+callout points: <p>
+ (?C1)deabc(?C2)def<br>
+ <p>
+If the PCRE_AUTO_CALLOUT option bit is set when <b>pcre_compile()</b> is called,
+PCRE automatically inserts callouts, all with number 255, before each item
+in the pattern. For example, if PCRE_AUTO_CALLOUT is used with the pattern
+<p>
+ A(\d{2}|--)<br>
+ <p>
+it is processed as if it were <p>
+(?C255)A(?C255)((?C255)\d{2}(?C255)|(?C255)-(?C255)-(?C255))(?C255)
+<p>
+Notice that there is a callout before and after each parenthesis and alternation
+bar. Automatic callouts can be used for tracking the progress of pattern
+matching. The <b>pcretest</b> 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 trying to optimize the performance of a
+particular pattern.
+<h2><a name='sect2' href='#toc2'>Missing Callouts</a></h2>
+ <p>
+You should be aware that, because
+of optimizations in the way PCRE matches patterns, callouts sometimes do
+not happen. For example, if the pattern is <p>
+ ab(?C4)cd<br>
+ <p>
+PCRE knows that any matching string must contain the letter "d". If the
+subject string is "abyz", the lack of "d" means that matching doesn’t ever
+start, and the callout is never reached. However, with "abyd", though the
+result is still no match, the callout is obeyed.
+<h2><a name='sect3' href='#toc3'>the Callout Interface</a></h2>
+
+<p>
+During matching, when PCRE reaches a callout point, the external function
+defined by <i>pcre_callout</i> is called (if it is set). The only argument is a
+pointer to a <b>pcre_callout</b> block. This structure contains the following fields:
+<p>
+ int <i>version</i>;<br>
+ int <i>callout_number</i>;<br>
+ int *<i>offset_vector</i>;<br>
+ const char *<i>subject</i>;<br>
+ int <i>subject_length</i>;<br>
+ int <i>start_match</i>;<br>
+ int <i>current_position</i>;<br>
+ int <i>capture_top</i>;<br>
+ int <i>capture_last</i>;<br>
+ void *<i>callout_data</i>;<br>
+ int <i>pattern_position</i>;<br>
+ int <i>next_item_length</i>;<br>
+ <p>
+The <i>version</i> field is an integer containing the version number of the block
+format. The initial version was 0; the current version is 1. The version
+number will change again in future if additional fields are added, but
+the intention is never to remove any of the existing fields. <p>
+The <i>callout_number</i>
+field contains the number of the callout, as compiled into the pattern
+(that is, the number after ?C for manual callouts, and 255 for automatically
+generated callouts). <p>
+The <i>offset_vector</i> field is a pointer to the vector
+of offsets that was passed by the caller to <b>pcre_exec()</b>. The contents can
+be inspected in order to extract substrings that have been matched so far,
+in the same way as for extracting substrings after a match has completed.
+<p>
+The <i>subject</i> and <i>subject_length</i> fields contain copies of the values that
+were passed to <b>pcre_exec()</b>. <p>
+The <i>start_match</i> field contains the offset within
+the subject at which the current match attempt started. If the pattern is
+not anchored, the callout function may be called several times from the
+same point in the pattern for different starting points in the subject.
+<p>
+The <i>current_position</i> field contains the offset within the subject of the
+current match pointer. <p>
+The <i>capture_top</i> field contains one more than the
+number of the highest numbered captured substring so far. If no substrings
+have been captured, the value of <i>capture_top</i> is one. <p>
+The <i>capture_last</i> field
+contains the number of the most recently captured substring. If no substrings
+have been captured, its value is -1. <p>
+The <i>callout_data</i> field contains a value
+that is passed to <b>pcre_exec()</b> by the caller specifically so that it can
+be passed back in callouts. It is passed in the <i>pcre_callout</i> field of the
+<b>pcre_extra</b> data structure. If no such data was passed, the value of <i>callout_data</i>
+in a <b>pcre_callout</b> block is NULL. There is a description of the <b>pcre_extra</b>
+structure in the <b>pcreapi</b> documentation. <p>
+The <i>pattern_position</i> field is
+present from version 1 of the <i>pcre_callout</i> structure. It contains the offset
+to the next item to be matched in the pattern string. <p>
+The <i>next_item_length</i>
+field is present from version 1 of the <i>pcre_callout</i> structure. It contains
+the length of the next item to be matched in the pattern string. When the
+callout immediately precedes an alternation bar, a closing parenthesis,
+or the end of the pattern, the length is zero. When the callout precedes
+an opening parenthesis, the length is that of the entire subpattern. <p>
+The
+<i>pattern_position</i> and <i>next_item_length</i> fields are intended to help in distinguishing
+between different automatic callouts, which all have the same callout number.
+However, they are set for all callouts.
+<h2><a name='sect4' href='#toc4'>Return Values</a></h2>
+ <p>
+The external callout
+function returns an integer to PCRE. If the value is zero, matching proceeds
+as normal. If the value is greater than zero, matching fails at the current
+point, but backtracking to test other matching possibilities goes ahead,
+just as if a lookahead assertion had failed. If the value is less than zero,
+the match is abandoned, and <b>pcre_exec()</b> returns the negative value. <p>
+Negative
+values should normally be chosen from the set of PCRE_ERROR_xxx values.
+In particular, PCRE_ERROR_NOMATCH forces a standard "no match" failure.
+The error number PCRE_ERROR_CALLOUT is reserved for use by callout functions;
+it will never be used by PCRE itself. <p>
+ Last updated: 09 September 2004 <br>
+Copyright (c) 1997-2004 University of Cambridge. <p>
+
+<hr><p>
+<a name='toc'><b>Table of Contents</b></a><p>
+<ul>
+<li><a name='toc0' href='#sect0'>Name</a></li>
+<li><a name='toc1' href='#sect1'>Pcre Callouts</a></li>
+<li><a name='toc2' href='#sect2'>Missing Callouts</a></li>
+<li><a name='toc3' href='#sect3'>the Callout Interface</a></li>
+<li><a name='toc4' href='#sect4'>Return Values</a></li>
+</ul>
+</body>
+</html>
|