NAME
    re::engine::Hooks - Hookable variant of the Perl core regular expression
    engine.

VERSION
    Version 0.01

SYNOPSIS
    In your XS file :

        #include "re_engine_hooks.h"

        STATIC void dri_comp_hook(pTHX_ regexp *rx, regnode *node) {
         ...
        }

        STATIC void dri_exec_hook(pTHX_ regexp *rx, regnode *node,
                                  regmatch_info *info, regmatch_state *state) {
         ...
        }

        MODULE = Devel::Regexp::Instrument    PACKAGE = Devel::Regexp::Instrument

        BOOT:
        {
         reh_register("Devel::Regexp::Instrument", dri_comp_hook, dri_exec_hook);
        }

    In your Perl module file :

        package Devel::Regexp::Instrument;

        use strict;
        use warnings;

        our ($VERSION, @ISA);

        use re::engine::Hooks; # Before loading our own shared library

        BEGIN {
         $VERSION = '0.01';
         require DynaLoader;
         push @ISA, 'DynaLoader';
         __PACKAGE__->bootstrap($VERSION);
        }

        sub import   { re::engine::Hooks::enable(__PACKAGE__) }

        sub unimport { re::engine::Hooks::disable(__PACKAGE__) }

        1;

    In your Makefile.PL

        use ExtUtils::Depends;

        my $ed = ExtUtils::Depends->new(
         'Devel::Regexp::Instrument' => 're::engine::Hooks',
        );

        WriteMakefile(
         $ed->get_makefile_vars,
         ...
        );

DESCRIPTION
    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.

C API
    The C API is made available through the re_engine_hooks.h header file.

  "reh_comp_hook"
    The typedef for the regexp compilation phase hook. Currently evaluates
    to :

        typedef void (*reh_comp_hook)(pTHX_ regexp *, regnode *);

  "reh_exec_hook"
    The typedef for the regexp execution phase hook. Currently evaluates to
    :

        typedef void (*reh_exec_hook)(pTHX_ regexp *, regnode *, regmatch_info *, regmatch_state *);

  "reh_register"
        void reh_register(pTHX_ const char *key, reh_comp_hook comp, reh_exec_hook exec);

    Registers under the given name "key" a callback "comp" that will run
    during the compilation phase and a callback "exec" that will run during
    the execution phase. Null function pointers are allowed in case you
    don't want to hook one of the phases. "key" should match with the
    argument passed to "enable" and "disable" in Perl land. An exception
    will be thrown if "key" has already been used to register callbacks.

PERL API
  "enable"
        enable $key;

    Lexically enables the hooks associated with the key $key

  "disable"
        disable $key;

    Lexically disables the hooks associated with the key $key

EXAMPLES
    See the t/re-engine-Hooks-TestDist/ directory in the distribution. It
    implements a couple of simple examples.

DEPENDENCIES
    perl 5.10.1.

    ExtUtils::Depends.

SEE ALSO
    perlreguts.

AUTHOR
    Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.

    You can contact me by mail or on "irc.perl.org" (vincent).

BUGS
    Please report any bugs or feature requests to "bug-re-engine-hooks at
    rt.cpan.org", or through the web interface at
    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=re-engine-Hooks>. I will
    be notified, and then you'll automatically be notified of progress on
    your bug as I make changes.

SUPPORT
    You can find documentation for this module with the perldoc command :

        perldoc re::engine::Hooks

COPYRIGHT & LICENSE
    Copyright 2012 Vincent Pit, all rights reserved.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.