| Types::Serialiser - simple data types for common serialisation formats |
Types::Serialiser - simple data types for common serialisation formats
This module provides some extra datatypes that are used by common serialisation formats such as JSON or CBOR. The idea is to have a repository of simple/small constants and containers that can be shared by different implementations so they become interoperable between each other.
Simple scalar constants are values that are overloaded to act like simple Perl values, but have (class) type to differentiate them from normal Perl scalars. This is necessary because these have different representations in the serialisation formats.
This type has only two instances, true and false. A natural representation
for these in Perl is 1 and 0, but serialisation formats need to be
able to differentiate between them and mere numbers.
1. It is up to you whether you use the variable form
($Types::Serialiser::true) or the constant form (Types::Serialiser::true).
The constant is represented as a reference to a scalar containing 1 -
implementations are allowed to directly test for this.
0. It is up to you whether you use the variable form
($Types::Serialiser::false) or the constant form (Types::Serialiser::false).
The constant is represented as a reference to a scalar containing 0 -
implementations are allowed to directly test for this.
$value is either $Types::Serialiser::true or
$Types::Serialiser::false.
For example, you could differentiate between a perl true value and a
Types::Serialiser::true by using this:
$value && Types::Serialiser::is_bool $value
$value is $Types::Serialiser::true.
$value is $Types::Serialiser::false.
This class has only a single instance, error. It is used to signal
an encoding or decoding error. In CBOR for example, and object that
couldn't be encoded will be represented by a CBOR undefined value, which
is represented by the error value in Perl.
The constant is represented as a reference to a scalar containing undef
- implementations are allowed to directly test for this.
$value is $Types::Serialiser::error.
The recommended way to detect whether a scalar is one of these objects
is to check whether the stash is the Types::Serialiser::Boolean or
Types::Serialiser::Error stash, and then follow the scalar reference to
see if it's 1 (true), 0 (false) or undef (error).
While it is possible to use an isa test, directly comparing stash pointers is faster and guaranteed to work.
For historical reasons, the Types::Serialiser::Boolean stash is
just an alias for JSON::PP::Boolean. When printed, the classname
with usually be JSON::PP::Boolean, 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).
This section explains the object serialisation protocol used by the CBOR::XS manpage. It is meant to be generic enough to support any kind of generic object serialiser.
This protocol is called ``the Types::Serialiser object serialisation protocol''.
When the encoder encounters an object that it cannot otherwise encode (for
example, the CBOR::XS manpage can encode a few special types itself, and will first
attempt to use the special TO_CBOR serialisation protocol), it will
look up the FREEZE method on the object.
Note that the FREEZE method will normally be called during encoding,
and MUST NOT 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 the CBOR::XS manpage uses CBOR, and the JSON and the JSON::XS manpage modules
(or any other JSON serialiser), would use JSON as second argument.
The FREEZE 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
registered tag number for encoded perl objects.
The values that FREEZE 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, 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
FREEZE. For example, in CBOR it is permissible to return tagged CBOR
values, while JSON does not support these at all, so JSON would be a
valid (but too limited) data model name for CBOR::XS. similarly, a
serialising format that supports more or less the same data model as JSON
could use JSON as data model without losing anything.
When the decoder then encounters such an encoded perl object, it should
look up the THAW method on the stored classname, and invoke it with the
classname, the constant string to identify the data model/data format, and
all the return values returned by FREEZE.
See the OBJECT SERIALISATION section in the the CBOR::XS manpage manpage for
more details, an example implementation, and code examples.
Here is an example FREEZE/THAW method pair:
sub My::Object::FREEZE {
my ($self, $model) = @_;
($self->{type}, $self->{id}, $self->{variant})
}
sub My::Object::THAW {
my ($class, $model, $type, $id, $variant) = @_;
$class->new (type => $type, id => $id, variant => $variant)
}
The use of the overload manpage makes this module much heavier than it should be (on my system, this module: 4kB RSS, overload: 260kB RSS).
Currently, the JSON::XS manpage and the CBOR::XS manpage use these types.
Marc Lehmann <schmorp@schmorp.de> http://home.schmorp.de/
| Types::Serialiser - simple data types for common serialisation formats |