Build results of bb2712c (on master)

2 files changed, 77 insertions, 2 deletions

diff --git a/Changes b/Changes
index 68eb8ef..de992a4 100644
--- a/Changes
+++ b/Changes
@@ -1,4 +1,4 @@
 Revision history for Data::MultiValued
 
-0.0.1     2011-11-14 16:48:30 Europe/London
+0.0.1     2011-11-14 16:57:31 Europe/London
   - first working version
diff --git a/lib/Data/MultiValued/UglySerializationHelperRole.pm b/lib/Data/MultiValued/UglySerializationHelperRole.pm
index 60de111..34fc5c0 100644
--- a/lib/Data/MultiValued/UglySerializationHelperRole.pm
+++ b/lib/Data/MultiValued/UglySerializationHelperRole.pm
@@ -7,6 +7,9 @@ BEGIN {
 }
 use Moose::Role;
 
+# ABSTRACT: only use this if you know what you're doing
+
+
 sub new_in_place {
     my ($class,$hash) = @_;
 
@@ -20,6 +23,7 @@ sub new_in_place {
     return $self;
 }
 
+
 sub as_hash {
     my ($self) = @_;
 
@@ -38,6 +42,7 @@ sub as_hash {
     return \%ret;
 }
 
+
 1;
 
 __END__
@@ -45,12 +50,82 @@ __END__
 
 =head1 NAME
 
-Data::MultiValued::UglySerializationHelperRole
+Data::MultiValued::UglySerializationHelperRole - only use this if you know what you're doing
 
 =head1 VERSION
 
 version 0.0.1
 
+=head1 SYNOPSIS
+
+ package My::Class;
+ use Moose;
+ use Data::MultiValued::AttributeTrait::Tags;
+
+ with 'Data::MultiValued::UglySerializationHelperRole';
+
+ has tt => (
+    is => 'rw',
+    isa => 'Int',
+    traits => ['MultiValued::Tags'],
+    default => 3,
+    predicate => 'has_tt',
+    clearer => 'clear_tt',
+ );
+
+Later:
+
+  my $json = JSON::XS->new->utf8;
+  my $obj = My::Class->new(rr=>'foo');
+
+  my $str = $json->encode($obj->as_hash);
+
+  my $obj2 = My::Class->new_in_place($json->decode($str));
+
+  # $obj and $obj2 have the same contents
+
+=head1 DESCRIPTION
+
+This is an ugly hack. It pokes inside the internals of your objects,
+and will break if you're not careful. It assumes that your instances
+are hashref-based. It mostly assumes that you're not storing blessed
+refs inside the multi-value attributes. It goes to these lengths to
+give a decent serialisation performance, without lots of unnecessary
+copies. Oh, and on de-serialise it will skip all type constraint
+checking and bypass the accessors, so it may well give you an unusable
+object.
+
+=head1 METHODS
+
+=head2 C<new_in_place>
+
+  my $obj = My::Class->new_in_place($hashref);
+
+Directly C<bless>es the hashref into the class, then calls
+C<_rebless_slot> on any multi-value attribute.
+
+This is very dangerous, don't try this at home without the supervision
+of an adult.
+
+=head2 C<as_hash>
+
+  my $hashref = $obj->as_hash;
+
+Performs a shallow copy of the object's hash, then replaces the values
+of all the multi-value slots with the results of calling C<_as_hash>
+on the corresponding multi-value attribute.
+
+This is very dangerous, don't try this at home without the supervision
+of an adult.
+
+=head1 FINAL WARNING
+
+ my $obj_clone = My::Class->new_in_place($obj->as_hash);
+
+This will create a shallow clone. Most internals will be
+shared. Things may break. Just don't do it, C<dclone> the hashref, or
+do something equivalent (as in the synopsis), instead.
+
 =head1 AUTHOR
 
 Gianni Ceccarelli <dakkar@thenautilus.net>