embedaddon/pcre/doc/html/pcrecallout.html - view

File: [ELWIX - Embedded LightWeight unIX -] / embedaddon / pcre / doc / html / pcrecallout.html
Revision 1.1.1.4 (vendor branch): download - view: text, annotated - select for diffs - revision graph
Sun Jun 15 19:46:05 2014 UTC (10 years, 9 months ago) by misho
Branches: pcre, MAIN
CVS tags: v8_34, HEAD

pcre 8.34

1: <html> 2: <head> 3: <title>pcrecallout specification</title> 4: </head> 5: <body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB"> 6: <h1>pcrecallout man page</h1> 7:  8: Return to the <a href="index.html">PCRE index page</a>. 9:  10:  11: This page is part of the PCRE HTML documentation. It was generated automatically 12: from the original man page. If there is any nonsense in it, please consult the 13: man page, in case the conversion went wrong. 14:   15: <ul> 16: <li><a name="TOC1" href="#SEC1">SYNOPSIS</a> 17: <li><a name="TOC2" href="#SEC2">DESCRIPTION</a> 18: <li><a name="TOC3" href="#SEC3">MISSING CALLOUTS</a> 19: <li><a name="TOC4" href="#SEC4">THE CALLOUT INTERFACE</a> 20: <li><a name="TOC5" href="#SEC5">RETURN VALUES</a> 21: <li><a name="TOC6" href="#SEC6">AUTHOR</a> 22: <li><a name="TOC7" href="#SEC7">REVISION</a> 23: </ul> 24:  <a name="SEC1" href="#TOC1">SYNOPSIS</a>  25:  26: #include <pcre.h> 27:  28:  29: int (*pcre_callout)(pcre_callout_block *); 30:  31:  32: int (*pcre16_callout)(pcre16_callout_block *); 33:  34:  35: int (*pcre32_callout)(pcre32_callout_block *); 36:  37:  <a name="SEC2" href="#TOC1">DESCRIPTION</a>  38:  39: PCRE provides a feature called "callout", which is a means of temporarily 40: passing control to the caller of PCRE in the middle of pattern matching. The 41: caller of PCRE provides an external function by putting its entry point in the 42: global variable pcre_callout (pcre16_callout for the 16-bit 43: library, pcre32_callout for the 32-bit library). By default, this 44: variable contains NULL, which disables all calling out. 45:  46:  47: Within a regular expression, (?C) indicates the points at which the external 48: function is to be called. Different callout points can be identified by putting 49: a number less than 256 after the letter C. The default value is zero. 50: For example, this pattern has two callout points: 51: <pre> 52: (?C1)abc(?C2)def 53: </pre> 54: If the PCRE_AUTO_CALLOUT option bit is set when a pattern is compiled, PCRE 55: automatically inserts callouts, all with number 255, before each item in the 56: pattern. For example, if PCRE_AUTO_CALLOUT is used with the pattern 57: <pre> 58: A(\d{2}|--) 59: </pre> 60: it is processed as if it were 61:   62:   63: (?C255)A(?C255)((?C255)\d{2}(?C255)|(?C255)-(?C255)-(?C255))(?C255) 64:   65:   66: Notice that there is a callout before and after each parenthesis and 67: alternation bar. If the pattern contains a conditional group whose condition is 68: an assertion, an automatic callout is inserted immediately before the 69: condition. Such a callout may also be inserted explicitly, for example: 70: <pre> 71: (?(?C9)(?=a)ab|de) 72: </pre> 73: This applies only to assertion conditions (because they are themselves 74: independent groups). 75:  76:  77: Automatic callouts can be used for tracking the progress of pattern matching. 78: The 79: <a href="pcretest.html">pcretest</a> 80: program has a pattern qualifier (/C) that sets automatic callouts; when it is 81: used, the output indicates how the pattern is being matched. This is useful 82: information when you are trying to optimize the performance of a particular 83: pattern. 84:  85:  <a name="SEC3" href="#TOC1">MISSING CALLOUTS</a>  86:  87: You should be aware that, because of optimizations in the way PCRE compiles and 88: matches patterns, callouts sometimes do not happen exactly as you might expect. 89:  90:  91: At compile time, PCRE "auto-possessifies" repeated items when it knows that 92: what follows cannot be part of the repeat. For example, a+[bc] is compiled as 93: if it were a++[bc]. The pcretest output when this pattern is anchored and 94: then applied with automatic callouts to the string "aaaa" is: 95: <pre> 96: --->aaaa 97: +0 ^ ^ 98: +1 ^ a+ 99: +3 ^ ^ [bc] 100: No match 101: </pre> 102: This indicates that when matching [bc] fails, there is no backtracking into a+ 103: and therefore the callouts that would be taken for the backtracks do not occur. 104: You can disable the auto-possessify feature by passing PCRE_NO_AUTO_POSSESS 105: to pcre_compile(), or starting the pattern with (*NO_AUTO_POSSESS). If 106: this is done in pcretest (using the /O qualifier), the output changes to 107: this: 108: <pre> 109: --->aaaa 110: +0 ^ ^ 111: +1 ^ a+ 112: +3 ^ ^ [bc] 113: +3 ^ ^ [bc] 114: +3 ^ ^ [bc] 115: +3 ^^ [bc] 116: No match 117: </pre> 118: This time, when matching [bc] fails, the matcher backtracks into a+ and tries 119: again, repeatedly, until a+ itself fails. 120:  121:  122: Other optimizations that provide fast "no match" results also affect callouts. 123: For example, if the pattern is 124: <pre> 125: ab(?C4)cd 126: </pre> 127: PCRE knows that any matching string must contain the letter "d". If the subject 128: string is "abyz", the lack of "d" means that matching doesn't ever start, and 129: the callout is never reached. However, with "abyd", though the result is still 130: no match, the callout is obeyed. 131:  132:  133: If the pattern is studied, PCRE knows the minimum length of a matching string, 134: and will immediately give a "no match" return without actually running a match 135: if the subject is not long enough, or, for unanchored patterns, if it has 136: been scanned far enough. 137:  138:  139: You can disable these optimizations by passing the PCRE_NO_START_OPTIMIZE 140: option to the matching function, or by starting the pattern with 141: (*NO_START_OPT). This slows down the matching process, but does ensure that 142: callouts such as the example above are obeyed. 143:  144:  <a name="SEC4" href="#TOC1">THE CALLOUT INTERFACE</a>  145:  146: During matching, when PCRE reaches a callout point, the external function 147: defined by pcre_callout or pcre[16|32]_callout is called (if it is 148: set). This applies to both normal and DFA matching. The only argument to the 149: callout function is a pointer to a pcre_callout or 150: pcre[16|32]_callout block. These structures contains the following 151: fields: 152: <pre> 153: int version; 154: int callout_number; 155: int *offset_vector; 156: const char *subject; (8-bit version) 157: PCRE_SPTR16 subject; (16-bit version) 158: PCRE_SPTR32 subject; (32-bit version) 159: int subject_length; 160: int start_match; 161: int current_position; 162: int capture_top; 163: int capture_last; 164: void *callout_data; 165: int pattern_position; 166: int next_item_length; 167: const unsigned char *mark; (8-bit version) 168: const PCRE_UCHAR16 *mark; (16-bit version) 169: const PCRE_UCHAR32 *mark; (32-bit version) 170: </pre> 171: The version field is an integer containing the version number of the 172: block format. The initial version was 0; the current version is 2. The version 173: number will change again in future if additional fields are added, but the 174: intention is never to remove any of the existing fields. 175:  176:  177: The callout_number field contains the number of the callout, as compiled 178: into the pattern (that is, the number after ?C for manual callouts, and 255 for 179: automatically generated callouts). 180:  181:  182: The offset_vector field is a pointer to the vector of offsets that was 183: passed by the caller to the matching function. When pcre_exec() or 184: pcre[16|32]_exec() is used, the contents can be inspected, in order to 185: extract substrings that have been matched so far, in the same way as for 186: extracting substrings after a match has completed. For the DFA matching 187: functions, this field is not useful. 188:  189:  190: The subject and subject_length fields contain copies of the values 191: that were passed to the matching function. 192:  193:  194: The start_match field normally contains the offset within the subject at 195: which the current match attempt started. However, if the escape sequence \K 196: has been encountered, this value is changed to reflect the modified starting 197: point. If the pattern is not anchored, the callout function may be called 198: several times from the same point in the pattern for different starting points 199: in the subject. 200:  201:  202: The current_position field contains the offset within the subject of the 203: current match pointer. 204:  205:  206: When the pcre_exec() or pcre[16|32]_exec() is used, the 207: capture_top field contains one more than the number of the highest 208: numbered captured substring so far. If no substrings have been captured, the 209: value of capture_top is one. This is always the case when the DFA 210: functions are used, because they do not support captured substrings. 211:  212:  213: The capture_last field contains the number of the most recently captured 214: substring. However, when a recursion exits, the value reverts to what it was 215: outside the recursion, as do the values of all captured substrings. If no 216: substrings have been captured, the value of capture_last is -1. This is 217: always the case for the DFA matching functions. 218:  219:  220: The callout_data field contains a value that is passed to a matching 221: function specifically so that it can be passed back in callouts. It is passed 222: in the callout_data field of a pcre_extra or pcre[16|32]_extra 223: data structure. If no such data was passed, the value of callout_data in 224: a callout block is NULL. There is a description of the pcre_extra 225: structure in the 226: <a href="pcreapi.html">pcreapi</a> 227: documentation. 228:  229:  230: The pattern_position field is present from version 1 of the callout 231: structure. It contains the offset to the next item to be matched in the pattern 232: string. 233:  234:  235: The next_item_length field is present from version 1 of the callout 236: structure. It contains the length of the next item to be matched in the pattern 237: string. When the callout immediately precedes an alternation bar, a closing 238: parenthesis, or the end of the pattern, the length is zero. When the callout 239: precedes an opening parenthesis, the length is that of the entire subpattern. 240:  241:  242: The pattern_position and next_item_length fields are intended to 243: help in distinguishing between different automatic callouts, which all have the 244: same callout number. However, they are set for all callouts. 245:  246:  247: The mark field is present from version 2 of the callout structure. In 248: callouts from pcre_exec() or pcre[16|32]_exec() it contains a 249: pointer to the zero-terminated name of the most recently passed (*MARK), 250: (*PRUNE), or (*THEN) item in the match, or NULL if no such items have been 251: passed. Instances of (*PRUNE) or (*THEN) without a name do not obliterate a 252: previous (*MARK). In callouts from the DFA matching functions this field always 253: contains NULL. 254:  255:  <a name="SEC5" href="#TOC1">RETURN VALUES</a>  256:  257: The external callout function returns an integer to PCRE. If the value is zero, 258: matching proceeds as normal. If the value is greater than zero, matching fails 259: at the current point, but the testing of other matching possibilities goes 260: ahead, just as if a lookahead assertion had failed. If the value is less than 261: zero, the match is abandoned, the matching function returns the negative value. 262:  263:  264: Negative values should normally be chosen from the set of PCRE_ERROR_xxx 265: values. In particular, PCRE_ERROR_NOMATCH forces a standard "no match" failure. 266: The error number PCRE_ERROR_CALLOUT is reserved for use by callout functions; 267: it will never be used by PCRE itself. 268:  269:  <a name="SEC6" href="#TOC1">AUTHOR</a>  270:  271: Philip Hazel 272:   273: University Computing Service 274:   275: Cambridge CB2 3QH, England. 276:   277:  278:  <a name="SEC7" href="#TOC1">REVISION</a>  279:  280: Last updated: 12 November 2013 281:   282: Copyright © 1997-2013 University of Cambridge. 283:   284:  285: Return to the <a href="index.html">PCRE index page</a>. 286: 