1NAME 2 Types::Serialiser - simple data types for common serialisation formats 3 4SYNOPSIS 5DESCRIPTION 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 12SIMPLE 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 72NOTES 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 with 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 87A 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 Note that the "FREEZE" method will normally be called *during* encoding, 102 and *MUST NOT* change the data structure that is being encoded in any 103 way, or it might cause memory corruption or worse. 104 105 If it exists, it will call it with two arguments: the object to 106 serialise, and a constant string that indicates the name of the data 107 model. For example CBOR::XS uses "CBOR", and the JSON and JSON::XS 108 modules (or any other JSON serialiser), would use "JSON" as second 109 argument. 110 111 The "FREEZE" method can then return zero or more values to identify the 112 object instance. The serialiser is then supposed to encode the class 113 name and all of these return values (which must be encodable in the 114 format) using the relevant form for Perl objects. In CBOR for example, 115 there is a registered tag number for encoded perl objects. 116 117 The values that "FREEZE" returns must be serialisable with the 118 serialiser that calls it. Therefore, it is recommended to use simple 119 types such as strings and numbers, and maybe array references and hashes 120 (basically, the JSON data model). You can always use a more complex 121 format for a specific data model by checking the second argument, the 122 data model. 123 124 The "data model" is not the same as the "data format" - the data model 125 indicates what types and kinds of return values can be returned from 126 "FREEZE". For example, in "CBOR" it is permissible to return tagged CBOR 127 values, while JSON does not support these at all, so "JSON" would be a 128 valid (but too limited) data model name for "CBOR::XS". similarly, a 129 serialising format that supports more or less the same data model as 130 JSON could use "JSON" as data model without losing anything. 131 132 DECODING 133 When the decoder then encounters such an encoded perl object, it should 134 look up the "THAW" method on the stored classname, and invoke it with 135 the classname, the constant string to identify the data model/data 136 format, and all the return values returned by "FREEZE". 137 138 EXAMPLES 139 See the "OBJECT SERIALISATION" section in the CBOR::XS manpage for more 140 details, an example implementation, and code examples. 141 142 Here is an example "FREEZE"/"THAW" method pair: 143 144 sub My::Object::FREEZE { 145 my ($self, $model) = @_; 146 147 ($self->{type}, $self->{id}, $self->{variant}) 148 } 149 150 sub My::Object::THAW { 151 my ($class, $model, $type, $id, $variant) = @_; 152 153 $class->new (type => $type, id => $id, variant => $variant) 154 } 155 156BUGS 157 The use of overload makes this module much heavier than it should be (on 158 my system, this module: 4kB RSS, overload: 260kB RSS). 159 160SEE ALSO 161 Currently, JSON::XS and CBOR::XS use these types. 162 163AUTHOR 164 Marc Lehmann <schmorp@schmorp.de> 165 http://home.schmorp.de/ 166 167