Sub::Mutate - examination and modification of subroutines
use Sub::Mutate 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 ); $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); use Sub::Mutate qw(when_sub_bodied); when_sub_bodied($sub, sub { mutate_sub_foo($_[0], ...) });
This module contains functions that examine and modify many aspects of subroutines in Perl. It is intended to help in the implementation of attribute handlers, and for other such special effects.
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.
mutate_
Returns a keyword indicating the general nature of the implementation of SUB:
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.
The subroutine has no body, and so cannot be successfully called.
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.
Returns a keyword indicating the status of SUB with respect to the generation of closures in the Perl language:
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.
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.
The subroutine is independent of external lexical variables.
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.
:lvalue
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.
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.
:method
Marks or unmarks SUB as a method, depending on the truth value of NEW_METHODNESS.
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.
DB::sub
Changes whether the Perl debugger will intercept calls to SUB, depending on the truth value of NEW_DEBUGGABILITY.
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".)
undef
Sets or deletes the prototype of SUB, to match NEW_PROTOTYPE, which must be either a string or undef.
Queues a modification of SUB, to occur when SUB has acquired a body. This is required due to an oddity of how Perl constructs Perl-language subroutines. A subroutine object is initially created with no body, and then the body is later attached. Prior to Perl 5.15.4, attribute handlers are executed before the body is attached, so see it in that intermediate state. (From Perl 5.15.4 onwards, attribute handlers are executed after the body is attached.) It is otherwise unusual to see the subroutine in that intermediate state. If the implementation of an attribute can only be completed after the body is attached, this function is the way to schedule the implementation.
If this function is called when SUB is in the intermediate state, with body not yet attached, then ACTION is added to a queue. Shortly after a body is attached to SUB, the queued actions are performed. ACTION must be a reference to a function, which is called with one argument, a reference to the subroutine to act on. The subroutine passed to ACTION is not necessarily the same object as the original SUB: some subroutine construction sequences cause the partially-built subroutine to move from one object to another part way through, and the queue of pending actions moves with it.
If this function is called when SUB already has a body, the action will be performed immediately, or nearly so. Actions are always performed sequentially, in the order in which they were queued, so if an action is requested while another action is already executing then the newly-requested action will have to wait until the executing one has finished.
If a subroutine with pending actions is replaced, in the same subroutine object, by a new subroutine, then the queue of pending actions is discarded. This occurs in the case of a so-called "forward declaration", such as "sub foo ($);". The declaration creates a subroutine with no body, to influence compilation of calls to the subroutine, and it is intended that the empty subroutine will later be replaced by a full subroutine which has a body.
sub foo ($);
The code behind when_sub_bodied is an ugly experimental hack, which may turn out to be fragile. Details of its behaviour may change in future versions of this module, if better ways of achieving the desired effect are found.
when_sub_bodied
Before Perl 5.10, when_sub_bodied has a particular problem with redefining subroutines. A subroutine redefinition, including if the previous definition had no body (a pre-declaration), is the situation that causes a partially-built subroutine to move from one subroutine object to another. On pre-5.10 Perls, it is impossible to locate the destination object at the critical point in this process, and as a result any pending actions are lost.
Attribute::Lexical, B::CallChecker
Andrew Main (Zefram) <zefram@fysh.org>
Copyright (C) 2009, 2010, 2011 Andrew Main (Zefram) <zefram@fysh.org>
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Sub::Mutate, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Sub::Mutate
CPAN shell
perl -MCPAN -e shell install Sub::Mutate
For more information on module installation, please visit the detailed CPAN module installation guide.