1Devel::Pragma(3) User Contributed Perl Documentation Devel::Pragma(3)
2
6 Devel::Pragma - helper functions for developers of lexical pragmas
7
9 package MyPragma;
10 use Devel::Pragma qw(:all);
12 sub import {
14 my ($class, %options) = @_;
15 my $hints = hints; # the builtin (%^H) used to implement lexical pragmas
16 my $caller = ccstash(); # the name of the currently-compiling package (stash)
17 unless ($hints->{MyPragma}) { # top-level
19 $hints->{MyPragma} = 1;
20 }
21 if (new_scope($class)) {
23 ...
24 }
25 my $scope_id = scope();
27 }
28
30 This module provides helper functions for developers of lexical pragmas
31 (and a few functions that may be useful to non-pragma developers as
32 well).
33 Pragmas can be used both in older versions of perl (from 5.8.1), which
35 had limited support, and in the most recent versions, which have
36 improved support.
37
39 "Devel::Pragma" exports the following functions on demand. They can all
40 be imported at once by using the ":all" tag. e.g.
41 use Devel::Pragma qw(:all);
43 hints
45 This function enables the scoped behaviour of the hints hash ("%^H")
46 and then returns a reference to it.
47 The hints hash is a compile-time global variable (which is also
49 available at runtime in recent perls) that can be used to implement
50 lexically-scoped features and pragmas. This function provides a
51 convenient way to access this hash without the need to perform the bit-
52 twiddling that enables it on older perls. In addition, this module
53 loads Lexical::SealRequireHints, which implements bugfixes that are
54 required for the correct operation of the hints hash on older perls (<
55 5.12.0).
56 Typically, "hints" should be called from a pragma's "import" (and
58 optionally "unimport") method:
59 package MyPragma;
61 use Devel::Pragma qw(hints);
63 sub import {
65 my $class = shift;
66 my $hints = hints;
67 if ($hints->{MyPragma}) {
69 # ...
70 } else {
71 $hints->{MyPragma} = ...;
72 }
73 # ...
75 }
76 new_scope
78 This function returns true if the currently-compiling scope differs
79 from the scope being compiled the last time "new_scope" was called.
80 Subsequent calls will return false while the same scope is being
81 compiled.
82 "new_scope" takes an optional parameter that is used to uniquely
84 identify its caller. This should usually be supplied as the pragma's
85 class name unless "new_scope" is called by a module that is not
86 intended to be subclassed. e.g.
87 package MyPragma;
89 sub import {
91 my ($class, %options) = @_;
92 if (new_scope($class)) {
94 ...
95 }
96 }
97 If not supplied, the identifier defaults to the name of the calling
99 package.
100 scope
102 This returns an integer that uniquely identifies the currently-
103 compiling scope. It can be used to distinguish or compare scopes.
104 A warning is issued if "scope" (or "new_scope") is called in a context
106 in which it doesn't make sense i.e. if the scoped behaviour of "%^H"
107 has not been enabled - either by explicitly modifying $^H, or by
108 calling "hints".
109 ccstash
111 Returns the name of the currently-compiling package (stash). It only
112 works inside code that's being "required", either in a BEGIN block via
113 "use" or at runtime. In practice, its use should be restricted to
114 compile-time i.e. "import" methods and any other methods/functions
115 that can be traced back to "import".
116 When called from code that isn't being "require"d, it returns undef.
118 It can be used as a replacement for the scalar form of "caller" to
120 provide the name of the package in which "use MyPragma" is called.
121 Unlike "caller", it returns the same value regardless of the number of
122 intervening calls before "MyPragma::import" is reached.
123 package Caller;
125 use Callee;
127 package Callee;
129 use Devel::Pragma qw(ccstash);
131 sub import {
133 A();
134 }
135 sub A() {
137 B();
138 }
139 sub B {
141 C();
142 }
143 sub C {
145 say ccstash; # Caller
146 }
147 fqname
149 Takes a subroutine name and an optional caller (package name). If no
150 caller is supplied, it defaults to "ccstash", which requires "fqname"
151 to be called from "import" (or a function/method that can be traced
152 back to "import").
153 It returns the supplied name in package-qualified form. In addition,
155 old-style "'" separators are converted to new-style "::".
156 If the name contains no separators, then the "caller"/"ccstash" package
158 name is prepended. If the name is already package-qualified, it is
159 returned unchanged.
160 In list context, "fqname" returns the package and unqualified
162 subroutine name (e.g. 'Foo::Bar' and 'baz'), and in scalar context it
163 returns the package and sub name joined by '::' (e.g. 'Foo::Bar::baz').
164 e.g.
166 package MyPragma::Loader;
168 use MyPragma (\&coderef, 'foo', 'MyPragmaLoader::bar');
170 package MyPragma;
172 sub import {
174 my ($class, @listeners) = @_;
175 my @subs;
176 for my $listener (@listeners) {
178 push @subs, handle_sub($listener);
179 }
180 }
181 sub handle_sub {
183 my $sub = shift
184 if (ref($ub) eq 'CODE') {
186 return $sub;
187 } else {
188 handle_name($sub);
189 }
190 }
191 sub handle_name {
193 my ($package, $name) = fqname($name); # uses ccstash e.g. foo -> MyPragma::Loader::foo
194 my $sub = $package->can($name);
195 die "no such sub: $package\::$name" unless ($sub);
196 return $sub;
197 }
198
200 1.1.0
201
203 · Devel::Hints
204 · Lexical::Hints
206 · Lexical::SealRequireHints
208 · perlpragma
210 · pragma
212 · http://tinyurl.com/45pwzo
214
216 chocolateboy <chocolate@cpan.org>
217
219 Copyright (C) 2008-2016 by chocolateboy
220 This library is free software; you can redistribute it and/or modify it
222 under the same terms as Perl itself, either Perl version 5.8.1 or, at
223 your option, any later version of Perl 5 you may have available.
224perl v5.28.1 2016-07-01 Devel::Pragma(3)