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

Comparing CBOR-XS/README (file contents):
Revision 1.5 by root, Sun Oct 27 22:48:12 2013 UTC vs.
Revision 1.13 by root, Sun Jan 5 14:24:54 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 IS A PRE-ALPHA RELEASE! IT WILL CRASH, CORRUPT YOUR DATA
27	AND EAT YOUR CHILDREN! (Actually, apart from being untested and a bit
28	feature-limited, it might already be useful).
29
30	This module converts Perl data structures to the Concise Binary Object	26	This module converts Perl data structures to the Concise Binary Object
31	Representation (CBOR) and vice versa. CBOR is a fast binary	27	Representation (CBOR) and vice versa. CBOR is a fast binary
32	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
33	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
34	represent it in CBOR.	30	should be able to represent it in CBOR.
35		31
36	This makes it a faster and more compact binary alternative to JSON, with	32	In short, CBOR is a faster and quite compact binary alternative to JSON,
37	the added ability of supporting serialising 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).
38		51
39	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
40	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.
41		54
42	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
…		…
64	disabled.	77	disabled.
65		78
66	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
67	calls can be chained:	80	calls can be chained:
68		81
69	#TODO my $cbor = CBOR::XS->new->encode ({a => [1,2]});	82	my $cbor = CBOR::XS->new->encode ({a => [1,2]});
70		83
71	$cbor = $cbor->max_depth ([$maximum_nesting_depth])	84	$cbor = $cbor->max_depth ([$maximum_nesting_depth])
72	$max_depth = $cbor->get_max_depth	85	$max_depth = $cbor->get_max_depth
73	Sets the maximum nesting level (default 512) accepted while encoding	86	Sets the maximum nesting level (default 512) accepted while encoding
74	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
…		…
105	as when 0 is specified).	118	as when 0 is specified).
106		119
107	See SECURITY CONSIDERATIONS, below, for more info on why this is	120	See SECURITY CONSIDERATIONS, below, for more info on why this is
108	useful.	121	useful.
109		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
110	$cbor_data = $cbor->encode ($perl_scalar)	271	$cbor_data = $cbor->encode ($perl_scalar)
111	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
112	representation.	273	representation.
113		274
114	$perl_scalar = $cbor->decode ($cbor_data)	275	$perl_scalar = $cbor->decode ($cbor_data)
…		…
126	the next one starts.	287	the next one starts.
127		288
128	CBOR::XS->new->decode_prefix ("......")	289	CBOR::XS->new->decode_prefix ("......")
129	=> ("...", 3)	290	=> ("...", 3)
130		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
131	MAPPING	350	MAPPING
132	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
133	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
134	circumstances automatically, preserving round-tripping characteristics	353	circumstances automatically, preserving round-tripping characteristics
135	(what you put in comes out as something equivalent).	354	(what you put in comes out as something equivalent).
…		…
142	integers	361	integers
143	CBOR integers become (numeric) perl scalars. On perls without 64 bit	362	CBOR integers become (numeric) perl scalars. On perls without 64 bit
144	support, 64 bit integers will be truncated or otherwise corrupted.	363	support, 64 bit integers will be truncated or otherwise corrupted.
145		364
146	byte strings	365	byte strings
147	Byte strings will become octet strings in Perl (the byte values	366	Byte strings will become octet strings in Perl (the Byte values
148	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).
149		368
150	UTF-8 strings	369	UTF-8 strings
151	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
152	decoded into proper Unicode code points. At the moment, the validity	371	decoded into proper Unicode code points. At the moment, the validity
…		…
166	"Types:Serialiser::false" and "Types::Serialiser::error",	385	"Types:Serialiser::false" and "Types::Serialiser::error",
167	respectively. They are overloaded to act almost exactly like the	386	respectively. They are overloaded to act almost exactly like the
168	numbers 1 and 0 (for true and false) or to throw an exception on	387	numbers 1 and 0 (for true and false) or to throw an exception on
169	access (for error). See the Types::Serialiser manpage for details.	388	access (for error). See the Types::Serialiser manpage for details.
170		389
171	CBOR tag 256 (perl object)	390	tagged values
172	The tag value 256 (TODO: pending iana registration) will be used to
173	deserialise a Perl object serialised with "FREEZE". See "OBJECT
174	SERIALISATION", below, for details.
175
176	CBOR tag 55799 (magic header)
177	The tag 55799 is ignored (this tag implements the magic header).
178
179	other CBOR tags
180	Tagged items consists of a numeric tag and another CBOR value. Tags	391	Tagged items consists of a numeric tag and another CBOR value.
181	not handled internally are currently converted into a
182	CBOR::XS::Tagged object, which is simply a blessed array reference
183	consisting of the numeric tag value followed by the (decoded) CBOR
184	value.
185		392
186	In the future, support for user-supplied conversions might get	393	See "TAG HANDLING AND EXTENSIONS" and the description of "->filter"
187	added.	394	for details on which tags are handled how.
188		395
189	anything else	396	anything else
190	Anything else (e.g. unsupported simple values) will raise a decoding	397	Anything else (e.g. unsupported simple values) will raise a decoding
191	error.	398	error.
192		399
193	PERL -> CBOR	400	PERL -> CBOR
194	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
195	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
196	by a Perl value.	403	is meant by a perl value.
197		404
198	hash references	405	hash references
199	Perl hash references become CBOR maps. As there is no inherent	406	Perl hash references become CBOR maps. As there is no inherent
200	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
201	in a pseudo-random order.	408	in a pseudo-random order. This order can be different each time a
		409	hahs is encoded.
202		410
203	Currently, tied hashes will use the indefinite-length format, while	411	Currently, tied hashes will use the indefinite-length format, while
204	normal hashes will use the fixed-length format.	412	normal hashes will use the fixed-length format.
205		413
206	array references	414	array references
207	Perl array references become fixed-length CBOR arrays.	415	Perl array references become fixed-length CBOR arrays.
208		416
209	other references	417	other references
210	Other unblessed references are generally not allowed and will cause	418	Other unblessed references will be represented using the indirection
211	an exception to be thrown, except for references to the integers 0	419	tag extension (tag value 22098,
212	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.
213		424
214	CBOR::XS::Tagged objects	425	CBOR::XS::Tagged objects
215	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,
216	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
217	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.
218		430
219	Types::Serialiser::true, Types::Serialiser::false,	431	Types::Serialiser::true, Types::Serialiser::false,
220	Types::Serialiser::error	432	Types::Serialiser::error
221	These special values become CBOR true, CBOR false and CBOR undefined	433	These special values become CBOR true, CBOR false and CBOR undefined
222	values, respectively. You can also use "\1", "\0" and "\undef"	434	values, respectively. You can also use "\1", "\0" and "\undef"
223	directly if you want.	435	directly if you want.
224		436
225	other blessed objects	437	other blessed objects
226	Other blessed objects are serialised via "TO_CBOR" or "FREEZE". See	438	Other blessed objects are serialised via "TO_CBOR" or "FREEZE". See
227	"OBJECT SERIALISATION", below, for details.	439	"TAG HANDLING AND EXTENSIONS" for specific classes handled by this
		440	module, and "OBJECT SERIALISATION" for generic object serialisation.
228		441
229	simple scalars	442	simple scalars
230	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
231	the most difficult objects to encode: CBOR::XS will encode undefined	444	most difficult objects to encode: CBOR::XS will encode undefined
232	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
233	string context before encoding as CBOR strings, and anything else as	446	string context before encoding as CBOR strings, and anything else as
234	number value:	447	number value:
235		448
236	# dump as number	449	# dump as number
237	encode_cbor [2] # yields [2]	450	encode_cbor [2] # yields [2]
238	encode_cbor [-3.0e17] # yields [-3e+17]	451	encode_cbor [-3.0e17] # yields [-3e+17]
239	my $value = 5; encode_cbor [$value] # yields [5]	452	my $value = 5; encode_cbor [$value] # yields [5]
240		453
241	# used as string, so dump as string	454	# used as string, so dump as string (either byte or text)
242	print $value;	455	print $value;
243	encode_cbor [$value] # yields ["5"]	456	encode_cbor [$value] # yields ["5"]
244		457
245	# undef becomes null	458	# undef becomes null
246	encode_cbor [undef] # yields [null]	459	encode_cbor [undef] # yields [null]
…		…
249		462
250	my $x = 3.1; # some variable containing a number	463	my $x = 3.1; # some variable containing a number
251	"$x"; # stringified	464	"$x"; # stringified
252	$x .= ""; # another, more awkward way to stringify	465	$x .= ""; # another, more awkward way to stringify
253	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.
254		477
255	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:
256		479
257	my $x = "3"; # some variable containing a string	480	my $x = "3"; # some variable containing a string
258	$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
…		…
268	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
269	than IEEE double to represent numerical values are supported, but	492	than IEEE double to represent numerical values are supported, but
270	might suffer loss of precision.	493	might suffer loss of precision.
271		494
272	OBJECT SERIALISATION	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
273	This module knows two way to serialise a Perl object: The CBOR-specific	501	This module knows two way to serialise a Perl object: The CBOR-specific
274	way, and the generic way.	502	way, and the generic way.
275		503
276	Whenever the encoder encounters a Perl object that it cnanot serialise	504	Whenever the encoder encounters a Perl object that it cannot serialise
277	directly (most of them), it will first look up the "TO_CBOR" method on	505	directly (most of them), it will first look up the "TO_CBOR" method on
278	it.	506	it.
279		507
280	If it has a "TO_CBOR" method, it will call it with the object as only	508	If it has a "TO_CBOR" method, it will call it with the object as only
281	argument, and expects exactly one return value, which it will then	509	argument, and expects exactly one return value, which it will then
…		…
286	"CBOR" as the second argument, to distinguish it from other serialisers.	514	"CBOR" as the second argument, to distinguish it from other serialisers.
287		515
288	The "FREEZE" method can return any number of values (i.e. zero or more).	516	The "FREEZE" method can return any number of values (i.e. zero or more).
289	These will be encoded as CBOR perl object, together with the classname.	517	These will be encoded as CBOR perl object, together with the classname.
290		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
291	If an object supports neither "TO_CBOR" nor "FREEZE", encoding will fail	523	If an object supports neither "TO_CBOR" nor "FREEZE", encoding will fail
292	with an error.	524	with an error.
293		525
		526	DECODING
294	Objects encoded via "TO_CBOR" cannot be automatically decoded, but	527	Objects encoded via "TO_CBOR" cannot (normally) be automatically
295	objects encoded via "FREEZE" can be decoded using the following	528	decoded, but objects encoded via "FREEZE" can be decoded using the
296	protocol:	529	following protocol:
297		530
298	When an encoded CBOR perl object is encountered by the decoder, it will	531	When an encoded CBOR perl object is encountered by the decoder, it will
299	look up the "THAW" method, by using the stored classname, and will fail	532	look up the "THAW" method, by using the stored classname, and will fail
300	if the method cannot be found.	533	if the method cannot be found.
301		534
…		…
322		555
323	sub URI::TO_CBOR {	556	sub URI::TO_CBOR {
324	my ($self) = @_;	557	my ($self) = @_;
325	my $uri = "$self"; # stringify uri	558	my $uri = "$self"; # stringify uri
326	utf8::upgrade $uri; # make sure it will be encoded as UTF-8 string	559	utf8::upgrade $uri; # make sure it will be encoded as UTF-8 string
327	CBOR::XS::tagged 32, "$_[0]"	560	CBOR::XS::tag 32, "$_[0]"
328	}	561	}
329		562
330	This will encode URIs as a UTF-8 string with tag 32, which indicates an	563	This will encode URIs as a UTF-8 string with tag 32, which indicates an
331	URI.	564	URI.
332		565
…		…
367		600
368	MAGIC HEADER	601	MAGIC HEADER
369	There is no way to distinguish CBOR from other formats programmatically.	602	There is no way to distinguish CBOR from other formats programmatically.
370	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
371	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
372	CBOR string without changing it's meaning.	605	CBOR string without changing its meaning.
373		606
374	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
375	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
376	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
377	as required.	610	as required.
		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.
378		772
379	CBOR and JSON	773	CBOR and JSON
380	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,
381	with some coercion, able to represent all JSON texts (something that	775	with some coercion, able to represent all JSON texts (something that
382	other "binary JSON" formats such as BSON generally do not support).	776	other "binary JSON" formats such as BSON generally do not support).
…		…
438	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
439	encoded properly. Half precision types are accepted, but not encoded.	833	encoded properly. Half precision types are accepted, but not encoded.
440		834
441	Strict mode and canonical mode are not implemented.	835	Strict mode and canonical mode are not implemented.
442		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
443	THREADS	844	THREADS
444	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
445	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
446	horribly slow so-called "threads" which are simply slow and bloated	847	horribly slow so-called "threads" which are simply slow and bloated
447	process simulations - use fork, it's much faster, cheaper, better).	848	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.5 by root, Sun Oct 27 22:48:12 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.5 by root, Sun Oct 27 22:48:12 2013 UTC vs.
Revision 1.13 by root, Sun Jan 5 14:24:54 2014 UTC