Sub::HandlesVia - alternative handles_via implementation
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 });
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.
Note: as Sub::HandlesVia needs to detect whether you're using Moo, Moose, or Mouse, and often needs to detect whether your package is a class or a role, it needs to be loaded after Moo/Moose/Mouse.
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', }, ); }
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.)
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.)
You should be able to use Sub::HandlesVia with Mite 0.001011 or above. Your project will still have a dependency on Sub::HandlesVia.
package MyApp::Kitchen { use MyApp::Mite; use Sub::HandlesVia; has food => ( is => 'ro', isa => 'ArrayRef[Str]', handles_via => 'Array', default => sub { [] }, handles => { 'add_food' => 'push', 'find_food' => 'grep', }, ); }
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.
has
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
$kitchen->food
$kitchen->food($value)
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.)
delegations
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 cmp : SubHV div : SubHV DataP Moose Mouse eq : SubHV ge : SubHV get : SubHV gt : SubHV le : SubHV lt : SubHV mod : SubHV DataP Moose Mouse mul : SubHV DataP Moose Mouse ne : SubHV set : SubHV Moose sub : SubHV DataP Moose Mouse Scalar ========================================== make_getter : SubHV make_setter : SubHV scalar_reference : SubHV String ========================================== append : SubHV DataP Moose Mouse chomp : SubHV DataP Moose Mouse chop : SubHV DataP Moose Mouse clear : SubHV DataP Moose Mouse cmp : SubHV cmpi : SubHV contains : SubHV contains_i : SubHV ends_with : SubHV ends_with_i : SubHV eq : SubHV eqi : SubHV fc : SubHV ge : SubHV gei : SubHV get : SubHV gt : SubHV gti : SubHV inc : SubHV DataP Moose Mouse lc : SubHV le : SubHV lei : SubHV length : SubHV DataP Moose Mouse lt : SubHV lti : SubHV match : SubHV DataP Moose Mouse match_i : SubHV ne : SubHV nei : SubHV prepend : SubHV DataP Moose Mouse replace : SubHV DataP Moose Mouse replace_globally : SubHV Mouse reset : SubHV set : SubHV starts_with : SubHV starts_with_i : SubHV substr : SubHV DataP Moose Mouse uc : SubHV
For further details see: Array, Bool, Code, Counter, Hash, Number, Scalar, and String.
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:
$kitchen->remove_food
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_food
# remove the three most recent foods $kitchen->remove_food->remove_food->remove_food;
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', },
You can delegate to coderefs:
handles_via => 'Array', handles => { 'find_healthiest' => sub { my $foods = shift; ... }, }
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):
$kitchen->find_food($coderef)
my @result = grep $coderef->(), @{ $kitchen->food };
And $kitchen->find_healthiest_food does this:
$kitchen->find_healthiest_food
$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.
find_healthiest
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.
$kitchen->get_food(0)
$kitchen->get_food(1)
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 ], },
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.
$object->ship_shape
$object->the_keys
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.
get
handles_via
But you can be specific:
isa => ArrayRef|HashRef, handles_via => [ 'Array', 'Hash' ], handles => { get_foo => 'Array->get', get_bar => 'Hash->get', }
Please report any bugs to https://github.com/tobyink/p5-sub-handlesvia/issues.
(There are known bugs for Moose native types that do coercion.)
Documentation for delegatable methods: Array, Bool, Code, Counter, Hash, Number, Scalar, and String.
Other implementations of the same concept: Moose::Meta::Attribute::Native, MouseX::NativeTraits, and MooX::HandlesVia with Data::Perl.
Toby Inkster <tobyink@cpan.org>.
This software is copyright (c) 2020, 2022 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.
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.
To install Sub::HandlesVia, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Sub::HandlesVia
CPAN shell
perl -MCPAN -e shell install Sub::HandlesVia
For more information on module installation, please visit the detailed CPAN module installation guide.