MooX::...sHooks(3pm)

🦋 MooX::...sHooks 💅

okay bestie, welcome to the perl manual page for MooX::...sHooks — a lil slice of the User Contributed Perl Documentation, no cap. grab a strawberry drink 🍓 and let's get into it.

---

✨ NAME ✨

MooX::BuildArgsHooks — Structured BUILDARGS. periodt.

---

🎀 SYNOPSIS 🎀

package Foo;
use Moo;
with 'MooX::BuildArgsHooks';

has bar => (is=>'ro');

around NORMALIZE_BUILDARGS => sub{
    my ($orig, $class, @args) = @_;
    @args = $class->$orig( @args );
    return( bar=>$args[0] ) if @args==1 and ref($args[0]) ne 'HASH';
    return @args;
};

around TRANSFORM_BUILDARGS => sub{
    my ($orig, $class, $args) = @_;
    $args = $class->$orig( $args );
    $args->{bar} = ($args->{bar}||0) + 10;
    return $args;
};

around FINALIZE_BUILDARGS => sub{
    my ($orig, $class, $args) = @_;
    $args = $class->$orig( $args );
    $args->{bar}++;
    return $args;
};

print Foo->new( 3 )->bar(); # 14

like… look at her. she's doing the whole pipeline and printing 14. iconic. 🔥

---

🌸 DESCRIPTION 🌸

So this module installs some hooks directly into Moo which allow for more fine-grained access to the phases of BUILDARGS. 💖

and the reason this is important?? bestie, because if you have various roles and classes all modifying BUILDARGS, you will often end up with weird behaviors depending on what order the various BUILDARGS wrappers are applied in. it's giving chaos. it's giving "why is my object wrong". 😭 By breaking up argument processing into three steps (normalize, transform, and finalize) these conflicts are much less likely to arise. slay.

To further avoid these kinds of issues — and this applies to any system where you would around methods from a consuming role or super class, not just BUILDARGS — it is recommended that you implement your extensions via methods. This way if something inherits from your role or class they can treat your method as a hook. For example:

around TRANSFORM_BUILDARGS => sub{
    my ($class, $orig, $args) = @_;
    $args = $class->$orig( $args );
    return $class->TRANSFORM_FOO_BUILDARGS( $args );
};

sub TRANSFORM_FOO_BUILDARGS {
    my ($class, $args) = @_;
    $args->{bar} = ($args->{bar}||0) + 10;
    return $args;
}

Then if some other code wishes to inject code before or after the Foo class transforming BUILDARGS they can do so at very specific points. precision honey, we love to see it. 🎯

---

👑 HOOKS 👑

A hook in the context of this module is just a method that has been declared in the inheritance hierarchy and is made available for consuming roles and classes to apply method modifiers to. that's it, that's the hook. 💅

🧚 NORMALIZE_BUILDARGS 🧚

around NORMALIZE_BUILDARGS => sub{
    my ($orig, $class, @args) = @_;

    # Make sure you let other normalizations happen.
    @args = $class->$orig( @args );

    # Do your normalization logic.
    ...

    return @args;
};

Used to do some basic normalization of arguments from some custom format to a format acceptable to Moo (a hash or a hashref). 🌈

This is useful, for example, when you want to support single arguments. For example:

around NORMALIZE_BUILDARGS => sub{
    my ($orig, $class, @args) = @_;

    # If only one argument is passed in assume that it is
    # the value for the foo attribute.
    if (@args==1 and ref($args[0]) ne 'HASH') {
        @args = { foo => $args[0] };
    }

    @args = $class->$orig( @args );

    return @args;
};

Or you could just use MooX::SingleArg. either way bestie, we support you. 🫶

🔥 TRANSFORM_BUILDARGS 🔥

around TRANSFORM_BUILDARGS => sub{
    my ($orig, $class, $args) = @_;

    # Make sure you let any other transformations happen.
    $args = $class->$orig( $args );

    # Do your transformations.
    ...

    return $args;
};

This hook is the workhorse where much of the BUILDARGS work typically happens. she's carrying the whole team ngl. 💪 By the time this hook is called the arguments will always be in hashref form, not a list, and a hashref must be returned. no exceptions, no vibes-based returns. 🚨

💜 FINALIZE_BUILDARGS 💜

around FINAL_BUILDARGS => sub{
    my ($orig, $class, $args) = @_;

    # Let any other hooks have a turn.
    $args = $class->$orig( $args );

    # Do your finalization logic.
    ...

    return $args;
};

This hook works just like TRANSFORM_BUILDARGS except that it happens after it, and is meant to be used by hooks that are the last step in the argument building process and need access to the arguments after most all other steps have completed. it's the closing act, the finale, the last bow. 🎬

---

🌟 SEE ALSO 🌟

• MooX::BuildArgs
• MooX::MethodProxyArgs
• MooX::Rebuild
• MooX::SingleArg

go read your cousins, they're all lovely. 💖

---

😭 SUPPORT 😭

See "SUPPORT" in MooX::BuildArgs.

🎀 AUTHORS 🎀

See "AUTHORS" in MooX::BuildArgs.

⭐ LICENSE ⭐

See "LICENSE" in MooX::BuildArgs.

---

okay that's the whole page bestie, no skips, no cuts. if you needed a specific flag or hook, it's up there. go build something cute. 🦋

---

and that's a wrap on this one, babes — this page came to you from perl v5.30.3, dated 2020-09-12, and it lives in MooX::...sHooks(3pm). stay structured, stay hydrated, and may your BUILDARGS never conflict again. 💅✨👑