=pod

=encoding utf-8

=head1 NAME

Sub::HandlesVia::Manual::WithMouse - using Sub::HandlesVia with Mouse

=head1 SYNOPSIS

 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',
     },
   );
 }

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

=head1 MANUAL

Sub::HandlesVia allows you to delegate methods from your class to the
values of your objects' attributes.

Conceptually, it allows you to define C<< $object->push_number($n) >>
to be a shortcut for C<< $object->numbers->push($n) >> except that
C<< $object->numbers >> is an arrayref, so doesn't have methods you
can call on it like C<push>.

You should be able to use Sub::HandlesVia as a drop-in replacement for
L<MouseX::NativeTraits>, just replacing C<< traits => ['Array'] >> in an
attribute definition with C<< handles_via => 'Array' >>.

=head2 Usage in Mouse Roles

Mouse roles are only partially supported.

 package R1 {
   use Mouse:Role;
 }
 
 package R2 {
   use Mouse:Role;
   use Sub::HandlesVia;
   
   # define some attributes with delegation
 }
 
 # This class is broken.
 package C1 {
   use Mouse;
   with 'R1', 'R2';
 }
 
 # This class should work.
 package C2 {
   use Mouse;
   with 'R1';
   with 'R2';
 }

For details, see L<https://github.com/tobyink/p5-sub-handlesvia/issues/9>.

Patches to fix the issue are very welcome!

=head2 Which Methods Can Be Delegated To?

The C<handles_via> option indicates which library of methods should be
available. Valid values include
L<Array|Sub::HandlesVia::HandlerLibrary::Array>,
L<Blessed|Sub::HandlesVia::HandlerLibrary::Blessed>,
L<Bool|Sub::HandlesVia::HandlerLibrary::Bool>,
L<Code|Sub::HandlesVia::HandlerLibrary::Code>,
L<Counter|Sub::HandlesVia::HandlerLibrary::Counter>,
L<Enum|Sub::HandlesVia::HandlerLibrary::Enum>,
L<Hash|Sub::HandlesVia::HandlerLibrary::Hash>,
L<Number|Sub::HandlesVia::HandlerLibrary::Number>,
L<Scalar|Sub::HandlesVia::HandlerLibrary::Scalar>, and
L<String|Sub::HandlesVia::HandlerLibrary::String>.

An arrayref can be provided for C<handles_via>, though many of the options
are conceptually contradictory.

 handles_via => [ 'Number', 'Scalar' ]

=head2 Mouse Native Types

Although the synopsis shows L<Types::Standard> being used for type constraints,
Mouse native types should also 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',
     },
   );
 }

=head2 True MouseX::NativeTraits Drop-In Syntax

Sub::HandlesVia will also recognize L<MouseX::NativeTraits>-style
C<traits>. It will jump in and handle them before L<MouseX::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',
     },
   );
 }

=head1 BUGS

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

=head1 SEE ALSO

Misc advanced documentation:
L<Sub::HandlesVia::Manual::Advanced>.

L<Sub::HandlesVia>.

Documentation for delegatable methods:
L<Sub::HandlesVia::HandlerLibrary::Array>,
L<Sub::HandlesVia::HandlerLibrary::Blessed>,
L<Sub::HandlesVia::HandlerLibrary::Bool>,
L<Sub::HandlesVia::HandlerLibrary::Code>,
L<Sub::HandlesVia::HandlerLibrary::Counter>,
L<Sub::HandlesVia::HandlerLibrary::Enum>,
L<Sub::HandlesVia::HandlerLibrary::Hash>,
L<Sub::HandlesVia::HandlerLibrary::Number>,
L<Sub::HandlesVia::HandlerLibrary::Scalar>, and
L<Sub::HandlesVia::HandlerLibrary::String>.

=head1 AUTHOR

Toby Inkster E<lt>tobyink@cpan.orgE<gt>.

=head1 COPYRIGHT AND LICENCE

This software is copyright (c) 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.

=head1 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.

