--- Types-Serialiser/Serialiser.pm 2013/10/29 13:08:35 1.6 +++ Types-Serialiser/Serialiser.pm 2020/12/01 01:47:20 1.10 @@ -19,7 +19,7 @@ use common::sense; # required to suppress annoying warnings -our $VERSION = 0.03; +our $VERSION = '1.01'; =head1 SIMPLE SCALAR CONSTANTS @@ -28,6 +28,9 @@ scalars. This is necessary because these have different representations in the serialisation formats. +In the following, functions with zero or one arguments have a prototype of +C<()> and C<($)>, respectively, so act as constants and unary operators. + =head2 BOOLEANS (Types::Serialiser::Boolean class) This type has only two instances, true and false. A natural representation @@ -54,6 +57,13 @@ The constant is represented as a reference to a scalar containing C<0> - implementations are allowed to directly test for this. +=item Types::Serialiser::as_bool $value + +Converts a Perl scalar into a boolean, which is useful syntactic +sugar. Strictly equivalent to: + + $value ? $Types::Serialiser::true : $Types::Serialiser::false + =item $is_bool = Types::Serialiser::is_bool $value Returns true iff the C<$value> is either C<$Types::Serialiser::true> or @@ -129,6 +139,8 @@ sub false () { $false } sub error () { $error } +sub as_bool($) { $_[0] ? $true : $false } + sub is_bool ($) { UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: } sub is_true ($) { $_[0] && UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: } sub is_false ($) { !$_[0] && UNIVERSAL::isa $_[0], Types::Serialiser::Boolean:: } @@ -159,7 +171,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). @@ -179,30 +191,41 @@ 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. +Note that the C method will normally be called I encoding, +and I change the data structure that is being encoded in any +way, or it might cause memory corruption or worse. + +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. For +example L uses C, and the L and L modules +(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 and all of these return values (which must be encodable in the format) -using the relevant form for perl objects. In CBOR for example, there is a +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 -serialiser by checking the second argument. +data model by checking the second argument, the data model. + +The "data model" is not the same as the "data format" - the data model +indicates what types and kinds of return values can be returned from +C. For example, in C it is permissible to return tagged CBOR +values, while JSON does not support these at all, so C would be a +valid (but too limited) data model name for C. similarly, a +serialising format that supports more or less the same data model as JSON +could use C as data model without losing anything. =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 @@ -212,15 +235,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