NAME
Sub::Metadata - read and write subroutine metadata
SYNOPSIS
use Sub::Metadata qw(
sub_body_type
sub_closure_role
sub_is_lvalue
sub_is_constant
sub_is_method mutate_sub_is_method
sub_is_debuggable mutate_sub_is_debuggable
sub_prototype mutate_sub_prototype
sub_package mutate_sub_package);
$type = sub_body_type($sub);
$type = sub_closure_role($sub);
if(sub_is_lvalue($sub)) { ...
if(sub_is_constant($sub)) { ...
if(sub_is_method($sub)) { ...
mutate_sub_is_method($sub, 1);
if(sub_is_debuggable($sub)) { ...
mutate_sub_is_debuggable($sub, 0);
$proto = sub_prototype($sub);
mutate_sub_prototype($sub, $proto);
$pkg = sub_package($sub);
mutate_sub_package($sub, $pkg);
DESCRIPTION
This module contains functions that examine and modify data that Perl attaches to subroutines.
FUNCTIONS
Each of these functions takes an argument SUB, which must be a reference to a subroutine. The function operates on the subroutine referenced by SUB.
The mutate_
functions modify a subroutine in place. The subroutine's identity is not changed, but the attributes of the existing subroutine object are changed. All references to the existing subroutine will see the new attributes. Beware of action at a distance.
- sub_body_type(SUB)
-
Returns a keyword indicating the general nature of the implementation of SUB:
- PERL
-
The subroutine's body consists of a network of op nodes for the Perl interpreter. Subroutines written in Perl are almost always of this form.
- UNDEF
-
The subroutine has no body, and so cannot be successfully called.
- XSUB
-
The subroutine's body consists of native machine code. Usually these subroutines have been mainly written in C. Constant-valued subroutines written in Perl can also acquire this type of body.
- sub_closure_role(SUB)
-
Returns a keyword indicating the status of SUB with respect to the generation of closures in the Perl language:
- CLOSURE
-
The subroutine is a closure: it was generated from Perl code referencing external lexical variables, and now references a particular set of those variables to make up a complete subroutine.
- PROTOTYPE
-
The subroutine is a prototype for closures: it consists of Perl code referencing external lexical variables, and has not been attached to a particular set of those variables. This is not a complete subroutine and cannot be successfully called. It is an oddity of Perl that this type of object is represented as if it were a subroutine, and the situations where one can get access to this kind of object are rare. Prototype subroutines will mainly be encountered by attribute handlers.
- STANDALONE
-
The subroutine is independent of external lexical variables.
- sub_is_lvalue(SUB)
-
Returns a truth value indicating whether SUB is expected to return an lvalue. An lvalue subroutine is usually created by using the
:lvalue
attribute, which affects how the subroutine body is compiled and also sets the flag that this function extracts. - sub_is_constant(SUB)
-
Returns a truth value indicating whether SUB returns a constant value and can therefore be inlined. It is possible for a subroutine to actually be constant-valued without the compiler detecting it and setting this flag.
- sub_is_method(SUB)
-
Returns a truth value indicating whether SUB is marked as a method. This marker can be applied by use of the
:method
attribute, and (as of Perl 5.10) affects almost nothing. - mutate_sub_is_method(SUB, NEW_METHODNESS)
-
Marks or unmarks SUB as a method, depending on the truth value of NEW_METHODNESS.
- sub_is_debuggable(SUB)
-
Returns a truth value indicating whether, when the Perl debugger is activated, calls to SUB can be intercepted by
DB::sub
(see perldebguts). Normally this is true for all subroutines, but note that whether a particular call is intercepted also depends on the nature of the calling site. - mutate_sub_is_debuggable(SUB, NEW_DEBUGGABILITY)
-
Changes whether the Perl debugger will intercept calls to SUB, depending on the truth value of NEW_DEBUGGABILITY.
- sub_prototype(SUB)
-
Returns the prototype of SUB, which is a string, or
undef
if the subroutine has no prototype. (No prototype is different from the empty string prototype.) Prototypes affect the compilation of calls to the subroutine, where the identity of the called subroutine can be resolved at compile time. (This is unrelated to the closure prototypes described for "sub_closure_role".) - mutate_sub_prototype(SUB, NEW_PROTOTYPE)
-
Sets or deletes the prototype of SUB, to match NEW_PROTOTYPE, which must be either a string or
undef
. - sub_package(SUB)
-
Returns the name of the package within which SUB is defined, or
undef
if there is none. For a subroutine written in Perl, this is normally the package that is selected in the lexical scope of the subroutine definition. For a subroutine written in C it is normally not set. Where set, this is not necessarily a package containing a name by which the subroutine can be referenced. It is also (for subroutines written in Perl) not necessarily the selected package in any lexical scope within the subroutine. This association of each subroutine with a package affects almost nothing: the main effect is that subroutines in theDB
package are normally not subject to debugging, even when flagged as debuggable (see "sub_is_debuggable"). - mutate_sub_package(SUB, NEW_PACKAGE)
-
Sets or deletes the package of SUB, to match NEW_PACKAGE, which must be either a string or
undef
.
SEE ALSO
AUTHOR
Andrew Main (Zefram) <zefram@fysh.org>
COPYRIGHT
Copyright (C) 2009, 2010, 2011, 2013, 2015, 2017 Andrew Main (Zefram) <zefram@fysh.org>
LICENSE
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.