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!

If you supply an arrayref with a getter and setter, it's also possible to supply a third argument which is a coderef or string which will be called as a method if needing to "reset" the value. This can be thought of like a default or builder.

(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)
             reset : SubHV                       
           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  
             reset : SubHV                       
               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',
}