--- Types-Serialiser/Serialiser.pm 2013/10/28 15:28:44 1.4 +++ Types-Serialiser/Serialiser.pm 2013/11/04 15:12:16 1.8 @@ -19,7 +19,7 @@ use common::sense; # required to suppress annoying warnings -our $VERSION = 0.02; +our $VERSION = 0.03; =head1 SIMPLE SCALAR CONSTANTS @@ -103,9 +103,24 @@ # for historical reasons, and to avoid extra dependencies in JSON::PP, # we alias *Types::Serialiser::Boolean with JSON::PP::Boolean. package JSON::PP::Boolean; + *Types::Serialiser::Boolean:: = *JSON::PP::Boolean::; } +{ + # this must done before blessing to work around bugs + # in perl < 5.18 (it seems to be fixed in 5.18). + package Types::Serialiser::BooleanBase; + + use overload + "0+" => sub { ${$_[0]} }, + "++" => sub { $_[0] = ${$_[0]} + 1 }, + "--" => sub { $_[0] = ${$_[0]} - 1 }, + fallback => 1; + + @Types::Serialiser::Boolean::ISA = Types::Serialiser::BooleanBase::; +} + our $true = do { bless \(my $dummy = 1), Types::Serialiser::Boolean:: }; our $false = do { bless \(my $dummy = 0), Types::Serialiser::Boolean:: }; our $error = do { bless \(my $dummy ), Types::Serialiser::Error:: }; @@ -119,16 +134,6 @@ sub is_false ($) { !$_[0] && UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: } sub is_error ($) { UNIVERSAL::isa $_[0], Types::Serialiser::Error:: } -package Types::Serialiser::BooleanBase; - -use overload - "0+" => sub { ${$_[0]} }, - "++" => sub { $_[0] = ${$_[0]} + 1 }, - "--" => sub { $_[0] = ${$_[0]} - 1 }, - fallback => 1; - -@Types::Serialiser::Boolean::ISA = Types::Serialiser::BooleanBase::; - package Types::Serialiser::Error; sub error { @@ -154,7 +159,7 @@ For historical reasons, the C stash is just an alias for C. When printed, the classname -withh usually be C, but isa tests and stash pointer +with usually be C, but isa tests and stash pointer comparison will normally work correctly (i.e. Types::Serialiser::true ISA JSON::PP::Boolean, but also ISA Types::Serialiser::Boolean). @@ -174,11 +179,10 @@ attempt to use the special C serialisation protocol), it will look up the C method on the object. -If it exists, it will call it with two arguments: the object to -serialise, and a constant string that indicates the name of the -serialisationformat. For example L uses C, and L and -L (or any other JSON serialiser), would use C as second -argument. +If it exists, it will call it with two arguments: the object to serialise, +and a constant string that indicates the name of the data model or data +format. For example L uses C, and L and L +(or any other JSON serialiser), would use C as second argument. The C method can then return zero or more values to identify the object instance. The serialiser is then supposed to encode the class name @@ -186,12 +190,18 @@ using the relevant form for perl objects. In CBOR for example, there is a registered tag number for encoded perl objects. +The values that C returns must be serialisable with the serialiser +that calls it. Therefore, it is recommended to use simple types such as +strings and numbers, and maybe array references and hashes (basically, the +JSON data model). You can always use a more complex format for a specific +data model by checking the second argument. + =head2 DECODING When the decoder then encounters such an encoded perl object, it should look up the C method on the stored classname, and invoke it with the -classname, the constant string to identify the format, and all the return -values returned by C. +classname, the constant string to identify the data model/data format, and +all the return values returned by C. =head2 EXAMPLES @@ -201,15 +211,15 @@ Here is an example C/C method pair: sub My::Object::FREEZE { - my ($self, $serialiser) = @_; + my ($self, $model) = @_; ($self->{type}, $self->{id}, $self->{variant}) } sub My::Object::THAW { - my ($class, $serialiser, $type, $id, $variant) = @_; + my ($class, $model, $type, $id, $variant) = @_; - $class- $type, id => $id, variant => $variant) + $class->new (type => $type, id => $id, variant => $variant) } =head1 BUGS