NAME

Sub::HandlesVia - alternative handles_via implementation

SYNOPSIS

 package Kitchen {
   use Moo;
   use Sub::HandlesVia;
   use Types::Standard qw( ArrayRef Str );
   
   has food => (
     is          => 'ro',
     isa         => ArrayRef[Str],
     handles_via => 'Array',
     default     => sub { [] },
     handles     => {
       'add_food'    => 'push',
       'find_food'   => 'grep',
     },
   );
 }

 my $kitchen = Kitchen->new;
 $kitchen->add_food('Bacon');
 $kitchen->add_food('Eggs');
 $kitchen->add_food('Sausages');
 $kitchen->add_food('Beans');
 
 my @foods = $kitchen->find_food(sub { /^B/i });

DESCRIPTION

If you've used Moose's native attribute traits, or MooX::HandlesVia before, you should have a fairly good idea what this does.

Why re-invent the wheel? Well, this is an implementation that should work okay with Moo, Moose, Mouse, and any other OO toolkit you throw at it. One ring to rule them all, so to speak.

Also, unlike MooX::HandlesVia, it honours type constraints, plus it doesn't have the limitation that it can't mutate non-reference values.

Using with Moo

You should be able to use it as a drop-in replacement for MooX::HandlesVia.

 package Kitchen {
   use Moo;
   use Sub::HandlesVia;
   use Types::Standard qw( ArrayRef Str );
   
   has food => (
     is          => 'ro',
     isa         => ArrayRef[Str],
     handles_via => 'Array',
     default     => sub { [] },
     handles     => {
       'add_food'    => 'push',
       'find_food'   => 'grep',
     },
   );
 }

Using with Mouse

It works the same as Moo basically.

 package Kitchen {
   use Mouse;
   use Sub::HandlesVia;
   use Types::Standard qw( ArrayRef Str );
   
   has food => (
     is          => 'ro',
     isa         => ArrayRef[Str],
     handles_via => 'Array',
     default     => sub { [] },
     handles     => {
       'add_food'    => 'push',
       'find_food'   => 'grep',
     },
   );
 }

You are not forced to use Types::Standard. Mouse native types should work fine.

 package Kitchen {
   use Mouse;
   use Sub::HandlesVia;
   
   has food => (
     is          => 'ro',
     isa         => 'ArrayRef[Str]',
     handles_via => 'Array',
     default     => sub { [] },
     handles     => {
       'add_food'    => 'push',
       'find_food'   => 'grep',
     },
   );
 }

Sub::HandlesVia will also recognize MooseX::NativeTraits-style traits. It will jump in and handle them before MooseX::NativeTraits notices!

 package Kitchen {
   use Mouse;
   use Sub::HandlesVia;
   
   has food => (
     is          => 'ro',
     isa         => 'ArrayRef[Str]',
     traits      => ['Array'],
     default     => sub { [] },
     handles     => {
       'add_food'    => 'push',
       'find_food'   => 'grep',
     },
   );
 }

(If you have a mouse in your kitchen though, that might not be very hygienic.)

Using with Moose

It works the same as Mouse basically.

 package Kitchen {
   use Moose;
   use Sub::HandlesVia;
   use Types::Standard qw( ArrayRef Str );
   
   has food => (
     is          => 'ro',
     isa         => ArrayRef[Str],
     handles_via => 'Array',
     default     => sub { [] },
     handles     => {
       'add_food'    => 'push',
       'find_food'   => 'grep',
     },
   );
 }

You are not forced to use Types::Standard. Moose native types should work fine.

 package Kitchen {
   use Moose;
   use Sub::HandlesVia;
   
   has food => (
     is          => 'ro',
     isa         => 'ArrayRef[Str]',
     handles_via => 'Array',
     default     => sub { [] },
     handles     => {
       'add_food'    => 'push',
       'find_food'   => 'grep',
     },
   );
 }

Sub::HandlesVia will also recognize native-traits-style traits. It will jump in and handle them before Moose notices!

 package Kitchen {
   use Moose;
   use Sub::HandlesVia;
   
   has food => (
     is          => 'ro',
     isa         => 'ArrayRef[Str]',
     traits      => ['Array'],
     default     => sub { [] },
     handles     => {
       'add_food'    => 'push',
       'find_food'   => 'grep',
     },
   );
 }

(If you have a moose in your kitchen, that might be even worse than the mouse.)

Using with Anything

For Moose and Mouse, Sub::HandlesVia can use their metaobject protocols to grab an attribute's definition and install the methods it needs to. For Moo, it can wrap has and do its stuff that way. For other classes, you need to be more explicit and tell it what methods to delegate to what attributes.

 package Kitchen {
   use Class::Tiny {
     food => sub { [] },
   };
   
   use Sub::HandlesVia qw( delegations );
   
   delegations(
     attribute   => 'food'
     handles_via => 'Array',
     handles     => {
       'add_food'    => 'push',
       'find_food'   => 'grep',
     },
   );
 }

Setting attribute to "food" means that when Sub::HandlesVia needs to get the food list, it will call $kitchen->food and when it needs to set the food list, it will call $kitchen->food($value). If you have separate getter and setter methods, just do:

     attribute   => [ 'get_food', 'set_food' ],

Or if you don't have any accessors and want Sub::HandlesVia to directly access the underlying hashref:

     attribute   => '{food}',

Or maybe you have a setter, but want to use hashref access for the getter:

     attribute   => [ '{food}', 'set_food' ],

Or maybe you still want direct access for the getter, but your object is a blessed arrayref instead of a blessed hashref:

     attribute   => [ '[7]', 'set_food' ],

Or maybe your needs are crazy unique:

     attribute   => [ \&getter, \&setter ],

The coderefs are passed the instance as their first argument, and the setter is also passed a value to set.

Really, I don't think there's any object system that this won't work for!

(The delegations function can be imported into Moo/Mouse/Moose classes too, in which case the attribute needs to be the same attribute name you passed to has. You cannot use a arrayref, coderef, hash key, or array index.)

What methods can be delegated to?

The following table compares Sub::HandlesVia with Data::Perl, Moose native traits, and MouseX::NativeTraits.

  Array ===========================================
            accessor : SubHV  DataP  Moose  Mouse  
                 all : SubHV  DataP                
            all_true : SubHV                       
                 any : SubHV                Mouse  
               apply : SubHV                Mouse  
               clear : SubHV  DataP  Moose  Mouse  
               count : SubHV  DataP  Moose  Mouse  
              delete : SubHV  DataP  Moose  Mouse  
            elements : SubHV  DataP  Moose  Mouse  
               fetch :                      Mouse  (alias: get)
               first : SubHV  DataP  Moose  Mouse  
         first_index : SubHV  DataP  Moose         
             flatten : SubHV  DataP                
        flatten_deep : SubHV  DataP                
            for_each : SubHV                Mouse  
       for_each_pair : SubHV                Mouse  
                 get : SubHV  DataP  Moose  Mouse  
                grep : SubHV  DataP  Moose  Mouse  
                head : SubHV  DataP                
              insert : SubHV  DataP  Moose  Mouse  
            is_empty : SubHV  DataP  Moose  Mouse  
                join : SubHV  DataP  Moose  Mouse  
                 map : SubHV  DataP  Moose  Mouse  
                 max : SubHV                       
              maxstr : SubHV                       
                 min : SubHV                       
              minstr : SubHV                       
            natatime : SubHV  DataP  Moose         
        not_all_true : SubHV                       
           pairfirst : SubHV                       
            pairgrep : SubHV                       
            pairkeys : SubHV                       
             pairmap : SubHV                       
               pairs : SubHV                       
          pairvalues : SubHV                       
         pick_random : SubHV                       
                 pop : SubHV  DataP  Moose  Mouse  
               print : SubHV  DataP                
             product : SubHV                       
                push : SubHV  DataP  Moose  Mouse  
              reduce : SubHV  DataP  Moose  Mouse  
          reductions : SubHV                       
              remove :                      Mouse  (alias: delete)
             reverse : SubHV  DataP                
              sample : SubHV                       
                 set : SubHV  DataP  Moose  Mouse  
       shallow_clone : SubHV  DataP  Moose         
               shift : SubHV  DataP  Moose  Mouse  
             shuffle : SubHV  DataP  Moose  Mouse  
    shuffle_in_place : SubHV                       
                sort : SubHV  DataP  Moose  Mouse  
             sort_by :                      Mouse  (sort)
       sort_in_place : SubHV  DataP  Moose  Mouse  
    sort_in_place_by :                      Mouse  (sort_in_place)
              splice : SubHV  DataP  Moose  Mouse  
               store :                      Mouse  (alias: set)
                 sum : SubHV                       
                tail : SubHV  DataP                
                uniq : SubHV  DataP  Moose  Mouse  
       uniq_in_place : SubHV                       
             uniqnum : SubHV                       
    uniqnum_in_place : SubHV                       
             uniqstr : SubHV                       
    uniqstr_in_place : SubHV                       
             unshift : SubHV  DataP  Moose  Mouse  
 
  Bool ============================================
                 not : SubHV  DataP  Moose  Mouse  
               reset : SubHV                       
                 set : SubHV  DataP  Moose  Mouse  
              toggle : SubHV  DataP  Moose  Mouse  
               unset : SubHV  DataP  Moose  Mouse  
 
  Code ============================================
             execute : SubHV  DataP  Moose  Mouse  
      execute_method : SubHV         Moose  Mouse  
 
  Counter =========================================
                 dec : SubHV  DataP  Moose  Mouse  
                 inc : SubHV  DataP  Moose  Mouse  
               reset : SubHV  DataP  Moose  Mouse  
                 set : SubHV         Moose  Mouse  
 
  Hash ============================================
            accessor : SubHV  DataP  Moose  Mouse  
                 all : SubHV  DataP                
               clear : SubHV  DataP  Moose  Mouse  
               count : SubHV  DataP  Moose  Mouse  
             defined : SubHV  DataP  Moose  Mouse  
              delete : SubHV  DataP  Moose  Mouse  
            elements : SubHV  DataP  Moose  Mouse  
              exists : SubHV  DataP  Moose  Mouse  
               fetch :                      Mouse  (alias: get)
        for_each_key : SubHV                Mouse  
       for_each_pair : SubHV                Mouse  
      for_each_value : SubHV                Mouse  
                 get : SubHV  DataP  Moose  Mouse  
            is_empty : SubHV  DataP  Moose  Mouse  
                keys : SubHV  DataP  Moose  Mouse  
                  kv : SubHV  DataP  Moose  Mouse  
                 set : SubHV  DataP  Moose  Mouse  
       shallow_clone : SubHV  DataP  Moose         
         sorted_keys : SubHV                Mouse  
               store :                      Mouse  (alias: set)
              values : SubHV  DataP  Moose  Mouse  
 
  Number ==========================================
                 abs : SubHV  DataP  Moose  Mouse  
                 add : SubHV  DataP  Moose  Mouse  
                 div : SubHV  DataP  Moose  Mouse  
                 get : SubHV                       
                 mod : SubHV  DataP  Moose  Mouse  
                 mul : SubHV  DataP  Moose  Mouse  
                 set : SubHV         Moose         
                 sub : SubHV  DataP  Moose  Mouse  
 
  String ==========================================
              append : SubHV  DataP  Moose  Mouse  
               chomp : SubHV  DataP  Moose  Mouse  
                chop : SubHV  DataP  Moose  Mouse  
               clear : SubHV  DataP  Moose  Mouse  
                 get : SubHV                       
                 inc : SubHV  DataP  Moose  Mouse  
              length : SubHV  DataP  Moose  Mouse  
               match : SubHV  DataP  Moose  Mouse  
             prepend : SubHV  DataP  Moose  Mouse  
             replace : SubHV  DataP  Moose  Mouse  
    replace_globally : SubHV                Mouse  
               reset : SubHV                       
                 set : SubHV                       
              substr : SubHV  DataP  Moose  Mouse  

Method Chaining

Say you have the following

     handles_via => 'Array',
     handles     => {
       'add_food'    => 'push',
       'find_food'   => 'grep',
       'remove_food' => 'pop',
     },

Now $kitchen->remove_food will remove the last food on the list and return it. But what if we don't care about what food was removed? We just want to remove the food and discard it. You can do this:

     handles_via => 'Array',
     handles     => {
       'add_food'    => 'push',
       'find_food'   => 'grep',
       'remove_food' => 'pop...',
     },

Now the remove_food method will return the kitchen object instead of returning the food. This makes it suitable for chaining method calls:

  # remove the three most recent foods
  $kitchen->remove_food->remove_food->remove_food;

Hand Waving

Sub::HandlesVia tries to be strict by default, but you can tell it to be less rigourous checking method arguments, etc using the ~ prefix:

     handles_via => 'Array',
     handles     => {
       'find_food'   => '~grep',
     },

CodeRefs

You can delegate to coderefs:

     handles_via => 'Array',
     handles    => {
       'find_healthiest' => sub { my $foods = shift; ... },
     }

Named Methods

Let's say "FoodList" is a class where instances are blessed arrayrefs of strings.

     isa         => InstanceOf['FoodList'],
     handles_via => 'Array',
     handles     => {
       'find_food'             => 'grep',
       'find_healthiest_food'  => 'find_healthiest',
     },

Now $kitchen->find_food($coderef) does this (which breaks encapsulation of course):

  my @result = grep $coderef->(), @{ $kitchen->food };

And $kitchen->find_healthiest_food does this:

  $kitchen->food->find_healthiest

Basically, because find_healthiest isn't one of the methods offered by Sub::HandlesVia::HandlerList::Array, it assumes you want to call it on the arrayref like a proper method.

Currying Favour

All this talk of food is making me hungry, but as much as I'd like to eat a curry right now, that's not the kind of currying we're talking about.

     handles_via => 'Array',
     handles     => {
       'get_food'   => 'get',
     },

$kitchen->get_food(0) will return the first item on the list. $kitchen->get_food(1) will return the second item on the list. And so on.

     handles_via => 'Array',
     handles     => {
       'first_food'   => [ 'get' => 0 ],
       'second_food'  => [ 'get' => 1 ],
     },

I think you already know what this does. Right?

And yes, currying works with coderefs.

     handles_via => 'Array',
     handles     => {
       'blargy'       => [ sub { ... }, @curried ],
     },

Pick and Mix

    isa         => ArrayRef|HashRef,
    handles_via => [ 'Array', 'Hash' ],
    handles     => {
      the_keys     => 'keys',
      ship_shape   => 'sort_in_place',
    }

Here you have an attribute which might be an arrayref or a hashref. When it's an arrayref, $object->ship_shape will work nicely, but $object->the_keys will fail badly.

Still, this sort of thing can kind of make sense if you have an object that overloads both @{} and %{}.

Sometime a method will be ambiguous. For example, there's a get method for both hashes and arrays. In this case, the array one will win because you listed it first in handles_via.

But you can be specific:

    isa         => ArrayRef|HashRef,
    handles_via => [ 'Array', 'Hash' ],
    handles     => {
      get_foo => 'Array->get',
      get_bar => 'Hash->get',
    }

BUGS

Please report any bugs to http://rt.cpan.org/Dist/Display.html?Queue=Sub-HandlesVia.

(There are known bugs for Moose native types that do coercion.)

SEE ALSO

Moose, MouseX::NativeTraits, Data::Perl, MooX::HandlesVia.

AUTHOR

Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

This software is copyright (c) 2020 by Toby Inkster.

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.