view release on metacpan or  search on metacpan

lib/Aspect.pm  view on Meta::CPAN

          Aspect::Pointcut::Call->new('Function::one'),
          Aspect::Pointcut::Call->new('Function::two'),
      ),
      sub {
          print "Calling " . $_->sub_name . "\n";
      },
  );

You will be mostly working with this package (B<Aspect>) and the
L<Aspect::Point> package, which provides the methods for getting information
about the call to the join point within advice code.

When you C<use Aspect;> you will import a family of around fifteen
functions. These are all factories that allow you to create pointcuts,
advice, and aspects.

=head2 Back Compatibility

The various APIs in B<Aspect> have changed a few times between older versions
and the current implementation.

By default, none of these changes are available in the current version of the
B<Aspect> module. They can, however, be accessed by providing one of two flags
when loading B<Aspect>.

  # Support for pre-1.00 Aspect usage
  use Aspect ':deprecated';

The C<:deprecated> flag loads in all alternative and deprecated function and
method names, and exports the deprecated C<after_returning>, C<after_throwing>
advice constructors, and the deprecated C<if_true> alias for the C<true>
pointcut.

  # Support for pre-2010 Aspect usage (both usages are equivalent)
  use Aspect ':legacy';
  use Aspect::Legacy;

The C<:legacy> flag loads in all alternative and deprecated functions as per
the C<:deprecated> flag.

Instead of exporting all available functions and pointcut declarators it exports
C<only> the set of functions that were available in B<Aspect> 0.12.

Finally, it changes the behaviour of the exported version of C<after> to add an
implicit C<& returning> to all pointcuts, as the original implementation did not
trap exceptions.

=head1 FUNCTIONS

The following functions are exported by default (and are documented as such)
but are also available directly in Aspect:: namespace as well if needed.

They are documented in order from the simplest and and most common pointcut
declarator to the highest level declarator for enabling complete aspect classes.

=cut

use 5.008002;
use strict;

# Added by eilara as hack around caller() core dump
# NOTE: Now we've switched to Sub::Uplevel can this be removed?
# -- ADAMK
use Carp::Heavy                 ();
use Carp                        ();
use Params::Util           1.00 ();
use Sub::Install           0.92 ();
use Sub::Uplevel         0.2002 ();
use Aspect::Pointcut            ();
use Aspect::Pointcut::Or        ();
use Aspect::Pointcut::And       ();
use Aspect::Pointcut::Not       ();
use Aspect::Pointcut::True      ();
use Aspect::Pointcut::Call      ();
use Aspect::Pointcut::Cflow     ();
use Aspect::Pointcut::Highest   ();
use Aspect::Pointcut::Throwing  ();
use Aspect::Pointcut::Returning ();
use Aspect::Pointcut::Wantarray ();
use Aspect::Advice              ();
use Aspect::Advice::After       ();
use Aspect::Advice::Around      ();
use Aspect::Advice::Before      ();
use Aspect::Point               ();
use Aspect::Point::Static       ();

our $VERSION = '1.04';
our %FLAGS   = ();

# Track the location of exported functions so that pointcuts
# can avoid accidentally binding them.
our %EXPORTED = ();

sub install {
	Sub::Install::install_sub( {
		into => $_[1],
		code => $_[2],
		as   => $_[3] || $_[2],
	} );
	$EXPORTED{"$_[1]::$_[2]"} = 1;
}

sub import {
	my $class  = shift;
	my $into   = caller();
	my %flag   = ();
	my @export = ();

	# Handle import params
	while ( @_ ) {
		my $value = shift;
		if ( $value =~ /^:(\w+)$/ ) {
			$flag{$1} = 1;
		} else {
			push @export, $_;
		}
	}

	# Legacy API and deprecation support
	if ( $flag{legacy} or $flag{deprecated} ) {
		require Aspect::Legacy;
		if ( $flag{legacy} ) {
			return Aspect::Legacy->import;
		}
	}

	# Custom method export list
	if ( @export ) {
		$class->install( $into => $_ ) foreach @export;
		return 1;
	}

	# Install the modern API
	$class->install( $into => $_ ) foreach qw{
		aspect
		before
		after
		around
		call
		cflow
		throwing
		returning
		wantlist
		wantscalar
		wantvoid
		highest
		true
	};

	# Install deprecated API elements
	if ( $flag{deprecated} ) {
		$class->install( $into => $_ ) foreach qw{
			after_returning
			after_throwing
			if_true
		};
	}

	return 1;
}