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.56 by root, Thu Jul 26 11:33:35 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.43';
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;
… …
348enabled by this setting. 348enabled by this setting.
349 349
350If C<$enable> is false, then the C<allow_blessed> setting will decide what 350If C<$enable> is false, then the C<allow_blessed> setting will decide what
351to do when a blessed object is found. 351to do when a blessed object is found.
352 352
353=item $json = $json->filter_json_object ([$coderef]) 353=item $json = $json->filter_json_object ([$coderef->($hashref)])
354 354
355When C<$coderef> is specified, it will be called from C<decode> each 355When 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 356time 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 357newly-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 358need 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 359aliasing) is inserted into the deserialised data structure. If it returns
360an empty list (NOTE: I<not> C<undef>, which is a valid scalar), the 360an empty list (NOTE: I<not> C<undef>, which is a valid scalar), the
361original deserialised hash will be inserted. This setting can slow down 361original deserialised hash will be inserted. This setting can slow down
362decoding considerably. 362decoding considerably.
363 363
364When C<$coderef> is omitted or undefined, C<decode> will not change the 364When C<$coderef> is omitted or undefined, any existing callback will
365deserialised hash in any way. This is maximally fast. 365be removed and C<decode> will not change the deserialised hash in any
366way.
366 367
367Example, convert all JSON objects into the integer 5: 368Example, convert all JSON objects into the integer 5:
368 369
369 my $js = JSON::XS->new->filter_json_object (sub { 5 }); 370 my $js = JSON::XS->new->filter_json_object (sub { 5 });
370 # returns [5] 371 # returns [5]
371 $js->decode ('[{}]') 372 $js->decode ('[{}]')
372 # throw an exception because allow_nonref is not enabled: 373 # throw an exception because allow_nonref is not enabled
374 # so a lone 5 is not allowed.
373 $js->decode ('{"a":1, "b":2}'); 375 $js->decode ('{"a":1, "b":2}');
374 376
375=item $json = $json->filter_json_single_key_object ([$coderef]) 377=item $json = $json->filter_json_single_key_object ($key [=> $coderef->($value)])
376 378
377Works like C<filter_json_object>, but is only called for JSON objects 379Works remotely similar to C<filter_json_object>, but is only called for
378having only a single key. 380JSON objects having a single key named C<$key>.
379 381
380This C<$coderef> is called before the one specified via 382This C<$coderef> is called before the one specified via
381C<filter_json_object>, if any. If it returns something, that will be 383C<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 384object. 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 385structure. If it returns nothing (not even C<undef> but the empty list),
384insertion of single-key objects even in the presence of a mutating 386the callback from C<filter_json_object> will be called next, as if no
385C<filter_json_object> callback, simply return the passed hash. 387single-key callback were specified.
388
389If C<$coderef> is omitted or undefined, the corresponding callback will be
390disabled. There can only ever be one callback for a given key.
386 391
387As this callback gets called less often then the C<filter_json_object> 392As this callback gets called less often then the C<filter_json_object>
388one, decoding speed will not usually suffer as much. Therefore, single-key 393one, decoding speed will not usually suffer as much. Therefore, single-key
389objects make excellent targets to serialise Perl objects into, especially 394objects make excellent targets to serialise Perl objects into, especially
390as single-key JSON objects are as close to the type-tagged value concept 395as single-key JSON objects are as close to the type-tagged value concept
… …
401into the corresponding C<< $WIDGET{<id>} >> object: 406into the corresponding C<< $WIDGET{<id>} >> object:
402 407
403 # return whatever is in $WIDGET{5}: 408 # return whatever is in $WIDGET{5}:
404 JSON::XS 409 JSON::XS
405 ->new 410 ->new
406 ->filter_json_single_key_object (sub { 411 ->filter_json_single_key_object (__widget__ => sub {
407 exists $_[0]{__widget__}
408 ? $WIDGET{ $_[0]{__widget__} } 412 $WIDGET{ $_[0] }
409 : ()
410 }) 413 })
411 ->decode ('{"__widget__": 5') 414 ->decode ('{"__widget__": 5')
412 415
413 # this can be used with a TO_JSON method in some "widget" class 416 # this can be used with a TO_JSON method in some "widget" class
414 # for serialisation to json: 417 # for serialisation to json:
… …
550are represented by the same codepoints in the Perl string, so no manual 553are represented by the same codepoints in the Perl string, so no manual
551decoding is necessary. 554decoding is necessary.
552 555
553=item number 556=item number
554 557
555A JSON number becomes either an integer or numeric (floating point) 558A JSON number becomes either an integer, numeric (floating point) or
556scalar in perl, depending on its range and any fractional parts. On the 559string 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 560the Perl level, there is no difference between those as Perl handles all
558conversion details, but an integer may take slightly less memory and might 561the conversion details, but an integer may take slightly less memory and
559represent more values exactly than (floating point) numbers. 562might represent more values exactly than (floating point) numbers.
563
564If the number consists of digits only, JSON::XS will try to represent
565it as an integer value. If that fails, it will try to represent it as
566a numeric (floating point) value if that is possible without loss of
567precision. Otherwise it will preserve the number as a string value.
568
569Numbers containing a fractional or exponential part will always be
570represented as numeric (floating point) values, possibly at a loss of
571precision.
572
573This might create round-tripping problems as numbers might become strings,
574but as Perl is typeless there is no other way to do it.
560 575
561=item true, false 576=item true, false
562 577
563These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>, 578These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
564respectively. They are overloaded to act almost exactly like the numbers 579respectively. They are overloaded to act almost exactly like the numbers
… …
875still relatively early in its development. If you keep reporting bugs they 890still relatively early in its development. If you keep reporting bugs they
876will be fixed swiftly, though. 891will be fixed swiftly, though.
877 892
878=cut 893=cut
879 894
880our $true = do { bless \(my $dummy = "1"), "JSON::XS::Boolean" }; 895our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" };
881our $false = do { bless \(my $dummy = "0"), "JSON::XS::Boolean" }; 896our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" };
882 897
883sub true() { $true } 898sub true() { $true }
884sub false() { $false } 899sub false() { $false }
885 900
886sub is_bool($) { 901sub is_bool($) {

Diff Legend

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