diff options
Diffstat (limited to 'lib/Data/MultiValued/Tags.pm')
-rw-r--r-- | lib/Data/MultiValued/Tags.pm | 67 |
1 files changed, 66 insertions, 1 deletions
diff --git a/lib/Data/MultiValued/Tags.pm b/lib/Data/MultiValued/Tags.pm index fbf7948..083bbb8 100644 --- a/lib/Data/MultiValued/Tags.pm +++ b/lib/Data/MultiValued/Tags.pm @@ -6,7 +6,23 @@ use MooseX::Types::Moose qw(Num Str Undef Any); use Data::MultiValued::Exceptions; use Data::MultiValued::TagContainer; -# ABSTRACT: Handle values with tags and validity ranges +# ABSTRACT: Handle values with tags + +=head1 SYNOPSIS + + use Data::MultiValued::Tags; + + my $obj = Data::MultiValued::Tags->new(); + $obj->set({ + tag => 'tag1', + value => 'a string', + }); + say $obj->get({tag=>'tag1'}); # prints 'a string' + say $obj->get({tag=>'tag2'}); # dies + +=head1 METHODS + +=cut has _storage => ( is => 'rw', @@ -32,6 +48,21 @@ sub _as_hash { return {_storage=>\%ret}; } +=head2 C<set> + + $obj->set({ tag => $the_tag, value => $the_value }); + +Stores the given value for the given tag. Replaces existing +values. Does not throw exceptions. + +Not passing in a C<tag> is equivalent to passing in C<< tag => undef +>>. + +No cloning is done: if you pass in a reference, the reference is +just stored. + +=cut + sub set { my ($self,%args) = validated_hash( \@_, @@ -43,6 +74,22 @@ sub set { ->{value} = $args{value}; } +=head2 C<get> + + my $value = $obj->get({ tag => $the_tag }); + +Retrieves the value for the given tag. Throws a +L<Data::MultiValued::Exceptions::TagNotFound> exception if the tag +does not exists in this object. + +Not passing in a C<tag> is equivalent to passing in C<< tag => undef +>>. + +No cloning is done: if a reference was stored, you get it back +untouched. + +=cut + sub get { my ($self,%args) = validated_hash( \@_, @@ -53,6 +100,18 @@ sub get { ->{value}; } +=head2 C<clear> + + $obj->clear({ tag => $the_tag }); + +Deletes the given tag and all data associated with it. Does not throw +exceptions: if the tag does not exist, nothing happens. + +Not passing in a C<tag> clears everything. Yes, this means that there +is no way to just clear the value for the C<undef> tag. + +=cut + sub clear { my ($self,%args) = validated_hash( \@_, @@ -62,4 +121,10 @@ sub clear { $self->_storage->clear(\%args); } +=head1 SEE ALSO + +L<Data::MultiValued::TagContainer>, L<Data::MultiValued::Exceptions> + +=cut + 1; |