Moose::...:Native(3)

💅 Moose::Meta::Attribute::Native 💅

okay bestie, buckle up, because we're talking about Moose::Meta::Attribute::Native — that's the manual page you just opened, and yes it's from the User Contributed Perl Documentation crew. 🫶

🎀 NAME 🎀

Moose::Meta::Attribute::Native — Delegate to native Perl types

Like, it lets your boring old Perl data structures ~perform~ as if they were fancy objects. iconic behaviour honestly. 👑

---

✨ VERSION ✨

version 2.4000

---

🌸 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 let you delegate to native Perl data structures like they're literally objects. no cap. look at that SYNOPSIS up there — you got a hash reference out here living its best life, acting like it has methods named exists(), keys(), get(), and set(). the way that a plain hashref just woke up and chose method dispatch. 😭✨

The delegation methods (mostly) map straight onto Perl builtins and operators. The return values of these delegations should be the same as the corresponding Perl operation. And if anything deviates from that? It'll be explicitly documented, fr fr. 📝

---

🌈 API 🌈

Native delegations get switched on by passing certain options to has when you're creating an attribute. let's go option by option, bestie.

🦋 traits

To enable this feature, pass the appropriate name in the traits array reference for the attribute. So like, to enable it for a hash reference, we include 'Hash' in the list of traits. easy peasy. 💁

🦋 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. type check first, vibes second. 🎯

🦋 handles

This is just like any other delegation, BUT — and this is the plot twist — 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.

---

🔥 TRAITS FOR NATIVE DELEGATIONS 🔥

Below are some simple examples of each native trait. Heads up though: more features are available than what is shown here — this is just a quick synopsis. so don't come for me when you find out there's more. 🙈

⭐ Array (Moose::Meta::Attribute::Native::Trait::Array)

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

⭐ Bool (Moose::Meta::Attribute::Native::Trait::Bool)

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

⭐ Code (Moose::Meta::Attribute::Native::Trait::Code)

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

⭐ Counter (Moose::Meta::Attribute::Native::Trait::Counter)

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

⭐ Hash (Moose::Meta::Attribute::Native::Trait::Hash)

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

⭐ Number (Moose::Meta::Attribute::Native::Trait::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 (Moose::Meta::Attribute::Native::Trait::String)

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

---

🧚 COMPATIBILITY WITH MooseX::AttributeHelpers 🧚

So this whole feature used to be its own separate CPAN distribution called MooseX::AttributeHelpers. glow-up arc. ✨

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. so like… same energy, slightly different outfit. 💃

---

💀 BUGS 💀

See "BUGS" in Moose for details on reporting bugs. (yes that's the whole section. go report your bugs bestie, we're rooting for you 🫶)

---

👑 AUTHORS 👑

• Stevan Little <stevan@cpan.org>
• Dave Rolsky <autarch@urth.org>
• Jesse Luehrs <doy@cpan.org>
• Shawn M Moore <sartak@cpan.org>
• יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
• Karen Etheridge <ether@cpan.org>
• Florian Ragwitz <rafl@debian.org>
• Hans Dieter Pearcey <hdp@cpan.org>
• Chris Prather <chris@prather.org>
• Matt S Trout <mstrout@cpan.org>

---

💜 COPYRIGHT AND LICENSE 💜

This software is copyright (c) 2006 by Infinity Interactive, Inc.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. slay, free software, we love to see it. 🍓

---

and that's the whole page bestie!! this was Moose::...:Native(3) from perl v5.42.0, dated 2025-07-25 — written by the User Contributed Perl Documentation girlies, and honestly? ate. no crumbs. 💅✨ mwah, go forth and delegate 🦋