NAME

       MooX::BuildArgsHooks - Structured BUILDARGS.

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

DESCRIPTION

       This module installs some hooks directly into Moo which allow for more fine-grained access
       to the phases of "BUILDARGS".  The reason this is important is because if you have various
       roles and classes modifying BUILDARGS you will often end up with weird behaviors depending
       on what order the various BUILDARGS wrappers are applied in.  By breaking up argument
       processing into three steps (normalize, transform, and finalize) these conflicts are much
       less likely to arise.

       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.

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.

   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.

   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.  By the
       time this hook is called the arguments will always be in hashref form, not a list, and a
       hashref must be returned.

   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.

SEE ALSO

       •   MooX::BuildArgs

       •   MooX::MethodProxyArgs

       •   MooX::Rebuild

       •   MooX::SingleArg

SUPPORT

       See "SUPPORT" in MooX::BuildArgs.

AUTHORS

       See "AUTHORS" in MooX::BuildArgs.

LICENSE

       See "LICENSE" in MooX::BuildArgs.