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

Comparing CBOR-XS/README (file contents):
Revision 1.2 by root, Sat Oct 26 10:41:12 2013 UTC vs.
Revision 1.12 by root, Sun Dec 1 17:10:42 2013 UTC

…		…
8	$perl_value = decode_cbor $binary_cbor_data;	8	$perl_value = decode_cbor $binary_cbor_data;
9		9
10	# OO-interface	10	# OO-interface
11		11
12	$coder = CBOR::XS->new;	12	$coder = CBOR::XS->new;
13	#TODO	13	$binary_cbor_data = $coder->encode ($perl_value);
		14	$perl_value = $coder->decode ($binary_cbor_data);
		15
		16	# prefix decoding
		17
		18	my $many_cbor_strings = ...;
		19	while (length $many_cbor_strings) {
		20	my ($data, $length) = $cbor->decode_prefix ($many_cbor_strings);
		21	# data was decoded
		22	substr $many_cbor_strings, 0, $length, ""; # remove decoded cbor string
		23	}
14		24
15	DESCRIPTION	25	DESCRIPTION
16	WARNING! THIS IS A PRE-ALPHA RELEASE! IT WILL CRASH, CORRUPT YOUR DATA	26	This module converts Perl data structures to the Concise Binary Object
17	AND EAT YOUR CHILDREN!	27	Representation (CBOR) and vice versa. CBOR is a fast binary
		28	serialisation format that aims to use an (almost) superset of the JSON
		29	data model, i.e. when you can represent something useful in JSON, you
		30	should be able to represent it in CBOR.
18		31
19	This module converts Perl data structures to CBOR and vice versa. Its	32	In short, CBOR is a faster and quite compact binary alternative to JSON,
20	primary goal is to be correct and its secondary goal is to be fast.	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).
		51
		52	The primary goal of this module is to be correct and the secondary
21	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.
22		54
23	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
24	vice versa.	56	vice versa.
25		57
26	FUNCTIONAL INTERFACE	58	FUNCTIONAL INTERFACE
…		…
45	disabled.	77	disabled.
46		78
47	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
48	calls can be chained:	80	calls can be chained:
49		81
50	#TODO my $cbor = CBOR::XS->new->encode ({a => [1,2]});	82	my $cbor = CBOR::XS->new->encode ({a => [1,2]});
51		83
52	$cbor = $cbor->max_depth ([$maximum_nesting_depth])	84	$cbor = $cbor->max_depth ([$maximum_nesting_depth])
53	$max_depth = $cbor->get_max_depth	85	$max_depth = $cbor->get_max_depth
54	Sets the maximum nesting level (default 512) accepted while encoding	86	Sets the maximum nesting level (default 512) accepted while encoding
55	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
…		…
86	as when 0 is specified).	118	as when 0 is specified).
87		119
88	See SECURITY CONSIDERATIONS, below, for more info on why this is	120	See SECURITY CONSIDERATIONS, below, for more info on why this is
89	useful.	121	useful.
90		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
91	$cbor_data = $cbor->encode ($perl_scalar)	271	$cbor_data = $cbor->encode ($perl_scalar)
92	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
93	representation.	273	representation.
94		274
95	$perl_scalar = $cbor->decode ($cbor_data)	275	$perl_scalar = $cbor->decode ($cbor_data)
…		…
118	For the more enlightened: note that in the following descriptions,	298	For the more enlightened: note that in the following descriptions,
119	lowercase perl refers to the Perl interpreter, while uppercase Perl	299	lowercase perl refers to the Perl interpreter, while uppercase Perl
120	refers to the abstract Perl language itself.	300	refers to the abstract Perl language itself.
121		301
122	CBOR -> PERL	302	CBOR -> PERL
123	True, False	303	integers
124	These CBOR values become "CBOR::XS::true" and "CBOR::XS::false",	304	CBOR integers become (numeric) perl scalars. On perls without 64 bit
		305	support, 64 bit integers will be truncated or otherwise corrupted.
		306
		307	byte strings
		308	Byte strings will become octet strings in Perl (the Byte values
		309	0..255 will simply become characters of the same value in Perl).
		310
		311	UTF-8 strings
		312	UTF-8 strings in CBOR will be decoded, i.e. the UTF-8 octets will be
		313	decoded into proper Unicode code points. At the moment, the validity
		314	of the UTF-8 octets will not be validated - corrupt input will
		315	result in corrupted Perl strings.
		316
		317	arrays, maps
		318	CBOR arrays and CBOR maps will be converted into references to a
		319	Perl array or hash, respectively. The keys of the map will be
		320	stringified during this process.
		321
		322	null
		323	CBOR null becomes "undef" in Perl.
		324
		325	true, false, undefined
		326	These CBOR values become "Types:Serialiser::true",
		327	"Types:Serialiser::false" and "Types::Serialiser::error",
125	respectively. They are overloaded to act almost exactly like the	328	respectively. They are overloaded to act almost exactly like the
126	numbers 1 and 0. You can check whether a scalar is a CBOR boolean by	329	numbers 1 and 0 (for true and false) or to throw an exception on
127	using the "CBOR::XS::is_bool" function.	330	access (for error). See the Types::Serialiser manpage for details.
128		331
129	null	332	tagged values
130	A CBOR Null value becomes "undef" in Perl.	333	Tagged items consists of a numeric tag and another CBOR value.
		334
		335	See "TAG HANDLING AND EXTENSIONS" and the description of "->filter"
		336	for details on which tags are handled how.
		337
		338	anything else
		339	Anything else (e.g. unsupported simple values) will raise a decoding
		340	error.
131		341
132	PERL -> CBOR	342	PERL -> CBOR
133	The mapping from Perl to CBOR is slightly more difficult, as Perl is a	343	The mapping from Perl to CBOR is slightly more difficult, as Perl is a
134	truly typeless language, so we can only guess which CBOR type is meant	344	typeless language. That means this module can only guess which CBOR type
135	by a Perl value.	345	is meant by a perl value.
136		346
137	hash references	347	hash references
138	Perl hash references become CBOR maps. As there is no inherent	348	Perl hash references become CBOR maps. As there is no inherent
139	ordering in hash keys (or CBOR maps), they will usually be encoded	349	ordering in hash keys (or CBOR maps), they will usually be encoded
140	in a pseudo-random order.	350	in a pseudo-random order. This order can be different each time a
		351	hahs is encoded.
		352
		353	Currently, tied hashes will use the indefinite-length format, while
		354	normal hashes will use the fixed-length format.
141		355
142	array references	356	array references
143	Perl array references become CBOR arrays.	357	Perl array references become fixed-length CBOR arrays.
144		358
145	other references	359	other references
146	Other unblessed references are generally not allowed and will cause	360	Other unblessed references will be represented using the indirection
147	an exception to be thrown, except for references to the integers 0	361	tag extension (tag value 22098,
148	and 1, which get turned into "False" and "True" in CBOR.	362	<http://cbor.schmorp.de/indirection>). CBOR decoders are guaranteed
		363	to be able to decode these values somehow, by either "doing the
		364	right thing", decoding into a generic tagged object, simply ignoring
		365	the tag, or something else.
149		366
150	CBOR::XS::true, CBOR::XS::false	367	CBOR::XS::Tagged objects
		368	Objects of this type must be arrays consisting of a single "[tag,
		369	value]" pair. The (numerical) tag will be encoded as a CBOR tag, the
		370	value will be encoded as appropriate for the value. You must use
		371	"CBOR::XS::tag" to create such objects.
		372
		373	Types::Serialiser::true, Types::Serialiser::false,
		374	Types::Serialiser::error
151	These special values become CBOR True and CBOR False values,	375	These special values become CBOR true, CBOR false and CBOR undefined
152	respectively. You can also use "\1" and "\0" directly if you want.	376	values, respectively. You can also use "\1", "\0" and "\undef"
		377	directly if you want.
153		378
154	blessed objects	379	other blessed objects
155	Blessed objects are not directly representable in CBOR. TODO See the	380	Other blessed objects are serialised via "TO_CBOR" or "FREEZE". See
156	"allow_blessed" and "convert_blessed" methods on various options on	381	"TAG HANDLING AND EXTENSIONS" for specific classes handled by this
157	how to deal with this: basically, you can choose between throwing an	382	module, and "OBJECT SERIALISATION" for generic object serialisation.
158	exception, encoding the reference as if it weren't blessed, or
159	provide your own serialiser method.
160		383
161	simple scalars	384	simple scalars
162	TODO Simple Perl scalars (any scalar that is not a reference) are	385	Simple Perl scalars (any scalar that is not a reference) are the
163	the most difficult objects to encode: CBOR::XS will encode undefined	386	most difficult objects to encode: CBOR::XS will encode undefined
164	scalars as CBOR "Null" values, scalars that have last been used in a	387	scalars as CBOR null values, scalars that have last been used in a
165	string context before encoding as CBOR strings, and anything else as	388	string context before encoding as CBOR strings, and anything else as
166	number value:	389	number value:
167		390
168	# dump as number	391	# dump as number
169	encode_cbor [2] # yields [2]	392	encode_cbor [2] # yields [2]
170	encode_cbor [-3.0e17] # yields [-3e+17]	393	encode_cbor [-3.0e17] # yields [-3e+17]
171	my $value = 5; encode_cbor [$value] # yields [5]	394	my $value = 5; encode_cbor [$value] # yields [5]
172		395
173	# used as string, so dump as string	396	# used as string, so dump as string (either byte or text)
174	print $value;	397	print $value;
175	encode_cbor [$value] # yields ["5"]	398	encode_cbor [$value] # yields ["5"]
176		399
177	# undef becomes null	400	# undef becomes null
178	encode_cbor [undef] # yields [null]	401	encode_cbor [undef] # yields [null]
…		…
182	my $x = 3.1; # some variable containing a number	405	my $x = 3.1; # some variable containing a number
183	"$x"; # stringified	406	"$x"; # stringified
184	$x .= ""; # another, more awkward way to stringify	407	$x .= ""; # another, more awkward way to stringify
185	print $x; # perl does it for you, too, quite often	408	print $x; # perl does it for you, too, quite often
186		409
		410	You can force whether a string ie encoded as byte or text string by
		411	using "utf8::upgrade" and "utf8::downgrade"):
		412
		413	utf8::upgrade $x; # encode $x as text string
		414	utf8::downgrade $x; # encode $x as byte string
		415
		416	Perl doesn't define what operations up- and downgrade strings, so if
		417	the difference between byte and text is important, you should up- or
		418	downgrade your string as late as possible before encoding.
		419
187	You can force the type to be a CBOR number by numifying it:	420	You can force the type to be a CBOR number by numifying it:
188		421
189	my $x = "3"; # some variable containing a string	422	my $x = "3"; # some variable containing a string
190	$x += 0; # numify it, ensuring it will be dumped as a number	423	$x += 0; # numify it, ensuring it will be dumped as a number
191	$x *= 1; # same thing, the choice is yours.	424	$x *= 1; # same thing, the choice is yours.
192		425
193	You can not currently force the type in other, less obscure, ways.	426	You can not currently force the type in other, less obscure, ways.
194	Tell me if you need this capability (but don't forget to explain why	427	Tell me if you need this capability (but don't forget to explain why
195	it's needed :).	428	it's needed :).
196		429
197	Note that numerical precision has the same meaning as under Perl (so	430	Perl values that seem to be integers generally use the shortest
198	binary to decimal conversion follows the same rules as in Perl,	431	possible representation. Floating-point values will use either the
199	which can differ to other languages). Also, your perl interpreter	432	IEEE single format if possible without loss of precision, otherwise
200	might expose extensions to the floating point numbers of your	433	the IEEE double format will be used. Perls that use formats other
201	platform, such as infinities or NaN's - these cannot be represented	434	than IEEE double to represent numerical values are supported, but
202	in CBOR, and it is an error to pass those in.	435	might suffer loss of precision.
203		436
		437	OBJECT SERIALISATION
		438	This module implements both a CBOR-specific and the generic
		439	Types::Serialier object serialisation protocol. The following
		440	subsections explain both methods.
		441
		442	ENCODING
		443	This module knows two way to serialise a Perl object: The CBOR-specific
		444	way, and the generic way.
		445
		446	Whenever the encoder encounters a Perl object that it cannot serialise
		447	directly (most of them), it will first look up the "TO_CBOR" method on
		448	it.
		449
		450	If it has a "TO_CBOR" method, it will call it with the object as only
		451	argument, and expects exactly one return value, which it will then
		452	substitute and encode it in the place of the object.
		453
		454	Otherwise, it will look up the "FREEZE" method. If it exists, it will
		455	call it with the object as first argument, and the constant string
		456	"CBOR" as the second argument, to distinguish it from other serialisers.
		457
		458	The "FREEZE" method can return any number of values (i.e. zero or more).
		459	These will be encoded as CBOR perl object, together with the classname.
		460
		461	These methods MUST NOT change the data structure that is being
		462	serialised. Failure to comply to this can result in memory corruption -
		463	and worse.
		464
		465	If an object supports neither "TO_CBOR" nor "FREEZE", encoding will fail
		466	with an error.
		467
		468	DECODING
		469	Objects encoded via "TO_CBOR" cannot (normally) be automatically
		470	decoded, but objects encoded via "FREEZE" can be decoded using the
		471	following protocol:
		472
		473	When an encoded CBOR perl object is encountered by the decoder, it will
		474	look up the "THAW" method, by using the stored classname, and will fail
		475	if the method cannot be found.
		476
		477	After the lookup it will call the "THAW" method with the stored
		478	classname as first argument, the constant string "CBOR" as second
		479	argument, and all values returned by "FREEZE" as remaining arguments.
		480
		481	EXAMPLES
		482	Here is an example "TO_CBOR" method:
		483
		484	sub My::Object::TO_CBOR {
		485	my ($obj) = @_;
		486
		487	["this is a serialised My::Object object", $obj->{id}]
		488	}
		489
		490	When a "My::Object" is encoded to CBOR, it will instead encode a simple
		491	array with two members: a string, and the "object id". Decoding this
		492	CBOR string will yield a normal perl array reference in place of the
		493	object.
		494
		495	A more useful and practical example would be a serialisation method for
		496	the URI module. CBOR has a custom tag value for URIs, namely 32:
		497
		498	sub URI::TO_CBOR {
		499	my ($self) = @_;
		500	my $uri = "$self"; # stringify uri
		501	utf8::upgrade $uri; # make sure it will be encoded as UTF-8 string
		502	CBOR::XS::tag 32, "$_[0]"
		503	}
		504
		505	This will encode URIs as a UTF-8 string with tag 32, which indicates an
		506	URI.
		507
		508	Decoding such an URI will not (currently) give you an URI object, but
		509	instead a CBOR::XS::Tagged object with tag number 32 and the string -
		510	exactly what was returned by "TO_CBOR".
		511
		512	To serialise an object so it can automatically be deserialised, you need
		513	to use "FREEZE" and "THAW". To take the URI module as example, this
		514	would be a possible implementation:
		515
		516	sub URI::FREEZE {
		517	my ($self, $serialiser) = @_;
		518	"$self" # encode url string
		519	}
		520
		521	sub URI::THAW {
		522	my ($class, $serialiser, $uri) = @_;
		523
		524	$class->new ($uri)
		525	}
		526
		527	Unlike "TO_CBOR", multiple values can be returned by "FREEZE". For
		528	example, a "FREEZE" method that returns "type", "id" and "variant"
		529	values would cause an invocation of "THAW" with 5 arguments:
		530
		531	sub My::Object::FREEZE {
		532	my ($self, $serialiser) = @_;
		533
		534	($self->{type}, $self->{id}, $self->{variant})
		535	}
		536
		537	sub My::Object::THAW {
		538	my ($class, $serialiser, $type, $id, $variant) = @_;
		539
		540	$class-<new (type => $type, id => $id, variant => $variant)
		541	}
		542
		543	MAGIC HEADER
		544	There is no way to distinguish CBOR from other formats programmatically.
		545	To make it easier to distinguish CBOR from other formats, the CBOR
		546	specification has a special "magic string" that can be prepended to any
		547	CBOR string without changing its meaning.
		548
		549	This string is available as $CBOR::XS::MAGIC. This module does not
		550	prepend this string to the CBOR data it generates, but it will ignore it
		551	if present, so users can prepend this string as a "file type" indicator
		552	as required.
		553
		554	THE CBOR::XS::Tagged CLASS
		555	CBOR has the concept of tagged values - any CBOR value can be tagged
		556	with a numeric 64 bit number, which are centrally administered.
		557
		558	"CBOR::XS" handles a few tags internally when en- or decoding. You can
		559	also create tags yourself by encoding "CBOR::XS::Tagged" objects, and
		560	the decoder will create "CBOR::XS::Tagged" objects itself when it hits
		561	an unknown tag.
		562
		563	These objects are simply blessed array references - the first member of
		564	the array being the numerical tag, the second being the value.
		565
		566	You can interact with "CBOR::XS::Tagged" objects in the following ways:
		567
		568	$tagged = CBOR::XS::tag $tag, $value
		569	This function(!) creates a new "CBOR::XS::Tagged" object using the
		570	given $tag (0..2**64-1) to tag the given $value (which can be any
		571	Perl value that can be encoded in CBOR, including serialisable Perl
		572	objects and "CBOR::XS::Tagged" objects).
		573
		574	$tagged->[0]
		575	$tagged->[0] = $new_tag
		576	$tag = $tagged->tag
		577	$new_tag = $tagged->tag ($new_tag)
		578	Access/mutate the tag.
		579
		580	$tagged->[1]
		581	$tagged->[1] = $new_value
		582	$value = $tagged->value
		583	$new_value = $tagged->value ($new_value)
		584	Access/mutate the tagged value.
		585
		586	EXAMPLES
		587	Here are some examples of "CBOR::XS::Tagged" uses to tag objects.
		588
		589	You can look up CBOR tag value and emanings in the IANA registry at
		590	<http://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml>.
		591
		592	Prepend a magic header ($CBOR::XS::MAGIC):
		593
		594	my $cbor = encode_cbor CBOR::XS::tag 55799, $value;
		595	# same as:
		596	my $cbor = $CBOR::XS::MAGIC . encode_cbor $value;
		597
		598	Serialise some URIs and a regex in an array:
		599
		600	my $cbor = encode_cbor [
		601	(CBOR::XS::tag 32, "http://www.nethype.de/"),
		602	(CBOR::XS::tag 32, "http://software.schmorp.de/"),
		603	(CBOR::XS::tag 35, "^[Pp][Ee][Rr][lL]\$"),
		604	];
		605
		606	Wrap CBOR data in CBOR:
		607
		608	my $cbor_cbor = encode_cbor
		609	CBOR::XS::tag 24,
		610	encode_cbor [1, 2, 3];
		611
		612	TAG HANDLING AND EXTENSIONS
		613	This section describes how this module handles specific tagged values
		614	and extensions. If a tag is not mentioned here and no additional filters
		615	are provided for it, then the default handling applies (creating a
		616	CBOR::XS::Tagged object on decoding, and only encoding the tag when
		617	explicitly requested).
		618
		619	Tags not handled specifically are currently converted into a
		620	CBOR::XS::Tagged object, which is simply a blessed array reference
		621	consisting of the numeric tag value followed by the (decoded) CBOR
		622	value.
		623
		624	Future versions of this module reserve the right to special case
		625	additional tags (such as base64url).
		626
		627	ENFORCED TAGS
		628	These tags are always handled when decoding, and their handling cannot
		629	be overriden by the user.
		630
		631	26 (perl-object, <http://cbor.schmorp.de/perl-object>)
		632	These tags are automatically created (and decoded) for serialisable
		633	objects using the "FREEZE/THAW" methods (the Types::Serialier object
		634	serialisation protocol). See "OBJECT SERIALISATION" for details.
		635
		636	28, 29 (shareable, sharedref, L <http://cbor.schmorp.de/value-sharing>)
		637	These tags are automatically decoded when encountered (and they do
		638	not result in a cyclic data structure, see "allow_cycles"),
		639	resulting in shared values in the decoded object. They are only
		640	encoded, however, when "allow_sharing" is enabled.
		641
		642	Not all shared values can be successfully decoded: values that
		643	reference themselves will currently decode as "undef" (this is not
		644	the same as a reference pointing to itself, which will be
		645	represented as a value that contains an indirect reference to itself
		646	- these will be decoded properly).
		647
		648	Note that considerably more shared value data structures can be
		649	decoded than will be encoded - currently, only values pointed to by
		650	references will be shared, others will not. While non-reference
		651	shared values can be generated in Perl with some effort, they were
		652	considered too unimportant to be supported in the encoder. The
		653	decoder, however, will decode these values as shared values.
		654
		655	256, 25 (stringref-namespace, stringref, L
		656	<http://cbor.schmorp.de/stringref>)
		657	These tags are automatically decoded when encountered. They are only
		658	encoded, however, when "pack_strings" is enabled.
		659
		660	22098 (indirection, <http://cbor.schmorp.de/indirection>)
		661	This tag is automatically generated when a reference are encountered
		662	(with the exception of hash and array refernces). It is converted to
		663	a reference when decoding.
		664
		665	55799 (self-describe CBOR, RFC 7049)
		666	This value is not generated on encoding (unless explicitly requested
		667	by the user), and is simply ignored when decoding.
		668
		669	NON-ENFORCED TAGS
		670	These tags have default filters provided when decoding. Their handling
		671	can be overriden by changing the %CBOR::XS::FILTER entry for the tag, or
		672	by providing a custom "filter" callback when decoding.
		673
		674	When they result in decoding into a specific Perl class, the module
		675	usually provides a corresponding "TO_CBOR" method as well.
		676
		677	When any of these need to load additional modules that are not part of
		678	the perl core distribution (e.g. URI), it is (currently) up to the user
		679	to provide these modules. The decoding usually fails with an exception
		680	if the required module cannot be loaded.
		681
		682	0, 1 (date/time string, seconds since the epoch)
		683	These tags are decoded into Time::Piece objects. The corresponding
		684	"Time::Piece::TO_CBOR" method always encodes into tag 1 values
		685	currently.
		686
		687	The Time::Piece API is generally surprisingly bad, and fractional
		688	seconds are only accidentally kept intact, so watch out. On the plus
		689	side, the module comes with perl since 5.10, which has to count for
		690	something.
		691
		692	2, 3 (positive/negative bignum)
		693	These tags are decoded into Math::BigInt objects. The corresponding
		694	"Math::BigInt::TO_CBOR" method encodes "small" bigints into normal
		695	CBOR integers, and others into positive/negative CBOR bignums.
		696
		697	4, 5 (decimal fraction/bigfloat)
		698	Both decimal fractions and bigfloats are decoded into Math::BigFloat
		699	objects. The corresponding "Math::BigFloat::TO_CBOR" method always
		700	encodes into a decimal fraction.
		701
		702	CBOR cannot represent bigfloats with very large exponents -
		703	conversion of such big float objects is undefined.
		704
		705	Also, NaN and infinities are not encoded properly.
		706
		707	21, 22, 23 (expected later JSON conversion)
		708	CBOR::XS is not a CBOR-to-JSON converter, and will simply ignore
		709	these tags.
		710
		711	32 (URI)
		712	These objects decode into URI objects. The corresponding
		713	"URI::TO_CBOR" method again results in a CBOR URI value.
		714
204	CBOR and JSON	715	CBOR and JSON
205	TODO	716	CBOR is supposed to implement a superset of the JSON data model, and is,
		717	with some coercion, able to represent all JSON texts (something that
		718	other "binary JSON" formats such as BSON generally do not support).
		719
		720	CBOR implements some extra hints and support for JSON interoperability,
		721	and the spec offers further guidance for conversion between CBOR and
		722	JSON. None of this is currently implemented in CBOR, and the guidelines
		723	in the spec do not result in correct round-tripping of data. If JSON
		724	interoperability is improved in the future, then the goal will be to
		725	ensure that decoded JSON data will round-trip encoding and decoding to
		726	CBOR intact.
206		727
207	SECURITY CONSIDERATIONS	728	SECURITY CONSIDERATIONS
208	When you are using CBOR in a protocol, talking to untrusted potentially	729	When you are using CBOR in a protocol, talking to untrusted potentially
209	hostile creatures requires relatively few measures.	730	hostile creatures requires relatively few measures.
210		731
…		…
253	uses long double to represent floating point values, they might not be	774	uses long double to represent floating point values, they might not be
254	encoded properly. Half precision types are accepted, but not encoded.	775	encoded properly. Half precision types are accepted, but not encoded.
255		776
256	Strict mode and canonical mode are not implemented.	777	Strict mode and canonical mode are not implemented.
257		778
		779	LIMITATIONS ON PERLS WITHOUT 64-BIT INTEGER SUPPORT
		780	On perls that were built without 64 bit integer support (these are rare
		781	nowadays, even on 32 bit architectures), support for any kind of 64 bit
		782	integer in CBOR is very limited - most likely, these 64 bit values will
		783	be truncated, corrupted, or otherwise not decoded correctly. This also
		784	includes string, array and map sizes that are stored as 64 bit integers.
		785
258	THREADS	786	THREADS
259	This module is not guaranteed to be thread safe and there are no plans	787	This module is not guaranteed to be thread safe and there are no plans
260	to change this until Perl gets thread support (as opposed to the	788	to change this until Perl gets thread support (as opposed to the
261	horribly slow so-called "threads" which are simply slow and bloated	789	horribly slow so-called "threads" which are simply slow and bloated
262	process simulations - use fork, it's much faster, cheaper, better).	790	process simulations - use fork, it's much faster, cheaper, better).
…		…
273		801
274	SEE ALSO	802	SEE ALSO
275	The JSON and JSON::XS modules that do similar, but human-readable,	803	The JSON and JSON::XS modules that do similar, but human-readable,
276	serialisation.	804	serialisation.
277		805
		806	The Types::Serialiser module provides the data model for true, false and
		807	error values.
		808
278	AUTHOR	809	AUTHOR
279	Marc Lehmann <schmorp@schmorp.de>	810	Marc Lehmann <schmorp@schmorp.de>
280	http://home.schmorp.de/	811	http://home.schmorp.de/
281		812

Diff Legend

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

Comparing CBOR-XS/README (file contents): Revision 1.2 by root, Sat Oct 26 10:41:12 2013 UTC vs. Revision 1.12 by root, Sun Dec 1 17:10:42 2013 UTC

Diff Legend

Comparing CBOR-XS/README (file contents):
Revision 1.2 by root, Sat Oct 26 10:41:12 2013 UTC vs.
Revision 1.12 by root, Sun Dec 1 17:10:42 2013 UTC