File Coverage

blib/lib/Sub/Metadata.pm

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