README

   1 NAME
   2     re::engine::Hooks - Hookable variant of the Perl core regular expression
   3     engine.
   4
   5 VERSION
   6     Version 0.05
   7
   8 SYNOPSIS
   9     In your XS file :
  10
  11         #include "re_engine_hooks.h"
  12
  13         STATIC void dri_comp_node_hook(pTHX_ regexp *rx, regnode *node) {
  14          ...
  15         }
  16
  17         STATIC void dri_exec_node_hook(pTHX_
  18            regexp *rx, regnode *node, regmatch_info *info, regmatch_state *state) {
  19          ...
  20         }
  21
  22         MODULE = Devel::Regexp::Instrument    PACKAGE = Devel::Regexp::Instrument
  23
  24         BOOT:
  25         {
  26          reh_config cfg;
  27          cfg.comp_node = dri_comp_node_hook;
  28          cfg.exec_node = dri_exec_node_hook;
  29          reh_register("Devel::Regexp::Instrument", &cfg);
  30         }
  31
  32     In your Perl module file :
  33
  34         package Devel::Regexp::Instrument;
  35
  36         use strict;
  37         use warnings;
  38
  39         our ($VERSION, @ISA);
  40
  41         use re::engine::Hooks; # Before loading our own shared library
  42
  43         BEGIN {
  44          $VERSION = '0.01';
  45          require DynaLoader;
  46          push @ISA, 'DynaLoader';
  47          __PACKAGE__->bootstrap($VERSION);
  48         }
  49
  50         sub import   { re::engine::Hooks::enable(__PACKAGE__) }
  51
  52         sub unimport { re::engine::Hooks::disable(__PACKAGE__) }
  53
  54         1;
  55
  56     In your Makefile.PL
  57
  58         use ExtUtils::Depends;
  59
  60         my $ed = ExtUtils::Depends->new(
  61          'Devel::Regexp::Instrument' => 're::engine::Hooks',
  62         );
  63
  64         WriteMakefile(
  65          $ed->get_makefile_vars,
  66          ...
  67         );
  68
  69 DESCRIPTION
  70     This module provides a version of the perl regexp engine that can call
  71     user-defined XS callbacks at the compilation and at the execution of
  72     each regexp node.
  73
  74 C API
  75     The C API is made available through the re_engine_hooks.h header file.
  76
  77   "reh_comp_node_hook"
  78     The typedef for the regexp node compilation phase hook. Currently
  79     evaluates to :
  80
  81         typedef void (*reh_comp_node_hook)(pTHX_ regexp *, regnode *);
  82
  83   "reh_exec_node_hook"
  84     The typedef for the regexp node_execution phase hook. Currently
  85     evaluates to :
  86
  87         typedef void (*reh_exec_node_hook)(pTHX_ regexp *, regnode *, regmatch_info *, regmatch_state *);
  88
  89   "reh_config"
  90     A typedef'd struct that holds a set of all the different callbacks
  91     publicized by this module. It has the following members :
  92
  93     *   "comp_node"
  94
  95         A function pointer of type "reh_comp_node_hook" that will be called
  96         each time a regnode is compiled. Allowed to be "NULL" if you don't
  97         want to call anything for this phase.
  98
  99     *   "exec_node"
 100
 101         A function pointer of type "reh_exec_node_hook" that will be called
 102         each time a regnode is executed. Allowed to be "NULL" if you don't
 103         want to call anything for this phase.
 104
 105   "reh_register"
 106         void reh_register(pTHX_ const char *key, reh_config *cfg);
 107
 108     Registers the callbacks specified by the "reh_config *" object "cfg"
 109     under the given name "key". "cfg" can be a pointer to a static object of
 110     type "reh_config". "key" is expected to be a nul-terminated string and
 111     should match the argument passed to "enable" and "disable" in Perl land.
 112     An exception will be thrown if "key" has already been used to register
 113     callbacks.
 114
 115 PERL API
 116   "enable"
 117         enable $key;
 118
 119     Lexically enables the hooks associated with the key $key.
 120
 121   "disable"
 122         disable $key;
 123
 124     Lexically disables the hooks associated with the key $key.
 125
 126 EXAMPLES
 127     Please refer to the t/re-engine-Hooks-TestDist/ directory in the
 128     distribution. It implements a couple of simple examples.
 129
 130 DEPENDENCIES
 131     Any stable release of perl since 5.10.1, or a development release of
 132     perl from the 5.19 branch.
 133
 134     A C compiler. This module may happen to build with a C++ compiler as
 135     well, but don't rely on it, as no guarantee is made in this regard.
 136
 137     ExtUtils::Depends.
 138
 139 SEE ALSO
 140     perlreguts.
 141
 142 AUTHOR
 143     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 144
 145     You can contact me by mail or on "irc.perl.org" (vincent).
 146
 147 BUGS
 148     Please report any bugs or feature requests to "bug-re-engine-hooks at
 149     rt.cpan.org", or through the web interface at
 150     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=re-engine-Hooks>. I will
 151     be notified, and then you'll automatically be notified of progress on
 152     your bug as I make changes.
 153
 154 SUPPORT
 155     You can find documentation for this module with the perldoc command :
 156
 157         perldoc re::engine::Hooks
 158
 159 COPYRIGHT & LICENSE
 160     Copyright 2012,2013 Vincent Pit, all rights reserved.
 161
 162     This program is free software; you can redistribute it and/or modify it
 163     under the same terms as Perl itself.
 164