.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Moose::Meta::Attribute::Native 3"
.TH Moose::Meta::Attribute::Native 3 "2021-11-07" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Moose::Meta::Attribute::Native \- Delegate to native Perl types
.SH "VERSION"
.IX Header "VERSION"
version 2.2201
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  package MyClass;
\&  use Moose;
\&
\&  has \*(Aqmapping\*(Aq => (
\&      traits  => [\*(AqHash\*(Aq],
\&      is      => \*(Aqrw\*(Aq,
\&      isa     => \*(AqHashRef[Str]\*(Aq,
\&      default => sub { {} },
\&      handles => {
\&          exists_in_mapping => \*(Aqexists\*(Aq,
\&          ids_in_mapping    => \*(Aqkeys\*(Aq,
\&          get_mapping       => \*(Aqget\*(Aq,
\&          set_mapping       => \*(Aqset\*(Aq,
\&          set_quantity      => [ set => \*(Aqquantity\*(Aq ],
\&      },
\&  );
\&
\&  my $obj = MyClass\->new;
\&  $obj\->set_quantity(10);      # quantity => 10
\&  $obj\->set_mapping(\*(Aqfoo\*(Aq, 4); # foo => 4
\&  $obj\->set_mapping(\*(Aqbar\*(Aq, 5); # bar => 5
\&  $obj\->set_mapping(\*(Aqbaz\*(Aq, 6); # baz => 6
\&
\&  # prints 5
\&  print $obj\->get_mapping(\*(Aqbar\*(Aq) if $obj\->exists_in_mapping(\*(Aqbar\*(Aq);
\&
\&  # prints \*(Aqquantity, foo, bar, baz\*(Aq
\&  print join \*(Aq, \*(Aq, $obj\->ids_in_mapping;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Native delegations allow you to delegate to native Perl data
structures as if they were objects. For example, in the \*(L"\s-1SYNOPSIS\*(R"\s0 you can
see a hash reference being treated as if it has methods named \f(CW\*(C`exists()\*(C'\fR,
\&\f(CW\*(C`keys()\*(C'\fR, \f(CW\*(C`get()\*(C'\fR, and \f(CW\*(C`set()\*(C'\fR.
.PP
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.
.SH "API"
.IX Header "API"
Native delegations are enabled by passing certain options to \f(CW\*(C`has\*(C'\fR when
creating an attribute.
.SS "traits"
.IX Subsection "traits"
To enable this feature, pass the appropriate name in the \f(CW\*(C`traits\*(C'\fR array
reference for the attribute. For example, to enable this feature for hash
reference, we include \f(CW\*(AqHash\*(Aq\fR in the list of traits.
.SS "isa"
.IX Subsection "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 \f(CW\*(C`HashRef\*(C'\fR.
.SS "handles"
.IX Subsection "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.
.PP
See the docs for each native trait for details on what methods are available.
.SH "TRAITS FOR NATIVE DELEGATIONS"
.IX Header "TRAITS FOR NATIVE DELEGATIONS"
Below are some simple examples of each native trait. More features are
available than what is shown here; this is just a quick synopsis.
.IP "Array (Moose::Meta::Attribute::Native::Trait::Array)" 4
.IX Item "Array (Moose::Meta::Attribute::Native::Trait::Array)"
.Vb 11
\&    has \*(Aqqueue\*(Aq => (
\&        traits  => [\*(AqArray\*(Aq],
\&        is      => \*(Aqro\*(Aq,
\&        isa     => \*(AqArrayRef[Str]\*(Aq,
\&        default => sub { [] },
\&        handles => {
\&            add_item  => \*(Aqpush\*(Aq,
\&            next_item => \*(Aqshift\*(Aq,
\&            # ...
\&        }
\&    );
.Ve
.IP "Bool (Moose::Meta::Attribute::Native::Trait::Bool)" 4
.IX Item "Bool (Moose::Meta::Attribute::Native::Trait::Bool)"
.Vb 10
\&    has \*(Aqis_lit\*(Aq => (
\&        traits  => [\*(AqBool\*(Aq],
\&        is      => \*(Aqro\*(Aq,
\&        isa     => \*(AqBool\*(Aq,
\&        default => 0,
\&        handles => {
\&            illuminate  => \*(Aqset\*(Aq,
\&            darken      => \*(Aqunset\*(Aq,
\&            flip_switch => \*(Aqtoggle\*(Aq,
\&            is_dark     => \*(Aqnot\*(Aq,
\&            # ...
\&        }
\&    );
.Ve
.IP "Code (Moose::Meta::Attribute::Native::Trait::Code)" 4
.IX Item "Code (Moose::Meta::Attribute::Native::Trait::Code)"
.Vb 12
\&    has \*(Aqcallback\*(Aq => (
\&        traits  => [\*(AqCode\*(Aq],
\&        is      => \*(Aqro\*(Aq,
\&        isa     => \*(AqCodeRef\*(Aq,
\&        default => sub {
\&            sub {\*(Aqcalled\*(Aq}
\&        },
\&        handles => {
\&            call => \*(Aqexecute\*(Aq,
\&            # ...
\&        }
\&    );
.Ve
.IP "Counter (Moose::Meta::Attribute::Native::Trait::Counter)" 4
.IX Item "Counter (Moose::Meta::Attribute::Native::Trait::Counter)"
.Vb 12
\&    has \*(Aqcounter\*(Aq => (
\&        traits  => [\*(AqCounter\*(Aq],
\&        is      => \*(Aqro\*(Aq,
\&        isa     => \*(AqNum\*(Aq,
\&        default => 0,
\&        handles => {
\&            inc_counter   => \*(Aqinc\*(Aq,
\&            dec_counter   => \*(Aqdec\*(Aq,
\&            reset_counter => \*(Aqreset\*(Aq,
\&            # ...
\&        }
\&    );
.Ve
.IP "Hash (Moose::Meta::Attribute::Native::Trait::Hash)" 4
.IX Item "Hash (Moose::Meta::Attribute::Native::Trait::Hash)"
.Vb 12
\&    has \*(Aqoptions\*(Aq => (
\&        traits  => [\*(AqHash\*(Aq],
\&        is      => \*(Aqro\*(Aq,
\&        isa     => \*(AqHashRef[Str]\*(Aq,
\&        default => sub { {} },
\&        handles => {
\&            set_option => \*(Aqset\*(Aq,
\&            get_option => \*(Aqget\*(Aq,
\&            has_option => \*(Aqexists\*(Aq,
\&            # ...
\&        }
\&    );
.Ve
.IP "Number (Moose::Meta::Attribute::Native::Trait::Number)" 4
.IX Item "Number (Moose::Meta::Attribute::Native::Trait::Number)"
.Vb 10
\&    has \*(Aqinteger\*(Aq => (
\&        traits  => [\*(AqNumber\*(Aq],
\&        is      => \*(Aqro\*(Aq,
\&        isa     => \*(AqInt\*(Aq,
\&        default => 5,
\&        handles => {
\&            set => \*(Aqset\*(Aq,
\&            add => \*(Aqadd\*(Aq,
\&            sub => \*(Aqsub\*(Aq,
\&            mul => \*(Aqmul\*(Aq,
\&            div => \*(Aqdiv\*(Aq,
\&            mod => \*(Aqmod\*(Aq,
\&            abs => \*(Aqabs\*(Aq,
\&            # ...
\&        }
\&    );
.Ve
.IP "String (Moose::Meta::Attribute::Native::Trait::String)" 4
.IX Item "String (Moose::Meta::Attribute::Native::Trait::String)"
.Vb 11
\&    has \*(Aqtext\*(Aq => (
\&        traits  => [\*(AqString\*(Aq],
\&        is      => \*(Aqro\*(Aq,
\&        isa     => \*(AqStr\*(Aq,
\&        default => q{},
\&        handles => {
\&            add_text     => \*(Aqappend\*(Aq,
\&            replace_text => \*(Aqreplace\*(Aq,
\&            # ...
\&        }
\&    );
.Ve
.SH "COMPATIBILITY WITH MooseX::AttributeHelpers"
.IX Header "COMPATIBILITY WITH MooseX::AttributeHelpers"
This feature used to be a separated \s-1CPAN\s0 distribution called
MooseX::AttributeHelpers.
.PP
When the feature was incorporated into the Moose core, some of the \s-1API\s0 details
were changed. The underlying capabilities are the same, but some details of
the \s-1API\s0 were changed.
.SH "BUGS"
.IX Header "BUGS"
See \*(L"\s-1BUGS\*(R"\s0 in Moose for details on reporting bugs.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
Stevan Little <stevan@cpan.org>
.IP "\(bu" 4
Dave Rolsky <autarch@urth.org>
.IP "\(bu" 4
Jesse Luehrs <doy@cpan.org>
.IP "\(bu" 4
Shawn M Moore <sartak@cpan.org>
.IP "\(bu" 4
יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
.IP "\(bu" 4
Karen Etheridge <ether@cpan.org>
.IP "\(bu" 4
Florian Ragwitz <rafl@debian.org>
.IP "\(bu" 4
Hans Dieter Pearcey <hdp@cpan.org>
.IP "\(bu" 4
Chris Prather <chris@prather.org>
.IP "\(bu" 4
Matt S Trout <mstrout@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2006 by Infinity Interactive, Inc.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.