File Coverage

blib/lib/Sub/Metadata.pm
Criterion Covered Total %
statement 12 12 100.0
branch n/a
condition n/a
subroutine 4 4 100.0
pod n/a
total 16 16 100.0


line stmt bran cond sub pod time code
1             =head1 NAME
2              
3             Sub::Metadata - read and write subroutine metadata
4              
5             =head1 SYNOPSIS
6              
7             use Sub::Metadata qw(
8             sub_body_type
9             sub_closure_role
10             sub_is_lvalue
11             sub_is_constant
12             sub_is_method mutate_sub_is_method
13             sub_is_debuggable mutate_sub_is_debuggable
14             sub_prototype mutate_sub_prototype
15             sub_package mutate_sub_package
16             );
17              
18             $type = sub_body_type($sub);
19             $type = sub_closure_role($sub);
20             if(sub_is_lvalue($sub)) { ...
21             if(sub_is_constant($sub)) { ...
22             if(sub_is_method($sub)) { ...
23             mutate_sub_is_method($sub, 1);
24             if(sub_is_debuggable($sub)) { ...
25             mutate_sub_is_debuggable($sub, 0);
26             $proto = sub_prototype($sub);
27             mutate_sub_prototype($sub, $proto);
28             $pkg = sub_package($sub);
29             mutate_sub_package($sub, $pkg);
30              
31             =head1 DESCRIPTION
32              
33             This module contains functions that examine and modify data that Perl
34             attaches to subroutines.
35              
36             =cut
37              
38             package Sub::Metadata;
39              
40 8     8   110811 { use 5.006; }
  8         23  
  8         244  
41 8     8   30 use warnings;
  8         8  
  8         221  
42 8     8   35 use strict;
  8         23  
  8         344  
43              
44             our $VERSION = "0.001";
45              
46 8     8   3173 use parent "Exporter";
  8         1838  
  8         30  
47             our @EXPORT_OK = qw(
48             sub_body_type
49             sub_closure_role
50             sub_is_lvalue
51             sub_is_constant
52             sub_is_method mutate_sub_is_method
53             sub_is_debuggable mutate_sub_is_debuggable
54             sub_prototype mutate_sub_prototype
55             sub_package mutate_sub_package
56             );
57              
58             require XSLoader;
59             XSLoader::load(__PACKAGE__, $VERSION);
60              
61             =head1 FUNCTIONS
62              
63             Each of these functions takes an argument I, which must be a
64             reference to a subroutine. The function operates on the subroutine
65             referenced by I.
66              
67             The C functions modify a subroutine in place. The subroutine's
68             identity is not changed, but the attributes of the existing subroutine
69             object are changed. All references to the existing subroutine will see
70             the new attributes. Beware of action at a distance.
71              
72             =over
73              
74             =item sub_body_type(SUB)
75              
76             Returns a keyword indicating the general nature of the implementation
77             of I:
78              
79             =over
80              
81             =item B
82              
83             The subroutine's body consists of a network of op nodes for the Perl
84             interpreter. Subroutines written in Perl are almost always of this form.
85              
86             =item B
87              
88             The subroutine has no body, and so cannot be successfully called.
89              
90             =item B
91              
92             The subroutine's body consists of native machine code. Usually these
93             subroutines have been mainly written in C. Constant-valued subroutines
94             written in Perl can also acquire this type of body.
95              
96             =back
97              
98             =item sub_closure_role(SUB)
99              
100             Returns a keyword indicating the status of I with respect to the
101             generation of closures in the Perl language:
102              
103             =over
104              
105             =item B
106              
107             The subroutine is a closure: it was generated from Perl code referencing
108             external lexical variables, and now references a particular set of those
109             variables to make up a complete subroutine.
110              
111             =item B
112              
113             The subroutine is a prototype for closures: it consists of Perl code
114             referencing external lexical variables, and has not been attached to a
115             particular set of those variables. This is not a complete subroutine
116             and cannot be successfully called. It is an oddity of Perl that this
117             type of object is represented as if it were a subroutine, and the
118             situations where one can get access to this kind of object are rare.
119             Prototype subroutines will mainly be encountered by attribute handlers.
120              
121             =item B
122              
123             The subroutine is independent of external lexical variables.
124              
125             =back
126              
127             =item sub_is_lvalue(SUB)
128              
129             Returns a truth value indicating whether I is expected to return an
130             lvalue. An lvalue subroutine is usually created by using the C<:lvalue>
131             attribute, which affects how the subroutine body is compiled and also
132             sets the flag that this function extracts.
133              
134             =item sub_is_constant(SUB)
135              
136             Returns a truth value indicating whether I returns a constant
137             value and can therefore be inlined. It is possible for a subroutine
138             to actually be constant-valued without the compiler detecting it and
139             setting this flag.
140              
141             =item sub_is_method(SUB)
142              
143             Returns a truth value indicating whether I is marked as a method.
144             This marker can be applied by use of the C<:method> attribute, and
145             (as of Perl 5.10) affects almost nothing.
146              
147             =item mutate_sub_is_method(SUB, NEW_METHODNESS)
148              
149             Marks or unmarks I as a method, depending on the truth value of
150             I.
151              
152             =item sub_is_debuggable(SUB)
153              
154             Returns a truth value indicating whether, when the Perl debugger
155             is activated, calls to I can be intercepted by C (see
156             L). Normally this is true for all subroutines, but note
157             that whether a particular call is intercepted also depends on the nature
158             of the calling site.
159              
160             =item mutate_sub_is_debuggable(SUB, NEW_DEBUGGABILITY)
161              
162             Changes whether the Perl debugger will intercept calls to I,
163             depending on the truth value of I.
164              
165             =item sub_prototype(SUB)
166              
167             Returns the prototype of I, which is a string, or C if the
168             subroutine has no prototype. (No prototype is different from the empty
169             string prototype.) Prototypes affect the compilation of calls to the
170             subroutine, where the identity of the called subroutine can be resolved
171             at compile time. (This is unrelated to the closure prototypes described
172             for L.)
173              
174             =item mutate_sub_prototype(SUB, NEW_PROTOTYPE)
175              
176             Sets or deletes the prototype of I, to match I,
177             which must be either a string or C.
178              
179             =item sub_package(SUB)
180              
181             Returns the name of the package within which I is defined, or
182             C if there is none. For a subroutine written in Perl, this
183             is normally the package that is selected in the lexical scope of the
184             subroutine definition. For a subroutine written in C it is normally
185             not set. Where set, this is not necessarily a package containing a name
186             by which the subroutine can be referenced. It is also (for subroutines
187             written in Perl) not necessarily the selected package in any lexical
188             scope within the subroutine. This association of each subroutine with
189             a package affects almost nothing: the main effect is that subroutines
190             in the C package are normally not subject to debugging, even when
191             flagged as debuggable (see L).
192              
193             =item mutate_sub_package(SUB, NEW_PACKAGE)
194              
195             Sets or deletes the package of I, to match I, which
196             must be either a string or C.
197              
198             =back
199              
200             =head1 SEE ALSO
201              
202             L
203              
204             =head1 AUTHOR
205              
206             Andrew Main (Zefram)
207              
208             =head1 COPYRIGHT
209              
210             Copyright (C) 2009, 2010, 2011, 2013, 2015
211             Andrew Main (Zefram)
212              
213             =head1 LICENSE
214              
215             This module is free software; you can redistribute it and/or modify it
216             under the same terms as Perl itself.
217              
218             =cut
219              
220             1;