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

Comparing CBOR-XS/README (file contents):
Revision 1.8 by root, Tue Oct 29 22:04:52 2013 UTC vs.
Revision 1.9 by root, Fri Nov 22 16:18:59 2013 UTC

…		…
23	}	23	}
24		24
25	DESCRIPTION	25	DESCRIPTION
26	WARNING! This module is very new, and not very well tested (that's up to	26	WARNING! This module is very new, and not very well tested (that's up to
27	you to do). Furthermore, details of the implementation might change	27	you to do). Furthermore, details of the implementation might change
28	freely before version 1.0. And lastly, the object serialisation protocol	28	freely before version 1.0. And lastly, most extensions depend on an IANA
29	depends on a pending IANA assignment, and until that assignment is	29	assignment, and until that assignment is official, this implementation
30	official, this implementation is not interoperable with other	30	is not interoperable with other implementations (even future versions of
31	implementations (even future versions of this module) until the	31	this module) until the assignment is done.
32	assignment is done.
33		32
34	You are still invited to try out CBOR, and this module.	33	You are still invited to try out CBOR, and this module.
35		34
36	This module converts Perl data structures to the Concise Binary Object	35	This module converts Perl data structures to the Concise Binary Object
37	Representation (CBOR) and vice versa. CBOR is a fast binary	36	Representation (CBOR) and vice versa. CBOR is a fast binary
…		…
50	data, the worse Storable performs in comparison.	49	data, the worse Storable performs in comparison.
51		50
52	As for compactness, "CBOR::XS" encoded data structures are usually about	51	As for compactness, "CBOR::XS" encoded data structures are usually about
53	20% smaller than the same data encoded as (compact) JSON or Storable.	52	20% smaller than the same data encoded as (compact) JSON or Storable.
54		53
		54	In addition to the core CBOR data format, this module implements a
		55	number of extensions, to support cyclic and self-referencing data
		56	structures (see "allow_sharing"), string deduplication (see
		57	"allow_stringref") and scalar references (always enabled).
		58
55	The primary goal of this module is to be correct and the secondary	59	The primary goal of this module is to be correct and the secondary
56	goal is to be fast. To reach the latter goal it was written in C.	60	goal is to be fast. To reach the latter goal it was written in C.
57		61
58	See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and	62	See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and
59	vice versa.	63	vice versa.
…		…
80	disabled.	84	disabled.
81		85
82	The mutators for flags all return the CBOR object again and thus	86	The mutators for flags all return the CBOR object again and thus
83	calls can be chained:	87	calls can be chained:
84		88
85	#TODO my $cbor = CBOR::XS->new->encode ({a => [1,2]});	89	my $cbor = CBOR::XS->new->encode ({a => [1,2]});
86		90
87	$cbor = $cbor->max_depth ([$maximum_nesting_depth])	91	$cbor = $cbor->max_depth ([$maximum_nesting_depth])
88	$max_depth = $cbor->get_max_depth	92	$max_depth = $cbor->get_max_depth
89	Sets the maximum nesting level (default 512) accepted while encoding	93	Sets the maximum nesting level (default 512) accepted while encoding
90	or decoding. If a higher nesting level is detected in CBOR data or a	94	or decoding. If a higher nesting level is detected in CBOR data or a
…		…
121	as when 0 is specified).	125	as when 0 is specified).
122		126
123	See SECURITY CONSIDERATIONS, below, for more info on why this is	127	See SECURITY CONSIDERATIONS, below, for more info on why this is
124	useful.	128	useful.
125		129
		130	$cbor = $cbor->allow_unknown ([$enable])
		131	$enabled = $cbor->get_allow_unknown
		132	If $enable is true (or missing), then "encode" will not throw an
		133	exception when it encounters values it cannot represent in CBOR (for
		134	example, filehandles) but instead will encode a CBOR "error" value.
		135
		136	If $enable is false (the default), then "encode" will throw an
		137	exception when it encounters anything it cannot encode as CBOR.
		138
		139	This option does not affect "decode" in any way, and it is
		140	recommended to leave it off unless you know your communications
		141	partner.
		142
		143	$cbor = $cbor->allow_sharing ([$enable])
		144	$enabled = $cbor->get_allow_sharing
		145	If $enable is true (or missing), then "encode" will not
		146	double-encode values that have been referenced before (e.g. when the
		147	same object, such as an array, is referenced multiple times), but
		148	instead will emit a reference to the earlier value.
		149
		150	This means that such values will only be encoded once, and will not
		151	result in a deep cloning of the value on decode, in decoders
		152	supporting the value sharing extension.
		153
		154	It is recommended to leave it off unless you know your communication
		155	partner supports the value sharing extensions to CBOR
		156	(http://cbor.schmorp.de/value-sharing).
		157
		158	Detecting shared values incurs a runtime overhead when values are
		159	encoded that have a reference counter large than one, and might
		160	unnecessarily increase the encoded size, as potentially shared
		161	values are encode as sharable whether or not they are actually
		162	shared.
		163
		164	At the moment, only targets of references can be shared (e.g.
		165	scalars, arrays or hashes pointed to by a reference). Weirder
		166	constructs, such as an array with multiple "copies" of the same
		167	string, which are hard but not impossible to create in Perl, are not
		168	supported (this is the same as for Storable).
		169
		170	If $enable is false (the default), then "encode" will encode
		171	exception when it encounters anything it cannot encode as CBOR.
		172
		173	This option does not affect "decode" in any way - shared values and
		174	references will always be decoded properly if present.
		175
		176	$cbor = $cbor->allow_stringref ([$enable])
		177	$enabled = $cbor->get_allow_stringref
		178	If $enable is true (or missing), then "encode" will try not to
		179	encode the same string twice, but will instead encode a reference to
		180	the string instead. Depending on your data format. this can save a
		181	lot of space, but also results in a very large runtime overhead
		182	(expect encoding times to be 2-4 times as high as without).
		183
		184	It is recommended to leave it off unless you know your
		185	communications partner supports the stringref extension to CBOR
		186	(http://cbor.schmorp.de/stringref).
		187
		188	If $enable is false (the default), then "encode" will encode
		189	exception when it encounters anything it cannot encode as CBOR.
		190
		191	This option does not affect "decode" in any way - string references
		192	will always be decoded properly if present.
		193
		194	$cbor = $cbor->filter ([$cb->($tag, $value)])
		195	$cb_or_undef = $cbor->get_filter
		196	Sets or replaces the tagged value decoding filter (when $cb is
		197	specified) or clears the filter (if no argument or "undef" is
		198	provided).
		199
		200	The filter callback is called only during decoding, when a
		201	non-enforced tagged value has been decoded (see "TAG HANDLING AND
		202	EXTENSIONS" for a list of enforced tags). For specific tags, it's
		203	often better to provide a default converter using the
		204	%CBOR::XS::FILTER hash (see below).
		205
		206	The first argument is the numerical tag, the second is the (decoded)
		207	value that has been tagged.
		208
		209	The filter function should return either exactly one value, which
		210	will replace the tagged value in the decoded data structure, or no
		211	values, which will result in default handling, which currently means
		212	the decoder creates a "CBOR::XS::Tagged" object to hold the tag and
		213	the value.
		214
		215	When the filter is cleared (the default state), the default filter
		216	function, "CBOR::XS::default_filter", is used. This function simply
		217	looks up the tag in the %CBOR::XS::FILTER hash. If an entry exists
		218	it must be a code reference that is called with tag and value, and
		219	is responsible for decoding the value. If no entry exists, it
		220	returns no values.
		221
		222	Example: decode all tags not handled internally into
		223	CBOR::XS::Tagged objects, with no other special handling (useful
		224	when working with potentially "unsafe" CBOR data).
		225
		226	CBOR::XS->new->filter (sub { })->decode ($cbor_data);
		227
		228	Example: provide a global filter for tag 1347375694, converting the
		229	value into some string form.
		230
		231	$CBOR::XS::FILTER{1347375694} = sub {
		232	my ($tag, $value);
		233
		234	"tag 1347375694 value $value"
		235	};
		236
126	$cbor_data = $cbor->encode ($perl_scalar)	237	$cbor_data = $cbor->encode ($perl_scalar)
127	Converts the given Perl data structure (a scalar value) to its CBOR	238	Converts the given Perl data structure (a scalar value) to its CBOR
128	representation.	239	representation.
129		240
130	$perl_scalar = $cbor->decode ($cbor_data)	241	$perl_scalar = $cbor->decode ($cbor_data)
…		…
182	"Types:Serialiser::false" and "Types::Serialiser::error",	293	"Types:Serialiser::false" and "Types::Serialiser::error",
183	respectively. They are overloaded to act almost exactly like the	294	respectively. They are overloaded to act almost exactly like the
184	numbers 1 and 0 (for true and false) or to throw an exception on	295	numbers 1 and 0 (for true and false) or to throw an exception on
185	access (for error). See the Types::Serialiser manpage for details.	296	access (for error). See the Types::Serialiser manpage for details.
186		297
187	CBOR tag 256 (perl object)	298	tagged values
188	The tag value 256 (TODO: pending iana registration) will be used to
189	deserialise a Perl object serialised with "FREEZE". See OBJECT
190	SERIALISATION, below, for details.
191
192	CBOR tag 55799 (magic header)
193	The tag 55799 is ignored (this tag implements the magic header).
194
195	other CBOR tags
196	Tagged items consists of a numeric tag and another CBOR value. Tags	299	Tagged items consists of a numeric tag and another CBOR value.
197	not handled internally are currently converted into a
198	CBOR::XS::Tagged object, which is simply a blessed array reference
199	consisting of the numeric tag value followed by the (decoded) CBOR
200	value.
201		300
202	In the future, support for user-supplied conversions might get	301	See "TAG HANDLING AND EXTENSIONS" and the description of "->filter"
203	added.	302	for details.
204		303
205	anything else	304	anything else
206	Anything else (e.g. unsupported simple values) will raise a decoding	305	Anything else (e.g. unsupported simple values) will raise a decoding
207	error.	306	error.
208		307
…		…
239	values, respectively. You can also use "\1", "\0" and "\undef"	338	values, respectively. You can also use "\1", "\0" and "\undef"
240	directly if you want.	339	directly if you want.
241		340
242	other blessed objects	341	other blessed objects
243	Other blessed objects are serialised via "TO_CBOR" or "FREEZE". See	342	Other blessed objects are serialised via "TO_CBOR" or "FREEZE". See
244	"OBJECT SERIALISATION", below, for details.	343	"TAG HANDLING AND EXTENSIONS" for specific classes handled by this
		344	module, and "OBJECT SERIALISATION" for generic object serialisation.
245		345
246	simple scalars	346	simple scalars
247	TODO Simple Perl scalars (any scalar that is not a reference) are	347	Simple Perl scalars (any scalar that is not a reference) are the
248	the most difficult objects to encode: CBOR::XS will encode undefined	348	most difficult objects to encode: CBOR::XS will encode undefined
249	scalars as CBOR null values, scalars that have last been used in a	349	scalars as CBOR null values, scalars that have last been used in a
250	string context before encoding as CBOR strings, and anything else as	350	string context before encoding as CBOR strings, and anything else as
251	number value:	351	number value:
252		352
253	# dump as number	353	# dump as number
…		…
384		484
385	MAGIC HEADER	485	MAGIC HEADER
386	There is no way to distinguish CBOR from other formats programmatically.	486	There is no way to distinguish CBOR from other formats programmatically.
387	To make it easier to distinguish CBOR from other formats, the CBOR	487	To make it easier to distinguish CBOR from other formats, the CBOR
388	specification has a special "magic string" that can be prepended to any	488	specification has a special "magic string" that can be prepended to any
389	CBOR string without changing it's meaning.	489	CBOR string without changing its meaning.
390		490
391	This string is available as $CBOR::XS::MAGIC. This module does not	491	This string is available as $CBOR::XS::MAGIC. This module does not
392	prepend this string tot he CBOR data it generates, but it will ignroe it	492	prepend this string to the CBOR data it generates, but it will ignore it
393	if present, so users can prepend this string as a "file type" indicator	493	if present, so users can prepend this string as a "file type" indicator
394	as required.	494	as required.
395		495
396	THE CBOR::XS::Tagged CLASS	496	THE CBOR::XS::Tagged CLASS
397	CBOR has the concept of tagged values - any CBOR value can be tagged	497	CBOR has the concept of tagged values - any CBOR value can be tagged
…		…
448	Wrap CBOR data in CBOR:	548	Wrap CBOR data in CBOR:
449		549
450	my $cbor_cbor = encode_cbor	550	my $cbor_cbor = encode_cbor
451	CBOR::XS::tag 24,	551	CBOR::XS::tag 24,
452	encode_cbor [1, 2, 3];	552	encode_cbor [1, 2, 3];
		553
		554	TAG HANDLING AND EXTENSIONS
		555	This section describes how this module handles specific tagged values
		556	and extensions. If a tag is not mentioned here and no additional filters
		557	are provided for it, then the default handling applies (creating a
		558	CBOR::XS::Tagged object on decoding, and only encoding the tag when
		559	explicitly requested).
		560
		561	Tags not handled specifically are currently converted into a
		562	CBOR::XS::Tagged object, which is simply a blessed array reference
		563	consisting of the numeric tag value followed by the (decoded) CBOR
		564	value.
		565
		566	Future versions of this module reserve the right to special case
		567	additional tags (such as base64url).
		568
		569	ENFORCED TAGS
		570	These tags are always handled when decoding, and their handling cannot
		571	be overriden by the user.
		572
		573	<unassigned> (perl-object, <http://cbor.schmorp.de/perl-object>)
		574	These tags are automatically created (and decoded) for serialisable
		575	objects using the "FREEZE/THAW" methods (the Types::Serialier object
		576	serialisation protocol). See "OBJECT SERIALISATION" for details.
		577
		578	<unassigned>, <unassigned> (sharable, sharedref, L
		579	<http://cbor.schmorp.de/value-sharing>)
		580	These tags are automatically decoded when encountered, resulting in
		581	shared values in the decoded object. They are only encoded, however,
		582	when "allow_sharable" is enabled.
		583
		584	<unassigned>, <unassigned> (stringref-namespace, stringref, L
		585	<http://cbor.schmorp.de/stringref>)
		586	These tags are automatically decoded when encountered. They are only
		587	encoded, however, when "allow_stringref" is enabled.
		588
		589	22098 (indirection, <http://cbor.schmorp.de/indirection>)
		590	This tag is automatically generated when a reference are encountered
		591	(with the exception of hash and array refernces). It is converted to
		592	a reference when decoding.
		593
		594	55799 (self-describe CBOR, RFC 7049)
		595	This value is not generated on encoding (unless explicitly requested
		596	by the user), and is simply ignored when decoding.
		597
		598	NON-ENFORCED TAGS
		599	These tags have default filters provided when decoding. Their handling
		600	can be overriden by changing the %CBOR::XS::FILTER entry for the tag, or
		601	by providing a custom "filter" callback when decoding.
		602
		603	When they result in decoding into a specific Perl class, the module
		604	usually provides a corresponding "TO_CBOR" method as well.
		605
		606	When any of these need to load additional modules that are not part of
		607	the perl core distribution (e.g. URI), it is (currently) up to the user
		608	to provide these modules. The decoding usually fails with an exception
		609	if the required module cannot be loaded.
		610
		611	2, 3 (positive/negative bignum)
		612	These tags are decoded into Math::BigInt objects. The corresponding
		613	"Math::BigInt::TO_CBOR" method encodes "small" bigints into normal
		614	CBOR integers, and others into positive/negative CBOR bignums.
		615
		616	4, 5 (decimal fraction/bigfloat)
		617	Both decimal fractions and bigfloats are decoded into Math::BigFloat
		618	objects. The corresponding "Math::BigFloat::TO_CBOR" method always
		619	encodes into a decimal fraction.
		620
		621	CBOR cannot represent bigfloats with very large exponents -
		622	conversion of such big float objects is undefined.
		623
		624	Also, NaN and infinities are not encoded properly.
		625
		626	21, 22, 23 (expected later JSON conversion)
		627	CBOR::XS is not a CBOR-to-JSON converter, and will simply ignore
		628	these tags.
		629
		630	32 (URI)
		631	These objects decode into URI objects. The corresponding
		632	"URI::TO_CBOR" method again results in a CBOR URI value.
453		633
454	CBOR and JSON	634	CBOR and JSON
455	CBOR is supposed to implement a superset of the JSON data model, and is,	635	CBOR is supposed to implement a superset of the JSON data model, and is,
456	with some coercion, able to represent all JSON texts (something that	636	with some coercion, able to represent all JSON texts (something that
457	other "binary JSON" formats such as BSON generally do not support).	637	other "binary JSON" formats such as BSON generally do not support).

Diff Legend

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

Comparing CBOR-XS/README (file contents): Revision 1.8 by root, Tue Oct 29 22:04:52 2013 UTC vs. Revision 1.9 by root, Fri Nov 22 16:18:59 2013 UTC

Diff Legend

Comparing CBOR-XS/README (file contents):
Revision 1.8 by root, Tue Oct 29 22:04:52 2013 UTC vs.
Revision 1.9 by root, Fri Nov 22 16:18:59 2013 UTC