type
The "type" method is a convenience provided in the situation something has a Aspect::Point method and
wants to know the advice declarator it is made for.
Returns "before" in Aspect::Advice::Before advice, "after" in Aspect::Advice::After advice, or "around"
in Aspect::Advice::Around advice.
pointcut
my $pointcut = $_->pointcut;
The "pointcut" method provides access to the original join point specification (as a tree of
Aspect::Pointcut objects) that the current join point matched against.
Please note that the pointcut returned is the full and complete pointcut tree, due to the heavy
optimisation used on the actual pointcut code when it is run there is no way at the time of advice
execution to indicate which specific conditions in the pointcut tree matched and which did not.
Returns an object which is a sub-class of Aspect::Pointcut.
original
$_->original->( 1, 2, 3 );
In a pointcut, the "original" method returns a "CODE" reference to the original function before it was
hooked by the Aspect weaving process.
Calls made to the function are unprotected, parameters and calling context will not be replicated into
the function, return params and exception will not be caught.
sub_name
# Prints "Full::Function::name"
before {
print $_->sub_name . "\n";
} call 'Full::Function::name';
The "sub_name" method returns a string with the full resolved function name at the join point the advice
code is running at.
package_name
# Prints "Just::Package"
before {
print $_->package_name . "\n";
} call 'Just::Package::name';
The "package_name" parameter is a convenience wrapper around the "sub_name" method. Where "sub_name" will
return the fully resolved function name, the "package_name" method will return just the namespace of the
package of the join point.
short_name
# Prints "name"
before {
print $_->short_name . "\n";
} call 'Just::Package::name';
The "short_name" parameter is a convenience wrapper around the "sub_name" method. Where "sub_name" will
return the fully resolved function name, the "short_name" method will return just the name of the
function.
args
# Add a parameter to the function call
$_->args( $_->args, 'more' );
The "args" method allows you to get or set the list of parameters to a function. It is the method
equivalent of manipulating the @_ array.
It uses a slightly unusual calling convention based on list context, but does so in a way that allows
your advice code to read very naturally.
To summarise the situation, the three uses of the "args" method are listed below, along with their @_
equivalents.
# Get the parameters as a list
my @list = $_->args; # my $list = @_;
# Get the number of parameters
my $count = $_->args; # my $count = @_;
# Set the parameters
$_->args( 1, 2, 3 ); # @_ = ( 1, 2, 3 );
As you can see from the above example, when "args" is called in list context it returns the list of
parameters. When it is called in scalar context, it returns the number of parameters. And when it is
called in void context, it sets the parameters to the passed values.
Although this is somewhat unconventional, it does allow the most common existing uses of the older
"params" method to be changed directly to the new "args" method (such as the first example above).
And unlike the original, you can legally call "args" in such a way as to set the function parameters to
be an empty list (which you could not do with the older "params" method).
# Set the function parameters to a null list
$_->args();
self
after {
$_->self->save;
} My::Foo::set;
The "self" method is a convenience provided for when you are writing advice that will be working with
object-oriented Perl code. It returns the first parameter to the method (which should be object), which
you can then call methods on.
The result is advice code that is much more natural to read, as you can see in the above example where we
implement an auto-save feature on the class "My::Foo", writing the contents to disk every time a value is
set without error.
At present the "self" method is implemented fairly naively, if used outside of object-oriented code it
will still return something (including "undef" in the case where there were no parameters to the join
point function).
wantarray
# Return differently depending on the calling context
if ( $_->wantarray ) {
$_->return_value(5);
} else {
$_->return_value(1, 2, 3, 4, 5);
}
The "wantarray" method returns the "wantarray" in perlfunc context of the call to the function for the
current join point.
As with the core Perl "wantarray" function, returns true if the function is being called in list context,
false if the function is being called in scalar context, or "undef" if the function is being called in
void context.
BackcompatibilityNote:
Prior to Aspect 0.98 the wantarray context of the call to the join point was available not only via the
"wantarray" method, but the advice code itself was called in matching wantarray context to the function
call, allowing you to use plain "wantarray" in the advice code as well.
As all the other information about the join point was available through methods, having this one piece of
metadata available different was becoming an oddity.
The "wantarray" context of the join point is now only available by the "wantarray" method.
exception
unless ( $_->exception ) {
$_->exception('Kaboom');
}
The "exception" method is used to get the current die message or exception object, or to set the die
message or exception object.
return_value
# Add an extra value to the returned list
$_->return_value( $_->return_value, 'thing' );
The "return_value" method is used to get or set the return value for the join point function, in a
similar way to the normal Perl "return" keyword.
As with the "args" method, the "return_value" method is sensitive to the context in which it is called.
When called in list context, the "return_value" method returns the join point return value as a list. If
the join point is called in scalar context, this will be a single-element list containing the scalar
return value. If the join point is called in void context, this will be a null list.
When called in scalar context, the "return_value" method returns the join point return value as a scalar.
If the join point is called in list context, this will be the number of vales in the return list. If the
join point is called in void context, this will be "undef"
When called in void context, the "return_value" method sets the return value for the join point using
semantics identical to the "return" keyword.
Because of this change in behavior based on the context in which "return_value" is called, you should
generally always set "return_value" in it's own statement to prevent accidentally calling it in non-void
context.
# Return null (equivalent to "return;")
$_->return_value;
In advice types that can be triggered by an exception, or need to determine whether to continue to the
join point function, setting a return value via "return_value" is seen as implicitly indicating that any
exception should be suppressed, or that we do not want to continue to the join point function.
When you call the "return_value" method this does NOT trigger an immediate "return" equivalent in the
advice code, the lines after "return_value" will continue to be executed as normal (to provide an
opportunity for cleanup operations to be done and so on).
If you use "return_value" inside an if/else structure you will still need to do an explicit "return" if
you wish to break out of the advice code.
Thus, if you wish to break out of the advice code as well as return with an alternative value, you should
do the following.
return $_->return_value('value');
This usage of "return_value" appears to be contrary to the above instruction that setting the return
value should always be done on a standalone line to guarentee void context.
However, in Perl the context of the current function is inherited by a function called with return in the
manner shown above. Thus the usage of "return_value" in this way alone is guarenteed to also set the
return value rather than fetch it.
Install Now
PNG Icons
