File Coverage

blib/lib/Method/Utils.pm

Criterion	Covered	Total	%
statement	44	44	100.0
branch	9	10	90.0
condition	4	9	44.4
subroutine	13	13	100.0
pod	4	4	100.0
total	74	80	92.5

#  You may distribute under the terms of either the GNU General Public License
#  or the Artistic License (the same terms as Perl itself)
#
#  (C) Paul Evans, 2011-2014 -- [e-mail]

package Method::Utils;

use strict;
use warnings;

our $VERSION = '0.03';

use Exporter 'import';

our @EXPORT_OK = qw(
   maybe
   possibly

   inwardly
   outwardly
);

require mro;

=head1 NAME

C - functional-style utilities for method calls

=cut

=head1 SYNOPSIS

 use Method::Utils qw( maybe possibly inwardly );

 $obj->${maybe "do_thing"}(@args);
 # equivalent to
 #   $obj->do_thing(@args) if defined $obj;

 $obj->${possibly "do_another"}(@args);
 # equivalent to
 #   $obj->do_another(@args) if $obj->can( "do_another" );

 $obj->${inwardly "do_all_these"}();
 # invokes the method on every subclass in 'mro' order

=cut

=head1 FUNCTIONS

All of the following functions are intended to be used as method call
modifiers. That is, they return a C reference to a C reference
which allows them to be used in the following syntax

 $ball->${possibly "bounce"}( "10 metres" );

Since the returned double-reference can be dereferenced by C<${ }> to obtain
the C reference directly, it can be used to create new methods. For
example:

 *bounce_if_you_can = ${possibly "bounce"};

This is especially useful for creating methods in base classes which
distribute across all the classes in a class heirarchy; for example

 *DESTROY = ${inwardly "COLLAPSE"};

=cut

=head2 maybe $method

Invokes the named method on the object or class, if one is provided, and
return what it returned. If invoked on C, returns C in scalar
context or the empty list in list context.

C<$method> here may also be a double-ref to a C, such as returned by
the remaining utility functions given below. In this case, it will be
dereferenced automatically, allowing you to conveniently perform

  $obj->${maybe possibly 'method'}( @args )

=cut

sub maybe
{
   my $mth = shift;
   $mth = $$mth if ref $mth eq "REF" and ref $$mth eq "CODE";
   \sub {
      my $self = shift;
      defined $self or return;
      $self->$mth( @_ );
   };
}

=head2 possibly $method

Invokes the named method on the object or class and return what it returned,
if it exists. If the method does not exist, returns C in scalar context
or the empty list in list context.

=cut

sub possibly
{
   my $mth = shift;
   \sub {
      my $self = shift;
      return unless $self->can( $mth );
      $self->$mth( @_ );
   };
}

=head2 inwardly $method

=head2 outwardly $method

Invokes the named method on the object or class for I class that
provides such a method in the C<@ISA> heirarchy, not just the first one that
is found. C searches all the classes in L order, finding the
class itself first and then its superclasses. C runs in reverse,
starting its search at the base-most superclass, searching upward before
finally ending at the class itself.

=cut

sub inwardly
{
   my $mth = shift;
   \sub {
      my $self = shift;
      foreach my $class ( @{ mro::get_linear_isa( ref $self || $self ) } ) {
         no strict 'refs';
         defined &{$class."::$mth"} or next;
         &{$class."::$mth"}( $self, @_ );
      }
   }
}

sub outwardly
{
   my $mth = shift;
   \sub {
      my $self = shift;
      foreach my $class ( reverse @{ mro::get_linear_isa( ref $self || $self ) } ) {
         no strict 'refs';
         defined &{$class."::$mth"} or next;
         &{$class."::$mth"}( $self, @_ );
      }
   }
}

=head1 TODO

=over 4

=item *

Consider C, which would C-wrap the call, returning
C/empty if it failed.

=item *

Consider better ways to combine more of these. E.g. C
would C-wrap each subclass call. C without C would
fail if no class provides the method.

=back

=cut

=head1 SEE ALSO

=over 4

=item *

L - Madness With Methods

=back

=cut

=head1 AUTHOR

Paul Evans

=cut

0x55AA;