1Devel::Pragma(3)      User Contributed Perl Documentation     Devel::Pragma(3)
2
3
4

NAME

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

SYNOPSIS

9           package MyPragma;
10
11           use Devel::Pragma qw(:all);
12
13           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
18               unless ($hints->{MyPragma}) { # top-level
19                   $hints->{MyPragma} = 1;
20               }
21
22               if (new_scope($class)) {
23                   ...
24               }
25
26               my $scope_id = scope();
27           }
28

DESCRIPTION

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
34       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

EXPORTS

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
42           use Devel::Pragma qw(:all);
43
44   hints
45       This function enables the scoped behaviour of the hints hash ("%^H")
46       and then returns a reference to it.
47
48       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
57       Typically, "hints" should be called from a pragma's "import" (and
58       optionally "unimport") method:
59
60           package MyPragma;
61
62           use Devel::Pragma qw(hints);
63
64           sub import {
65               my $class = shift;
66               my $hints = hints;
67
68               if ($hints->{MyPragma}) {
69                   # ...
70               } else {
71                   $hints->{MyPragma} = ...;
72               }
73
74               # ...
75           }
76
77   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
83       "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
88           package MyPragma;
89
90           sub import {
91               my ($class, %options) = @_;
92
93               if (new_scope($class)) {
94                   ...
95               }
96           }
97
98       If not supplied, the identifier defaults to the name of the calling
99       package.
100
101   scope
102       This returns an integer that uniquely identifies the currently-
103       compiling scope. It can be used to distinguish or compare scopes.
104
105       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
110   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
117       When called from code that isn't being "require"d, it returns undef.
118
119       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
124           package Caller;
125
126           use Callee;
127
128           package Callee;
129
130           use Devel::Pragma qw(ccstash);
131
132           sub import {
133               A();
134           }
135
136           sub A() {
137               B();
138           }
139
140           sub B {
141               C();
142           }
143
144           sub C {
145               say ccstash; # Caller
146           }
147
148   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
154       It returns the supplied name in package-qualified form. In addition,
155       old-style "'" separators are converted to new-style "::".
156
157       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
161       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
165       e.g.
166
167           package MyPragma::Loader;
168
169           use MyPragma (\&coderef, 'foo', 'MyPragmaLoader::bar');
170
171           package MyPragma;
172
173           sub import {
174               my ($class, @listeners) = @_;
175               my @subs;
176
177               for my $listener (@listeners) {
178                   push @subs, handle_sub($listener);
179               }
180           }
181
182           sub handle_sub {
183               my $sub = shift
184
185               if (ref($ub) eq 'CODE') {
186                   return $sub;
187               } else {
188                   handle_name($sub);
189               }
190           }
191
192           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

VERSION

200       1.1.0
201

SEE ALSO

203       •   Devel::Hints
204
205       •   Lexical::Hints
206
207       •   Lexical::SealRequireHints
208
209       •   perlpragma
210
211       •   pragma
212
213http://tinyurl.com/45pwzo
214

AUTHOR

216       chocolateboy <chocolate@cpan.org>
217
219       Copyright (C) 2008-2016 by chocolateboy
220
221       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.
224
225
226
227perl v5.34.0                      2022-01-21                  Devel::Pragma(3)
Impressum