1 files changed, 252 insertions, 11 deletions

diff --git a/lib/Data/MultiValued/AttributeTrait.pm b/lib/Data/MultiValued/AttributeTrait.pm
index afeea2e..88ae6e3 100644
--- a/lib/Data/MultiValued/AttributeTrait.pm
+++ b/lib/Data/MultiValued/AttributeTrait.pm
@@ -11,23 +11,43 @@ use MooseX::Types::Moose qw(Str);
 use Try::Tiny;
 use namespace::autoclean;
 
+# ABSTRACT: "base role" for traits of multi-valued Moose attributes
+
+
 has 'full_storage_slot' => (
     is => 'ro',
     isa => Str,
     lazy_build => 1,
-    init_arg => undef,
 );
 sub _build_full_storage_slot { shift->name . '__MULTIVALUED_STORAGE__' }
 
+
+my @accs_to_multiply=qw(accessor reader writer predicate clearer);
+
+for my $acc (@accs_to_multiply) {
+    has "multi_$acc" => (
+        is => 'ro',
+        isa => Str,
+        predicate => "has_multi_$acc",
+    );
+}
+
+
 requires 'multivalue_storage_class';
+
+
 requires 'opts_to_pass_set';
+
+
 requires 'opts_to_pass_get';
 
+
 around slots => sub {
     my ($orig, $self) = @_;
     return ($self->$orig(), $self->full_storage_slot);
 };
 
+
 sub set_full_storage {
     my ($self,$instance) = @_;
 
@@ -40,6 +60,7 @@ sub set_full_storage {
     return $ret;
 }
 
+
 sub get_full_storage {
     my ($self,$instance) = @_;
 
@@ -50,6 +71,7 @@ sub get_full_storage {
         );
 }
 
+
 sub full_storage {
     my ($self,$instance) = @_;
 
@@ -57,24 +79,30 @@ sub full_storage {
         || $self->set_full_storage($instance);
 }
 
+
 sub accessor_metaclass { 'Data::MultiValued::AttributeAccessors' }
 
+
 after install_accessors => sub {
     my ($self) = @_;
 
     my $class  = $self->associated_class;
 
-    for my $meth (qw(accessor reader writer predicate clearer)) {
+    for my $meth (@accs_to_multiply) {
+        my $type = "multi_$meth";
         my $check = "has_$meth";
-        next unless $self->$check;
+        my $multi_check = "has_$type";
+        next unless $self->$check || $self->$multi_check;
 
-        my $type = "multi_$meth";
-        my $basename = $self->$meth;
+        my $name = $self->$type;
+        if (!$name) {
+            my $basename = $self->$meth;
 
-        die 'MultiValued attribute trait is not compatible with subref accessors'
-            if ref($basename);
+            die 'MultiValued attribute trait is not compatible with subref accessors'
+                if ref($basename);
 
-        my $name = "${basename}_multi";
+            $name = "${basename}_multi";
+        }
 
         $class->add_method(
             $self->_process_accessors($type => $name,0)
@@ -94,6 +122,7 @@ sub _filter_opts {
     return \%ret;
 }
 
+
 sub load_multi_value {
     my ($self,$instance,$opts) = @_;
 
@@ -118,6 +147,7 @@ sub load_multi_value {
     }
 }
 
+
 sub raw_clear_value {
     my ($self,$instance) = @_;
 
@@ -128,6 +158,7 @@ sub raw_clear_value {
         );
 }
 
+
 sub store_multi_value {
     my ($self,$instance,$opts) = @_;
 
@@ -140,12 +171,14 @@ sub store_multi_value {
 
 our $dyn_opts = {};
 
+
 before get_value => sub {
     my ($self,$instance) = @_;
 
     $self->load_multi_value($instance,$dyn_opts);
 };
 
+
 sub get_multi_value {
     my ($self,$instance,$opts,$value) = @_;
 
@@ -154,12 +187,14 @@ sub get_multi_value {
     return $self->get_value($instance,$value);
 }
 
+
 after set_initial_value => sub {
     my ($self,$instance,$value) = @_;
 
     $self->store_multi_value($instance,$dyn_opts);
 };
 
+
 after set_value => sub {
     my ($self,$instance,$value) = @_;
 
@@ -174,6 +209,7 @@ sub set_multi_value {
     return $self->set_value($instance,$value);
 }
 
+
 before has_value => sub {
     my ($self,$instance) = @_;
 
@@ -188,6 +224,7 @@ sub has_multi_value {
     return $self->has_value($instance);
 }
 
+
 after clear_value => sub {
     my ($self,$instance) = @_;
 
@@ -203,16 +240,20 @@ sub clear_multi_value {
     return $self->clear_value($instance);
 }
 
+
 sub get_multi_read_method  { 
     my $self   = shift;
-    return $self->get_read_method . '_multi';
+    return $self->multi_reader || $self->multi_accessor
+        || $self->get_read_method . '_multi';
 }
 
 sub get_multi_write_method  { 
     my $self   = shift;
-    return $self->get_write_method . '_multi';
+    return $self->multi_writer || $self->multi_accessor
+        || $self->get_write_method . '_multi';
 }
 
+
 sub _rebless_slot {
     my ($self,$instance) = @_;
 
@@ -223,6 +264,7 @@ sub _rebless_slot {
     $st->_rebless_storage;
 }
 
+
 sub _as_hash {
     my ($self,$instance) = @_;
 
@@ -239,12 +281,211 @@ __END__
 
 =head1 NAME
 
-Data::MultiValued::AttributeTrait
+Data::MultiValued::AttributeTrait - "base role" for traits of multi-valued Moose attributes
 
 =head1 VERSION
 
 version 0.0.1
 
+=head1 DESCRIPTION
+
+Don't use this role directly, use
+L<Data::MultiValued::AttributeTrait::Tags>,
+L<Data::MultiValued::AttributeTrait::Ranges> or
+L<Data::MultiValued::AttributeTrait::TagsAndRanges>.
+
+This role (together with L<Data::MultiValued::AttributeAccessors>)
+defines all the basic plumbing to glue C<Data::MultiValued::Tags> etc
+into Moose attributes.
+
+=head1 Implementation details
+
+The multi-value object is stored in the instance slot named by the
+L</full_storage_slot> attribute attribute. C<before> modifiers on
+getters load the appropriate value from the multi-value object into
+the regular instance slot, C<after> modifiers on setters store the
+value from the regular instance slot into the multi-value object.
+
+=head1 ATTRIBUTES
+
+These are the attributes that this trait adds to the attribute in
+your class. Example:
+
+  has stuff => (
+    is => 'rw',
+    isa => 'Int',
+    traits => ['MultiValued::Tags'],
+    predicate => 'has_stuff',
+    multi_accessor => 'stuff_tagged',
+    multi_predicate => 'has_stuff_tagged',
+  );
+
+=head2 C<full_storage_slot>
+
+The instance slot to use to store the C<Data::MultiValued::Tags> or
+similar object. Defaults to C<"${name}__MULTIVALUED_STORAGE__">, where
+C<$name> is the attribute name.
+
+=head2 C<multi_accessor>
+
+=head2 C<multi_reader>
+
+=head2 C<multi_writer>
+
+=head2 C<multi_predicate>
+
+=head2 C<multi_clearer>
+
+The names to use for the various additional accessors. See
+L<Class::MOP::Attribute> for details. These default to
+C<"multi_$name"> where C<$name> is the name of the corresponding
+non-multi accessor. So, for example,
+
+  has stuff => (
+    is => 'rw',
+    traits => ['MultiValued::Tags'],
+  );
+
+will create a C<stuff> read / write accessor and a C<stuff_multi> read
+/ write tagged accessor.
+
+=head1 REQUIREMENTS
+
+These methods must be provided by any class consuming this role. See
+L<Data::MultiValued::AttributeTrait::Tags> etc. for examples.
+
+=head2 C<multivalue_storage_class>
+
+The class to use to create the multi-value objects.
+
+=head2 C<opts_to_pass_set>
+
+Which options to pass from the multi-value accessors to the C<set>
+method of the multi-value object.
+
+=head2 C<opts_to_pass_get>
+
+Which options to pass from the multi-value accessors to the C<get>
+method of the multi-value object.
+
+=head1 METHODS
+
+=head2 C<slots>
+
+Adds the L</full_storage_slot> to the list of used slots.
+
+=head2 C<set_full_storage>
+
+Stores a new instance of L</multivalue_storage_class> into the
+L</full_storage_slot> of the instance.
+
+=head2 C<get_full_storage>
+
+Retrieves the value of the L</full_storage_slot> of the instance.
+
+=head2 C<full_storage>
+
+Returns an instance of L</multivalue_storage_class>, either by
+retrieving it from the instance, or by creating one (and setting it in
+the instance). Calls L</get_full_storage> and L</set_full_storage>.
+
+=head2 C<accessor_metaclass>
+
+Makes sure that all accessors for this attribute are created via the
+L<Data::MultiValued::AttributeAccessors> method meta class.
+
+=head2 C<install_accessors>
+
+After the regular L<Moose::Meta::Attribute> method, installs the
+multi-value accessors.
+
+Each installed normal accessor gets a multi-value version
+
+You can add or rename the multi-value version by using the attributes
+described above
+
+If you are passing explicit subrefs for your accessors, things won't work.
+
+=head2 C<load_multi_value>
+
+Retrieves a value from the multi-value object, and stores it in the
+regular slot in the instance. If the value is not found, clears the
+slot.
+
+This traps the L<Data::MultiValued::Exceptions::NotFound> exception
+that may be thrown by the multi-value object, but re-throws any other
+exception.
+
+=head2 C<raw_clear_value>
+
+Clears the instance slot. Does the same as
+L<Moose::Meta::Attribute/clear_value>, but we need this method because
+the other one gets changed by this trait.
+
+=head2 C<store_multi_value>
+
+Gets the value from the regular slot in the instance, and stores it
+into the multi-value object.
+
+=head2 C<get_value>
+
+Before the normal method, calls L</load_multi_value>. Normally, no
+options will be passed to the multi-value object C<get> method.
+
+=head2 C<get_multi_value>
+
+Sets the options that L</load_multi_value> will use, then calls L</get_value>.
+
+The options are passed via an ugly C<local>ised package
+variable. There might be a better way.
+
+=head2 C<set_initial_value>
+
+After the normal method, calls L</store_multi_value>.
+
+=head2 C<set_value>
+
+=head2 C<set_multi_value>
+
+Just like L</get_value> and L</get_multi_value>, but calling
+L</store_multi_value> after the regular C<set_value>
+
+=head2 C<has_value>
+
+=head2 C<has_multi_value>
+
+Just like L</get_value> and L</get_multi_value>.
+
+=head2 C<clear_value>
+
+=head2 C<clear_multi_value>
+
+Call the C<clear> method on the multi-value object.
+
+=head2 C<get_multi_read_method>
+
+=head2 C<get_multi_write_method>
+
+Return the name of the reader or writer method, honoring
+L</multi_reader>, L</multi_writer> and L</multi_accessor>.
+
+=head1 Serialisation helpers
+
+These are used through
+L<Data::MultiValued::UglySerializationHelperRole>.
+
+=head2 C<_rebless_slot>
+
+Blesses the value inside the L</full_storage_slot> of the instance
+into L</multivalue_storage_class>, then calls C<_rebless_storage> on
+it.
+
+=head2 C<_as_hash>
+
+Returns the result of calling C<_as_hash> on the value inside the
+L</full_storage_slot> of the instance. Returns nothing if the slot
+does not have a value.
+
 =head1 AUTHOR
 
 Gianni Ceccarelli <dakkar@thenautilus.net>