Moose::Meta::Attribute::Native(3p)

NAME
Moose::Meta::Attribute::Native - Delegate to native Perl types

SYNOPSIS
  package MyClass;
  use Moose;

  has 'mapping' => (
      traits  => ['Hash'],
      is      => 'rw',
      isa     => 'HashRef[Str]',
      default => sub { {} },
      handles => {
          exists_in_mapping => 'exists',
          ids_in_mapping    => 'keys',
          get_mapping       => 'get',
          set_mapping       => 'set',
          set_quantity      => [ set => 'quantity' ],
      },
  );

  my $obj = MyClass->new;
  $obj->set_quantity(10);      # quantity => 10
  $obj->set_mapping('foo', 4); # foo => 4
  $obj->set_mapping('bar', 5); # bar => 5
  $obj->set_mapping('baz', 6); # baz => 6

  # prints 5
  print $obj->get_mapping('bar') if $obj->exists_in_mapping('bar');

  # prints 'quantity, foo, bar, baz'
  print join ', ', $obj->ids_in_mapping;

DESCRIPTION
Native delegations allow you to delegate to native Perl data structures as if they were objects. For example, in the "SYNOPSIS" you can see a hash reference being treated as if it has methods named "exists()", "keys()", "get()", and "set()".

The delegation methods (mostly) map to Perl builtins and operators. The return values of these delegations should be the same as the corresponding Perl operation. Any deviations will be explicitly documented.

API
Native delegations are enabled by passing certain options to "has" when creating an attribute.

  traits
To enable this feature, pass the appropriate name in the "traits" array reference for the attribute. For example, to enable this feature for hash reference, we include 'Hash' in the list of traits.

  isa
You will need to make sure that the attribute has an appropriate type. For example, to use this with a Hash you must specify that your attribute is some sort of "HashRef".

If you don't specify a type, each trait has a default type it will use.

  handles
This is just like any other delegation, but only a hash reference is allowed when defining native delegations. The keys are the methods to be created in the class which contains the attribute. The values are the methods provided by the associated trait. Currying works the same way as it does with any other delegation.

See the docs for each native trait for details on what methods are available.

  is
Some traits provide a default "is" for historical reasons. This behavior is deprecated, and you are strongly encouraged to provide a value. If you don't plan to read and write the attribute value directly, you can set "is => 'bare'" to prevent standard accessor generation.

  default or builder
Some traits provide a default "default" for historical reasons. This behavior is deprecated, and you are strongly encouraged to provide a default value or make the attribute required.

TRAITS FOR NATIVE DELEGATIONS

Array
        has 'queue' => (
            traits  => ['Array'],
            is      => 'ro',
            isa     => 'ArrayRef[Str]',
            default => sub { [] },
            handles => {
                add_item  => 'push',
                next_item => 'shift',
                # ...
            }
        );

Bool
        has 'is_lit' => (
            traits  => ['Bool'],
            is      => 'ro',
            isa     => 'Bool',
            default => 0,
            handles => {
                illuminate  => 'set',
                darken      => 'unset',
                flip_switch => 'toggle',
                is_dark     => 'not',
                # ...
            }
        );

Code
        has 'callback' => (
            traits  => ['Code'],
            is      => 'ro',
            isa     => 'CodeRef',
            default => sub {
                sub {'called'}
            },
            handles => {
                call => 'execute',
                # ...
            }
        );

Counter
        has 'counter' => (
            traits  => ['Counter'],
            is      => 'ro',
            isa     => 'Num',
            default => 0,
            handles => {
                inc_counter   => 'inc',
                dec_counter   => 'dec',
                reset_counter => 'reset',
                # ...
            }
        );

Hash
        has 'options' => (
            traits  => ['Hash'],
            is      => 'ro',
            isa     => 'HashRef[Str]',
            default => sub { {} },
            handles => {
                set_option => 'set',
                get_option => 'get',
                has_option => 'exists',
                # ...
            }
        );

Number
        has 'integer' => (
            traits  => ['Number'],
            is      => 'ro',
            isa     => 'Int',
            default => 5,
            handles => {
                set => 'set',
                add => 'add',
                sub => 'sub',
                mul => 'mul',
                div => 'div',
                mod => 'mod',
                abs => 'abs',
                # ...
            }
        );

String
        has 'text' => (
            traits  => ['String'],
            is      => 'ro',
            isa     => 'Str',
            default => q{},
            handles => {
                add_text     => 'append',
                replace_text => 'replace',
                # ...
            }
        );

COMPATIBILITY WITH MooseX::AttributeHelpers
This feature used to be a separated CPAN distribution called MooseX::AttributeHelpers.

When the feature was incorporated into the Moose core, some of the API details were changed. The underlying capabilities are the same, but some details of the API were changed.

BUGS
See "BUGS" in Moose for details on reporting bugs.

AUTHOR
Stevan Little <stevan@iinteractive.com>

with contributions from:

Robert (rlb3) Boone

Paul (frodwith) Driver

Shawn (Sartak) Moore

Chris (perigrin) Prather

Robert (phaylon) Sedlacek

Tom (dec) Lanyon

Yuval Kogman

Jason May

Cory (gphat) Watson

Florian (rafl) Ragwitz

Evan Carroll

Jesse (doy) Luehrs

Jay Hannah

Robert Buels

COPYRIGHT AND LICENSE
Copyright 2007-2010 by Infinity Interactive, Inc.

<http://www.iinteractive.com>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.