---
name: "Sub::HandlesVia::Handler"
section: "3pm"
platform: "linux"
package: "perl-sub-handlesvia"
version: "0.053005-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/Sub::HandlesVia::Handler"
---

# Sub::HandlesVia::Handler(3pm)

template for a method that can be delegated to

## 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.