[ViewVC] Contents of: cvs/Types-Serialiser/README

NAME
    Types::Serialiser - simple data types for common serialisation formats

SYNOPSIS
DESCRIPTION
    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
    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.

  BOOLEANS (Types::Serialiser::Boolean class)
    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.

    $Types::Serialiser::true, Types::Serialiser::true
        This value represents the "true" value. In most contexts is acts
        like the number 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.

    $Types::Serialiser::false, Types::Serialiser::false
        This value represents the "false" value. In most contexts is acts
        like the number 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.

    $is_bool = Types::Serialiser::is_bool $value
        Returns true iff the $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

    $is_true = Types::Serialiser::is_true $value
        Returns true iff $value is $Types::Serialiser::true.

    $is_false = Types::Serialiser::is_false $value
        Returns false iff $value is $Types::Serialiser::false.

  ERROR (Types::Serialiser::Error class)
    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.

    $Types::Serialiser::error, Types::Serialiser::error
        This value represents the "error" value. Accessing values of this
        type will throw an exception.

        The constant is represented as a reference to a scalar containing
        "undef" - implementations are allowed to directly test for this.

    $is_error = Types::Serialiser::is_error $value
        Returns false iff $value is $Types::Serialiser::error.

NOTES FOR XS USERS
    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 withh
    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).

A GENERIC OBJECT SERIALIATION PROTOCOL
    This section explains the object serialisation protocol used by
    CBOR::XS. 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".

  ENCODING
    When the encoder encounters an object that it cannot otherwise encode
    (for example, CBOR::XS 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.

    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 CBOR::XS uses "CBOR", and JSON and
    JSON::XS (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 serialiser by checking the second argument.

  DECODING
    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 format, and all the
    return values returned by "FREEZE".

  EXAMPLES
    See the "OBJECT SERIALISATION" section in the CBOR::XS manpage for more
    details, an example implementation, and code examples.

    Here is an example "FREEZE"/"THAW" method pair:

       sub My::Object::FREEZE {
          my ($self, $serialiser) = @_;

          ($self->{type}, $self->{id}, $self->{variant})
       }

       sub My::Object::THAW {
          my ($class, $serialiser, $type, $id, $variant) = @_;

          $class-<new (type => $type, id => $id, variant => $variant)
       }

BUGS
    The use of overload makes this module much heavier than it should be (on
    my system, this module: 4kB RSS, overload: 260kB RSS).

SEE ALSO
    Currently, JSON::XS and CBOR::XS use these types.

AUTHOR
     Marc Lehmann <schmorp@schmorp.de>
     http://home.schmorp.de/

Revision:	1.4
Committed:	Tue Oct 29 13:08:35 2013 UTC (10 years, 8 months ago) by root
Branch:	MAIN
CVS Tags:	rel-0_03
Changes since 1.3:	+6 -0 lines
Log Message:	0.03
#	Content
1	NAME
2	Types::Serialiser - simple data types for common serialisation formats
3
4	SYNOPSIS
5	DESCRIPTION
6	This module provides some extra datatypes that are used by common
7	serialisation formats such as JSON or CBOR. The idea is to have a
8	repository of simple/small constants and containers that can be shared
9	by different implementations so they become interoperable between each
10	other.
11
12	SIMPLE SCALAR CONSTANTS
13	Simple scalar constants are values that are overloaded to act like
14	simple Perl values, but have (class) type to differentiate them from
15	normal Perl scalars. This is necessary because these have different
16	representations in the serialisation formats.
17
18	BOOLEANS (Types::Serialiser::Boolean class)
19	This type has only two instances, true and false. A natural
20	representation for these in Perl is 1 and 0, but serialisation formats
21	need to be able to differentiate between them and mere numbers.
22
23	$Types::Serialiser::true, Types::Serialiser::true
24	This value represents the "true" value. In most contexts is acts
25	like the number 1. It is up to you whether you use the variable form
26	($Types::Serialiser::true) or the constant form
27	("Types::Serialiser::true").
28
29	The constant is represented as a reference to a scalar containing 1
30	- implementations are allowed to directly test for this.
31
32	$Types::Serialiser::false, Types::Serialiser::false
33	This value represents the "false" value. In most contexts is acts
34	like the number 0. It is up to you whether you use the variable form
35	($Types::Serialiser::false) or the constant form
36	("Types::Serialiser::false").
37
38	The constant is represented as a reference to a scalar containing 0
39	- implementations are allowed to directly test for this.
40
41	$is_bool = Types::Serialiser::is_bool $value
42	Returns true iff the $value is either $Types::Serialiser::true or
43	$Types::Serialiser::false.
44
45	For example, you could differentiate between a perl true value and a
46	"Types::Serialiser::true" by using this:
47
48	$value && Types::Serialiser::is_bool $value
49
50	$is_true = Types::Serialiser::is_true $value
51	Returns true iff $value is $Types::Serialiser::true.
52
53	$is_false = Types::Serialiser::is_false $value
54	Returns false iff $value is $Types::Serialiser::false.
55
56	ERROR (Types::Serialiser::Error class)
57	This class has only a single instance, "error". It is used to signal an
58	encoding or decoding error. In CBOR for example, and object that
59	couldn't be encoded will be represented by a CBOR undefined value, which
60	is represented by the error value in Perl.
61
62	$Types::Serialiser::error, Types::Serialiser::error
63	This value represents the "error" value. Accessing values of this
64	type will throw an exception.
65
66	The constant is represented as a reference to a scalar containing
67	"undef" - implementations are allowed to directly test for this.
68
69	$is_error = Types::Serialiser::is_error $value
70	Returns false iff $value is $Types::Serialiser::error.
71
72	NOTES FOR XS USERS
73	The recommended way to detect whether a scalar is one of these objects
74	is to check whether the stash is the "Types::Serialiser::Boolean" or
75	"Types::Serialiser::Error" stash, and then follow the scalar reference
76	to see if it's 1 (true), 0 (false) or "undef" (error).
77
78	While it is possible to use an isa test, directly comparing stash
79	pointers is faster and guaranteed to work.
80
81	For historical reasons, the "Types::Serialiser::Boolean" stash is just
82	an alias for "JSON::PP::Boolean". When printed, the classname withh
83	usually be "JSON::PP::Boolean", but isa tests and stash pointer
84	comparison will normally work correctly (i.e. Types::Serialiser::true
85	ISA JSON::PP::Boolean, but also ISA Types::Serialiser::Boolean).
86
87	A GENERIC OBJECT SERIALIATION PROTOCOL
88	This section explains the object serialisation protocol used by
89	CBOR::XS. It is meant to be generic enough to support any kind of
90	generic object serialiser.
91
92	This protocol is called "the Types::Serialiser object serialisation
93	protocol".
94
95	ENCODING
96	When the encoder encounters an object that it cannot otherwise encode
97	(for example, CBOR::XS can encode a few special types itself, and will
98	first attempt to use the special "TO_CBOR" serialisation protocol), it
99	will look up the "FREEZE" method on the object.
100
101	If it exists, it will call it with two arguments: the object to
102	serialise, and a constant string that indicates the name of the
103	serialisationformat. For example CBOR::XS uses "CBOR", and JSON and
104	JSON::XS (or any other JSON serialiser), would use "JSON" as second
105	argument.
106
107	The "FREEZE" method can then return zero or more values to identify the
108	object instance. The serialiser is then supposed to encode the class
109	name and all of these return values (which must be encodable in the
110	format) using the relevant form for perl objects. In CBOR for example,
111	there is a registered tag number for encoded perl objects.
112
113	The values that "FREEZE" returns must be serialisable with the
114	serialiser that calls it. Therefore, it is recommended to use simple
115	types such as strings and numbers, and maybe array references and hashes
116	(basically, the JSON data model). You can always use a more complex
117	format for a specific serialiser by checking the second argument.
118
119	DECODING
120	When the decoder then encounters such an encoded perl object, it should
121	look up the "THAW" method on the stored classname, and invoke it with
122	the classname, the constant string to identify the format, and all the
123	return values returned by "FREEZE".
124
125	EXAMPLES
126	See the "OBJECT SERIALISATION" section in the CBOR::XS manpage for more
127	details, an example implementation, and code examples.
128
129	Here is an example "FREEZE"/"THAW" method pair:
130
131	sub My::Object::FREEZE {
132	my ($self, $serialiser) = @_;
133
134	($self->{type}, $self->{id}, $self->{variant})
135	}
136
137	sub My::Object::THAW {
138	my ($class, $serialiser, $type, $id, $variant) = @_;
139
140	$class-<new (type => $type, id => $id, variant => $variant)
141	}
142
143	BUGS
144	The use of overload makes this module much heavier than it should be (on
145	my system, this module: 4kB RSS, overload: 260kB RSS).
146
147	SEE ALSO
148	Currently, JSON::XS and CBOR::XS use these types.
149
150	AUTHOR
151	Marc Lehmann <schmorp@schmorp.de>
152	http://home.schmorp.de/
153