NAME

Sub::HandlesVia::HandlerLibrary::Code - library of code-related methods

SYNOPSIS

  package My::Class {
    use Moo;
    use Sub::HandlesVia;
    use Types::Standard 'CodeRef';
    has attr => (
      is => 'rwp',
      isa => CodeRef,
      handles_via => 'Code',
      handles => {
        'my_execute' => 'execute',
        'my_execute_list' => 'execute_list',
        'my_execute_method' => 'execute_method',
        'my_execute_method_list' => 'execute_method_list',
        'my_execute_method_scalar' => 'execute_method_scalar',
        'my_execute_method_void' => 'execute_method_void',
        'my_execute_scalar' => 'execute_scalar',
        'my_execute_void' => 'execute_void',
      },
    );
  }

DESCRIPTION

This is a library of methods for Sub::HandlesVia.

DELEGATABLE METHODS

execute( @args )

Calls the coderef, passing it any arguments.

  my $coderef = sub { 'code' };
  my $object  = My::Class->new( attr => $coderef );
  
  # Calls: $coderef->( 1, 2, 3 )
  $object->my_execute( 1, 2, 3 );

execute_list( @args )

Calls the coderef, passing it any arguments, and forcing list context. If called in scalar context, returns an arrayref.

  my $context;
  my $coderef = sub { $context = wantarray(); 'code' };
  my $object  = My::Class->new( attr => $coderef );
  
  # Calls: $coderef->( 1, 2, 3 )
  my $result = $object->my_execute_list( 1, 2, 3 );
  
  say Dumper( $result );  ## ==> [ 'code' ]
  say $context;           ## ==> true

execute_method( @args )

Calls the coderef as if it were a method, passing any arguments.

  my $coderef = sub { 'code' };
  my $object  = My::Class->new( attr => $coderef );
  
  # Calls: $coderef->( $object, 1, 2, 3 )
  $object->my_execute_method( 1, 2, 3 );

execute_method_list( @args )

Calls the coderef as if it were a method, passing any arguments, and forcing list context. If called in scalar context, returns an arrayref.

  my $context;
  my $coderef = sub { $context = wantarray(); 'code' };
  my $object  = My::Class->new( attr => $coderef );
  
  # Calls: $coderef->( $object, 1, 2, 3 )
  my $result = $object->my_execute_method_list( 1, 2, 3 );
  
  say Dumper( $result );  ## ==> [ 'code' ]
  say $context;           ## ==> true

execute_method_scalar( @args )

Calls the coderef as if it were a method, passing any arguments, and forcing scalar context.

  my $context;
  my $coderef = sub { $context = wantarray(); 'code' };
  my $object  = My::Class->new( attr => $coderef );
  
  # Calls: $coderef->( $object, 1, 2, 3 )
  my $result = $object->my_execute_method_scalar( 1, 2, 3 );
  
  say $result;  ## ==> 'code'
  say $context; ## ==> false

execute_method_void( @args )

Calls the coderef as if it were a method, passing any arguments, and forcing void context. Returns undef.

  my $context;
  my $coderef = sub { $context = wantarray(); 'code' };
  my $object  = My::Class->new( attr => $coderef );
  
  # Calls: $coderef->( $object, 1, 2, 3 )
  my $result = $object->my_execute_method_void( 1, 2, 3 );
  
  say $result;  ## ==> undef
  say $context; ## ==> undef

execute_scalar( @args )

Calls the coderef, passing it any arguments, and forcing scalar context.

  my $context;
  my $coderef = sub { $context = wantarray(); 'code' };
  my $object  = My::Class->new( attr => $coderef );
  
  # Calls: $coderef->( 1, 2, 3 )
  my $result = $object->my_execute_scalar( 1, 2, 3 );
  
  say $result;  ## ==> 'code'
  say $context; ## ==> false

execute_void( @args )

Calls the coderef, passing it any arguments, and forcing void context. Returns undef.

  my $context;
  my $coderef = sub { $context = wantarray(); 'code' };
  my $object  = My::Class->new( attr => $coderef );
  
  # Calls: $coderef->( 1, 2, 3 )
  my $result = $object->my_execute_void( 1, 2, 3 );
  
  say $result;  ## ==> undef
  say $context; ## ==> undef

EXTENDED EXAMPLES

Using execute_method

The execute_method handler allows a class to effectively provide certain methods which can be overridden by parameters in the constructor.

  use strict;
  use warnings;
  use Data::Dumper;
  
  package My::Processor {
    use Moo;
    use Sub::HandlesVia;
    use Types::Standard qw( Str CodeRef );
    
    has name => (
      is => 'ro',
      isa => Str,
      default => 'Main Process',
    );
    
    my $NULL_CODEREF = sub {};
    
    has _debug => (
      is => 'ro',
      isa => CodeRef,
      handles_via => 'Code',
      handles => { debug => 'execute_method' },
      default => sub { $NULL_CODEREF },
      init_arg => 'debug',
    );
    
    sub _do_stuff {
      my $self = shift;
      $self->debug( 'continuing process' );
      return;
    }
    
    sub run_process {
      my $self = shift;
      $self->debug( 'starting process' );
      $self->_do_stuff;
      $self->debug( 'ending process' );
    }
  }
  
  my $p1 = My::Processor->new( name => 'First Process' );
  $p1->run_process; # no output
  
  my @got;
  my $p2 = My::Processor->new(
    name => 'Second Process',
    debug => sub {
      my ( $processor, $message ) = @_;
      push @got, sprintf( '%s: %s', $processor->name, $message );
    },
  );
  $p2->run_process; # logged output
  
  my @expected = (
    'Second Process: starting process',
    'Second Process: continuing process',
    'Second Process: ending process',
  );
  say Dumper( \@got ); ## ==> \@expected

BUGS

Please report any bugs to <https://github.com/tobyink/p5-sub-handlesvia/issues>.

AUTHOR

Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

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

DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.