pcrecallout man page on Aros

Printed from http://www.polarhome.com/service/man/?qf=pcrecallout&af=0&tf=2&of=Aros

PCRE(3)								       PCRE(3)

NAME
       PCRE - Perl-compatible regular expressions

PCRE CALLOUTS

       int (*pcre_callout)(pcre_callout_block *);

       PCRE provides a feature called "callout", which is a means of temporar‐
       ily 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 pcre_callout. By	default,  this
       variable contains NULL, which disables all calling out.

       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:

	 (?C1)abc(?C2)def

       During matching, when PCRE reaches a callout point (and pcre_callout is
       set), the external function is called. Its only argument is  a  pointer
       to a pcre_callout block. This contains the following variables:

	 int	      version;
	 int	      callout_number;
	 int	     *offset_vector;
	 const char  *subject;
	 int	      subject_length;
	 int	      start_match;
	 int	      current_position;
	 int	      capture_top;
	 int	      capture_last;
	 void	     *callout_data;

       The  version  field  is an integer containing the version number of the
       block format. The current version  is  zero.  The  version  number  may
       change  in  future if additional fields are added, but the intention is
       never to remove any of the existing fields.

       The callout_number field contains the number of the  callout,  as  com‐
       piled into the pattern (that is, the number after ?C).

       The  offset_vector field is a pointer to the vector of offsets that was
       passed by the caller to pcre_exec(). 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.

       The subject and subject_length fields contain copies  the  values  that
       were passed to pcre_exec().

       The  start_match	 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 for different starting
       points.

       The current_position field contains the offset within  the  subject  of
       the current match pointer.

       The  capture_top field contains one more than the number of the highest
       numbered captured substring so far. If no  substrings  have  been  cap‐
       tured, the value of capture_top is one.

       The  capture_last  field	 contains the number of the most recently cap‐
       tured substring.

       The callout_data field contains a value that is passed  to  pcre_exec()
       by  the	caller specifically so that it can be passed back in callouts.
       It is passed in the pcre_callout field of the  pcre_extra  data	struc‐
       ture.  If  no  such  data  was  passed,	the value of callout_data in a
       pcre_callout block is NULL. There is a description  of  the  pcre_extra
       structure in the pcreapi documentation.

RETURN VALUES

       The callout function returns an integer. 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 possibilities goes
       ahead, just as if a lookahead assertion had failed.  If	the  value  is
       less  than  zero,  the  match is abandoned, and pcre_exec() returns the
       value.

       Negative	 values	 should	 normally  be	chosen	 from	the   set   of
       PCRE_ERROR_xxx values. In particular, PCRE_ERROR_NOMATCH forces a stan‐
       dard "no	 match"	 failure.   The	 error	number	PCRE_ERROR_CALLOUT  is
       reserved	 for  use  by callout functions; it will never be used by PCRE
       itself.

Last updated: 21 January 2003
Copyright (c) 1997-2003 University of Cambridge.

								       PCRE(3)
[top]

List of man pages available for Aros

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net