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.48 by root, Mon Jun 25 22:11:39 2007 UTC vs.
Revision 1.56 by root, Thu Jul 26 11:33:35 2007 UTC

… …
9 # exported functions, they croak on error 9 # exported functions, they croak on error
10 # and expect/generate UTF-8 10 # and expect/generate UTF-8
11 11
12 $utf8_encoded_json_text = to_json $perl_hash_or_arrayref; 12 $utf8_encoded_json_text = to_json $perl_hash_or_arrayref;
13 $perl_hash_or_arrayref = from_json $utf8_encoded_json_text; 13 $perl_hash_or_arrayref = from_json $utf8_encoded_json_text;
14
15 # objToJson and jsonToObj aliases to to_json and from_json
16 # are exported for compatibility to the JSON module,
17 # but should not be used in new code.
18 14
19 # OO-interface 15 # OO-interface
20 16
21 $coder = JSON::XS->new->ascii->pretty->allow_nonref; 17 $coder = JSON::XS->new->ascii->pretty->allow_nonref;
22 $pretty_printed_unencoded = $coder->encode ($perl_scalar); 18 $pretty_printed_unencoded = $coder->encode ($perl_scalar);
… …
85 81
86package JSON::XS; 82package JSON::XS;
87 83
88use strict; 84use strict;
89 85
90our $VERSION = '1.4'; 86our $VERSION = '1.43';
91our @ISA = qw(Exporter); 87our @ISA = qw(Exporter);
92 88
93our @EXPORT = qw(to_json from_json objToJson jsonToObj); 89our @EXPORT = qw(to_json from_json);
94 90
95use Exporter; 91use Exporter;
96use XSLoader; 92use XSLoader;
97 93
98=head1 FUNCTIONAL INTERFACE 94=head1 FUNCTIONAL INTERFACE
… …
351future, global hooks might get installed that influence C<decode> and are 347future, global hooks might get installed that influence C<decode> and are
352enabled by this setting. 348enabled by this setting.
353 349
354If 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
355to do when a blessed object is found. 351to do when a blessed object is found.
352
353=item $json = $json->filter_json_object ([$coderef->($hashref)])
354
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
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
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
361original deserialised hash will be inserted. This setting can slow down
362decoding considerably.
363
364When C<$coderef> is omitted or undefined, any existing callback will
365be removed and C<decode> will not change the deserialised hash in any
366way.
367
368Example, convert all JSON objects into the integer 5:
369
370 my $js = JSON::XS->new->filter_json_object (sub { 5 });
371 # returns [5]
372 $js->decode ('[{}]')
373 # throw an exception because allow_nonref is not enabled
374 # so a lone 5 is not allowed.
375 $js->decode ('{"a":1, "b":2}');
376
377=item $json = $json->filter_json_single_key_object ($key [=> $coderef->($value)])
378
379Works remotely similar to C<filter_json_object>, but is only called for
380JSON objects having a single key named C<$key>.
381
382This C<$coderef> is called before the one specified via
383C<filter_json_object>, if any. It gets passed the single value in the JSON
384object. If it returns a single value, it will be inserted into the data
385structure. If it returns nothing (not even C<undef> but the empty list),
386the callback from C<filter_json_object> will be called next, as if no
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.
391
392As this callback gets called less often then the C<filter_json_object>
393one, decoding speed will not usually suffer as much. Therefore, single-key
394objects make excellent targets to serialise Perl objects into, especially
395as single-key JSON objects are as close to the type-tagged value concept
396as JSON gets (its basically an ID/VALUE tuple). Of course, JSON does not
397support this in any way, so you need to make sure your data never looks
398like a serialised Perl hash.
399
400Typical names for the single object key are C<__class_whatever__>, or
401C<$__dollars_are_rarely_used__$> or C<}ugly_brace_placement>, or even
402things like C<__class_md5sum(classname)__>, to reduce the risk of clashing
403with real hashes.
404
405Example, decode JSON objects of the form C<< { "__widget__" => <id> } >>
406into the corresponding C<< $WIDGET{<id>} >> object:
407
408 # return whatever is in $WIDGET{5}:
409 JSON::XS
410 ->new
411 ->filter_json_single_key_object (__widget__ => sub {
412 $WIDGET{ $_[0] }
413 })
414 ->decode ('{"__widget__": 5')
415
416 # this can be used with a TO_JSON method in some "widget" class
417 # for serialisation to json:
418 sub WidgetBase::TO_JSON {
419 my ($self) = @_;
420
421 unless ($self->{id}) {
422 $self->{id} = ..get..some..id..;
423 $WIDGET{$self->{id}} = $self;
424 }
425
426 { __widget__ => $self->{id} }
427 }
356 428
357=item $json = $json->shrink ([$enable]) 429=item $json = $json->shrink ([$enable])
358 430
359Perl usually over-allocates memory a bit when allocating space for 431Perl usually over-allocates memory a bit when allocating space for
360strings. This flag optionally resizes strings generated by either 432strings. This flag optionally resizes strings generated by either
… …
481are 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
482decoding is necessary. 554decoding is necessary.
483 555
484=item number 556=item number
485 557
486A JSON number becomes either an integer or numeric (floating point) 558A JSON number becomes either an integer, numeric (floating point) or
487scalar 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
488Perl 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
489conversion details, but an integer may take slightly less memory and might 561the conversion details, but an integer may take slightly less memory and
490represent 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.
491 575
492=item true, false 576=item true, false
493 577
494These 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>,
495respectively. They are overloaded to act almost exactly like the numbers 579respectively. They are overloaded to act almost exactly like the numbers

Diff Legend

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