ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/CBOR-XS/README
(Generate patch)

Comparing CBOR-XS/README (file contents):
Revision 1.4 by root, Sat Oct 26 23:02:55 2013 UTC vs.
Revision 1.5 by root, Sun Oct 27 22:48:12 2013 UTC

… …
8 $perl_value = decode_cbor $binary_cbor_data; 8 $perl_value = decode_cbor $binary_cbor_data;
9 9
10 # OO-interface 10 # OO-interface
11 11
12 $coder = CBOR::XS->new; 12 $coder = CBOR::XS->new;
13 #TODO 13 $binary_cbor_data = $coder->encode ($perl_value);
14 $perl_value = $coder->decode ($binary_cbor_data);
15
16 # prefix decoding
17
18 my $many_cbor_strings = ...;
19 while (length $many_cbor_strings) {
20 my ($data, $length) = $cbor->decode_prefix ($many_cbor_strings);
21 # data was decoded
22 substr $many_cbor_strings, 0, $length, ""; # remove decoded cbor string
23 }
14 24
15DESCRIPTION 25DESCRIPTION
16 WARNING! THIS IS A PRE-ALPHA RELEASE! IT WILL CRASH, CORRUPT YOUR DATA 26 WARNING! THIS IS A PRE-ALPHA RELEASE! IT WILL CRASH, CORRUPT YOUR DATA
17 AND EAT YOUR CHILDREN! (Actually, apart from being untested and a bit 27 AND EAT YOUR CHILDREN! (Actually, apart from being untested and a bit
18 feature-limited, it might already be useful). 28 feature-limited, it might already be useful).
… …
21 Representation (CBOR) and vice versa. CBOR is a fast binary 31 Representation (CBOR) and vice versa. CBOR is a fast binary
22 serialisation format that aims to use a superset of the JSON data model, 32 serialisation format that aims to use a superset of the JSON data model,
23 i.e. when you can represent something in JSON, you should be able to 33 i.e. when you can represent something in JSON, you should be able to
24 represent it in CBOR. 34 represent it in CBOR.
25 35
26 This makes it a faster and more compact binary alternative to JSON. 36 This makes it a faster and more compact binary alternative to JSON, with
37 the added ability of supporting serialising of perl objects.
27 38
28 The primary goal of this module is to be *correct* and the secondary 39 The primary goal of this module is to be *correct* and the secondary
29 goal is to be *fast*. To reach the latter goal it was written in C. 40 goal is to be *fast*. To reach the latter goal it was written in C.
30 41
31 See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and 42 See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and
… …
145 arrays, maps 156 arrays, maps
146 CBOR arrays and CBOR maps will be converted into references to a 157 CBOR arrays and CBOR maps will be converted into references to a
147 Perl array or hash, respectively. The keys of the map will be 158 Perl array or hash, respectively. The keys of the map will be
148 stringified during this process. 159 stringified during this process.
149 160
150 true, false 161 null
151 These CBOR values become "CBOR::XS::true" and "CBOR::XS::false", 162 CBOR null becomes "undef" in Perl.
163
164 true, false, undefined
165 These CBOR values become "Types:Serialiser::true",
166 "Types:Serialiser::false" and "Types::Serialiser::error",
152 respectively. They are overloaded to act almost exactly like the 167 respectively. They are overloaded to act almost exactly like the
153 numbers 1 and 0. You can check whether a scalar is a CBOR boolean by 168 numbers 1 and 0 (for true and false) or to throw an exception on
154 using the "CBOR::XS::is_bool" function. 169 access (for error). See the Types::Serialiser manpage for details.
155 170
156 null, undefined 171 CBOR tag 256 (perl object)
157 CBOR null and undefined values becomes "undef" in Perl (in the 172 The tag value 256 (TODO: pending iana registration) will be used to
158 future, Undefined may raise an exception or something else). 173 deserialise a Perl object serialised with "FREEZE". See "OBJECT
174 SERIALISATION", below, for details.
159 175
160 tags 176 CBOR tag 55799 (magic header)
161 Tagged items consists of a numeric tag and another CBOR value. The
162 tag 55799 is ignored (this tag implements the magic header). 177 The tag 55799 is ignored (this tag implements the magic header).
163 178
164 All other tags are currently converted into a CBOR::XS::Tagged 179 other CBOR tags
180 Tagged items consists of a numeric tag and another CBOR value. Tags
181 not handled internally are currently converted into a
165 object, which is simply a blessed array reference consistsing of the 182 CBOR::XS::Tagged object, which is simply a blessed array reference
166 numeric tag value followed by the (decoded) BOR value. 183 consisting of the numeric tag value followed by the (decoded) CBOR
184 value.
185
186 In the future, support for user-supplied conversions might get
187 added.
167 188
168 anything else 189 anything else
169 Anything else (e.g. unsupported simple values) will raise a decoding 190 Anything else (e.g. unsupported simple values) will raise a decoding
170 error. 191 error.
171 192
… …
193 CBOR::XS::Tagged objects 214 CBOR::XS::Tagged objects
194 Objects of this type must be arrays consisting of a single "[tag, 215 Objects of this type must be arrays consisting of a single "[tag,
195 value]" pair. The (numerical) tag will be encoded as a CBOR tag, the 216 value]" pair. The (numerical) tag will be encoded as a CBOR tag, the
196 value will be encoded as appropriate for the value. 217 value will be encoded as appropriate for the value.
197 218
198 CBOR::XS::true, CBOR::XS::false 219 Types::Serialiser::true, Types::Serialiser::false,
220 Types::Serialiser::error
199 These special values become CBOR true and CBOR false values, 221 These special values become CBOR true, CBOR false and CBOR undefined
200 respectively. You can also use "\1" and "\0" directly if you want. 222 values, respectively. You can also use "\1", "\0" and "\undef"
223 directly if you want.
201 224
202 blessed objects 225 other blessed objects
203 Other blessed objects currently need to have a "TO_CBOR" method. It 226 Other blessed objects are serialised via "TO_CBOR" or "FREEZE". See
204 will be called on every object that is being serialised, and must 227 "OBJECT SERIALISATION", below, for details.
205 return something that can be encoded in CBOR.
206 228
207 simple scalars 229 simple scalars
208 TODO Simple Perl scalars (any scalar that is not a reference) are 230 TODO Simple Perl scalars (any scalar that is not a reference) are
209 the most difficult objects to encode: CBOR::XS will encode undefined 231 the most difficult objects to encode: CBOR::XS will encode undefined
210 scalars as CBOR null values, scalars that have last been used in a 232 scalars as CBOR null values, scalars that have last been used in a
… …
245 IEEE single format if possible without loss of precision, otherwise 267 IEEE single format if possible without loss of precision, otherwise
246 the IEEE double format will be used. Perls that use formats other 268 the IEEE double format will be used. Perls that use formats other
247 than IEEE double to represent numerical values are supported, but 269 than IEEE double to represent numerical values are supported, but
248 might suffer loss of precision. 270 might suffer loss of precision.
249 271
272 OBJECT SERIALISATION
273 This module knows two way to serialise a Perl object: The CBOR-specific
274 way, and the generic way.
275
276 Whenever the encoder encounters a Perl object that it cnanot serialise
277 directly (most of them), it will first look up the "TO_CBOR" method on
278 it.
279
280 If it has a "TO_CBOR" method, it will call it with the object as only
281 argument, and expects exactly one return value, which it will then
282 substitute and encode it in the place of the object.
283
284 Otherwise, it will look up the "FREEZE" method. If it exists, it will
285 call it with the object as first argument, and the constant string
286 "CBOR" as the second argument, to distinguish it from other serialisers.
287
288 The "FREEZE" method can return any number of values (i.e. zero or more).
289 These will be encoded as CBOR perl object, together with the classname.
290
291 If an object supports neither "TO_CBOR" nor "FREEZE", encoding will fail
292 with an error.
293
294 Objects encoded via "TO_CBOR" cannot be automatically decoded, but
295 objects encoded via "FREEZE" can be decoded using the following
296 protocol:
297
298 When an encoded CBOR perl object is encountered by the decoder, it will
299 look up the "THAW" method, by using the stored classname, and will fail
300 if the method cannot be found.
301
302 After the lookup it will call the "THAW" method with the stored
303 classname as first argument, the constant string "CBOR" as second
304 argument, and all values returned by "FREEZE" as remaining arguments.
305
306 EXAMPLES
307 Here is an example "TO_CBOR" method:
308
309 sub My::Object::TO_CBOR {
310 my ($obj) = @_;
311
312 ["this is a serialised My::Object object", $obj->{id}]
313 }
314
315 When a "My::Object" is encoded to CBOR, it will instead encode a simple
316 array with two members: a string, and the "object id". Decoding this
317 CBOR string will yield a normal perl array reference in place of the
318 object.
319
320 A more useful and practical example would be a serialisation method for
321 the URI module. CBOR has a custom tag value for URIs, namely 32:
322
323 sub URI::TO_CBOR {
324 my ($self) = @_;
325 my $uri = "$self"; # stringify uri
326 utf8::upgrade $uri; # make sure it will be encoded as UTF-8 string
327 CBOR::XS::tagged 32, "$_[0]"
328 }
329
330 This will encode URIs as a UTF-8 string with tag 32, which indicates an
331 URI.
332
333 Decoding such an URI will not (currently) give you an URI object, but
334 instead a CBOR::XS::Tagged object with tag number 32 and the string -
335 exactly what was returned by "TO_CBOR".
336
337 To serialise an object so it can automatically be deserialised, you need
338 to use "FREEZE" and "THAW". To take the URI module as example, this
339 would be a possible implementation:
340
341 sub URI::FREEZE {
342 my ($self, $serialiser) = @_;
343 "$self" # encode url string
344 }
345
346 sub URI::THAW {
347 my ($class, $serialiser, $uri) = @_;
348
349 $class->new ($uri)
350 }
351
352 Unlike "TO_CBOR", multiple values can be returned by "FREEZE". For
353 example, a "FREEZE" method that returns "type", "id" and "variant"
354 values would cause an invocation of "THAW" with 5 arguments:
355
356 sub My::Object::FREEZE {
357 my ($self, $serialiser) = @_;
358
359 ($self->{type}, $self->{id}, $self->{variant})
360 }
361
362 sub My::Object::THAW {
363 my ($class, $serialiser, $type, $id, $variant) = @_;
364
365 $class-<new (type => $type, id => $id, variant => $variant)
366 }
367
250 MAGIC HEADER 368MAGIC HEADER
251 There is no way to distinguish CBOR from other formats programmatically. 369 There is no way to distinguish CBOR from other formats programmatically.
252 To make it easier to distinguish CBOR from other formats, the CBOR 370 To make it easier to distinguish CBOR from other formats, the CBOR
253 specification has a special "magic string" that can be prepended to any 371 specification has a special "magic string" that can be prepended to any
254 CBOR string without changing it's meaning. 372 CBOR string without changing it's meaning.
255 373
256 This string is available as $CBOR::XS::MAGIC. This module does not 374 This string is available as $CBOR::XS::MAGIC. This module does not
257 prepend this string tot he CBOR data it generates, but it will ignroe it 375 prepend this string tot he CBOR data it generates, but it will ignroe it
258 if present, so users can prepend this string as a "file type" indicator 376 if present, so users can prepend this string as a "file type" indicator
259 as required. 377 as required.
260 378
261 CBOR and JSON 379CBOR and JSON
262 CBOR is supposed to implement a superset of the JSON data model, and is, 380 CBOR is supposed to implement a superset of the JSON data model, and is,
263 with some coercion, able to represent all JSON texts (something that 381 with some coercion, able to represent all JSON texts (something that
264 other "binary JSON" formats such as BSON generally do not support). 382 other "binary JSON" formats such as BSON generally do not support).
265 383
266 CBOR implements some extra hints and support for JSON interoperability, 384 CBOR implements some extra hints and support for JSON interoperability,
… …
340 458
341SEE ALSO 459SEE ALSO
342 The JSON and JSON::XS modules that do similar, but human-readable, 460 The JSON and JSON::XS modules that do similar, but human-readable,
343 serialisation. 461 serialisation.
344 462
463 The Types::Serialiser module provides the data model for true, false and
464 error values.
465
345AUTHOR 466AUTHOR
346 Marc Lehmann <schmorp@schmorp.de> 467 Marc Lehmann <schmorp@schmorp.de>
347 http://home.schmorp.de/ 468 http://home.schmorp.de/
348 469

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines