view release on metacpan or  search on metacpan

local/lib/perl5/Test/Trap/Builder.pm  view on Meta::CPAN

Note: Direct calls to the Exception method within closures may cause
circular references and so leakage.  To avoid this, fetch an
L</"ExceptionFunction"> and call it from the closure instead.

=head2 ExceptionFunction

This method returns a function that may be called with the same effect
as calling the L</"Exception"> method, allowing closures to throw
exceptions without causing circular references by closing over the
trap object itself.

To illustrate:

  # this will create a circular reference chain:
  # trap object has property collection has teardown closure has trap object
  $self->Teardown($_) for sub {
    do_stuff() or $self->Exception("Stuff didn't work.");
  };

  # this will break the circular reference chain:
  # teardown closure no longer has trap object
  $Exception = $self->ExceptionFunction;
  $self->Teardown($_) for sub {
    do_things() or $Exception->("Things didn't work.");
  };

=head1 METHODS

=head2 new

Returns a singleton object.  Don't expect this module to work with a
different instance object of this class.

=head2 trap TRAPPER, GLOBREF, LAYERARRAYREF, CODE

Implements a trap for the I<TRAPPER> module, applying the layers of
I<LAYERARRAYREF>, trapping various outcomes of the user I<CODE>, and
storing the trap object into the scalar slot of I<GLOBREF>.

In most cases, the trapper should conveniently export a function
calling this method.

=head2 layer NAME, CODE

Registers a layer by I<NAME> to the calling trapper.  When the layer
is applied, the I<CODE> will be invoked on the trap object being
built, with no arguments, and should call either the Next() or Run()
method or equivalent.

=head2 output_layer NAME, GLOBREF

Registers (by I<NAME> and to the calling trapper) a layer for trapping
output on the file handle of the I<GLOBREF>, using I<NAME> also as the
attribute name.

=head2 capture_strategy NAME, [CODE]

When called with two arguments, registers (by I<NAME> and globally) a
strategy for output trap layers.  When called with a single argument,
looks up and returns the strategy registered by I<NAME> (or undef).

When a layer using this strategy is applied, the I<CODE> will be called
on the trap object, with the layer name and the output handle's fileno
and globref as arguments.

=head2 output_layer_backend SPEC

Back-compat alias of the above.

=head2 first_capture_strategy SPEC

Where I<SPEC> is empty, just returns.

Where I<SPEC> is a string of comma-or-semicolon separated names, runs
through the names, returning the first strategy it finds.  Dies if no
strategy is found by any of these names.

=head2 first_output_layer_backend SPEC

Back-compat alias of the above.

=head2 multi_layer NAME, LAYERS

Registers (by I<NAME>) a layer that just pushes a number of other
I<LAYERS> on the stack of layers.  If any of the I<LAYERS> is neither
an anonymous method nor the name of a layer registered to the caller
or a trapper it inherits from, an exception is raised.

=head2 layer_implementation TRAPPER, LAYERS

Returns the subroutines that implement the requested I<LAYERS>.  If
any of the I<LAYERS> is neither an anonymous method nor the name of a
layer registered to or inherited by the I<TRAPPER>, an exception is
raised.

=head2 accessor NAMED_ARGS

Generates and registers any number of accessors according to the
I<NAMED_ARGS>, and also generates the proper test methods for these
accessors (see below).

The following named arguments are recognized:

=over

=item is_leaveby

If true, the tests methods will generate better diagnostics if the
trap was not left as specified.  Also, a special did_I<ACCESSOR> test
method will be generated (unless already present), simply passing as
long as the trap was left as specified.

=item is_array

If true, the simple accessor(s) will be smart about context and
arguments, returning an arrayref on no argument (in any context), an
array slice in list context (on any number of arguments), and the
element indexed by the first argument otherwise.

=item simple