CBOR-XS/XS.pm

=head1 NAME

CBOR::XS - Concise Binary Object Representation (CBOR, RFC7049)

=encoding utf-8

=head1 SYNOPSIS

 use CBOR::XS;

 $binary_cbor_data = encode_cbor $perl_value;
 $perl_value       = decode_cbor $binary_cbor_data;

 # OO-interface

 $coder = CBOR::XS->new;
 #TODO

=head1 DESCRIPTION

WARNING! THIS IS A PRE-ALPHA RELEASE! IT WILL CRASH, CORRUPT YOUR DATA AND
EAT YOUR CHILDREN!

This module converts Perl data structures to CBOR and vice versa. Its
primary goal is to be I<correct> and its secondary goal is to be
I<fast>. To reach the latter goal it was written in C.

See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and
vice versa.

=cut

package CBOR::XS;

use common::sense;

our $VERSION = 0.02;
our @ISA = qw(Exporter);

our @EXPORT = qw(encode_cbor decode_cbor);

use Exporter;
use XSLoader;

our $MAGIC = "\xd9\xd9\xf7";

=head1 FUNCTIONAL INTERFACE

The following convenience methods are provided by this module. They are
exported by default:

=over 4

=item $cbor_data = encode_cbor $perl_scalar

Converts the given Perl data structure to CBOR representation. Croaks on
error.

=item $perl_scalar = decode_cbor $cbor_data

The opposite of C<encode_cbor>: expects a valid CBOR string to parse,
returning the resulting perl scalar. Croaks on error.

=back


=head1 OBJECT-ORIENTED INTERFACE

The object oriented interface lets you configure your own encoding or
decoding style, within the limits of supported formats.

=over 4

=item $cbor = new CBOR::XS

Creates a new CBOR::XS object that can be used to de/encode CBOR
strings. All boolean flags described below are by default I<disabled>.

The mutators for flags all return the CBOR object again and thus calls can
be chained:

#TODO
   my $cbor = CBOR::XS->new->encode ({a => [1,2]});

=item $cbor = $cbor->max_depth ([$maximum_nesting_depth])

=item $max_depth = $cbor->get_max_depth

Sets the maximum nesting level (default C<512>) accepted while encoding
or decoding. If a higher nesting level is detected in CBOR data or a Perl
data structure, then the encoder and decoder will stop and croak at that
point.

Nesting level is defined by number of hash- or arrayrefs that the encoder
needs to traverse to reach a given point or the number of C<{> or C<[>
characters without their matching closing parenthesis crossed to reach a
given character in a string.

Setting the maximum depth to one disallows any nesting, so that ensures
that the object is only a single hash/object or array.

If no argument is given, the highest possible setting will be used, which
is rarely useful.

Note that nesting is implemented by recursion in C. The default value has
been chosen to be as large as typical operating systems allow without
crashing.

See SECURITY CONSIDERATIONS, below, for more info on why this is useful.

=item $cbor = $cbor->max_size ([$maximum_string_size])

=item $max_size = $cbor->get_max_size

Set the maximum length a CBOR string may have (in bytes) where decoding
is being attempted. The default is C<0>, meaning no limit. When C<decode>
is called on a string that is longer then this many bytes, it will not
attempt to decode the string but throw an exception. This setting has no
effect on C<encode> (yet).

If no argument is given, the limit check will be deactivated (same as when
C<0> is specified).

See SECURITY CONSIDERATIONS, below, for more info on why this is useful.

=item $cbor_data = $cbor->encode ($perl_scalar)

Converts the given Perl data structure (a scalar value) to its CBOR
representation.

=item $perl_scalar = $cbor->decode ($cbor_data)

The opposite of C<encode>: expects CBOR data and tries to parse it,
returning the resulting simple scalar or reference. Croaks on error.

=item ($perl_scalar, $octets) = $cbor->decode_prefix ($cbor_data)

This works like the C<decode> method, but instead of raising an exception
when there is trailing garbage after the CBOR string, it will silently
stop parsing there and return the number of characters consumed so far.

This is useful if your CBOR texts are not delimited by an outer protocol
and you need to know where the first CBOR string ends amd the next one
starts.

   CBOR::XS->new->decode_prefix ("......")
   => ("...", 3)

=back


=head1 MAPPING

This section describes how CBOR::XS maps Perl values to CBOR values and
vice versa. These mappings are designed to "do the right thing" in most
circumstances automatically, preserving round-tripping characteristics
(what you put in comes out as something equivalent).

For the more enlightened: note that in the following descriptions,
lowercase I<perl> refers to the Perl interpreter, while uppercase I<Perl>
refers to the abstract Perl language itself.


=head2 CBOR -> PERL

=over 4

=item True, False

These CBOR values become C<CBOR::XS::true> and C<CBOR::XS::false>,
respectively. They are overloaded to act almost exactly like the numbers
C<1> and C<0>. You can check whether a scalar is a CBOR boolean by using
the C<CBOR::XS::is_bool> function.

=item Null, Undefined

CBOR Null and Undefined values becomes C<undef> in Perl (in the future,
Undefined may raise an exception).

=back


=head2 PERL -> CBOR

The mapping from Perl to CBOR is slightly more difficult, as Perl is a
truly typeless language, so we can only guess which CBOR type is meant by
a Perl value.

=over 4

=item hash references

Perl hash references become CBOR maps. As there is no inherent ordering
in hash keys (or CBOR maps), they will usually be encoded in a
pseudo-random order.

=item array references

Perl array references become CBOR arrays.

=item other references

Other unblessed references are generally not allowed and will cause an
exception to be thrown, except for references to the integers C<0> and
C<1>, which get turned into C<False> and C<True> in CBOR.

=item CBOR::XS::true, CBOR::XS::false

These special values become CBOR True and CBOR False values,
respectively. You can also use C<\1> and C<\0> directly if you want.

=item blessed objects

Blessed objects are not directly representable in CBOR. TODO
See the
C<allow_blessed> and C<convert_blessed> methods on various options on
how to deal with this: basically, you can choose between throwing an
exception, encoding the reference as if it weren't blessed, or provide
your own serialiser method.

=item simple scalars

TODO
Simple Perl scalars (any scalar that is not a reference) are the most
difficult objects to encode: CBOR::XS will encode undefined scalars as
CBOR C<Null> values, scalars that have last been used in a string context
before encoding as CBOR strings, and anything else as number value:

   # dump as number
   encode_cbor [2]                      # yields [2]
   encode_cbor [-3.0e17]                # yields [-3e+17]
   my $value = 5; encode_cbor [$value]  # yields [5]

   # used as string, so dump as string
   print $value;
   encode_cbor [$value]                 # yields ["5"]

   # undef becomes null
   encode_cbor [undef]                  # yields [null]

You can force the type to be a CBOR string by stringifying it:

   my $x = 3.1; # some variable containing a number
   "$x";        # stringified
   $x .= "";    # another, more awkward way to stringify
   print $x;    # perl does it for you, too, quite often

You can force the type to be a CBOR number by numifying it:

   my $x = "3"; # some variable containing a string
   $x += 0;     # numify it, ensuring it will be dumped as a number
   $x *= 1;     # same thing, the choice is yours.

You can not currently force the type in other, less obscure, ways. Tell me
if you need this capability (but don't forget to explain why it's needed
:).

Note that numerical precision has the same meaning as under Perl (so
binary to decimal conversion follows the same rules as in Perl, which
can differ to other languages). Also, your perl interpreter might expose
extensions to the floating point numbers of your platform, such as
infinities or NaN's - these cannot be represented in CBOR, and it is an
error to pass those in.

=back


=head2 MAGIC HEADER

There is no way to distinguish CBOR from other formats
programmatically. To make it easier to distinguish CBOR from other
formats, the CBOR specification has a special "magic string" that can be
prepended to any CBOR string without changing it's meaning.

This string is available as C<$CBOR::XS::MAGIC>. This module does not
prepend this string tot he CBOR data it generates, but it will ignroe it
if present, so users can prepend this string as a "file type" indicator as
required.


=head2 CBOR and JSON

TODO


=head1 SECURITY CONSIDERATIONS

When you are using CBOR in a protocol, talking to untrusted potentially
hostile creatures requires relatively few measures.

First of all, your CBOR decoder should be secure, that is, should not have
any buffer overflows. Obviously, this module should ensure that and I am
trying hard on making that true, but you never know.

Second, you need to avoid resource-starving attacks. That means you should
limit the size of CBOR data you accept, or make sure then when your
resources run out, that's just fine (e.g. by using a separate process that
can crash safely). The size of a CBOR string in octets is usually a good
indication of the size of the resources required to decode it into a Perl
structure. While CBOR::XS can check the size of the CBOR text, it might be
too late when you already have it in memory, so you might want to check
the size before you accept the string.

Third, CBOR::XS recurses using the C stack when decoding objects and
arrays. The C stack is a limited resource: for instance, on my amd64
machine with 8MB of stack size I can decode around 180k nested arrays but
only 14k nested CBOR objects (due to perl itself recursing deeply on croak
to free the temporary). If that is exceeded, the program crashes. To be
conservative, the default nesting limit is set to 512. If your process
has a smaller stack, you should adjust this setting accordingly with the
C<max_depth> method.

Something else could bomb you, too, that I forgot to think of. In that
case, you get to keep the pieces. I am always open for hints, though...

Also keep in mind that CBOR::XS might leak contents of your Perl data
structures in its error messages, so when you serialise sensitive
information you might want to make sure that exceptions thrown by CBOR::XS
will not end up in front of untrusted eyes.

=head1 CBOR IMPLEMENTATION NOTES

This section contains some random implementation notes. They do not
describe guaranteed behaviour, but merely behaviour as-is implemented
right now.

64 bit integers are only properly decoded when Perl was built with 64 bit
support.

Strings and arrays are encoded with a definite length. Hashes as well,
unless they are tied (or otherwise magical).

Only the double data type is supported for NV data types - when Perl uses
long double to represent floating point values, they might not be encoded
properly. Half precision types are accepted, but not encoded.

Strict mode and canonical mode are not implemented.


=head1 THREADS

This module is I<not> guaranteed to be thread safe and there are no
plans to change this until Perl gets thread support (as opposed to the
horribly slow so-called "threads" which are simply slow and bloated
process simulations - use fork, it's I<much> faster, cheaper, better).

(It might actually work, but you have been warned).


=head1 BUGS

While the goal of this module is to be correct, that unfortunately does
not mean it's bug-free, only that I think its design is bug-free. If you
keep reporting bugs they will be fixed swiftly, though.

Please refrain from using rt.cpan.org or any other bug reporting
service. I put the contact address into my modules for a reason.

=cut

our $true  = do { bless \(my $dummy = 1), "CBOR::XS::Boolean" };
our $false = do { bless \(my $dummy = 0), "CBOR::XS::Boolean" };

sub true()  { $true  }
sub false() { $false }

sub is_bool($) {
   UNIVERSAL::isa $_[0], "CBOR::XS::Boolean"
#      or UNIVERSAL::isa $_[0], "CBOR::Literal"
}

XSLoader::load "CBOR::XS", $VERSION;

package CBOR::XS::Boolean;

use overload
   "0+"     => sub { ${$_[0]} },
   "++"     => sub { $_[0] = ${$_[0]} + 1 },
   "--"     => sub { $_[0] = ${$_[0]} - 1 },
   fallback => 1;

1;

=head1 SEE ALSO

The L<JSON> and L<JSON::XS> modules that do similar, but human-readable,
serialisation.

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/

=cut

Revision:	1.3
Committed:	Sat Oct 26 11:08:34 2013 UTC (10 years, 6 months ago) by root
Branch:	MAIN
CVS Tags:	rel-0_02
Changes since 1.2:	+16 -1 lines
Log Message:	0.02
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3			CBOR::XS - Concise Binary Object Representation (CBOR, RFC7049)
4
5			=encoding utf-8
6
7			=head1 SYNOPSIS
8
9			use CBOR::XS;
10
11			$binary_cbor_data = encode_cbor $perl_value;
12			$perl_value = decode_cbor $binary_cbor_data;
13
14			# OO-interface
15
16			$coder = CBOR::XS->new;
17			#TODO
18
19			=head1 DESCRIPTION
20
21			WARNING! THIS IS A PRE-ALPHA RELEASE! IT WILL CRASH, CORRUPT YOUR DATA AND
22			EAT YOUR CHILDREN!
23
24			This module converts Perl data structures to CBOR and vice versa. Its
25			primary goal is to be I<correct> and its secondary goal is to be
26			I<fast>. To reach the latter goal it was written in C.
27
28			See MAPPING, below, on how CBOR::XS maps perl values to CBOR values and
29			vice versa.
30
31			=cut
32
33			package CBOR::XS;
34
35			use common::sense;
36
37	root	1.3	our $VERSION = 0.02;
38	root	1.1	our @ISA = qw(Exporter);
39
40			our @EXPORT = qw(encode_cbor decode_cbor);
41
42			use Exporter;
43			use XSLoader;
44
45	root	1.3	our $MAGIC = "\xd9\xd9\xf7";
46
47	root	1.1	=head1 FUNCTIONAL INTERFACE
48
49			The following convenience methods are provided by this module. They are
50			exported by default:
51
52			=over 4
53
54			=item $cbor_data = encode_cbor $perl_scalar
55
56			Converts the given Perl data structure to CBOR representation. Croaks on
57			error.
58
59			=item $perl_scalar = decode_cbor $cbor_data
60
61			The opposite of C<encode_cbor>: expects a valid CBOR string to parse,
62			returning the resulting perl scalar. Croaks on error.
63
64			=back
65
66
67			=head1 OBJECT-ORIENTED INTERFACE
68
69			The object oriented interface lets you configure your own encoding or
70			decoding style, within the limits of supported formats.
71
72			=over 4
73
74			=item $cbor = new CBOR::XS
75
76			Creates a new CBOR::XS object that can be used to de/encode CBOR
77			strings. All boolean flags described below are by default I<disabled>.
78
79			The mutators for flags all return the CBOR object again and thus calls can
80			be chained:
81
82			#TODO
83			my $cbor = CBOR::XS->new->encode ({a => [1,2]});
84
85			=item $cbor = $cbor->max_depth ([$maximum_nesting_depth])
86
87			=item $max_depth = $cbor->get_max_depth
88
89			Sets the maximum nesting level (default C<512>) accepted while encoding
90			or decoding. If a higher nesting level is detected in CBOR data or a Perl
91			data structure, then the encoder and decoder will stop and croak at that
92			point.
93
94			Nesting level is defined by number of hash- or arrayrefs that the encoder
95			needs to traverse to reach a given point or the number of C<{> or C<[>
96			characters without their matching closing parenthesis crossed to reach a
97			given character in a string.
98
99			Setting the maximum depth to one disallows any nesting, so that ensures
100			that the object is only a single hash/object or array.
101
102			If no argument is given, the highest possible setting will be used, which
103			is rarely useful.
104
105			Note that nesting is implemented by recursion in C. The default value has
106			been chosen to be as large as typical operating systems allow without
107			crashing.
108
109			See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
110
111			=item $cbor = $cbor->max_size ([$maximum_string_size])
112
113			=item $max_size = $cbor->get_max_size
114
115			Set the maximum length a CBOR string may have (in bytes) where decoding
116			is being attempted. The default is C<0>, meaning no limit. When C<decode>
117			is called on a string that is longer then this many bytes, it will not
118			attempt to decode the string but throw an exception. This setting has no
119			effect on C<encode> (yet).
120
121			If no argument is given, the limit check will be deactivated (same as when
122			C<0> is specified).
123
124			See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
125
126			=item $cbor_data = $cbor->encode ($perl_scalar)
127
128			Converts the given Perl data structure (a scalar value) to its CBOR
129			representation.
130
131			=item $perl_scalar = $cbor->decode ($cbor_data)
132
133			The opposite of C<encode>: expects CBOR data and tries to parse it,
134			returning the resulting simple scalar or reference. Croaks on error.
135
136			=item ($perl_scalar, $octets) = $cbor->decode_prefix ($cbor_data)
137
138			This works like the C<decode> method, but instead of raising an exception
139			when there is trailing garbage after the CBOR string, it will silently
140			stop parsing there and return the number of characters consumed so far.
141
142			This is useful if your CBOR texts are not delimited by an outer protocol
143			and you need to know where the first CBOR string ends amd the next one
144			starts.
145
146			CBOR::XS->new->decode_prefix ("......")
147			=> ("...", 3)
148
149			=back
150
151
152			=head1 MAPPING
153
154			This section describes how CBOR::XS maps Perl values to CBOR values and
155			vice versa. These mappings are designed to "do the right thing" in most
156			circumstances automatically, preserving round-tripping characteristics
157			(what you put in comes out as something equivalent).
158
159			For the more enlightened: note that in the following descriptions,
160			lowercase I<perl> refers to the Perl interpreter, while uppercase I<Perl>
161			refers to the abstract Perl language itself.
162
163
164			=head2 CBOR -> PERL
165
166			=over 4
167
168			=item True, False
169
170			These CBOR values become C<CBOR::XS::true> and C<CBOR::XS::false>,
171			respectively. They are overloaded to act almost exactly like the numbers
172			C<1> and C<0>. You can check whether a scalar is a CBOR boolean by using
173			the C<CBOR::XS::is_bool> function.
174
175	root	1.2	=item Null, Undefined
176	root	1.1
177	root	1.2	CBOR Null and Undefined values becomes C<undef> in Perl (in the future,
178			Undefined may raise an exception).
179	root	1.1
180			=back
181
182
183			=head2 PERL -> CBOR
184
185			The mapping from Perl to CBOR is slightly more difficult, as Perl is a
186			truly typeless language, so we can only guess which CBOR type is meant by
187			a Perl value.
188
189			=over 4
190
191			=item hash references
192
193			Perl hash references become CBOR maps. As there is no inherent ordering
194			in hash keys (or CBOR maps), they will usually be encoded in a
195			pseudo-random order.
196
197			=item array references
198
199			Perl array references become CBOR arrays.
200
201			=item other references
202
203			Other unblessed references are generally not allowed and will cause an
204			exception to be thrown, except for references to the integers C<0> and
205			C<1>, which get turned into C<False> and C<True> in CBOR.
206
207			=item CBOR::XS::true, CBOR::XS::false
208
209			These special values become CBOR True and CBOR False values,
210			respectively. You can also use C<\1> and C<\0> directly if you want.
211
212			=item blessed objects
213
214			Blessed objects are not directly representable in CBOR. TODO
215			See the
216			C<allow_blessed> and C<convert_blessed> methods on various options on
217			how to deal with this: basically, you can choose between throwing an
218			exception, encoding the reference as if it weren't blessed, or provide
219			your own serialiser method.
220
221			=item simple scalars
222
223			TODO
224			Simple Perl scalars (any scalar that is not a reference) are the most
225			difficult objects to encode: CBOR::XS will encode undefined scalars as
226			CBOR C<Null> values, scalars that have last been used in a string context
227			before encoding as CBOR strings, and anything else as number value:
228
229			# dump as number
230			encode_cbor [2] # yields [2]
231			encode_cbor [-3.0e17] # yields [-3e+17]
232			my $value = 5; encode_cbor [$value] # yields [5]
233
234			# used as string, so dump as string
235			print $value;
236			encode_cbor [$value] # yields ["5"]
237
238			# undef becomes null
239			encode_cbor [undef] # yields [null]
240
241			You can force the type to be a CBOR string by stringifying it:
242
243			my $x = 3.1; # some variable containing a number
244			"$x"; # stringified
245			$x .= ""; # another, more awkward way to stringify
246			print $x; # perl does it for you, too, quite often
247
248			You can force the type to be a CBOR number by numifying it:
249
250			my $x = "3"; # some variable containing a string
251			$x += 0; # numify it, ensuring it will be dumped as a number
252			$x *= 1; # same thing, the choice is yours.
253
254			You can not currently force the type in other, less obscure, ways. Tell me
255			if you need this capability (but don't forget to explain why it's needed
256			:).
257
258			Note that numerical precision has the same meaning as under Perl (so
259			binary to decimal conversion follows the same rules as in Perl, which
260			can differ to other languages). Also, your perl interpreter might expose
261			extensions to the floating point numbers of your platform, such as
262			infinities or NaN's - these cannot be represented in CBOR, and it is an
263			error to pass those in.
264
265			=back
266
267
268	root	1.3	=head2 MAGIC HEADER
269
270			There is no way to distinguish CBOR from other formats
271			programmatically. To make it easier to distinguish CBOR from other
272			formats, the CBOR specification has a special "magic string" that can be
273			prepended to any CBOR string without changing it's meaning.
274
275			This string is available as C<$CBOR::XS::MAGIC>. This module does not
276			prepend this string tot he CBOR data it generates, but it will ignroe it
277			if present, so users can prepend this string as a "file type" indicator as
278			required.
279
280
281	root	1.1	=head2 CBOR and JSON
282
283			TODO
284
285
286			=head1 SECURITY CONSIDERATIONS
287
288			When you are using CBOR in a protocol, talking to untrusted potentially
289			hostile creatures requires relatively few measures.
290
291			First of all, your CBOR decoder should be secure, that is, should not have
292			any buffer overflows. Obviously, this module should ensure that and I am
293			trying hard on making that true, but you never know.
294
295			Second, you need to avoid resource-starving attacks. That means you should
296			limit the size of CBOR data you accept, or make sure then when your
297			resources run out, that's just fine (e.g. by using a separate process that
298			can crash safely). The size of a CBOR string in octets is usually a good
299			indication of the size of the resources required to decode it into a Perl
300			structure. While CBOR::XS can check the size of the CBOR text, it might be
301			too late when you already have it in memory, so you might want to check
302			the size before you accept the string.
303
304			Third, CBOR::XS recurses using the C stack when decoding objects and
305			arrays. The C stack is a limited resource: for instance, on my amd64
306			machine with 8MB of stack size I can decode around 180k nested arrays but
307			only 14k nested CBOR objects (due to perl itself recursing deeply on croak
308			to free the temporary). If that is exceeded, the program crashes. To be
309			conservative, the default nesting limit is set to 512. If your process
310			has a smaller stack, you should adjust this setting accordingly with the
311			C<max_depth> method.
312
313			Something else could bomb you, too, that I forgot to think of. In that
314			case, you get to keep the pieces. I am always open for hints, though...
315
316			Also keep in mind that CBOR::XS might leak contents of your Perl data
317			structures in its error messages, so when you serialise sensitive
318			information you might want to make sure that exceptions thrown by CBOR::XS
319			will not end up in front of untrusted eyes.
320
321			=head1 CBOR IMPLEMENTATION NOTES
322
323			This section contains some random implementation notes. They do not
324			describe guaranteed behaviour, but merely behaviour as-is implemented
325			right now.
326
327			64 bit integers are only properly decoded when Perl was built with 64 bit
328			support.
329
330			Strings and arrays are encoded with a definite length. Hashes as well,
331			unless they are tied (or otherwise magical).
332
333			Only the double data type is supported for NV data types - when Perl uses
334			long double to represent floating point values, they might not be encoded
335			properly. Half precision types are accepted, but not encoded.
336
337			Strict mode and canonical mode are not implemented.
338
339
340			=head1 THREADS
341
342			This module is I<not> guaranteed to be thread safe and there are no
343			plans to change this until Perl gets thread support (as opposed to the
344			horribly slow so-called "threads" which are simply slow and bloated
345			process simulations - use fork, it's I<much> faster, cheaper, better).
346
347			(It might actually work, but you have been warned).
348
349
350			=head1 BUGS
351
352			While the goal of this module is to be correct, that unfortunately does
353			not mean it's bug-free, only that I think its design is bug-free. If you
354			keep reporting bugs they will be fixed swiftly, though.
355
356			Please refrain from using rt.cpan.org or any other bug reporting
357			service. I put the contact address into my modules for a reason.
358
359			=cut
360
361			our $true = do { bless \(my $dummy = 1), "CBOR::XS::Boolean" };
362			our $false = do { bless \(my $dummy = 0), "CBOR::XS::Boolean" };
363
364			sub true() { $true }
365			sub false() { $false }
366
367			sub is_bool($) {
368			UNIVERSAL::isa $_[0], "CBOR::XS::Boolean"
369			# or UNIVERSAL::isa $_[0], "CBOR::Literal"
370			}
371
372			XSLoader::load "CBOR::XS", $VERSION;
373
374			package CBOR::XS::Boolean;
375
376			use overload
377			"0+" => sub { ${$_[0]} },
378			"++" => sub { $_[0] = ${$_[0]} + 1 },
379			"--" => sub { $_[0] = ${$_[0]} - 1 },
380			fallback => 1;
381
382			1;
383
384			=head1 SEE ALSO
385
386			The L<JSON> and L<JSON::XS> modules that do similar, but human-readable,
387			serialisation.
388
389			=head1 AUTHOR
390
391			Marc Lehmann <schmorp@schmorp.de>
392			http://home.schmorp.de/
393
394			=cut
395