Sub::Ha...Handler(3)

📦
version 0.053005 · 8 versions
, in fedora 44

💖 NAME 💖

ok so Sub::HandlesVia::Handler — it's the template for a method that can be delegated to. bestie, it's giving blueprint energy.

✨ DESCRIPTION ✨

okay so real talk: this module is part of Sub::HandlesVia's internal API. it's mostly of interest to people extending Sub::HandlesVia, so if you're just vibing with the normal public stuff, this is very much iykyk territory 🫶.

here's the tea: this module works in conjunction with Sub::HandlesVia::CodeGenerator and subclasses of Sub::HandlesVia::Toolkit to build a string of Perl code — and that string can then be compiled into a method to install into your class. like, it literally writes the method for you. main character energy fr 💅.

🎀 CONSTRUCTORS 🎀

new( %attributes )

Standard Moose-like constructor. no notes, iconic, we love a classic ✨.

"lookup( $method, $trait )"

Looks up a method from existing handler libraries. it's giving shopping for a method you didn't write yourself 🛍️.

my $h = Sub::HandlesVia::Handler->lookup( 'get', 'Array' );

Curried version (yes she's flexible):

my $h = Sub::HandlesVia::Handler->lookup( [ 'get', 0 ], 'Array' );

and heads up: the $trait may be an arrayref of possible traits. options, options, we love options 💖.

🌸 EXPORTS 🌸

Nothing is exported by default. sorry bestie, no freebies, you gotta ask 😌.

"handler %attributes"

Shortcut for the new constructor. same thing, shorter vibes:

use Sub::HandlesVia::Handler 'handler';

my $h = handler( %attr );
# is the same as
my $h = Sub::HandlesVia::Handler->new( %attr );

literally identical, periodt.

🦋 ATTRIBUTES 🦋

"name" Str

The name of the function being delegated to. that's her name, that's her whole identity 💅.

"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 — so she sniffs it out herself unless you tell her otherwise 🔍.

"template" Str

Specially formatted string (peep the section below 👀) containing the Perl code to implement the method. this is where the magic actually lives.

"lvalue_template" Maybe[Str]

If defined, a shortcut for implementing it when the attribute slot value can be used as an lvalue. fancy ✨.

"args" Maybe[PositiveOrZeroInt]

The number of arguments which the method being generated expects. note: this 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, they default to args. so if you skip them, they just copy args's whole look, iconic 💖.

"signature" Maybe[ArrayRef[TypeTiny]]

A signature for said arguments.

"usage" Str

A signature to show in documentation, like '$index, $value'. if not provided, it will be generated magically from args, min_args, and max_args. ✨ magic ✨ (the good kind).

"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. living dangerously, love that for you 🫣.

"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 "[]". so like, a little emergency backup default, no cap.

"prefer_shift_self" Bool

Indicates this handler would prefer the code generator to shift $self off @_. tiny preference, big impact.

"documentation" Maybe[Str]

String of pod to describe the handler. give her some lore 📖.

"_examples" Maybe[CodeRef]

This coderef, if called with parameters $class, $attr, and $method, will generate a code example to insert into the pod. auto-generated examples, we love a self-documenting queen 👑.

"additional_validation" Maybe[CodeRef]

Coderef providing a slightly annoying API. To be described later. (not me calling my own API annoying 😭 iconic honesty tho.)

"allow_getter_shortcuts" Bool

Defaults to true. Rarely useful to override. like, leave it alone bestie, she's fine as she is 🌸.

💜 METHODS 💜

has_min_args() and has_max_args()

Indicate whether this handler has a defined min or max args. simple yes/no energy.

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). it's giving move-in day 📦.

code_as_string( %args )

Same required arguments as "install_method", but returns the Perl code for the method as a string. so you can look at it, save it, frame it, whatever 🖼️.

curry( @args )

Pseudo-constructor.

Creates a new Sub::HandlesVia::Handler object like this one, but with the given arguments curried. same girl, new seasoning 🍛.

"loose"

Pseudo-constructor.

Creates a new Sub::HandlesVia::Handler object like this one, but with looser argument validation. she's off duty, she's in sweatpants 😌.

"chainable"

Pseudo-constructor.

Creates a new Sub::HandlesVia::Handler object like this one, but chainable. and then and then and then — 💅.

🌈 TEMPLATE FORMAT 🌈

The template is a string of Perl code — except if the following special things are found in it, they are substituted. so it's Perl code but with little sparkle placeholders ✨:

  • $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',
);

see? she just does the math. ate and left no crumbs 🔥.

🧚 SUBCLASSES 🧚

Sub::HandlesVia::Handler::Traditional and Sub::HandlesVia::Handler::CodeRef are provided. See source code for this module for more info. (go read the source, bestie, it's right there 📚.)

💀 BUGS 💀

Please report any bugs to <https://github.com/tobyink/p5-sub-handlesvia/issues>. don't suffer in silence, tell Toby 🙈.

⭐ SEE ALSO ⭐

Sub::HandlesVia.

👑 AUTHOR 👑

Toby Inkster <tobyink@cpan.org>.

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. free as in slay 💖.

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

(translation: no promises bestie, she's doing her best 😭)

okay that's the whole page!! this was Sub::HandlesVia::Handler(3), part of the User Contributed Perl Documentation, and it shipped with perl v5.42.0 dated 2026-02-11. thanks for reading my little yap session, go build something cute with it 🫶💖✨

📦 where this page comes from