File Coverage

lib/Aspect/Library/Wormhole.pm

Criterion	Covered	Total	%
statement	19	19	100.0
branch			n/a
condition			n/a
subroutine	7	7	100.0
pod	0	1	0.0
total	26	27	96.3

package Aspect::Library::Wormhole;

use strict;
use warnings;
use Carp;
use Aspect;

use base 'Aspect::Modular';

sub get_advice {
	my ($self, $source, $target) = @_;
	before { my $c = shift; $c->append_param($c->source->self) }
		call $target & cflow source => $source;
}

1;

=head1 NAME

Aspect::Library::Wormhole - A wormhole between call frames

=head1 SYNOPSIS

  package A;
  sub new { bless {}, shift }
  sub a { B->new->b }

  package B;
  sub new { bless {}, shift }
  sub b { C->new->c }

  package C;
  sub new { bless {}, shift }
  sub c { ref pop }

  package main;

  print ref A->new->a; # without aspect, prints C

  use Aspect::Library::Wormhole;
  aspect Wormhole => 'A::a', 'C::c';
  print ref A->new->a; # with aspect, prints A

=head1 SUPER

L

=head1 DESCRIPTION

A reusable aspect for passing objects down a call flow, without adding
extra arguments to the frames between the source and the target. It is a
tool for acquiring implicit context.

Suppose C calls C calls C... until C.

All is well, until one day you get a requirement with a crosscutting
implication- C requires one extra argument. It requires an
instance of the class C. The very same instance on which the method
C was called, high up the call chain of C.

Without this aspect you can either add a global C<$Current_A> (very
problematic), or make C send C its C<$self>, make
C pass it on to C, and so on until C. You are
forced to add many arguments to many methods.

Show me a developer who has never encountered this situation: you need
to add an argument to a long call flow, just because someone at the
bottom needs it, yet only someone on the top has it. The monkey code
required I in the call flow, I
that I requires, is suffering from B- Extraneous
Embedded Knowledge (L).

The code for the frames between the two ends of the wormhole, knows more
about the world than it should. This extraneous knowledge is embedded in
each method on the call flow, and there is no easy way to remove it.

This aspect removes the EEK by allowing you to setup a wormhole between
the source and target frames in the call flow. The only effect the
wormhole has on the call flow, is that the target gets called with one
extra argument: the calling source object. Thus the target acquires
implicit context.

So this wormhole:

  aspect Wormhole => 'A::a', 'Z::z';

Means: before the method C is called, I C exists in
the call flow, I append one argument to the argument list of
C. The argument appended is the calling C object.

No method in the call flow is required to pass the source object, but
C will still receive it.

  +--------+                                       +--------+
  | source |    +--------+    +--------+           | target |
  +--------+--> | B::b() |--> | C::c() |--> ...--> +--------+
  | A::a() |    +--------+    +--------+           | Z::z() |
  +--------+                                       +--------+
      .                                                ,
      |                                               /|\
      |                                              / | \
      |                                                |
      +------------- The Bajoran Wormhole -------------+

=head1 USING

The aspect constructor takes two pointcut specs, a source and a target.
The spec can be a string (full sub name), a regex (sub will match if
rexep matches), or a coderef (called with sub name, will match if returns
true).

For example, this will append a calling C to any call to a sub
defined on C, if it is in the call flow of C:

  aspect Wormhole => 'Printer::Print', qr/^Page::/;

=head1 SEE ALSO

See the L pods for a guide to the Aspect module.

You can find an example comparing the OO and AOP solutions in the
C directory of the distribution.

=cut