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

       Sub::HandlesVia.

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.