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

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.15 by root, Mon Apr 27 20:21:53 2015 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.15 by root, Mon Apr 27 20:21:53 2015 UTC