paultcochrane / hook-afterruntime Goto Github PK

NAME
    Hook::AfterRuntime - Run code at the end of the compiling scope's
    runtime.

DESCRIPTION
    Useful for creating modules that need a behavior to be added when a
    module that uses them completes its runtime. Like B::Hooks::EndOfScope
    except it triggers for run-time instead of compile-time.

    Example where it might be handy:

        #!/usr/bin/perl
        use strict;
        use warnings;
        use Moose;

        ...

        # It would be nice not to need this....
        __PACKAGE__->make_immutable;

SYNOPSYS
    MooseX/AutoImmute.pm

        package MooseX::AutoImmute;
        use strict;
        use warnings;
        use Hook::AfterRuntime;

        sub import {
            my $class = shift;
            my $caller = caller;
            eval "package $caller; use Moose; 1" || die $@;
            after_runtime { $caller->make_immutable }
        }

        1;

    t/mytest.t

        #!/usr/bin/perl
        use strict;
        use warnings;
        use MooseX::AutoImmute;

        ....

        #EOF
        # Package is now immutable autamatically

CAVEATS
    It is important to understand how Hook::AfterRuntime works n order to
    know its limitations. When you use a module that calls after_runtime()
    in its import() method, after_runtime() will inject code directly after
    your import statement:

        import MooseX::AutoImmute;

    becomes:

        import MooseX::AutoImmute; my $__ENDRUNXXXXXXXX = Hook::AfterRuntime->new($id);

    This creates a Hook::AfterRuntime object in the corrunt scope. This
    object's id is used to reference the code provided to after_runtime() in
    MooseX::AutoImmute()'s import() method. When the object falls out of
    scope the DESTROY() method kicks in and calls the referenced code. This
    occurs at the end of the file when 'use' is called at the package level.

  EDGE CASES
    Loading in a scope other than package level:
        If you use the 'use' directive on a level other than the package
        level, the behavior will trigger when the end of the scope is
        reached. If that is a subroutine than it will trigger at the end of
        EVERY call to that subroutine. You really should not import a class
        using Hook::AfterRuntime outside tha package level scope.

            package XXX;

            sub thing {
                # Happens at compile time
                use Object::Using::AfterRuntime;

                # At run time the hook behavior triggers here!
            }

            # hook behavior has not triggered

            thing()

            # Hook behavior has triggered

            1;

    require, and use class ();
            When require and use class () are used the import method is not called,
            thus the hook is never installed.

    class->import
            The hook effects the code that is currently compiling. calling
            class->import happens after the compilation phase. You must wrap the
            statement in a BEGIN {} to call import manually. Failure to do this will
            result in the hook triggering in the wrong class, or not at all.

USER WARNING
    When you write a class that depends on this hook you should insert the
    following warning into the docs:

    This class uses Hook::AfterRuntime, it MUST be imported at the package
    level at compile time. This means 'use MODULE' or 'BEGIN { require
    MODULE; MODULE->import() }'. Failure to use one of these correct forms
    will result in a missing hook and unpredictable behavior.

SEE ALSO
    B::Hooks::EndOfScope
        Does almost the same thing, except it is triggered after
        compile-time instead of run-time.

FENNEC PROJECT
    This module is part of the Fennec project. See Fennec for more details.
    Fennec is a project to develop an extendable and powerful testing
    framework. Together the tools that make up the Fennec framework provide
    a potent testing environment.

    The tools provided by Fennec are also useful on their own. Sometimes a
    tool created for Fennec is useful outside the greator framework. Such
    tools are turned into their own projects. This is one such project.

    Fennec - The core framework
      The primary Fennec project that ties them all together.

AUTHORS
    Chad Granum [email protected]

COPYRIGHT
    Copyright (C) 2010 Chad Granum

    Hook-AfterRuntime is free software; Standard perl licence.

    Hook-AfterRuntime is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the license for
    more details.