.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Sub::HandlesVia::Handler 3"
.TH Sub::HandlesVia::Handler 3 2024-09-02 "perl v5.40.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Sub::HandlesVia::Handler \- template for a method that can be delegated to
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fBThis module is part of Sub::HandlesVia's internal API.\fR
It is mostly of interest to people extending Sub::HandlesVia.
.PP
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.
.SH CONSTRUCTORS
.IX Header "CONSTRUCTORS"
.ie n .SS "new( %attributes )"
.el .SS "\f(CWnew( %attributes )\fP"
.IX Subsection "new( %attributes )"
Standard Moose-like constructor.
.ie n .SS """lookup( $method, $trait )"""
.el .SS "\f(CWlookup( $method, $trait )\fP"
.IX Subsection "lookup( $method, $trait )"
Looks up a method from existing handler libraries.
.PP
.Vb 1
\&  my $h = Sub::HandlesVia::Handler\->lookup( \*(Aqget\*(Aq, \*(AqArray\*(Aq );
.Ve
.PP
Curried version:
.PP
.Vb 1
\&  my $h = Sub::HandlesVia::Handler\->lookup( [ \*(Aqget\*(Aq, 0 ], \*(AqArray\*(Aq );
.Ve
.PP
The \f(CW$trait\fR may be an arrayref of possible traits.
.SH EXPORTS
.IX Header "EXPORTS"
Nothing is exported by default.
.ie n .SS """handler %attributes"""
.el .SS "\f(CWhandler %attributes\fP"
.IX Subsection "handler %attributes"
Shortcut for the \f(CW\*(C`new\*(C'\fR constructor.
.PP
.Vb 1
\&  use Sub::HandlesVia::Handler \*(Aqhandler\*(Aq;
\&  
\&  my $h = handler( %attr );
\&  # is the same as
\&  my $h = Sub::HandlesVia::Handler\->new( %attr );
.Ve
.SH ATTRIBUTES
.IX Header "ATTRIBUTES"
.ie n .SS """name"" \fBStr\fP"
.el .SS "\f(CWname\fP \fBStr\fP"
.IX Subsection "name Str"
The name of the function being delegated to.
.ie n .SS """is_mutator"" \fBBool\fP"
.el .SS "\f(CWis_mutator\fP \fBBool\fP"
.IX Subsection "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.
.ie n .SS """template"" \fBStr\fP"
.el .SS "\f(CWtemplate\fP \fBStr\fP"
.IX Subsection "template Str"
Specially formatted string (see section below) containing the Perl code
to implement the method.
.ie n .SS """lvalue_template"" \fBMaybe[Str]\fP"
.el .SS "\f(CWlvalue_template\fP \fBMaybe[Str]\fP"
.IX Subsection "lvalue_template Maybe[Str]"
If defined, a shortcut for implementing it when the attribute slot
value can be used as an lvalue.
.ie n .SS """args"" \fBMaybe[PositiveOrZeroInt]\fP"
.el .SS "\f(CWargs\fP \fBMaybe[PositiveOrZeroInt]\fP"
.IX Subsection "args Maybe[PositiveOrZeroInt]"
The number of arguments which the method being generated expects
(does not include the attibute value itself).
.ie n .SS """min_args"" and ""max_args"" \fBMaybe[PositiveOrZeroInt]\fP"
.el .SS "\f(CWmin_args\fP and \f(CWmax_args\fP \fBMaybe[PositiveOrZeroInt]\fP"
.IX Subsection "min_args and max_args Maybe[PositiveOrZeroInt]"
For methods which take a variable number of arguments. If omitted, default
to \f(CW\*(C`args\*(C'\fR.
.ie n .SS """signature"" \fBMaybe[ArrayRef[TypeTiny]]\fP"
.el .SS "\f(CWsignature\fP \fBMaybe[ArrayRef[TypeTiny]]\fP"
.IX Subsection "signature Maybe[ArrayRef[TypeTiny]]"
A signature for said arguments.
.ie n .SS """usage"" \fBStr\fP"
.el .SS "\f(CWusage\fP \fBStr\fP"
.IX Subsection "usage Str"
A signature to show in documentation, like \f(CW\*(Aq$index, $value\*(Aq\fR.
If not provided, will be generated magically from \f(CW\*(C`args\*(C'\fR, \f(CW\*(C`min_args\*(C'\fR,
and \f(CW\*(C`max_args\*(C'\fR.
.ie n .SS """curried"" \fBMaybe[ArrayRef[Item]]\fP"
.el .SS "\f(CWcurried\fP \fBMaybe[ArrayRef[Item]]\fP"
.IX Subsection "curried Maybe[ArrayRef[Item]]"
An arrayref of curried arguments.
.ie n .SS """is_chainable"" \fBBool\fP"
.el .SS "\f(CWis_chainable\fP \fBBool\fP"
.IX Subsection "is_chainable Bool"
Whether to force the generated method to be chainable.
.ie n .SS """no_validation_needed"" \fBBool\fP"
.el .SS "\f(CWno_validation_needed\fP \fBBool\fP"
.IX Subsection "no_validation_needed Bool"
Whether to do less validation of input data.
.ie n .SS """default_for_reset"" \fBMaybe[Str]\fP"
.el .SS "\f(CWdefault_for_reset\fP \fBMaybe[Str]\fP"
.IX Subsection "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 \f(CW"[]"\fR.
.ie n .SS """prefer_shift_self"" \fBBool\fP"
.el .SS "\f(CWprefer_shift_self\fP \fBBool\fP"
.IX Subsection "prefer_shift_self Bool"
Indicates this handler would prefer the code generator to shift
\&\f(CW$self\fR off \f(CW@_\fR.
.ie n .SS """documentation"" \fBMaybe[Str]\fP"
.el .SS "\f(CWdocumentation\fP \fBMaybe[Str]\fP"
.IX Subsection "documentation Maybe[Str]"
String of pod to describe the handler.
.ie n .SS """_examples"" \fBMaybe[CodeRef]\fP"
.el .SS "\f(CW_examples\fP \fBMaybe[CodeRef]\fP"
.IX Subsection "_examples Maybe[CodeRef]"
This coderef, if called with parameters \f(CW$class\fR, \f(CW$attr\fR, and
\&\f(CW$method\fR, will generate a code example to insert into the pod.
.ie n .SS """additional_validation"" \fBMaybe[CodeRef]\fP"
.el .SS "\f(CWadditional_validation\fP \fBMaybe[CodeRef]\fP"
.IX Subsection "additional_validation Maybe[CodeRef]"
Coderef providing a slightly annoying API. To be described later.
.ie n .SS """allow_getter_shortcuts"" \fBBool\fP"
.el .SS "\f(CWallow_getter_shortcuts\fP \fBBool\fP"
.IX Subsection "allow_getter_shortcuts Bool"
Defaults to true. Rarely useful to override.
.SH METHODS
.IX Header "METHODS"
.ie n .SS "has_min_args() and has_max_args()"
.el .SS "\f(CWhas_min_args()\fP and \f(CWhas_max_args()\fP"
.IX Subsection "has_min_args() and has_max_args()"
Indicate whether this handler has a defined min or max args.
.ie n .SS "install_method( %args )"
.el .SS "\f(CWinstall_method( %args )\fP"
.IX Subsection "install_method( %args )"
The required arguments are \f(CW\*(C`method_name\*(C'\fR and \f(CW\*(C`code_generator\*(C'\fR.
Installs the delegated method into the target class (taken from
the code generator).
.ie n .SS "code_as_string( %args )"
.el .SS "\f(CWcode_as_string( %args )\fP"
.IX Subsection "code_as_string( %args )"
Same required arguments as \f(CW\*(C`install_method\*(C'\fR, but returns the Perl
code for the method as a string.
.ie n .SS "curry( @args )"
.el .SS "\f(CWcurry( @args )\fP"
.IX Subsection "curry( @args )"
Pseudo-constructor.
.PP
Creates a new Sub::HandlesVia::Handler object like this one, but
with the given arguments curried.
.ie n .SS """loose"""
.el .SS \f(CWloose\fP
.IX Subsection "loose"
Pseudo-constructor.
.PP
Creates a new Sub::HandlesVia::Handler object like this one, but
with looser argument validation.
.ie n .SS """chainable"""
.el .SS \f(CWchainable\fP
.IX Subsection "chainable"
Pseudo-constructor.
.PP
Creates a new Sub::HandlesVia::Handler object like this one, but
chainable.
.SH "TEMPLATE FORMAT"
.IX Header "TEMPLATE FORMAT"
The template is a string of Perl code, except if the following special
things are found in it, they are substituted.
.ie n .IP $SELF 4
.el .IP \f(CW$SELF\fR 4
.IX Item "$SELF"
The invocant.
.ie n .IP $SLOT 4
.el .IP \f(CW$SLOT\fR 4
.IX Item "$SLOT"
Direct hashref access for the attribute.
.ie n .IP $GET 4
.el .IP \f(CW$GET\fR 4
.IX Item "$GET"
The current value of the attribute.
.ie n .IP @ARG 4
.el .IP \f(CW@ARG\fR 4
.IX Item "@ARG"
Any additional arguments passed to the delegated method.
.Sp
\&\f(CW$ARG[$n]\fR will also work.
.ie n .IP """#ARG""" 4
.el .IP \f(CW#ARG\fR 4
.IX Item "#ARG"
The number of additional arguments passed to the delegated method.
.ie n .IP $ARG 4
.el .IP \f(CW$ARG\fR 4
.IX Item "$ARG"
The first element in \f(CW@ARG\fR.
.ie n .IP $DEFAULT 4
.el .IP \f(CW$DEFAULT\fR 4
.IX Item "$DEFAULT"
The attribute's default value, if known.
.ie n .IP """« EXPR »""" 4
.el .IP "\f(CW« EXPR »\fR" 4
.IX Item "« EXPR »"
An expression in double angled quotes sets the attribute's value to the
expression.
.PP
For example, a handler to halve the value of a numeric attribute might be:
.PP
.Vb 6
\&  \*(AqSub::HandlesVia::Handler\*(Aq\->new(
\&    name => \*(AqMyNumber:halve\*(Aq,
\&    args => 0,
\&    template => \*(Aq« $GET / 2 »\*(Aq,
\&    lvalue_template => \*(Aq$GET /= 2\*(Aq,
\&  );
.Ve
.SH SUBCLASSES
.IX Header "SUBCLASSES"
Sub::HandlesVia::Handler::Traditional and Sub::HandlesVia::Handler::CodeRef
are provided. See source code for this module for more info.
.SH BUGS
.IX Header "BUGS"
Please report any bugs to
<https://github.com/tobyink/p5\-sub\-handlesvia/issues>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Sub::HandlesVia.
.SH AUTHOR
.IX Header "AUTHOR"
Toby Inkster <tobyink@cpan.org>.
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
This software is copyright (c) 2020, 2022 by Toby Inkster.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
.SH "DISCLAIMER OF WARRANTIES"
.IX Header "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.