1 package re::engine::Hooks;
10 re::engine::Hooks - Hookable variant of the Perl core regular expression engine.
20 sub dl_load_flags { 0x01 }
25 push @ISA, qw<Regexp DynaLoader>;
26 __PACKAGE__->bootstrap($VERSION);
33 #include "re_engine_hooks.h"
35 STATIC void dri_comp_hook(pTHX_ regexp *rx, regnode *node) {
39 STATIC void dri_exec_hook(pTHX_ regexp *rx, regnode *node,
40 regmatch_info *info, regmatch_state *state) {
44 MODULE = Devel::Regexp::Instrument PACKAGE = Devel::Regexp::Instrument
48 reh_register("Devel::Regexp::Instrument", dri_comp_hook, dri_exec_hook);
51 In your Perl module file :
53 package Devel::Regexp::Instrument;
60 use re::engine::Hooks; # Before loading our own shared library
65 push @ISA, 'DynaLoader';
66 __PACKAGE__->bootstrap($VERSION);
69 sub import { re::engine::Hooks::enable(__PACKAGE__) }
71 sub unimport { re::engine::Hooks::disable(__PACKAGE__) }
75 In your F<Makefile.PL>
77 use ExtUtils::Depends;
79 my $ed = ExtUtils::Depends->new(
80 'Devel::Regexp::Instrument' => 're::engine::Hooks',
84 $ed->get_makefile_vars,
90 This module provides a version of the perl regexp engine that can call user-defined XS callbacks at the compilation and at the execution of each regexp node.
94 The C API is made available through the F<re_engine_hooks.h> header file.
96 =head2 C<reh_comp_hook>
98 The typedef for the regexp compilation phase hook.
99 Currently evaluates to :
101 typedef void (*reh_comp_hook)(pTHX_ regexp *, regnode *);
103 =head2 C<reh_exec_hook>
105 The typedef for the regexp execution phase hook.
106 Currently evaluates to :
108 typedef void (*reh_exec_hook)(pTHX_ regexp *, regnode *, regmatch_info *, regmatch_state *);
110 =head2 C<reh_register>
112 void reh_register(pTHX_ const char *key, reh_comp_hook comp, reh_exec_hook exec);
114 Registers under the given name C<key> a callback C<comp> that will run during the compilation phase and a callback C<exec> that will run during the execution phase.
115 Null function pointers are allowed in case you don't want to hook one of the phases.
116 C<key> should match with the argument passed to L</enable> and L</disable> in Perl land.
117 An exception will be thrown if C<key> has already been used to register callbacks.
121 my $RE_ENGINE = _ENGINE();
134 Lexically enables the hooks associated with the key C<$key>
140 Lexically disables the hooks associated with the key C<$key>
147 s/^\s+//, s/\s+$// for $key;
148 $croak->('Invalid key') if $key =~ /\s/ or not _registered($key);
149 $croak->('Another regexp engine is in use') if $^H{regcomp}
150 and $^H{regcomp} != $RE_ENGINE;
154 my $hint = $^H{+(__PACKAGE__)} // '';
155 $hint = "$key $hint";
156 $^H{+(__PACKAGE__)} = $hint;
158 $^H{regcomp} = $RE_ENGINE;
166 s/^\s+//, s/\s+$// for $key;
167 $croak->('Invalid key') if $key =~ /\s/ or not _registered($key);
171 my @other_keys = grep !/^\Q$key\E$/, split /\s+/, $^H{+(__PACKAGE__)} // '';
172 $^H{+(__PACKAGE__)} = join ' ', @other_keys, '';
174 delete $^H{regcomp} if $^H{regcomp} and $^{regcomp} == $RE_ENGINE
182 See the F<t/re-engine-Hooks-TestDist/> directory in the distribution.
183 It implements a couple of simple examples.
189 L<ExtUtils::Depends>.
197 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
199 You can contact me by mail or on C<irc.perl.org> (vincent).
203 Please report any bugs or feature requests to C<bug-re-engine-hooks at rt.cpan.org>, or through the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=re-engine-Hooks>.
204 I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
208 You can find documentation for this module with the perldoc command :
210 perldoc re::engine::Hooks
212 =head1 COPYRIGHT & LICENSE
214 Copyright 2012 Vincent Pit, all rights reserved.
216 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.