/ 
Devel-Pragma-0.22
River stage one • 2 direct dependents • 7 total dependents
/ Devel::Pragma

NAME

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

SYNOPSIS

package MyPragma;

use Devel::Pragma qw(my_hints ccstash new_scope);

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

    $hints->{MyPragma} = 1;

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

DESCRIPTION

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

In addition to the helper functions, this module applies a global fix that makes %^H lexically-scoped rather than dynamically-scoped. Until perl change #33311, which isn't currently available in any stable perl release, values set in %^H are visible in modules loaded by use, require and do FILE. This makes pragmas leak from the scope in which they're meant to be enabled into scopes in which they're not. This module applies a fix which ensures that values in %^H no longer leak across file boundaries.

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);

my_hints

my_hints sets the appropriate flag to make %^H lexically-scoped, and returns a reference to %^H. More precisely, it sets the flag in $^H that makes %^H copy and restore its values as scopes are entered and exited. The fix that clears %^H before use, require and do FILE statements is applied globally when the Devel::Pragma module is first loaded.

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.

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.

VERSION

0.22

SEE ALSO

AUTHOR

chocolateboy <chocolate.boy@email.com>

COPYRIGHT AND LICENSE

Copyright (C) 2008-2009 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.8 or, at your option, any later version of Perl 5 you may have available.