From 5dbdfc53752cd050b171f416ea3625b18e4018b8 Mon Sep 17 00:00:00 2001 From: Gianni Ceccarelli Date: Mon, 14 Nov 2011 14:48:16 +0000 Subject: some docs --- dist.ini | 2 + lib/Data/MultiValued.pod | 70 +++++++++++++++++++++++ lib/Data/MultiValued/Ranges.pm | 101 +++++++++++++++++++++++++++++++++- lib/Data/MultiValued/Tags.pm | 67 +++++++++++++++++++++- lib/Data/MultiValued/TagsAndRanges.pm | 60 ++++++++++++++++++++ 5 files changed, 298 insertions(+), 2 deletions(-) create mode 100644 lib/Data/MultiValued.pod diff --git a/dist.ini b/dist.ini index a84f6f2..8ac2925 100644 --- a/dist.ini +++ b/dist.ini @@ -6,6 +6,8 @@ copyright_year = 2011 abstract = Handle values with tags and validity ranges +main_module = lib/Data/MultiValued.pod + [GatherDir] [PodWeaver] diff --git a/lib/Data/MultiValued.pod b/lib/Data/MultiValued.pod new file mode 100644 index 0000000..ebae360 --- /dev/null +++ b/lib/Data/MultiValued.pod @@ -0,0 +1,70 @@ +# PODNAME: Data::MultiValued +# ABSTRACT: store tag- and range-dependant data in a scalar or Moose attribute + +=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 + +Also: + + package My::Class; + use Moose; + use Data::MultiValued::AttributeTrait::Tags; + + has stuff => ( + is => 'rw', + isa => 'Int', + traits => ['MultiValued::Tags'], + ); + + # later + + my $obj = My::Class->new(); + $obj->stuff_multi({tag=>'tag1'},123); + say $obj->stuff_multi({tag=>'tag1'}); # prints 123 + +=head1 DESCRIPTION + +This set of classes allows you to store different values inside a +single object, and access them by tag and / or by a numeric value. + +Yes, you could do the same with hashes and some clever use of +arrays. Or you could use L. Or some other CPAN +module. Why use these? + +=over 4 + +=item * + +they are optimised for serialisation, see +L and F. + +=item * + +you get accessors generated for your Moose attributes just by setting +a trait + +=item * + +tags and ranges interact in sensible ways, including clearing ranges + +=back + +=head1 Where to go from here + +Look at the tests for detailed examples of usage. Look at +L, L and +L for the containers +themselves. Look at L, +L and +L for the Moose +attribute traits. + diff --git a/lib/Data/MultiValued/Ranges.pm b/lib/Data/MultiValued/Ranges.pm index 9c69626..21898af 100644 --- a/lib/Data/MultiValued/Ranges.pm +++ b/lib/Data/MultiValued/Ranges.pm @@ -6,7 +6,24 @@ use MooseX::Types::Moose qw(Num Str Undef Any); use Data::MultiValued::Exceptions; use Data::MultiValued::RangeContainer; -# ABSTRACT: Handle values with tags and validity ranges +# ABSTRACT: Handle values with validity ranges + +=head1 SYNOPSIS + + use Data::MultiValued::Ranges; + + my $obj = Data::MultiValued::Ranges->new(); + $obj->set({ + from => 10, + to => 20, + value => 'foo', + }); + say $obj->get({at => 15}); # prints 'foo' + say $obj->get({at => 35}); # dies + +=head1 METHODS + +=cut has _storage => ( is => 'rw', @@ -32,6 +49,39 @@ sub _as_hash { return {_storage=>\%ret}; } +=head2 C + + $obj->set({ from => $min, to => $max, value => $the_value }); + +Stores the given value for the given range. Does not throw exceptions. + +The range is defined as C<< Num $x : $min <= $x < $max >>. A C<< from +=> undef >> means "from -Inf", and a C<< to => undef >> means "to ++Inf". Not passing in C or C is equivalent to passing +C. + +If the given range intersects existing ranges, these are spliced to +avoid overlaps. In other words: + + $obj->set({ + from => 10, + to => 20, + value => 'foo', + }); + $obj->set({ + from => 15, + to => 25, + value => 'bar', + }); + say $obj->get({at => 12}); # prints 'foo' + say $obj->get({at => 15}); # prints 'bar' + say $obj->get({at => 25}); # dies + +No cloning is done: if you pass in a reference, the reference is +just stored. + +=cut + sub set { my ($self,%args) = validated_hash( \@_, @@ -44,6 +94,23 @@ sub set { ->{value} = $args{value}; } +=head2 C + + my $value = $obj->get({ at => $point }); + +Retrieves the value for the given point. Throws a +L exception if no ranges +exist in this object that include the point (remember that a range +does not include its C point). + +A C<< at => undef >> means "at -Inf". Not passing in C is +equivalent to passing C. + +No cloning is done: if a reference was stored, you get it back +untouched. + +=cut + sub get { my ($self,%args) = validated_hash( \@_, @@ -54,6 +121,33 @@ sub get { ->{value}; } +=head2 C + + $obj->clear({ from => $min, to => $max }); + +Deletes all values for the given range. Does not throw exceptions. + +A C<< from => undef >> means "from -Inf", and a C<< to => undef >> +means "to +Inf". Not passing in C or C is equivalent to +passing C. Thus, C<< $obj->clear() >> clears everything. + +If the given range intersects existing ranges, these are spliced. In +other words: + + $obj->set({ + from => 10, + to => 20, + value => 'foo', + }); + $obj->clear({ + from => 15, + to => 25, + }); + say $obj->get({at => 12}); # prints 'foo' + say $obj->get({at => 15}); # dies + +=cut + sub clear { my ($self,%args) = validated_hash( \@_, @@ -64,5 +158,10 @@ sub clear { $self->_storage->clear(\%args); } +=head1 SEE ALSO + +L, L + +=cut 1; 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 + + $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 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 + + my $value = $obj->get({ tag => $the_tag }); + +Retrieves the value for the given tag. Throws a +L exception if the tag +does not exists in this object. + +Not passing in a C 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 + + $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 clears everything. Yes, this means that there +is no way to just clear the value for the C tag. + +=cut + sub clear { my ($self,%args) = validated_hash( \@_, @@ -62,4 +121,10 @@ sub clear { $self->_storage->clear(\%args); } +=head1 SEE ALSO + +L, L + +=cut + 1; diff --git a/lib/Data/MultiValued/TagsAndRanges.pm b/lib/Data/MultiValued/TagsAndRanges.pm index 6208435..32e2acb 100644 --- a/lib/Data/MultiValued/TagsAndRanges.pm +++ b/lib/Data/MultiValued/TagsAndRanges.pm @@ -8,6 +8,25 @@ use Data::MultiValued::TagContainerForRanges; # ABSTRACT: Handle values with tags and validity ranges +=head1 SYNOPSIS + + use Data::MultiValued::TagsAndRanges; + + my $obj = Data::MultiValued::TagsAndRanges->new(); + $obj->set({ + tag => 'tag1', + from => 10, + to => 20, + value => 'foo', + }); + say $obj->get({tag => 'tag1', at => 15}); # prints 'foo' + say $obj->get({tag => 'tag1', at => 35}); # dies + say $obj->get({tag => 'tag2', at => 15}); # dies + +=head1 METHODS + +=cut + has _storage => ( is => 'rw', isa => class_type('Data::MultiValued::TagContainerForRanges'), @@ -33,6 +52,18 @@ sub _as_hash { return {_storage=>$ret}; } +=head2 C + + $obj->set({ tag => $the_tag, from => $min, to => $max, value => $the_value }); + +Stores the given value for the given tag and range. Does not throw +exceptions. + +See L and +L for more details. + +=cut + sub set { my ($self,%args) = validated_hash( \@_, @@ -47,6 +78,21 @@ sub set { ->{value} = $args{value}; } +=head2 C + + my $value = $obj->get({ tag => $the_tag, at => $point }); + +Retrieves the value for the given tag and point. Throws a +L exception if no ranges +exist in this object that include the point, and +L exception if the tag +does not exists in this object. + +See L and +L for more details. + +=cut + sub get { my ($self,%args) = validated_hash( \@_, @@ -59,6 +105,20 @@ sub get { ->{value}; } +=head2 C + + $obj->clear({ tag => $the_tag, from => $min, to => $max }); + +If a range is specified, deletes all values for the given range and +tag. If no range is specified, delete all values for the given tag. + +Does not throw exceptions. + +See L and +L for more details. + +=cut + sub clear { my ($self,%args) = validated_hash( \@_, -- cgit v1.2.3