1Sub::HandlesVia::HandleUrs(e3r)Contributed Perl DocumentSautbi:o:nHandlesVia::Handler(3)
2
3
4

NAME

6       Sub::HandlesVia::Handler - template for a method that can be delegated
7       to
8

DESCRIPTION

10       This module is part of Sub::HandlesVia's internal API.  It is mostly of
11       interest to people extending Sub::HandlesVia.
12
13       This module works in conjunction with Sub::HandlesVia::CodeGenerator
14       and subclasses of Sub::HandlesVia::Toolkit to build a string of Perl
15       code which can be compiled into a method to install into your class.
16

CONSTRUCTORS

18   new( %attributes )
19       Standard Moose-like constructor.
20
21   "lookup( $method, $trait )"
22       Looks up a method from existing handler libraries.
23
24         my $h = Sub::HandlesVia::Handler->lookup( 'get', 'Array' );
25
26       Curried version:
27
28         my $h = Sub::HandlesVia::Handler->lookup( [ 'get', 0 ], 'Array' );
29
30       The $trait may be an arrayref of possible traits.
31

EXPORTS

33       Nothing is exported by default.
34
35   "handler %attributes"
36       Shortcut for the "new" constructor.
37
38         use Sub::HandlesVia::Handler 'handler';
39
40         my $h = handler( %attr );
41         # is the same as
42         my $h = Sub::HandlesVia::Handler->new( %attr );
43

ATTRIBUTES

45   "name" Str
46       The name of the function being delegated to.
47
48   "is_mutator" Bool
49       Indicates whether this handler might mutate an attribute value.  The
50       default is to try to detect it based on analysis of the templates.
51
52   "template" Str
53       Specially formatted string (see section below) containing the Perl code
54       to implement the method.
55
56   "lvalue_template" Maybe[Str]
57       If defined, a shortcut for implementing it when the attribute slot
58       value can be used as an lvalue.
59
60   "args" Maybe[PositiveOrZeroInt]
61       The number of arguments which the method being generated expects (does
62       not include the attibute value itself).
63
64   "min_args" and "max_args" Maybe[PositiveOrZeroInt]
65       For methods which take a variable number of arguments. If omitted,
66       default to "args".
67
68   "signature" Maybe[ArrayRef[TypeTiny]]
69       A signature for said arguments.
70
71   "usage" Str
72       A signature to show in documentation, like '$index, $value'.  If not
73       provided, will be generated magically from "args", "min_args", and
74       "max_args".
75
76   "curried" Maybe[ArrayRef[Item]]
77       An arrayref of curried arguments.
78
79   "is_chainable" Bool
80       Whether to force the generated method to be chainable.
81
82   "no_validation_needed" Bool
83       Whether to do less validation of input data.
84
85   "default_for_reset" Maybe[Str]
86       If this handler has to "reset" an attribute value to its default, and
87       the attribute doesn't have a default, this string of Perl code is
88       evaluated to provide a default. An example might be "[]".
89
90   "prefer_shift_self" Bool
91       Indicates this handler would prefer the code generator to shift $self
92       off @_.
93
94   "documentation" Maybe[Str]
95       String of pod to describe the handler.
96
97   "_examples" Maybe[CodeRef]
98       This coderef, if called with parameters $class, $attr, and $method,
99       will generate a code example to insert into the pod.
100
101   "additional_validation" Maybe[CodeRef]
102       Coderef providing a slightly annoying API. To be described later.
103
104   "allow_getter_shortcuts" Bool
105       Defaults to true. Rarely useful to override.
106

METHODS

108   has_min_args() and has_max_args()
109       Indicate whether this handler has a defined min or max args.
110
111   install_method( %args )
112       The required arguments are "method_name" and "code_generator".
113       Installs the delegated method into the target class (taken from the
114       code generator).
115
116   code_as_string( %args )
117       Same required arguments as "install_method", but returns the Perl code
118       for the method as a string.
119
120   curry( @args )
121       Pseudo-constructor.
122
123       Creates a new Sub::HandlesVia::Handler object like this one, but with
124       the given arguments curried.
125
126   "loose"
127       Pseudo-constructor.
128
129       Creates a new Sub::HandlesVia::Handler object like this one, but with
130       looser argument validation.
131
132   "chainable"
133       Pseudo-constructor.
134
135       Creates a new Sub::HandlesVia::Handler object like this one, but
136       chainable.
137

TEMPLATE FORMAT

139       The template is a string of Perl code, except if the following special
140       things are found in it, they are substituted.
141
142       $SELF
143           The invocant.
144
145       $SLOT
146           Direct hashref access for the attribute.
147
148       $GET
149           The current value of the attribute.
150
151       @ARG
152           Any additional arguments passed to the delegated method.
153
154           $ARG[$n] will also work.
155
156       "#ARG"
157           The number of additional arguments passed to the delegated method.
158
159       $ARG
160           The first element in @ARG.
161
162       $DEFAULT
163           The attribute's default value, if known.
164
165       "« EXPR »"
166           An expression in double angled quotes sets the attribute's value to
167           the expression.
168
169       For example, a handler to halve the value of a numeric attribute might
170       be:
171
172         'Sub::HandlesVia::Handler'->new(
173           name => 'MyNumber:halve',
174           args => 0,
175           template => '« $GET / 2 »',
176           lvalue_template => '$GET /= 2',
177         );
178

SUBCLASSES

180       Sub::HandlesVia::Handler::Traditional and
181       Sub::HandlesVia::Handler::CodeRef are provided. See source code for
182       this module for more info.
183

BUGS

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

SEE ALSO

189       Sub::HandlesVia.
190

AUTHOR

192       Toby Inkster <tobyink@cpan.org>.
193

195       This software is copyright (c) 2020, 2022 by Toby Inkster.
196
197       This is free software; you can redistribute it and/or modify it under
198       the same terms as the Perl 5 programming language system itself.
199

DISCLAIMER OF WARRANTIES

201       THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
202       WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
203       MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
204
205
206
207perl v5.36.0                      2023-04-06       Sub::HandlesVia::Handler(3)
Impressum