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.51 by root, Mon Jul 2 01:12:27 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);
… …
88use strict; 84use strict;
89 85
90our $VERSION = '1.4'; 86our $VERSION = '1.4';
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])
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, C<decode> will not change the
365deserialised hash in any way. This is maximally fast.
366
367Example, convert all JSON objects into the integer 5:
368
369 my $js = JSON::XS->new->filter_json_object (sub { 5 });
370 # returns [5]
371 $js->decode ('[{}]')
372 # throw an exception because allow_nonref is not enabled:
373 $js->decode ('{"a":1, "b":2}');
374
375=item $json = $json->filter_json_single_key_object ([$coderef])
376
377Works like C<filter_json_object>, but is only called for JSON objects
378having only a single key.
379
380This C<$coderef> is called before the one specified via
381C<filter_json_object>, if any. If it returns something, that will be
382inserted into the data structure. If it returns nothing, the callback
383from C<filter_json_object> will be called next. If you want to force
384insertion of single-key objects even in the presence of a mutating
385C<filter_json_object> callback, simply return the passed hash.
386
387As this callback gets called less often then the C<filter_json_object>
388one, decoding speed will not usually suffer as much. Therefore, single-key
389objects make excellent targets to serialise Perl objects into, especially
390as single-key JSON objects are as close to the type-tagged value concept
391as JSON gets (its basically an ID/VALUE tuple). Of course, JSON does not
392support this in any way, so you need to make sure your data never looks
393like a serialised Perl hash.
394
395Typical names for the single object key are C<__class_whatever__>, or
396C<$__dollars_are_rarely_used__$> or C<}ugly_brace_placement>, or even
397things like C<__class_md5sum(classname)__>, to reduce the risk of clashing
398with real hashes.
399
400Example, decode JSON objects of the form C<< { "__widget__" => <id> } >>
401into the corresponding C<< $WIDGET{<id>} >> object:
402
403 # return whatever is in $WIDGET{5}:
404 JSON::XS
405 ->new
406 ->filter_json_single_key_object (sub {
407 exists $_[0]{__widget__}
408 ? $WIDGET{ $_[0]{__widget__} }
409 : ()
410 })
411 ->decode ('{"__widget__": 5')
412
413 # this can be used with a TO_JSON method in some "widget" class
414 # for serialisation to json:
415 sub WidgetBase::TO_JSON {
416 my ($self) = @_;
417
418 unless ($self->{id}) {
419 $self->{id} = ..get..some..id..;
420 $WIDGET{$self->{id}} = $self;
421 }
422
423 { __widget__ => $self->{id} }
424 }
356 425
357=item $json = $json->shrink ([$enable]) 426=item $json = $json->shrink ([$enable])
358 427
359Perl usually over-allocates memory a bit when allocating space for 428Perl usually over-allocates memory a bit when allocating space for
360strings. This flag optionally resizes strings generated by either 429strings. This flag optionally resizes strings generated by either
… …
806still relatively early in its development. If you keep reporting bugs they 875still relatively early in its development. If you keep reporting bugs they
807will be fixed swiftly, though. 876will be fixed swiftly, though.
808 877
809=cut 878=cut
810 879
811our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" }; 880our $true = do { bless \(my $dummy = "1"), "JSON::XS::Boolean" };
812our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" }; 881our $false = do { bless \(my $dummy = "0"), "JSON::XS::Boolean" };
813 882
814sub true() { $true } 883sub true() { $true }
815sub false() { $false } 884sub false() { $false }
816 885
817sub is_bool($) { 886sub is_bool($) {

Diff Legend

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