Provided by: libdevel-pragma-perl_0.60-1_amd64 bug

NAME

       Devel::Pragma - helper functions for developers of lexical pragmas

SYNOPSIS

           package MyPragma;

           use Devel::Pragma qw(:all);

           sub import {
               my ($class, %options) = @_;
               my $hints  = hints;        # lexically-scoped %^H
               my $caller = ccstash();    # currently-compiling stash

               unless ($hints->{MyPragma}) { # top-level
                   $hints->{MyPragma} = 1;

                   # disable/enable this pragma before/after compile-time requires
                   on_require \&teardown, \&setup;
               }

               if (new_scope($class)) {
                   ...
               }

               my $scope_id = scope();
           }

DESCRIPTION

       This module provides helper functions for developers of lexical pragmas. These can be used
       both in older versions of perl (from 5.8.1), which have limited support for lexical
       pragmas, and in the most recent versions, which have improved support.

EXPORTS

       "Devel::Pragma" exports the following functions on demand. They can all be imported at
       once by using the ":all" tag. e.g.

           use Devel::Pragma qw(:all);

   hints
       This function enables the scoped behaviour of the hints hash ("%^H") and then returns a
       reference to it.

       The hints hash is a compile-time global variable (which is also available at runtime in
       recent perls) that can be used to implement lexically-scoped features and pragmas. This
       function provides a convenient way to access this hash without the need to perform the
       bit-twiddling that enables it on older perls.  In addition, this module loads
       Lexical::SealRequireHints, which implements bugfixes that are required for the correct
       operation of the hints hash on older perls (< 5.12.0).

       Typically, "hints" should be called from a pragma's "import" (and optionally "unimport")
       method:

           package MyPragma;

           use Devel::Pragma qw(hints);

           sub import {
               my $class = shift;
               my $hints = hints;

               if ($hints->{MyPragma}) {
                   # ...
               } else {
                   $hints->{MyPragma} = ...;
               }

               # ...
           }

   new_scope
       This function returns true if the currently-compiling scope differs from the scope being
       compiled the last time "new_scope" was called. Subsequent calls will return false while
       the same scope is being compiled.

       "new_scope" takes an optional parameter that is used to uniquely identify its caller. This
       should usually be supplied as the pragma's class name unless "new_scope" is called by a
       module that is not intended to be subclassed. e.g.

           package MyPragma;

           sub import {
               my ($class, %options) = @_;

               if (new_scope($class)) {
                   ...
               }
           }

       If not supplied, the identifier defaults to the name of the calling package.

   scope
       This returns an integer that uniquely identifies the currently-compiling scope. It can be
       used to distinguish or compare scopes.

       A warning is issued if "scope" (or "new_scope") is called in a context in which it doesn't
       make sense i.e. if the scoped behaviour of "%^H" has not been enabled - either by
       explicitly modifying $^H, or by calling "hints" or "on_require".

   ccstash
       This returns the name of the currently-compiling stash. It can be used as a replacement
       for the scalar form of "caller" to provide the name of the package in which "use MyPragma"
       is called. Unlike "caller", it returns the same value regardless of the number of
       intervening calls before "MyPragma::import" is reached.

       e.g. given a pragma:

           package MySuperPragma;

           use Devel::Hints qw(ccstash);

           sub import {
               my ($class, %options) = @_;
               my $caller = ccstash();

               no strict 'refs';

               *{"$caller\::whatever"} = ... ;
           }

       and a subclass:

           package MySubPragma

           use base qw(MySuperPragma);

           sub import {
               my ($class, %options) = @_;
               $class->SUPER::import(...);
           }

       and a script that uses the subclass:

           #!/usr/bin/env perl

           use MySubPragma;

       - the "ccstash" call in "MySuperPragma::import" returns the name of the package that's
       being compiled when the call to "MySuperPragma::import" (via "MySubPragma::import") takes
       place i.e. "main" in this case.

   fqname
       Given a subroutine name, usually supplied by the caller of the pragma's import method,
       this function returns the name in package-qualified form. In addition, old-style "'"
       separators are converted to new-style "::".

       If the name contains no separators, then the optional calling package is prepended. If not
       supplied, the caller defaults to the value returned by "ccstash". If the name is already
       package-qualified, then it is returned unchanged.

       In list context, "fqname" returns the package and unqualified subroutine name (e.g. 'main'
       and 'foo'), and in scalar context it returns the package and sub name joined by '::' (e.g.
       'main::foo').

       e.g.

           package MyPragma;

           sub import {
               my ($class, @names) = @_;

               for my $name (@names) {
                   my $fqname = fqname($name);
                   say $fqname;
               }
           }

           package MySubPragma;

           use base qw(MyPragma);

           sub import { shift->SUPER::import(@_) }

           #!/usr/bin/env perl

           use MyPragma qw(foo Foo::Bar::baz Foo'Bar'baz Foo'Bar::baz);

           {
               package Some::Other::Package;

               use MySubPragma qw(quux);
           }

       prints:

           main::foo
           Foo::Bar::baz
           Foo::Bar::baz
           Foo::Bar::baz
           Some::Other::Package::quux

   on_require
       This function allows pragmas to register pre- and post-"require" (and "do FILE")
       callbacks.  These are called whenever "require" or "do FILE" OPs are executed at compile-
       time, typically via "use" statements.

       "on_require" takes two callbacks (i.e. anonymous subs or sub references), each of which is
       called with a reference to a copy of "%^H". The first callback is called before "require",
       and the second is called after "require" has loaded and compiled its file. If the file has
       already been loaded, or the required value is a vstring rather than a file name, then both
       the callbacks are skipped.

       Multiple callbacks can be registered in a given scope, and they are called in the order in
       which they are registered. Callbacks are unregistered automatically at the end of the
       (compilation of) the scope in which they are registered.

       "on_require" callbacks can be used to rollback/restore lexical side-effects i.e. lexical
       features whose side-effects extend beyond "%^H" (like "hints", "on_require" implicitly
       enables the scoped behaviour of "%^H").

       Fatal exceptions raised in "on_require" callbacks are trapped and reported as warnings. If
       a fatal exception is raised in the "require" or "do FILE" call, the post-"require"
       callbacks are invoked before that exception is thrown.

VERSION

       0.60

SEE ALSO

       •   pragma

       •   perlpragma

       •   perlvar

       •   B::Hooks::EndOfScope

       •   B::Hooks::OP::Check

       •   B::Hooks::OP::PPAddr

       •   B::Hooks::OP::Annotation

       •   Devel::Hints

       •   Lexical::SealRequireHints

       •   http://tinyurl.com/45pwzo

AUTHOR

       chocolateboy <chocolate@cpan.org>

COPYRIGHT AND LICENSE

       Copyright (C) 2008-2013 by chocolateboy

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself, either Perl version 5.8.1 or, at your option, any later version of
       Perl 5 you may have available.