[ViewVC] Diff of: cvs/CBOR-XS/README

Comparing CBOR-XS/README (file contents):
Revision 1.4 by root, Sat Oct 26 23:02:55 2013 UTC vs.
Revision 1.13 by root, Sun Jan 5 14:24:54 2014 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
15	DESCRIPTION	25	DESCRIPTION
16	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
18	feature-limited, it might already be useful).
19
20	This module converts Perl data structures to the Concise Binary Object	26	This module converts Perl data structures to the Concise Binary Object
21	Representation (CBOR) and vice versa. CBOR is a fast binary	27	Representation (CBOR) and vice versa. CBOR is a fast binary
22	serialisation format that aims to use a superset of the JSON data model,	28	serialisation format that aims to use an (almost) superset of the JSON
23	i.e. when you can represent something in JSON, you should be able to	29	data model, i.e. when you can represent something useful in JSON, you
24	represent it in CBOR.	30	should be able to represent it in CBOR.
25		31
26	This makes it a faster and more compact binary alternative to JSON.	32	In short, CBOR is a faster and quite compact binary alternative to JSON,
		33	with the added ability of supporting serialisation of Perl objects.
		34	(JSON often compresses better than CBOR though, so if you plan to
		35	compress the data later and speed is less important you might want to
		36	compare both formats first).
		37
		38	To give you a general idea about speed, with texts in the megabyte
		39	range, "CBOR::XS" usually encodes roughly twice as fast as Storable or
		40	JSON::XS and decodes about 15%-30% faster than those. The shorter the
		41	data, the worse Storable performs in comparison.
		42
		43	Regarding compactness, "CBOR::XS"-encoded data structures are usually
		44	about 20% smaller than the same data encoded as (compact) JSON or
		45	Storable.
		46
		47	In addition to the core CBOR data format, this module implements a
		48	number of extensions, to support cyclic and shared data structures (see
		49	"allow_sharing" and "allow_cycles"), string deduplication (see
		50	"pack_strings") and scalar references (always enabled).
27		51
28	The primary goal of this module is to be correct and the secondary	52	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.	53	goal is to be fast. To reach the latter goal it was written in C.
30		54
31	See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and	55	See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and
…		…
53	disabled.	77	disabled.
54		78
55	The mutators for flags all return the CBOR object again and thus	79	The mutators for flags all return the CBOR object again and thus
56	calls can be chained:	80	calls can be chained:
57		81
58	#TODO my $cbor = CBOR::XS->new->encode ({a => [1,2]});	82	my $cbor = CBOR::XS->new->encode ({a => [1,2]});
59		83
60	$cbor = $cbor->max_depth ([$maximum_nesting_depth])	84	$cbor = $cbor->max_depth ([$maximum_nesting_depth])
61	$max_depth = $cbor->get_max_depth	85	$max_depth = $cbor->get_max_depth
62	Sets the maximum nesting level (default 512) accepted while encoding	86	Sets the maximum nesting level (default 512) accepted while encoding
63	or decoding. If a higher nesting level is detected in CBOR data or a	87	or decoding. If a higher nesting level is detected in CBOR data or a
…		…
94	as when 0 is specified).	118	as when 0 is specified).
95		119
96	See SECURITY CONSIDERATIONS, below, for more info on why this is	120	See SECURITY CONSIDERATIONS, below, for more info on why this is
97	useful.	121	useful.
98		122
		123	$cbor = $cbor->allow_unknown ([$enable])
		124	$enabled = $cbor->get_allow_unknown
		125	If $enable is true (or missing), then "encode" will not throw an
		126	exception when it encounters values it cannot represent in CBOR (for
		127	example, filehandles) but instead will encode a CBOR "error" value.
		128
		129	If $enable is false (the default), then "encode" will throw an
		130	exception when it encounters anything it cannot encode as CBOR.
		131
		132	This option does not affect "decode" in any way, and it is
		133	recommended to leave it off unless you know your communications
		134	partner.
		135
		136	$cbor = $cbor->allow_sharing ([$enable])
		137	$enabled = $cbor->get_allow_sharing
		138	If $enable is true (or missing), then "encode" will not
		139	double-encode values that have been referenced before (e.g. when the
		140	same object, such as an array, is referenced multiple times), but
		141	instead will emit a reference to the earlier value.
		142
		143	This means that such values will only be encoded once, and will not
		144	result in a deep cloning of the value on decode, in decoders
		145	supporting the value sharing extension. This also makes it possible
		146	to encode cyclic data structures (which need "allow_cycles" to ne
		147	enabled to be decoded by this module).
		148
		149	It is recommended to leave it off unless you know your communication
		150	partner supports the value sharing extensions to CBOR
		151	(<http://cbor.schmorp.de/value-sharing>), as without decoder
		152	support, the resulting data structure might be unusable.
		153
		154	Detecting shared values incurs a runtime overhead when values are
		155	encoded that have a reference counter large than one, and might
		156	unnecessarily increase the encoded size, as potentially shared
		157	values are encode as shareable whether or not they are actually
		158	shared.
		159
		160	At the moment, only targets of references can be shared (e.g.
		161	scalars, arrays or hashes pointed to by a reference). Weirder
		162	constructs, such as an array with multiple "copies" of the same
		163	string, which are hard but not impossible to create in Perl, are not
		164	supported (this is the same as with Storable).
		165
		166	If $enable is false (the default), then "encode" will encode shared
		167	data structures repeatedly, unsharing them in the process. Cyclic
		168	data structures cannot be encoded in this mode.
		169
		170	This option does not affect "decode" in any way - shared values and
		171	references will always be decoded properly if present.
		172
		173	$cbor = $cbor->allow_cycles ([$enable])
		174	$enabled = $cbor->get_allow_cycles
		175	If $enable is true (or missing), then "decode" will happily decode
		176	self-referential (cyclic) data structures. By default these will not
		177	be decoded, as they need manual cleanup to avoid memory leaks, so
		178	code that isn't prepared for this will not leak memory.
		179
		180	If $enable is false (the default), then "decode" will throw an error
		181	when it encounters a self-referential/cyclic data structure.
		182
		183	This option does not affect "encode" in any way - shared values and
		184	references will always be decoded properly if present.
		185
		186	$cbor = $cbor->pack_strings ([$enable])
		187	$enabled = $cbor->get_pack_strings
		188	If $enable is true (or missing), then "encode" will try not to
		189	encode the same string twice, but will instead encode a reference to
		190	the string instead. Depending on your data format, this can save a
		191	lot of space, but also results in a very large runtime overhead
		192	(expect encoding times to be 2-4 times as high as without).
		193
		194	It is recommended to leave it off unless you know your
		195	communications partner supports the stringref extension to CBOR
		196	(<http://cbor.schmorp.de/stringref>), as without decoder support,
		197	the resulting data structure might not be usable.
		198
		199	If $enable is false (the default), then "encode" will encode strings
		200	the standard CBOR way.
		201
		202	This option does not affect "decode" in any way - string references
		203	will always be decoded properly if present.
		204
		205	$cbor = $cbor->validate_utf8 ([$enable])
		206	$enabled = $cbor->get_validate_utf8
		207	If $enable is true (or missing), then "decode" will validate that
		208	elements (text strings) containing UTF-8 data in fact contain valid
		209	UTF-8 data (instead of blindly accepting it). This validation
		210	obviously takes extra time during decoding.
		211
		212	The concept of "valid UTF-8" used is perl's concept, which is a
		213	superset of the official UTF-8.
		214
		215	If $enable is false (the default), then "decode" will blindly accept
		216	UTF-8 data, marking them as valid UTF-8 in the resulting data
		217	structure regardless of whether thats true or not.
		218
		219	Perl isn't too happy about corrupted UTF-8 in strings, but should
		220	generally not crash or do similarly evil things. Extensions might be
		221	not so forgiving, so it's recommended to turn on this setting if you
		222	receive untrusted CBOR.
		223
		224	This option does not affect "encode" in any way - strings that are
		225	supposedly valid UTF-8 will simply be dumped into the resulting CBOR
		226	string without checking whether that is, in fact, true or not.
		227
		228	$cbor = $cbor->filter ([$cb->($tag, $value)])
		229	$cb_or_undef = $cbor->get_filter
		230	Sets or replaces the tagged value decoding filter (when $cb is
		231	specified) or clears the filter (if no argument or "undef" is
		232	provided).
		233
		234	The filter callback is called only during decoding, when a
		235	non-enforced tagged value has been decoded (see "TAG HANDLING AND
		236	EXTENSIONS" for a list of enforced tags). For specific tags, it's
		237	often better to provide a default converter using the
		238	%CBOR::XS::FILTER hash (see below).
		239
		240	The first argument is the numerical tag, the second is the (decoded)
		241	value that has been tagged.
		242
		243	The filter function should return either exactly one value, which
		244	will replace the tagged value in the decoded data structure, or no
		245	values, which will result in default handling, which currently means
		246	the decoder creates a "CBOR::XS::Tagged" object to hold the tag and
		247	the value.
		248
		249	When the filter is cleared (the default state), the default filter
		250	function, "CBOR::XS::default_filter", is used. This function simply
		251	looks up the tag in the %CBOR::XS::FILTER hash. If an entry exists
		252	it must be a code reference that is called with tag and value, and
		253	is responsible for decoding the value. If no entry exists, it
		254	returns no values.
		255
		256	Example: decode all tags not handled internally into
		257	"CBOR::XS::Tagged" objects, with no other special handling (useful
		258	when working with potentially "unsafe" CBOR data).
		259
		260	CBOR::XS->new->filter (sub { })->decode ($cbor_data);
		261
		262	Example: provide a global filter for tag 1347375694, converting the
		263	value into some string form.
		264
		265	$CBOR::XS::FILTER{1347375694} = sub {
		266	my ($tag, $value);
		267
		268	"tag 1347375694 value $value"
		269	};
		270
99	$cbor_data = $cbor->encode ($perl_scalar)	271	$cbor_data = $cbor->encode ($perl_scalar)
100	Converts the given Perl data structure (a scalar value) to its CBOR	272	Converts the given Perl data structure (a scalar value) to its CBOR
101	representation.	273	representation.
102		274
103	$perl_scalar = $cbor->decode ($cbor_data)	275	$perl_scalar = $cbor->decode ($cbor_data)
…		…
115	the next one starts.	287	the next one starts.
116		288
117	CBOR::XS->new->decode_prefix ("......")	289	CBOR::XS->new->decode_prefix ("......")
118	=> ("...", 3)	290	=> ("...", 3)
119		291
		292	INCREMENTAL PARSING
		293	In some cases, there is the need for incremental parsing of JSON texts.
		294	While this module always has to keep both CBOR text and resulting Perl
		295	data structure in memory at one time, it does allow you to parse a CBOR
		296	stream incrementally, using a similar to using "decode_prefix" to see if
		297	a full CBOR object is available, but is much more efficient.
		298
		299	It basically works by parsing as much of a CBOR string as possible - if
		300	the CBOR data is not complete yet, the pasrer will remember where it
		301	was, to be able to restart when more data has been accumulated. Once
		302	enough data is available to either decode a complete CBOR value or raise
		303	an error, a real decode will be attempted.
		304
		305	A typical use case would be a network protocol that consists of sending
		306	and receiving CBOR-encoded messages. The solution that works with CBOR
		307	and about anything else is by prepending a length to every CBOR value,
		308	so the receiver knows how many octets to read. More compact (and
		309	slightly slower) would be to just send CBOR values back-to-back, as
		310	"CBOR::XS" knows where a CBOR value ends, and doesn't need an explicit
		311	length.
		312
		313	The following methods help with this:
		314
		315	@decoded = $cbor->incr_parse ($buffer)
		316	This method attempts to decode exactly one CBOR value from the
		317	beginning of the given $buffer. The value is removed from the
		318	$buffer on success. When $buffer doesn't contain a complete value
		319	yet, it returns nothing. Finally, when the $buffer doesn't start
		320	with something that could ever be a valid CBOR value, it raises an
		321	exception, just as "decode" would. In the latter case the decoder
		322	state is undefined and must be reset before being able to parse
		323	further.
		324
		325	This method modifies the $buffer in place. When no CBOR value can be
		326	decoded, the decoder stores the current string offset. On the next
		327	call, continues decoding at the place where it stopped before. For
		328	this to make sense, the $buffer must begin with the same octets as
		329	on previous unsuccessful calls.
		330
		331	You can call this method in scalar context, in which case it either
		332	returns a decoded value or "undef". This makes it impossible to
		333	distinguish between CBOR null values (which decode to "undef") and
		334	an unsuccessful decode, which is often acceptable.
		335
		336	@decoded = $cbor->incr_parse_multiple ($buffer)
		337	Same as "incr_parse", but attempts to decode as many CBOR values as
		338	possible in one go, instead of at most one. Calls to "incr_parse"
		339	and "incr_parse_multiple" can be interleaved.
		340
		341	$cbor->incr_reset
		342	Resets the incremental decoder. This throws away any saved state, so
		343	that subsequent calls to "incr_parse" or "incr_parse_multiple" start
		344	to parse a new CBOR value from the beginning of the $buffer again.
		345
		346	This method can be caled at any time, but it must be called if you
		347	want to change your $buffer or there was a decoding error and you
		348	want to reuse the $cbor object for future incremental parsings.
		349
120	MAPPING	350	MAPPING
121	This section describes how CBOR::XS maps Perl values to CBOR values and	351	This section describes how CBOR::XS maps Perl values to CBOR values and
122	vice versa. These mappings are designed to "do the right thing" in most	352	vice versa. These mappings are designed to "do the right thing" in most
123	circumstances automatically, preserving round-tripping characteristics	353	circumstances automatically, preserving round-tripping characteristics
124	(what you put in comes out as something equivalent).	354	(what you put in comes out as something equivalent).
…		…
131	integers	361	integers
132	CBOR integers become (numeric) perl scalars. On perls without 64 bit	362	CBOR integers become (numeric) perl scalars. On perls without 64 bit
133	support, 64 bit integers will be truncated or otherwise corrupted.	363	support, 64 bit integers will be truncated or otherwise corrupted.
134		364
135	byte strings	365	byte strings
136	Byte strings will become octet strings in Perl (the byte values	366	Byte strings will become octet strings in Perl (the Byte values
137	0..255 will simply become characters of the same value in Perl).	367	0..255 will simply become characters of the same value in Perl).
138		368
139	UTF-8 strings	369	UTF-8 strings
140	UTF-8 strings in CBOR will be decoded, i.e. the UTF-8 octets will be	370	UTF-8 strings in CBOR will be decoded, i.e. the UTF-8 octets will be
141	decoded into proper Unicode code points. At the moment, the validity	371	decoded into proper Unicode code points. At the moment, the validity
…		…
145	arrays, maps	375	arrays, maps
146	CBOR arrays and CBOR maps will be converted into references to a	376	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	377	Perl array or hash, respectively. The keys of the map will be
148	stringified during this process.	378	stringified during this process.
149		379
150	true, false	380	null
151	These CBOR values become "CBOR::XS::true" and "CBOR::XS::false",	381	CBOR null becomes "undef" in Perl.
		382
		383	true, false, undefined
		384	These CBOR values become "Types:Serialiser::true",
		385	"Types:Serialiser::false" and "Types::Serialiser::error",
152	respectively. They are overloaded to act almost exactly like the	386	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	387	numbers 1 and 0 (for true and false) or to throw an exception on
154	using the "CBOR::XS::is_bool" function.	388	access (for error). See the Types::Serialiser manpage for details.
155		389
156	null, undefined	390	tagged values
157	CBOR null and undefined values becomes "undef" in Perl (in the
158	future, Undefined may raise an exception or something else).
159
160	tags
161	Tagged items consists of a numeric tag and another CBOR value. The	391	Tagged items consists of a numeric tag and another CBOR value.
162	tag 55799 is ignored (this tag implements the magic header).
163		392
164	All other tags are currently converted into a CBOR::XS::Tagged	393	See "TAG HANDLING AND EXTENSIONS" and the description of "->filter"
165	object, which is simply a blessed array reference consistsing of the	394	for details on which tags are handled how.
166	numeric tag value followed by the (decoded) BOR value.
167		395
168	anything else	396	anything else
169	Anything else (e.g. unsupported simple values) will raise a decoding	397	Anything else (e.g. unsupported simple values) will raise a decoding
170	error.	398	error.
171		399
172	PERL -> CBOR	400	PERL -> CBOR
173	The mapping from Perl to CBOR is slightly more difficult, as Perl is a	401	The mapping from Perl to CBOR is slightly more difficult, as Perl is a
174	truly typeless language, so we can only guess which CBOR type is meant	402	typeless language. That means this module can only guess which CBOR type
175	by a Perl value.	403	is meant by a perl value.
176		404
177	hash references	405	hash references
178	Perl hash references become CBOR maps. As there is no inherent	406	Perl hash references become CBOR maps. As there is no inherent
179	ordering in hash keys (or CBOR maps), they will usually be encoded	407	ordering in hash keys (or CBOR maps), they will usually be encoded
180	in a pseudo-random order.	408	in a pseudo-random order. This order can be different each time a
		409	hahs is encoded.
181		410
182	Currently, tied hashes will use the indefinite-length format, while	411	Currently, tied hashes will use the indefinite-length format, while
183	normal hashes will use the fixed-length format.	412	normal hashes will use the fixed-length format.
184		413
185	array references	414	array references
186	Perl array references become fixed-length CBOR arrays.	415	Perl array references become fixed-length CBOR arrays.
187		416
188	other references	417	other references
189	Other unblessed references are generally not allowed and will cause	418	Other unblessed references will be represented using the indirection
190	an exception to be thrown, except for references to the integers 0	419	tag extension (tag value 22098,
191	and 1, which get turned into false and true in CBOR.	420	<http://cbor.schmorp.de/indirection>). CBOR decoders are guaranteed
		421	to be able to decode these values somehow, by either "doing the
		422	right thing", decoding into a generic tagged object, simply ignoring
		423	the tag, or something else.
192		424
193	CBOR::XS::Tagged objects	425	CBOR::XS::Tagged objects
194	Objects of this type must be arrays consisting of a single "[tag,	426	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	427	value]" pair. The (numerical) tag will be encoded as a CBOR tag, the
196	value will be encoded as appropriate for the value.	428	value will be encoded as appropriate for the value. You must use
		429	"CBOR::XS::tag" to create such objects.
197		430
198	CBOR::XS::true, CBOR::XS::false	431	Types::Serialiser::true, Types::Serialiser::false,
		432	Types::Serialiser::error
199	These special values become CBOR true and CBOR false values,	433	These special values become CBOR true, CBOR false and CBOR undefined
200	respectively. You can also use "\1" and "\0" directly if you want.	434	values, respectively. You can also use "\1", "\0" and "\undef"
		435	directly if you want.
201		436
202	blessed objects	437	other blessed objects
203	Other blessed objects currently need to have a "TO_CBOR" method. It	438	Other blessed objects are serialised via "TO_CBOR" or "FREEZE". See
204	will be called on every object that is being serialised, and must	439	"TAG HANDLING AND EXTENSIONS" for specific classes handled by this
205	return something that can be encoded in CBOR.	440	module, and "OBJECT SERIALISATION" for generic object serialisation.
206		441
207	simple scalars	442	simple scalars
208	TODO Simple Perl scalars (any scalar that is not a reference) are	443	Simple Perl scalars (any scalar that is not a reference) are the
209	the most difficult objects to encode: CBOR::XS will encode undefined	444	most difficult objects to encode: CBOR::XS will encode undefined
210	scalars as CBOR null values, scalars that have last been used in a	445	scalars as CBOR null values, scalars that have last been used in a
211	string context before encoding as CBOR strings, and anything else as	446	string context before encoding as CBOR strings, and anything else as
212	number value:	447	number value:
213		448
214	# dump as number	449	# dump as number
215	encode_cbor [2] # yields [2]	450	encode_cbor [2] # yields [2]
216	encode_cbor [-3.0e17] # yields [-3e+17]	451	encode_cbor [-3.0e17] # yields [-3e+17]
217	my $value = 5; encode_cbor [$value] # yields [5]	452	my $value = 5; encode_cbor [$value] # yields [5]
218		453
219	# used as string, so dump as string	454	# used as string, so dump as string (either byte or text)
220	print $value;	455	print $value;
221	encode_cbor [$value] # yields ["5"]	456	encode_cbor [$value] # yields ["5"]
222		457
223	# undef becomes null	458	# undef becomes null
224	encode_cbor [undef] # yields [null]	459	encode_cbor [undef] # yields [null]
…		…
227		462
228	my $x = 3.1; # some variable containing a number	463	my $x = 3.1; # some variable containing a number
229	"$x"; # stringified	464	"$x"; # stringified
230	$x .= ""; # another, more awkward way to stringify	465	$x .= ""; # another, more awkward way to stringify
231	print $x; # perl does it for you, too, quite often	466	print $x; # perl does it for you, too, quite often
		467
		468	You can force whether a string ie encoded as byte or text string by
		469	using "utf8::upgrade" and "utf8::downgrade"):
		470
		471	utf8::upgrade $x; # encode $x as text string
		472	utf8::downgrade $x; # encode $x as byte string
		473
		474	Perl doesn't define what operations up- and downgrade strings, so if
		475	the difference between byte and text is important, you should up- or
		476	downgrade your string as late as possible before encoding.
232		477
233	You can force the type to be a CBOR number by numifying it:	478	You can force the type to be a CBOR number by numifying it:
234		479
235	my $x = "3"; # some variable containing a string	480	my $x = "3"; # some variable containing a string
236	$x += 0; # numify it, ensuring it will be dumped as a number	481	$x += 0; # numify it, ensuring it will be dumped as a number
…		…
245	IEEE single format if possible without loss of precision, otherwise	490	IEEE single format if possible without loss of precision, otherwise
246	the IEEE double format will be used. Perls that use formats other	491	the IEEE double format will be used. Perls that use formats other
247	than IEEE double to represent numerical values are supported, but	492	than IEEE double to represent numerical values are supported, but
248	might suffer loss of precision.	493	might suffer loss of precision.
249		494
		495	OBJECT SERIALISATION
		496	This module implements both a CBOR-specific and the generic
		497	Types::Serialier object serialisation protocol. The following
		498	subsections explain both methods.
		499
		500	ENCODING
		501	This module knows two way to serialise a Perl object: The CBOR-specific
		502	way, and the generic way.
		503
		504	Whenever the encoder encounters a Perl object that it cannot serialise
		505	directly (most of them), it will first look up the "TO_CBOR" method on
		506	it.
		507
		508	If it has a "TO_CBOR" method, it will call it with the object as only
		509	argument, and expects exactly one return value, which it will then
		510	substitute and encode it in the place of the object.
		511
		512	Otherwise, it will look up the "FREEZE" method. If it exists, it will
		513	call it with the object as first argument, and the constant string
		514	"CBOR" as the second argument, to distinguish it from other serialisers.
		515
		516	The "FREEZE" method can return any number of values (i.e. zero or more).
		517	These will be encoded as CBOR perl object, together with the classname.
		518
		519	These methods MUST NOT change the data structure that is being
		520	serialised. Failure to comply to this can result in memory corruption -
		521	and worse.
		522
		523	If an object supports neither "TO_CBOR" nor "FREEZE", encoding will fail
		524	with an error.
		525
		526	DECODING
		527	Objects encoded via "TO_CBOR" cannot (normally) be automatically
		528	decoded, but objects encoded via "FREEZE" can be decoded using the
		529	following protocol:
		530
		531	When an encoded CBOR perl object is encountered by the decoder, it will
		532	look up the "THAW" method, by using the stored classname, and will fail
		533	if the method cannot be found.
		534
		535	After the lookup it will call the "THAW" method with the stored
		536	classname as first argument, the constant string "CBOR" as second
		537	argument, and all values returned by "FREEZE" as remaining arguments.
		538
		539	EXAMPLES
		540	Here is an example "TO_CBOR" method:
		541
		542	sub My::Object::TO_CBOR {
		543	my ($obj) = @_;
		544
		545	["this is a serialised My::Object object", $obj->{id}]
		546	}
		547
		548	When a "My::Object" is encoded to CBOR, it will instead encode a simple
		549	array with two members: a string, and the "object id". Decoding this
		550	CBOR string will yield a normal perl array reference in place of the
		551	object.
		552
		553	A more useful and practical example would be a serialisation method for
		554	the URI module. CBOR has a custom tag value for URIs, namely 32:
		555
		556	sub URI::TO_CBOR {
		557	my ($self) = @_;
		558	my $uri = "$self"; # stringify uri
		559	utf8::upgrade $uri; # make sure it will be encoded as UTF-8 string
		560	CBOR::XS::tag 32, "$_[0]"
		561	}
		562
		563	This will encode URIs as a UTF-8 string with tag 32, which indicates an
		564	URI.
		565
		566	Decoding such an URI will not (currently) give you an URI object, but
		567	instead a CBOR::XS::Tagged object with tag number 32 and the string -
		568	exactly what was returned by "TO_CBOR".
		569
		570	To serialise an object so it can automatically be deserialised, you need
		571	to use "FREEZE" and "THAW". To take the URI module as example, this
		572	would be a possible implementation:
		573
		574	sub URI::FREEZE {
		575	my ($self, $serialiser) = @_;
		576	"$self" # encode url string
		577	}
		578
		579	sub URI::THAW {
		580	my ($class, $serialiser, $uri) = @_;
		581
		582	$class->new ($uri)
		583	}
		584
		585	Unlike "TO_CBOR", multiple values can be returned by "FREEZE". For
		586	example, a "FREEZE" method that returns "type", "id" and "variant"
		587	values would cause an invocation of "THAW" with 5 arguments:
		588
		589	sub My::Object::FREEZE {
		590	my ($self, $serialiser) = @_;
		591
		592	($self->{type}, $self->{id}, $self->{variant})
		593	}
		594
		595	sub My::Object::THAW {
		596	my ($class, $serialiser, $type, $id, $variant) = @_;
		597
		598	$class-<new (type => $type, id => $id, variant => $variant)
		599	}
		600
250	MAGIC HEADER	601	MAGIC HEADER
251	There is no way to distinguish CBOR from other formats programmatically.	602	There is no way to distinguish CBOR from other formats programmatically.
252	To make it easier to distinguish CBOR from other formats, the CBOR	603	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	604	specification has a special "magic string" that can be prepended to any
254	CBOR string without changing it's meaning.	605	CBOR string without changing its meaning.
255		606
256	This string is available as $CBOR::XS::MAGIC. This module does not	607	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	608	prepend this string to the CBOR data it generates, but it will ignore it
258	if present, so users can prepend this string as a "file type" indicator	609	if present, so users can prepend this string as a "file type" indicator
259	as required.	610	as required.
260		611
		612	THE CBOR::XS::Tagged CLASS
		613	CBOR has the concept of tagged values - any CBOR value can be tagged
		614	with a numeric 64 bit number, which are centrally administered.
		615
		616	"CBOR::XS" handles a few tags internally when en- or decoding. You can
		617	also create tags yourself by encoding "CBOR::XS::Tagged" objects, and
		618	the decoder will create "CBOR::XS::Tagged" objects itself when it hits
		619	an unknown tag.
		620
		621	These objects are simply blessed array references - the first member of
		622	the array being the numerical tag, the second being the value.
		623
		624	You can interact with "CBOR::XS::Tagged" objects in the following ways:
		625
		626	$tagged = CBOR::XS::tag $tag, $value
		627	This function(!) creates a new "CBOR::XS::Tagged" object using the
		628	given $tag (0..2**64-1) to tag the given $value (which can be any
		629	Perl value that can be encoded in CBOR, including serialisable Perl
		630	objects and "CBOR::XS::Tagged" objects).
		631
		632	$tagged->[0]
		633	$tagged->[0] = $new_tag
		634	$tag = $tagged->tag
		635	$new_tag = $tagged->tag ($new_tag)
		636	Access/mutate the tag.
		637
		638	$tagged->[1]
		639	$tagged->[1] = $new_value
		640	$value = $tagged->value
		641	$new_value = $tagged->value ($new_value)
		642	Access/mutate the tagged value.
		643
		644	EXAMPLES
		645	Here are some examples of "CBOR::XS::Tagged" uses to tag objects.
		646
		647	You can look up CBOR tag value and emanings in the IANA registry at
		648	<http://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml>.
		649
		650	Prepend a magic header ($CBOR::XS::MAGIC):
		651
		652	my $cbor = encode_cbor CBOR::XS::tag 55799, $value;
		653	# same as:
		654	my $cbor = $CBOR::XS::MAGIC . encode_cbor $value;
		655
		656	Serialise some URIs and a regex in an array:
		657
		658	my $cbor = encode_cbor [
		659	(CBOR::XS::tag 32, "http://www.nethype.de/"),
		660	(CBOR::XS::tag 32, "http://software.schmorp.de/"),
		661	(CBOR::XS::tag 35, "^[Pp][Ee][Rr][lL]\$"),
		662	];
		663
		664	Wrap CBOR data in CBOR:
		665
		666	my $cbor_cbor = encode_cbor
		667	CBOR::XS::tag 24,
		668	encode_cbor [1, 2, 3];
		669
		670	TAG HANDLING AND EXTENSIONS
		671	This section describes how this module handles specific tagged values
		672	and extensions. If a tag is not mentioned here and no additional filters
		673	are provided for it, then the default handling applies (creating a
		674	CBOR::XS::Tagged object on decoding, and only encoding the tag when
		675	explicitly requested).
		676
		677	Tags not handled specifically are currently converted into a
		678	CBOR::XS::Tagged object, which is simply a blessed array reference
		679	consisting of the numeric tag value followed by the (decoded) CBOR
		680	value.
		681
		682	Future versions of this module reserve the right to special case
		683	additional tags (such as base64url).
		684
		685	ENFORCED TAGS
		686	These tags are always handled when decoding, and their handling cannot
		687	be overriden by the user.
		688
		689	26 (perl-object, <http://cbor.schmorp.de/perl-object>)
		690	These tags are automatically created (and decoded) for serialisable
		691	objects using the "FREEZE/THAW" methods (the Types::Serialier object
		692	serialisation protocol). See "OBJECT SERIALISATION" for details.
		693
		694	28, 29 (shareable, sharedref, L <http://cbor.schmorp.de/value-sharing>)
		695	These tags are automatically decoded when encountered (and they do
		696	not result in a cyclic data structure, see "allow_cycles"),
		697	resulting in shared values in the decoded object. They are only
		698	encoded, however, when "allow_sharing" is enabled.
		699
		700	Not all shared values can be successfully decoded: values that
		701	reference themselves will currently decode as "undef" (this is not
		702	the same as a reference pointing to itself, which will be
		703	represented as a value that contains an indirect reference to itself
		704	- these will be decoded properly).
		705
		706	Note that considerably more shared value data structures can be
		707	decoded than will be encoded - currently, only values pointed to by
		708	references will be shared, others will not. While non-reference
		709	shared values can be generated in Perl with some effort, they were
		710	considered too unimportant to be supported in the encoder. The
		711	decoder, however, will decode these values as shared values.
		712
		713	256, 25 (stringref-namespace, stringref, L
		714	<http://cbor.schmorp.de/stringref>)
		715	These tags are automatically decoded when encountered. They are only
		716	encoded, however, when "pack_strings" is enabled.
		717
		718	22098 (indirection, <http://cbor.schmorp.de/indirection>)
		719	This tag is automatically generated when a reference are encountered
		720	(with the exception of hash and array refernces). It is converted to
		721	a reference when decoding.
		722
		723	55799 (self-describe CBOR, RFC 7049)
		724	This value is not generated on encoding (unless explicitly requested
		725	by the user), and is simply ignored when decoding.
		726
		727	NON-ENFORCED TAGS
		728	These tags have default filters provided when decoding. Their handling
		729	can be overriden by changing the %CBOR::XS::FILTER entry for the tag, or
		730	by providing a custom "filter" callback when decoding.
		731
		732	When they result in decoding into a specific Perl class, the module
		733	usually provides a corresponding "TO_CBOR" method as well.
		734
		735	When any of these need to load additional modules that are not part of
		736	the perl core distribution (e.g. URI), it is (currently) up to the user
		737	to provide these modules. The decoding usually fails with an exception
		738	if the required module cannot be loaded.
		739
		740	0, 1 (date/time string, seconds since the epoch)
		741	These tags are decoded into Time::Piece objects. The corresponding
		742	"Time::Piece::TO_CBOR" method always encodes into tag 1 values
		743	currently.
		744
		745	The Time::Piece API is generally surprisingly bad, and fractional
		746	seconds are only accidentally kept intact, so watch out. On the plus
		747	side, the module comes with perl since 5.10, which has to count for
		748	something.
		749
		750	2, 3 (positive/negative bignum)
		751	These tags are decoded into Math::BigInt objects. The corresponding
		752	"Math::BigInt::TO_CBOR" method encodes "small" bigints into normal
		753	CBOR integers, and others into positive/negative CBOR bignums.
		754
		755	4, 5 (decimal fraction/bigfloat)
		756	Both decimal fractions and bigfloats are decoded into Math::BigFloat
		757	objects. The corresponding "Math::BigFloat::TO_CBOR" method always
		758	encodes into a decimal fraction.
		759
		760	CBOR cannot represent bigfloats with very large exponents -
		761	conversion of such big float objects is undefined.
		762
		763	Also, NaN and infinities are not encoded properly.
		764
		765	21, 22, 23 (expected later JSON conversion)
		766	CBOR::XS is not a CBOR-to-JSON converter, and will simply ignore
		767	these tags.
		768
		769	32 (URI)
		770	These objects decode into URI objects. The corresponding
		771	"URI::TO_CBOR" method again results in a CBOR URI value.
		772
261	CBOR and JSON	773	CBOR and JSON
262	CBOR is supposed to implement a superset of the JSON data model, and is,	774	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	775	with some coercion, able to represent all JSON texts (something that
264	other "binary JSON" formats such as BSON generally do not support).	776	other "binary JSON" formats such as BSON generally do not support).
265		777
266	CBOR implements some extra hints and support for JSON interoperability,	778	CBOR implements some extra hints and support for JSON interoperability,
…		…
320	uses long double to represent floating point values, they might not be	832	uses long double to represent floating point values, they might not be
321	encoded properly. Half precision types are accepted, but not encoded.	833	encoded properly. Half precision types are accepted, but not encoded.
322		834
323	Strict mode and canonical mode are not implemented.	835	Strict mode and canonical mode are not implemented.
324		836
		837	LIMITATIONS ON PERLS WITHOUT 64-BIT INTEGER SUPPORT
		838	On perls that were built without 64 bit integer support (these are rare
		839	nowadays, even on 32 bit architectures), support for any kind of 64 bit
		840	integer in CBOR is very limited - most likely, these 64 bit values will
		841	be truncated, corrupted, or otherwise not decoded correctly. This also
		842	includes string, array and map sizes that are stored as 64 bit integers.
		843
325	THREADS	844	THREADS
326	This module is not guaranteed to be thread safe and there are no plans	845	This module is not guaranteed to be thread safe and there are no plans
327	to change this until Perl gets thread support (as opposed to the	846	to change this until Perl gets thread support (as opposed to the
328	horribly slow so-called "threads" which are simply slow and bloated	847	horribly slow so-called "threads" which are simply slow and bloated
329	process simulations - use fork, it's much faster, cheaper, better).	848	process simulations - use fork, it's much faster, cheaper, better).
…		…
340		859
341	SEE ALSO	860	SEE ALSO
342	The JSON and JSON::XS modules that do similar, but human-readable,	861	The JSON and JSON::XS modules that do similar, but human-readable,
343	serialisation.	862	serialisation.
344		863
		864	The Types::Serialiser module provides the data model for true, false and
		865	error values.
		866
345	AUTHOR	867	AUTHOR
346	Marc Lehmann <schmorp@schmorp.de>	868	Marc Lehmann <schmorp@schmorp.de>
347	http://home.schmorp.de/	869	http://home.schmorp.de/
348		870

Diff Legend

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

Comparing CBOR-XS/README (file contents): Revision 1.4 by root, Sat Oct 26 23:02:55 2013 UTC vs. Revision 1.13 by root, Sun Jan 5 14:24:54 2014 UTC

Diff Legend

Comparing CBOR-XS/README (file contents):
Revision 1.4 by root, Sat Oct 26 23:02:55 2013 UTC vs.
Revision 1.13 by root, Sun Jan 5 14:24:54 2014 UTC