NAME

Trait::Attribute::Derived - trait for lazy-built Moose attributes that are derived from another attribute

SYNOPSIS

use strict;
use warnings;
use Test::More;

{
   package Person;   
   use Moose;
   
   use Trait::Attribute::Derived Split => {
      fields    => { segment => 'Num' },
      processor => sub { (split)[$_{segment}] },
   };
   
   has full_name => (
      is            => 'ro',
      isa           => 'Str',
      required      => 1,
   );
   has first_name => (
      traits        => [ Split ],
      source        => 'full_name',
      segment       => 0,
   );
   has last_name => (
      traits       => [ Split ],
      source        => 'full_name',
      segment      => -1,
   );
   has initial => (
      traits        => [ Split ],
      source        => 'full_name',
      segment       => 0,
      postprocessor => sub { substr $_, 0, 1 },
   );
}

my $bob = Person->new(full_name => 'Robert Redford');
is($bob->first_name, 'Robert');
is($bob->initial, 'R');
is($bob->last_name, 'Redford');
done_testing;

DESCRIPTION

It is quite common in Moose to have one attribute derived from another via lazy builders. Often you will have several which are very similar:

has first_name => (
   is           => 'ro',
   lazy         => 1,
   builder      => '_build_first_name',
);

sub _build_first_name {
   my $self = shift;
   (split /\s/, $self->full_name)[0];
}

has last_name => (
   is           => 'ro',
   lazy         => 1,
   builder      => '_build_last_name',
);

sub _build_last_name {
   my $self = shift;
   (split /\s/, $self->full_name)[-1];
}

Other examples might be an attribute holding an XML DOM tree where several attributes are lazily built using XPath queries; or an attribute holding a DBI database handle where several attribues are lazily built by querying the database; or where one attribute holds the binary contents of a file, and others are fields extracted using unpack.

Trait::Attribute::Derived allows you to automate some of this, reducing duplicated code.

Trait::Attribute::Derived is a trait for Moose attributes; it a parameterized role. The first step when using it is to create a variant of the role with the parameters filled in.

use Trait::Attribute::Derived Split => {
   fields    => { segment => 'Num' },
   processor => sub { (split)[$_{segment}] },
};

This defines a variant called Split. The processor coderef is the template for deriving a lazily built attribute from a source attribute. Within this coderef, the special global $_ is set to the value of the source attribute, and the special global %_ hash contains a set of other fields useful in deriving the lazily built attributes.

Using our example from the SYNOPSIS, $_ will be the string "Robert Redford" and %_ will be a hash (segment => 0) when building the first_name or (segment => -1) when building the last_name.

If you'd rather not use magic global variables, the coderef is also passed as arguments (@_): $self, the source attribute value, and a refernce to that hash.

The fields hashref defines which fields will be available in %_ plus a type constraint for each.

Then when we define the attribute itself:

has first_name => (
   traits        => [ Split ],
   source        => 'full_name',
   segment       => 0,
);

First of all we reference the Split trait variant; secondly we tell it what source attribute to derive the first name from (full_name); lastly we tell it what segment of the name we want. This corresponds to the segment field we defined when creating the trait variant.

Here's another example:

{
   package Text;
   use Moose;
   
   use Trait::Attribute::Derived FindReplace => {
      fields => {
         find    => 'RegexpRef',
         replace => 'Str',
      },
      processor => sub {
         my ($self, $value, $fields) = @_;
         $value =~ s/$fields->{find}/$fields->{replace}/g;
         return $value;
      },
   };
   
   has plain => (
      is       => 'ro',
      isa      => 'Str',
   );
   has vowels_only => (
      traits   => [ FindReplace ],
      source   => 'plain',
      find     => qr{[^AEIOU]}i,
      replace  => '',
   );
   has no_vowels  => (
      traits   => [ FindReplace ],
      source   => 'plain',
      find     => qr{[AEIOU]}i,
      replace  => '',
   );
}

An alternative to setting source on each derived attribute is to set it once when creating the trait variant:

use Trait::Attribute::Derived FindReplace => {
   source    => 'plain',
   fields    => { ... },
   processor => sub { ... },
};

One last detail from the SYNOPSIS is postprocessing. An attribute can define a postprocessor coderef that executes after the processor coderef. This takes the same parameters as the processor coderef (and has access to $_ and %_) but rather than operating on the source attribute, operates on the output of the processor.

has first_three_vowels_only => (
   traits   => [ FindReplace ],
   source   => 'plain',
   find     => qr{[^AEIOU]}i,
   replace  => '',
   postprocessor => sub { substr($_, 0, 3) },
);

Introspection

use 5.010;

# say "full_name"
say Person->meta->get_attribute('first_name')->derived_from;

# say "0"
say Person->meta->get_attribute('first_name')->segment;

# say "1"
say Person->meta->get_attribute('initial')->has_postprocessor;

BUGS

Please report any bugs to http://rt.cpan.org/Dist/Display.html?Queue=Trait-Attribute-Derived.

SEE ALSO

Moose::Cookbook::Meta::WhyMeta, Moose::Cookbook::Meta::Labeled_AttributeTrait, Moose::Meta::Attribute.

AUTHOR

Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

This software is copyright (c) 2013 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.

cpanm Trait::Attribute::Derived

perl -MCPAN -e shell
install Trait::Attribute::Derived