ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/JSON-XS/XS.pm
(Generate patch)

Comparing JSON-XS/XS.pm (file contents):
Revision 1.51 by root, Mon Jul 2 01:12:27 2007 UTC vs.
Revision 1.59 by root, Mon Aug 27 01:49:01 2007 UTC

… …
81 81
82package JSON::XS; 82package JSON::XS;
83 83
84use strict; 84use strict;
85 85
86our $VERSION = '1.4'; 86our $VERSION = '1.5';
87our @ISA = qw(Exporter); 87our @ISA = qw(Exporter);
88 88
89our @EXPORT = qw(to_json from_json); 89our @EXPORT = qw(to_json from_json);
90 90
91use Exporter; 91use Exporter;
… …
278 278
279Example, space_before and indent disabled, space_after enabled: 279Example, space_before and indent disabled, space_after enabled:
280 280
281 {"key": "value"} 281 {"key": "value"}
282 282
283=item $json = $json->relaxed ([$enable])
284
285If C<$enable> is true (or missing), then C<decode> will accept some
286extensions to normal JSON syntax (see below). C<encode> will not be
287affected in anyway. I<Be aware that this option makes you accept invalid
288JSON texts as if they were valid!>. I suggest only to use this option to
289parse application-specific files written by humans (configuration files,
290resource files etc.)
291
292If C<$enable> is false (the default), then C<decode> will only accept
293valid JSON texts.
294
295Currently accepted extensions are:
296
297=over 4
298
299=item * list items can have an end-comma
300
301JSON I<separates> array elements and key-value pairs with commas. This
302can be annoying if you write JSON texts manually and want to be able to
303quickly append elements, so this extension accepts comma at the end of
304such items not just between them:
305
306 [
307 1,
308 2, <- this comma not normally allowed
309 ]
310 {
311 "k1": "v1",
312 "k2": "v2", <- this comma not normally allowed
313 }
314
315=back
316
283=item $json = $json->canonical ([$enable]) 317=item $json = $json->canonical ([$enable])
284 318
285If C<$enable> is true (or missing), then the C<encode> method will output JSON objects 319If C<$enable> is true (or missing), then the C<encode> method will output JSON objects
286by sorting their keys. This is adding a comparatively high overhead. 320by sorting their keys. This is adding a comparatively high overhead.
287 321
… …
348enabled by this setting. 382enabled by this setting.
349 383
350If C<$enable> is false, then the C<allow_blessed> setting will decide what 384If C<$enable> is false, then the C<allow_blessed> setting will decide what
351to do when a blessed object is found. 385to do when a blessed object is found.
352 386
353=item $json = $json->filter_json_object ([$coderef]) 387=item $json = $json->filter_json_object ([$coderef->($hashref)])
354 388
355When C<$coderef> is specified, it will be called from C<decode> each 389When C<$coderef> is specified, it will be called from C<decode> each
356time it decodes a JSON object. The only argument is a reference to the 390time it decodes a JSON object. The only argument is a reference to the
357newly-created hash. If the code references returns a single scalar (which 391newly-created hash. If the code references returns a single scalar (which
358need not be a reference), this value (i.e. a copy of that scalar to avoid 392need not be a reference), this value (i.e. a copy of that scalar to avoid
359aliasing) is inserted into the deserialised data structure. If it returns 393aliasing) is inserted into the deserialised data structure. If it returns
360an empty list (NOTE: I<not> C<undef>, which is a valid scalar), the 394an empty list (NOTE: I<not> C<undef>, which is a valid scalar), the
361original deserialised hash will be inserted. This setting can slow down 395original deserialised hash will be inserted. This setting can slow down
362decoding considerably. 396decoding considerably.
363 397
364When C<$coderef> is omitted or undefined, C<decode> will not change the 398When C<$coderef> is omitted or undefined, any existing callback will
365deserialised hash in any way. This is maximally fast. 399be removed and C<decode> will not change the deserialised hash in any
400way.
366 401
367Example, convert all JSON objects into the integer 5: 402Example, convert all JSON objects into the integer 5:
368 403
369 my $js = JSON::XS->new->filter_json_object (sub { 5 }); 404 my $js = JSON::XS->new->filter_json_object (sub { 5 });
370 # returns [5] 405 # returns [5]
371 $js->decode ('[{}]') 406 $js->decode ('[{}]')
372 # throw an exception because allow_nonref is not enabled: 407 # throw an exception because allow_nonref is not enabled
408 # so a lone 5 is not allowed.
373 $js->decode ('{"a":1, "b":2}'); 409 $js->decode ('{"a":1, "b":2}');
374 410
375=item $json = $json->filter_json_single_key_object ([$coderef]) 411=item $json = $json->filter_json_single_key_object ($key [=> $coderef->($value)])
376 412
377Works like C<filter_json_object>, but is only called for JSON objects 413Works remotely similar to C<filter_json_object>, but is only called for
378having only a single key. 414JSON objects having a single key named C<$key>.
379 415
380This C<$coderef> is called before the one specified via 416This C<$coderef> is called before the one specified via
381C<filter_json_object>, if any. If it returns something, that will be 417C<filter_json_object>, if any. It gets passed the single value in the JSON
382inserted into the data structure. If it returns nothing, the callback 418object. If it returns a single value, it will be inserted into the data
383from C<filter_json_object> will be called next. If you want to force 419structure. If it returns nothing (not even C<undef> but the empty list),
384insertion of single-key objects even in the presence of a mutating 420the callback from C<filter_json_object> will be called next, as if no
385C<filter_json_object> callback, simply return the passed hash. 421single-key callback were specified.
422
423If C<$coderef> is omitted or undefined, the corresponding callback will be
424disabled. There can only ever be one callback for a given key.
386 425
387As this callback gets called less often then the C<filter_json_object> 426As this callback gets called less often then the C<filter_json_object>
388one, decoding speed will not usually suffer as much. Therefore, single-key 427one, decoding speed will not usually suffer as much. Therefore, single-key
389objects make excellent targets to serialise Perl objects into, especially 428objects make excellent targets to serialise Perl objects into, especially
390as single-key JSON objects are as close to the type-tagged value concept 429as single-key JSON objects are as close to the type-tagged value concept
… …
401into the corresponding C<< $WIDGET{<id>} >> object: 440into the corresponding C<< $WIDGET{<id>} >> object:
402 441
403 # return whatever is in $WIDGET{5}: 442 # return whatever is in $WIDGET{5}:
404 JSON::XS 443 JSON::XS
405 ->new 444 ->new
406 ->filter_json_single_key_object (sub { 445 ->filter_json_single_key_object (__widget__ => sub {
407 exists $_[0]{__widget__}
408 ? $WIDGET{ $_[0]{__widget__} } 446 $WIDGET{ $_[0] }
409 : ()
410 }) 447 })
411 ->decode ('{"__widget__": 5') 448 ->decode ('{"__widget__": 5')
412 449
413 # this can be used with a TO_JSON method in some "widget" class 450 # this can be used with a TO_JSON method in some "widget" class
414 # for serialisation to json: 451 # for serialisation to json:
… …
550are represented by the same codepoints in the Perl string, so no manual 587are represented by the same codepoints in the Perl string, so no manual
551decoding is necessary. 588decoding is necessary.
552 589
553=item number 590=item number
554 591
555A JSON number becomes either an integer or numeric (floating point) 592A JSON number becomes either an integer, numeric (floating point) or
556scalar in perl, depending on its range and any fractional parts. On the 593string scalar in perl, depending on its range and any fractional parts. On
557Perl level, there is no difference between those as Perl handles all the 594the Perl level, there is no difference between those as Perl handles all
558conversion details, but an integer may take slightly less memory and might 595the conversion details, but an integer may take slightly less memory and
559represent more values exactly than (floating point) numbers. 596might represent more values exactly than (floating point) numbers.
597
598If the number consists of digits only, JSON::XS will try to represent
599it as an integer value. If that fails, it will try to represent it as
600a numeric (floating point) value if that is possible without loss of
601precision. Otherwise it will preserve the number as a string value.
602
603Numbers containing a fractional or exponential part will always be
604represented as numeric (floating point) values, possibly at a loss of
605precision.
606
607This might create round-tripping problems as numbers might become strings,
608but as Perl is typeless there is no other way to do it.
560 609
561=item true, false 610=item true, false
562 611
563These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>, 612These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
564respectively. They are overloaded to act almost exactly like the numbers 613respectively. They are overloaded to act almost exactly like the numbers
… …
875still relatively early in its development. If you keep reporting bugs they 924still relatively early in its development. If you keep reporting bugs they
876will be fixed swiftly, though. 925will be fixed swiftly, though.
877 926
878=cut 927=cut
879 928
880our $true = do { bless \(my $dummy = "1"), "JSON::XS::Boolean" }; 929our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" };
881our $false = do { bless \(my $dummy = "0"), "JSON::XS::Boolean" }; 930our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" };
882 931
883sub true() { $true } 932sub true() { $true }
884sub false() { $false } 933sub false() { $false }
885 934
886sub is_bool($) { 935sub is_bool($) {

Diff Legend

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