/ 
Aspect-0.16
River stage two • 10 direct dependents • 13 total dependents
/ Aspect::AdviceContext

NAME

Aspect::AdviceContext - a pointcut context for advice code

SYNOPSIS

$pointcut = call qr/^Person::[gs]et_/ & cflow company => qr/^Company::/;

# using in 'before' advice code
before {
   my $context = shift;             # context is only param to advice code
   print $context->type;            # 'before': advice type: before/after
   print $context->pointcut;        # $pointcut: the pointcut for this advice
   print $context->sub_name;        # package + sub name of matched sub
   print $context->package_name;    # 'Person': package name of matched sub
   print $context->short_sub_name;  # sub name of matched sub
   print $context->self;            # 1st parameter to matched sub
   print $context->params->[1];     # 2nd parameter to matched sub
   $context->append_param($rdbms);  # append param to matched sub
   $context->append_params($a, $b); # append params to matched sub
   $context->return_value(4)        # don't proceed to matched sub, return 4
   $context->original->(x => 3);    # call matched sub, don't proceed
   $context->proceed(1);            # do proceed to matched sub after all
   print $context->company->name;   # access cflow pointcut advice context
} $pointcut;

DESCRIPTION

Advice code is called when the advice pointcut is matched. In this code, there is always a need to access information about the context of the advice. Information like: what is the actual sub name matched? What are the parameters in this call that we matched? Sometimes you want to change the context for the matched sub: append a parameter, or even stop the matched sub from being called.

You do all these things through the AdviceContext. It is the only parameter provided to the advice code. It provides all the information required about the match context, and allows you to change the behavior of the matched sub.

Note that modifying parameters through the context, in the code of an after advice, will have no effect, since the matched sub has already been called.

CFLOW CONTEXT

If the pointcut of an advice is composed of at least one Aspect::Pointcut::Cflow, advice code may require not only the context of the advice, but also the context of the cflows. This is required if you want to find out, for example, what is the name of the sub that matched a cflow. E.g. for the synopsis example above, what method of Company started the chain of calls that eventually reached the get/set on Person?

You can access cflow context in the synopsis above, by calling:

$context->company;

You get it from the main advice context, by calling a method named after the context key used in the cflow spec. In the synopsis pointcut definition, the cflow part was:

cflow company => qr/^Company::/
      ^^^^^^^

An AdviceContext will be created for the cflow, and you can access it using the key company.

EXAMPLES

Print parameters to matched sub:

before { my $c = shift; print join(',', $c->params) } $pointcut;

Append a parameter:

before { shift->append_param('extra-param') } $pointcut;

Don't proceed to matched sub, return 4 instead:

before { shift->return_value(4) } $pointcut;

Call matched sub again, and again, until it returns something defined:

after {
   my $context = shift;
   my $return  = $context->return_value;
   while (!defined $return)
      { $return = $context->original($context->params) }
   $context->return_value($return);
} $pointcut;

Print the name of the Company object that started the chain of calls that eventually reached the get/set on Person:

before { print shift->company->name } $pointcut;

SEE ALSO

See the Aspect pod for a guide to the Aspect module.

You can find examples of using the AdviceContext in any advice code. The aspect library for example (e.g. Aspect::Library::Wormhole).

Aspect::Advice creates the main AdviceContext, and Aspect::Pointcut::Cflow creates contexts for each matched call flow.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests through the web interface at http://rt.cpan.org.

INSTALLATION

See perlmodinstall for information and options on installing Perl modules.

AVAILABILITY

The latest version of this module is available from the Comprehensive Perl Archive Network (CPAN). Visit <http://www.perl.com/CPAN/> to find a CPAN site near you. Or see <http://www.perl.com/CPAN/authors/id/M/MA/MARCEL/>.

AUTHORS

Marcel Grünauer, <marcel@cpan.org>

Ran Eilam <eilara@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2001 by Marcel Grünauer

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.