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

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

Diff Legend

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

Comparing CBOR-XS/README (file contents): Revision 1.4 by root, Sat Oct 26 23:02:55 2013 UTC vs. Revision 1.11 by root, Sat Nov 30 18:42:27 2013 UTC

Diff Legend

Comparing CBOR-XS/README (file contents):
Revision 1.4 by root, Sat Oct 26 23:02:55 2013 UTC vs.
Revision 1.11 by root, Sat Nov 30 18:42:27 2013 UTC