Docs tentatively finished.

[gitmo/MooseX-AttributeHelpers.git] / lib / MooseX / AttributeHelpers / MethodProvider / Collection / ImmutableHash.pm

package MooseX::AttributeHelpers::MethodProvider::Collection::ImmutableHash;
use MooseX::AttributeHelpers::MethodProvider;

our $VERSION   = '0.03';
our $AUTHORITY = 'cpan:STEVAN';

add_method_provider 'Collection::ImmutableHash' => (
    type => 'HashRef',
    provides => {
        exists => sub {
            my ($attr, $reader, $writer) = @_;
            return sub { CORE::exists $reader->($_[0])->{$_[1]} };
        },

        get => sub {
            my ($attr, $reader, $writer) = @_;
            return sub {
                my ($self, @keys) = @_;
                @{ $reader->($self) }{@keys}
            };
        },

        keys => sub {
            my ($attr, $reader, $writer) = @_;
            return sub { CORE::keys %{$reader->($_[0])} };
        },

        values => sub {
            my ($attr, $reader, $writer) = @_;
            return sub { CORE::values %{$reader->($_[0])} };
        },

        kv => sub {
            my ($attr, $reader, $writer) = @_;
            return sub {
                my $h = $reader->($_[0]);
                map {
                    [ $_, $h->{$_} ]
                } CORE::keys %{$h}
            };
        },

        count => sub {
            my ($attr, $reader, $writer) = @_;
            return sub { scalar CORE::keys %{$reader->($_[0])} };
        },

        # Deprecated.  Does the opposite of what it claims to.
        empty => sub {
            my ($attr, $reader, $writer) = @_;
            return sub { scalar CORE::keys %{$reader->($_[0])} ? 1 : 0 };
        },

        is_empty => sub {
            my ($attr, $reader, $writer) = @_;
            return sub { CORE::keys %{$reader->($_[0])} == 0 };
        },

        has_items => sub {
            my ($attr, $reader, $writer) = @_;
            return sub { CORE::keys %{$reader->($_[0])} > 0 };
        },
    },
);

1;

__END__

=pod

=head1 NAME

MooseX::AttributeHelpers::MethodProvider::ImmutableHash

=head1 DESCRIPTION

This module provides the method factories for
L<MooseX::AttributeHelpers::Collection::ImmutableHash>.

=head1 PROVIDED METHODS

=over 4

=item B<count>

Returns the number of items in the hash.

=item B<empty>

DEPRECATED.  This was a misleading name for what it does (returns a boolean
indicating whether the hash is NOT empty), but we're keeping it for backwards
compatibility.  Do not use it in new code.  Use is_empty or has_items instead,
depending on what you meant.

=item B<is_empty>

Returns a boolean which is true if and only if the hash has no items in it.

=item B<has_items>

Returns a boolean which is true if and only if the hash has at least one item.

=item B<exists>

L<perlfunc/exists>

=item B<get(@keys)>

Gets the values specified by @keys from the hash.

=item B<keys>

L<perlfunc/keys>

=item B<values>

L<perlfunc/values>

=item B<kv>

Returns a list of arrayrefs, each of which is a key => value pair mapping.

=back

=head1 BUGS

All complex software has bugs lurking in it, and this module is no
exception. If you find a bug please either email me, or add the bug
to cpan-RT.

=head1 AUTHOR

Stevan Little E<lt>stevan@iinteractive.comE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright 2007-2008 by Infinity Interactive, Inc.

L<http://www.iinteractive.com>

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

=cut