TOBYINK / Sub-HandlesVia-0.050001 / lib / Sub / HandlesVia / Manual / WithGeneric.pod 

            

              
—
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

              
=pod
=encoding utf-8
=head1 NAME
Sub::HandlesVia::Manual::WithGeneric - using Sub::HandlesVia with generic Perl classes
=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>.
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 C<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 {
    
   # constructor
   sub new {
     my ( $class, %arg ) = @_;
     $arg{food} ||= [];
     return bless( \%arg, $class );
   }
    
   # getter/setter for `food`
   sub food {
     (@_ == 1) ? $_[0]{food} : ( $_[0]{food} = $_[1] );
   }
    
   use Sub::HandlesVia qw( delegations );
    
   delegations(
     attribute   => 'food'
     handles_via => 'Array',
     handles     => {
       'add_food'    => 'push',
       'find_food'   => 'grep',
     },
   );
 }
Setting C<attribute> to "food" means that when Sub::HandlesVia needs
to get the food list, it will call C<< $kitchen->food >> and when
it needs to set the food list, it will call C<< $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 C<delegations> function can be imported into Moo/Mouse/Moose classes
too, in which case the C<attribute> needs to be the same attribute name
you passed to C<has>. You cannot use a arrayref, coderef, hash key, or
array index.)
=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.