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