]> git.vpit.fr Git - perl/modules/re-engine-Hooks.git/blob - README
This is 0.01
[perl/modules/re-engine-Hooks.git] / 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