NAME
Sub::HandlesVia::Handler - template for a method that can be delegated to
DESCRIPTION
This module is part of Sub::HandlesVia's internal API. It is mostly of interest to people extending Sub::HandlesVia.
This module works in conjunction with Sub::HandlesVia::CodeGenerator and subclasses of Sub::HandlesVia::Toolkit to build a string of Perl code which can be compiled into a method to install into your class.
CONSTRUCTORS
new( %attributes )
Standard Moose-like constructor.
lookup( $method, $trait )
Looks up a method from existing handler libraries.
my $h = Sub::HandlesVia::Handler->lookup( 'get', 'Array' );
Curried version:
my $h = Sub::HandlesVia::Handler->lookup( [ 'get', 0 ], 'Array' );
The $trait
may be an arrayref of possible traits.
EXPORTS
Nothing is exported by default.
handler %attributes
Shortcut for the new
constructor.
use Sub::HandlesVia::Handler 'handler';
my $h = handler( %attr );
# is the same as
my $h = Sub::HandlesVia::Handler->new( %attr );
ATTRIBUTES
name
Str
The name of the function being delegated to.
is_mutator
Bool
Indicates whether this handler might mutate an attribute value. The default is to try to detect it based on analysis of the templates.
template
Str
Specially formatted string (see section below) containing the Perl code to implement the method.
lvalue_template
Maybe[Str]
If defined, a shortcut for implementing it when the attribute slot value can be used as an lvalue.
args
Maybe[PositiveOrZeroInt]
The number of arguments which the method being generated expects (does not include the attibute value itself).
min_args
and max_args
Maybe[PositiveOrZeroInt]
For methods which take a variable number of arguments. If omitted, default to args
.
signature
Maybe[ArrayRef[TypeTiny]]
A signature for said arguments.
usage
Str
A signature to show in documentation, like '$index, $value'
. If not provided, will be generated magically from args
, min_args
, and max_args
.
curried
Maybe[ArrayRef[Item]]
An arrayref of curried arguments.
is_chainable
Bool
Whether to force the generated method to be chainable.
no_validation_needed
Bool
Whether to do less validation of input data.
default_for_reset
Maybe[Str]
If this handler has to "reset" an attribute value to its default, and the attribute doesn't have a default, this string of Perl code is evaluated to provide a default. An example might be "[]"
.
prefer_shift_self
Bool
Indicates this handler would prefer the code generator to shift $self
off @_
.
documentation
Maybe[Str]
String of pod to describe the handler.
_examples
Maybe[CodeRef]
This coderef, if called with parameters $class
, $attr
, and $method
, will generate a code example to insert into the pod.
additional_validation
Maybe[CodeRef]
Coderef providing a slightly annoying API. To be described later.
allow_getter_shortcuts
Bool
Defaults to true. Rarely useful to override.
METHODS
has_min_args()
and has_max_args()
Indicate whether this handler has a defined min or max args.
install_method( %args )
The required arguments are method_name
and code_generator
. Installs the delegated method into the target class (taken from the code generator).
code_as_string( %args )
Same required arguments as install_method
, but returns the Perl code for the method as a string.
curry( @args )
Pseudo-constructor.
Creates a new Sub::HandlesVia::Handler object like this one, but with the given arguments curried.
loose
Pseudo-constructor.
Creates a new Sub::HandlesVia::Handler object like this one, but with looser argument validation.
chainable
Pseudo-constructor.
Creates a new Sub::HandlesVia::Handler object like this one, but chainable.
TEMPLATE FORMAT
The template is a string of Perl code, except if the following special things are found in it, they are substituted.
$SELF
-
The invocant.
$SLOT
-
Direct hashref access for the attribute.
$GET
-
The current value of the attribute.
@ARG
-
Any additional arguments passed to the delegated method.
$ARG[$n]
will also work. #ARG
-
The number of additional arguments passed to the delegated method.
$ARG
-
The first element in
@ARG
. $DEFAULT
-
The attribute's default value, if known.
« EXPR »
-
An expression in double angled quotes sets the attribute's value to the expression.
For example, a handler to halve the value of a numeric attribute might be:
'Sub::HandlesVia::Handler'->new(
name => 'MyNumber:halve',
args => 0,
template => '« $GET / 2 »',
lvalue_template => '$GET /= 2',
);
SUBCLASSES
Sub::HandlesVia::Handler::Traditional and Sub::HandlesVia::Handler::CodeRef are provided. See source code for this module for more info.
BUGS
Please report any bugs to https://github.com/tobyink/p5-sub-handlesvia/issues.
SEE ALSO
AUTHOR
Toby Inkster <tobyink@cpan.org>.
COPYRIGHT AND LICENCE
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.
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.