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

Comparing CBOR-XS/README (file contents):
Revision 1.6 by root, Mon Oct 28 21:28:14 2013 UTC vs.
Revision 1.14 by root, Sat Oct 25 06:36:34 2014 UTC

…		…
21	# data was decoded	21	# data was decoded
22	substr $many_cbor_strings, 0, $length, ""; # remove decoded cbor string	22	substr $many_cbor_strings, 0, $length, ""; # remove decoded cbor string
23	}	23	}
24		24
25	DESCRIPTION	25	DESCRIPTION
26	WARNING! This module is very new, and not very well tested (that's up to
27	you to do). Furthermore, details of the implementation might change
28	freely before version 1.0. And lastly, the object serialisation protocol
29	depends on a pending IANA assignment, and until that assignment is
30	official, this implementation is not interoperable with other
31	implementations (even future versions of this module) until the
32	assignment is done.
33
34	You are still invited to try out CBOR, and this module.
35
36	This module converts Perl data structures to the Concise Binary Object	26	This module converts Perl data structures to the Concise Binary Object
37	Representation (CBOR) and vice versa. CBOR is a fast binary	27	Representation (CBOR) and vice versa. CBOR is a fast binary
38	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
39	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
40	represent it in CBOR.	30	should be able to represent it in CBOR.
41		31
42	In short, CBOR is a faster and very compact binary alternative to JSON,	32	In short, CBOR is a faster and quite compact binary alternative to JSON,
43	with the added ability of supporting serialisation of Perl objects.	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).
44		51
45	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
46	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.
47		54
48	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
…		…
70	disabled.	77	disabled.
71		78
72	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
73	calls can be chained:	80	calls can be chained:
74		81
75	#TODO my $cbor = CBOR::XS->new->encode ({a => [1,2]});	82	my $cbor = CBOR::XS->new->encode ({a => [1,2]});
76		83
77	$cbor = $cbor->max_depth ([$maximum_nesting_depth])	84	$cbor = $cbor->max_depth ([$maximum_nesting_depth])
78	$max_depth = $cbor->get_max_depth	85	$max_depth = $cbor->get_max_depth
79	Sets the maximum nesting level (default 512) accepted while encoding	86	Sets the maximum nesting level (default 512) accepted while encoding
80	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
…		…
111	as when 0 is specified).	118	as when 0 is specified).
112		119
113	See SECURITY CONSIDERATIONS, below, for more info on why this is	120	See SECURITY CONSIDERATIONS, below, for more info on why this is
114	useful.	121	useful.
115		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
116	$cbor_data = $cbor->encode ($perl_scalar)	276	$cbor_data = $cbor->encode ($perl_scalar)
117	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
118	representation.	278	representation.
119		279
120	$perl_scalar = $cbor->decode ($cbor_data)	280	$perl_scalar = $cbor->decode ($cbor_data)
…		…
132	the next one starts.	292	the next one starts.
133		293
134	CBOR::XS->new->decode_prefix ("......")	294	CBOR::XS->new->decode_prefix ("......")
135	=> ("...", 3)	295	=> ("...", 3)
136		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
137	MAPPING	355	MAPPING
138	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
139	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
140	circumstances automatically, preserving round-tripping characteristics	358	circumstances automatically, preserving round-tripping characteristics
141	(what you put in comes out as something equivalent).	359	(what you put in comes out as something equivalent).
…		…
148	integers	366	integers
149	CBOR integers become (numeric) perl scalars. On perls without 64 bit	367	CBOR integers become (numeric) perl scalars. On perls without 64 bit
150	support, 64 bit integers will be truncated or otherwise corrupted.	368	support, 64 bit integers will be truncated or otherwise corrupted.
151		369
152	byte strings	370	byte strings
153	Byte strings will become octet strings in Perl (the byte values	371	Byte strings will become octet strings in Perl (the Byte values
154	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).
155		373
156	UTF-8 strings	374	UTF-8 strings
157	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
158	decoded into proper Unicode code points. At the moment, the validity	376	decoded into proper Unicode code points. At the moment, the validity
…		…
172	"Types:Serialiser::false" and "Types::Serialiser::error",	390	"Types:Serialiser::false" and "Types::Serialiser::error",
173	respectively. They are overloaded to act almost exactly like the	391	respectively. They are overloaded to act almost exactly like the
174	numbers 1 and 0 (for true and false) or to throw an exception on	392	numbers 1 and 0 (for true and false) or to throw an exception on
175	access (for error). See the Types::Serialiser manpage for details.	393	access (for error). See the Types::Serialiser manpage for details.
176		394
177	CBOR tag 256 (perl object)	395	tagged values
178	The tag value 256 (TODO: pending iana registration) will be used to
179	deserialise a Perl object serialised with "FREEZE". See "OBJECT
180	SERIALISATION", below, for details.
181
182	CBOR tag 55799 (magic header)
183	The tag 55799 is ignored (this tag implements the magic header).
184
185	other CBOR tags
186	Tagged items consists of a numeric tag and another CBOR value. Tags	396	Tagged items consists of a numeric tag and another CBOR value.
187	not handled internally are currently converted into a
188	CBOR::XS::Tagged object, which is simply a blessed array reference
189	consisting of the numeric tag value followed by the (decoded) CBOR
190	value.
191		397
192	In the future, support for user-supplied conversions might get	398	See "TAG HANDLING AND EXTENSIONS" and the description of "->filter"
193	added.	399	for details on which tags are handled how.
194		400
195	anything else	401	anything else
196	Anything else (e.g. unsupported simple values) will raise a decoding	402	Anything else (e.g. unsupported simple values) will raise a decoding
197	error.	403	error.
198		404
199	PERL -> CBOR	405	PERL -> CBOR
200	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
201	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
202	by a Perl value.	408	is meant by a perl value.
203		409
204	hash references	410	hash references
205	Perl hash references become CBOR maps. As there is no inherent	411	Perl hash references become CBOR maps. As there is no inherent
206	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
207	in a pseudo-random order.	413	in a pseudo-random order. This order can be different each time a
		414	hahs is encoded.
208		415
209	Currently, tied hashes will use the indefinite-length format, while	416	Currently, tied hashes will use the indefinite-length format, while
210	normal hashes will use the fixed-length format.	417	normal hashes will use the fixed-length format.
211		418
212	array references	419	array references
213	Perl array references become fixed-length CBOR arrays.	420	Perl array references become fixed-length CBOR arrays.
214		421
215	other references	422	other references
216	Other unblessed references are generally not allowed and will cause	423	Other unblessed references will be represented using the indirection
217	an exception to be thrown, except for references to the integers 0	424	tag extension (tag value 22098,
218	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.
219		429
220	CBOR::XS::Tagged objects	430	CBOR::XS::Tagged objects
221	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,
222	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
223	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.
224		435
225	Types::Serialiser::true, Types::Serialiser::false,	436	Types::Serialiser::true, Types::Serialiser::false,
226	Types::Serialiser::error	437	Types::Serialiser::error
227	These special values become CBOR true, CBOR false and CBOR undefined	438	These special values become CBOR true, CBOR false and CBOR undefined
228	values, respectively. You can also use "\1", "\0" and "\undef"	439	values, respectively. You can also use "\1", "\0" and "\undef"
229	directly if you want.	440	directly if you want.
230		441
231	other blessed objects	442	other blessed objects
232	Other blessed objects are serialised via "TO_CBOR" or "FREEZE". See	443	Other blessed objects are serialised via "TO_CBOR" or "FREEZE". See
233	"OBJECT SERIALISATION", below, for details.	444	"TAG HANDLING AND EXTENSIONS" for specific classes handled by this
		445	module, and "OBJECT SERIALISATION" for generic object serialisation.
234		446
235	simple scalars	447	simple scalars
236	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
237	the most difficult objects to encode: CBOR::XS will encode undefined	449	most difficult objects to encode: CBOR::XS will encode undefined
238	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
239	string context before encoding as CBOR strings, and anything else as	451	string context before encoding as CBOR strings, and anything else as
240	number value:	452	number value:
241		453
242	# dump as number	454	# dump as number
243	encode_cbor [2] # yields [2]	455	encode_cbor [2] # yields [2]
244	encode_cbor [-3.0e17] # yields [-3e+17]	456	encode_cbor [-3.0e17] # yields [-3e+17]
245	my $value = 5; encode_cbor [$value] # yields [5]	457	my $value = 5; encode_cbor [$value] # yields [5]
246		458
247	# used as string, so dump as string	459	# used as string, so dump as string (either byte or text)
248	print $value;	460	print $value;
249	encode_cbor [$value] # yields ["5"]	461	encode_cbor [$value] # yields ["5"]
250		462
251	# undef becomes null	463	# undef becomes null
252	encode_cbor [undef] # yields [null]	464	encode_cbor [undef] # yields [null]
…		…
255		467
256	my $x = 3.1; # some variable containing a number	468	my $x = 3.1; # some variable containing a number
257	"$x"; # stringified	469	"$x"; # stringified
258	$x .= ""; # another, more awkward way to stringify	470	$x .= ""; # another, more awkward way to stringify
259	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.
260		482
261	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:
262		484
263	my $x = "3"; # some variable containing a string	485	my $x = "3"; # some variable containing a string
264	$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
…		…
274	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
275	than IEEE double to represent numerical values are supported, but	497	than IEEE double to represent numerical values are supported, but
276	might suffer loss of precision.	498	might suffer loss of precision.
277		499
278	OBJECT SERIALISATION	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
279	This module knows two way to serialise a Perl object: The CBOR-specific	506	This module knows two way to serialise a Perl object: The CBOR-specific
280	way, and the generic way.	507	way, and the generic way.
281		508
282	Whenever the encoder encounters a Perl object that it cnanot serialise	509	Whenever the encoder encounters a Perl object that it cannot serialise
283	directly (most of them), it will first look up the "TO_CBOR" method on	510	directly (most of them), it will first look up the "TO_CBOR" method on
284	it.	511	it.
285		512
286	If it has a "TO_CBOR" method, it will call it with the object as only	513	If it has a "TO_CBOR" method, it will call it with the object as only
287	argument, and expects exactly one return value, which it will then	514	argument, and expects exactly one return value, which it will then
…		…
292	"CBOR" as the second argument, to distinguish it from other serialisers.	519	"CBOR" as the second argument, to distinguish it from other serialisers.
293		520
294	The "FREEZE" method can return any number of values (i.e. zero or more).	521	The "FREEZE" method can return any number of values (i.e. zero or more).
295	These will be encoded as CBOR perl object, together with the classname.	522	These will be encoded as CBOR perl object, together with the classname.
296		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
297	If an object supports neither "TO_CBOR" nor "FREEZE", encoding will fail	528	If an object supports neither "TO_CBOR" nor "FREEZE", encoding will fail
298	with an error.	529	with an error.
299		530
		531	DECODING
300	Objects encoded via "TO_CBOR" cannot be automatically decoded, but	532	Objects encoded via "TO_CBOR" cannot (normally) be automatically
301	objects encoded via "FREEZE" can be decoded using the following	533	decoded, but objects encoded via "FREEZE" can be decoded using the
302	protocol:	534	following protocol:
303		535
304	When an encoded CBOR perl object is encountered by the decoder, it will	536	When an encoded CBOR perl object is encountered by the decoder, it will
305	look up the "THAW" method, by using the stored classname, and will fail	537	look up the "THAW" method, by using the stored classname, and will fail
306	if the method cannot be found.	538	if the method cannot be found.
307		539
…		…
328		560
329	sub URI::TO_CBOR {	561	sub URI::TO_CBOR {
330	my ($self) = @_;	562	my ($self) = @_;
331	my $uri = "$self"; # stringify uri	563	my $uri = "$self"; # stringify uri
332	utf8::upgrade $uri; # make sure it will be encoded as UTF-8 string	564	utf8::upgrade $uri; # make sure it will be encoded as UTF-8 string
333	CBOR::XS::tagged 32, "$_[0]"	565	CBOR::XS::tag 32, "$_[0]"
334	}	566	}
335		567
336	This will encode URIs as a UTF-8 string with tag 32, which indicates an	568	This will encode URIs as a UTF-8 string with tag 32, which indicates an
337	URI.	569	URI.
338		570
…		…
373		605
374	MAGIC HEADER	606	MAGIC HEADER
375	There is no way to distinguish CBOR from other formats programmatically.	607	There is no way to distinguish CBOR from other formats programmatically.
376	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
377	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
378	CBOR string without changing it's meaning.	610	CBOR string without changing its meaning.
379		611
380	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
381	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
382	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
383	as required.	615	as required.
		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.
384		777
385	CBOR and JSON	778	CBOR and JSON
386	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,
387	with some coercion, able to represent all JSON texts (something that	780	with some coercion, able to represent all JSON texts (something that
388	other "binary JSON" formats such as BSON generally do not support).	781	other "binary JSON" formats such as BSON generally do not support).
…		…
444	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
445	encoded properly. Half precision types are accepted, but not encoded.	838	encoded properly. Half precision types are accepted, but not encoded.
446		839
447	Strict mode and canonical mode are not implemented.	840	Strict mode and canonical mode are not implemented.
448		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), support for any kind of 64 bit
		845	integer in CBOR is very limited - most likely, these 64 bit values will
		846	be truncated, corrupted, or otherwise not decoded correctly. This also
		847	includes string, array and map sizes that are stored as 64 bit integers.
		848
449	THREADS	849	THREADS
450	This module is not guaranteed to be thread safe and there are no plans	850	This module is not guaranteed to be thread safe and there are no plans
451	to change this until Perl gets thread support (as opposed to the	851	to change this until Perl gets thread support (as opposed to the
452	horribly slow so-called "threads" which are simply slow and bloated	852	horribly slow so-called "threads" which are simply slow and bloated
453	process simulations - use fork, it's much faster, cheaper, better).	853	process simulations - use fork, it's much faster, cheaper, better).

Diff Legend

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

Comparing CBOR-XS/README (file contents): Revision 1.6 by root, Mon Oct 28 21:28:14 2013 UTC vs. Revision 1.14 by root, Sat Oct 25 06:36:34 2014 UTC

Diff Legend

Comparing CBOR-XS/README (file contents):
Revision 1.6 by root, Mon Oct 28 21:28:14 2013 UTC vs.
Revision 1.14 by root, Sat Oct 25 06:36:34 2014 UTC