README

   1 NAME
   2     re::engine::Hooks - Hookable variant of the Perl core regular expression
   3     engine.
   4
   5 VERSION
   6     Version 0.01
   7
   8 SYNOPSIS
   9     In your XS file :
  10
  11         #include "re_engine_hooks.h"
  12
  13         STATIC void dri_comp_hook(pTHX_ regexp *rx, regnode *node) {
  14          ...
  15         }
  16
  17         STATIC void dri_exec_hook(pTHX_ regexp *rx, regnode *node,
  18                                   regmatch_info *info, regmatch_state *state) {
  19          ...
  20         }
  21
  22         MODULE = Devel::Regexp::Instrument    PACKAGE = Devel::Regexp::Instrument
  23
  24         BOOT:
  25         {
  26          reh_register("Devel::Regexp::Instrument", dri_comp_hook, dri_exec_hook);
  27         }
  28
  29     In your Perl module file :
  30
  31         package Devel::Regexp::Instrument;
  32
  33         use strict;
  34         use warnings;
  35
  36         our ($VERSION, @ISA);
  37
  38         use re::engine::Hooks; # Before loading our own shared library
  39
  40         BEGIN {
  41          $VERSION = '0.01';
  42          require DynaLoader;
  43          push @ISA, 'DynaLoader';
  44          __PACKAGE__->bootstrap($VERSION);
  45         }
  46
  47         sub import   { re::engine::Hooks::enable(__PACKAGE__) }
  48
  49         sub unimport { re::engine::Hooks::disable(__PACKAGE__) }
  50
  51         1;
  52
  53     In your Makefile.PL
  54
  55         use ExtUtils::Depends;
  56
  57         my $ed = ExtUtils::Depends->new(
  58          'Devel::Regexp::Instrument' => 're::engine::Hooks',
  59         );
  60
  61         WriteMakefile(
  62          $ed->get_makefile_vars,
  63          ...
  64         );
  65
  66 DESCRIPTION
  67     This module provides a version of the perl regexp engine that can call
  68     user-defined XS callbacks at the compilation and at the execution of
  69     each regexp node.
  70
  71 C API
  72     The C API is made available through the re_engine_hooks.h header file.
  73
  74   "reh_comp_hook"
  75     The typedef for the regexp compilation phase hook. Currently evaluates
  76     to :
  77
  78         typedef void (*reh_comp_hook)(pTHX_ regexp *, regnode *);
  79
  80   "reh_exec_hook"
  81     The typedef for the regexp execution phase hook. Currently evaluates to
  82     :
  83
  84         typedef void (*reh_exec_hook)(pTHX_ regexp *, regnode *, regmatch_info *, regmatch_state *);
  85
  86   "reh_register"
  87         void reh_register(pTHX_ const char *key, reh_comp_hook comp, reh_exec_hook exec);
  88
  89     Registers under the given name "key" a callback "comp" that will run
  90     during the compilation phase and a callback "exec" that will run during
  91     the execution phase. Null function pointers are allowed in case you
  92     don't want to hook one of the phases. "key" should match with the
  93     argument passed to "enable" and "disable" in Perl land. An exception
  94     will be thrown if "key" has already been used to register callbacks.
  95
  96 PERL API
  97   "enable"
  98         enable $key;
  99
 100     Lexically enables the hooks associated with the key $key
 101
 102   "disable"
 103         disable $key;
 104
 105     Lexically disables the hooks associated with the key $key
 106
 107 EXAMPLES
 108     See the t/re-engine-Hooks-TestDist/ directory in the distribution. It
 109     implements a couple of simple examples.
 110
 111 DEPENDENCIES
 112     perl 5.10.1.
 113
 114     ExtUtils::Depends.
 115
 116 SEE ALSO
 117     perlreguts.
 118
 119 AUTHOR
 120     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 121
 122     You can contact me by mail or on "irc.perl.org" (vincent).
 123
 124 BUGS
 125     Please report any bugs or feature requests to "bug-re-engine-hooks at
 126     rt.cpan.org", or through the web interface at
 127     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=re-engine-Hooks>. I will
 128     be notified, and then you'll automatically be notified of progress on
 129     your bug as I make changes.
 130
 131 SUPPORT
 132     You can find documentation for this module with the perldoc command :
 133
 134         perldoc re::engine::Hooks
 135
 136 COPYRIGHT & LICENSE
 137     Copyright 2012 Vincent Pit, all rights reserved.
 138
 139     This program is free software; you can redistribute it and/or modify it
 140     under the same terms as Perl itself.
 141