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.62 by root, Thu Oct 11 22:52:52 2007 UTC

1=encoding utf-8
2
1=head1 NAME 3=head1 NAME
2 4
3JSON::XS - JSON serialising/deserialising, done correctly and fast 5JSON::XS - JSON serialising/deserialising, done correctly and fast
6
7JSON::XS - 正しくて高速な JSON シリアライザ/デシリアライザ
8 (http://fleur.hio.jp/perldoc/mix/lib/JSON/XS.html)
4 9
5=head1 SYNOPSIS 10=head1 SYNOPSIS
6 11
7 use JSON::XS; 12 use JSON::XS;
8 13
… …
81 86
82package JSON::XS; 87package JSON::XS;
83 88
84use strict; 89use strict;
85 90
86our $VERSION = '1.4'; 91our $VERSION = '1.5';
87our @ISA = qw(Exporter); 92our @ISA = qw(Exporter);
88 93
89our @EXPORT = qw(to_json from_json); 94our @EXPORT = qw(to_json from_json);
90 95
91use Exporter; 96use Exporter;
… …
278 283
279Example, space_before and indent disabled, space_after enabled: 284Example, space_before and indent disabled, space_after enabled:
280 285
281 {"key": "value"} 286 {"key": "value"}
282 287
288=item $json = $json->relaxed ([$enable])
289
290If C<$enable> is true (or missing), then C<decode> will accept some
291extensions to normal JSON syntax (see below). C<encode> will not be
292affected in anyway. I<Be aware that this option makes you accept invalid
293JSON texts as if they were valid!>. I suggest only to use this option to
294parse application-specific files written by humans (configuration files,
295resource files etc.)
296
297If C<$enable> is false (the default), then C<decode> will only accept
298valid JSON texts.
299
300Currently accepted extensions are:
301
302=over 4
303
304=item * list items can have an end-comma
305
306JSON I<separates> array elements and key-value pairs with commas. This
307can be annoying if you write JSON texts manually and want to be able to
308quickly append elements, so this extension accepts comma at the end of
309such items not just between them:
310
311 [
312 1,
313 2, <- this comma not normally allowed
314 ]
315 {
316 "k1": "v1",
317 "k2": "v2", <- this comma not normally allowed
318 }
319
320=item * shell-style '#'-comments
321
322Whenever JSON allows whitespace, shell-style comments are additionally
323allowed. They are terminated by the first carriage-return or line-feed
324character, after which more white-space and comments are allowed.
325
326 [
327 1, # this comment not allowed in JSON
328 # neither this one...
329 ]
330
331=back
332
283=item $json = $json->canonical ([$enable]) 333=item $json = $json->canonical ([$enable])
284 334
285If C<$enable> is true (or missing), then the C<encode> method will output JSON objects 335If 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. 336by sorting their keys. This is adding a comparatively high overhead.
287 337
… …
348enabled by this setting. 398enabled by this setting.
349 399
350If C<$enable> is false, then the C<allow_blessed> setting will decide what 400If C<$enable> is false, then the C<allow_blessed> setting will decide what
351to do when a blessed object is found. 401to do when a blessed object is found.
352 402
353=item $json = $json->filter_json_object ([$coderef]) 403=item $json = $json->filter_json_object ([$coderef->($hashref)])
354 404
355When C<$coderef> is specified, it will be called from C<decode> each 405When 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 406time 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 407newly-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 408need 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 409aliasing) is inserted into the deserialised data structure. If it returns
360an empty list (NOTE: I<not> C<undef>, which is a valid scalar), the 410an empty list (NOTE: I<not> C<undef>, which is a valid scalar), the
361original deserialised hash will be inserted. This setting can slow down 411original deserialised hash will be inserted. This setting can slow down
362decoding considerably. 412decoding considerably.
363 413
364When C<$coderef> is omitted or undefined, C<decode> will not change the 414When C<$coderef> is omitted or undefined, any existing callback will
365deserialised hash in any way. This is maximally fast. 415be removed and C<decode> will not change the deserialised hash in any
416way.
366 417
367Example, convert all JSON objects into the integer 5: 418Example, convert all JSON objects into the integer 5:
368 419
369 my $js = JSON::XS->new->filter_json_object (sub { 5 }); 420 my $js = JSON::XS->new->filter_json_object (sub { 5 });
370 # returns [5] 421 # returns [5]
371 $js->decode ('[{}]') 422 $js->decode ('[{}]')
372 # throw an exception because allow_nonref is not enabled: 423 # throw an exception because allow_nonref is not enabled
424 # so a lone 5 is not allowed.
373 $js->decode ('{"a":1, "b":2}'); 425 $js->decode ('{"a":1, "b":2}');
374 426
375=item $json = $json->filter_json_single_key_object ([$coderef]) 427=item $json = $json->filter_json_single_key_object ($key [=> $coderef->($value)])
376 428
377Works like C<filter_json_object>, but is only called for JSON objects 429Works remotely similar to C<filter_json_object>, but is only called for
378having only a single key. 430JSON objects having a single key named C<$key>.
379 431
380This C<$coderef> is called before the one specified via 432This C<$coderef> is called before the one specified via
381C<filter_json_object>, if any. If it returns something, that will be 433C<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 434object. 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 435structure. If it returns nothing (not even C<undef> but the empty list),
384insertion of single-key objects even in the presence of a mutating 436the callback from C<filter_json_object> will be called next, as if no
385C<filter_json_object> callback, simply return the passed hash. 437single-key callback were specified.
438
439If C<$coderef> is omitted or undefined, the corresponding callback will be
440disabled. There can only ever be one callback for a given key.
386 441
387As this callback gets called less often then the C<filter_json_object> 442As this callback gets called less often then the C<filter_json_object>
388one, decoding speed will not usually suffer as much. Therefore, single-key 443one, decoding speed will not usually suffer as much. Therefore, single-key
389objects make excellent targets to serialise Perl objects into, especially 444objects make excellent targets to serialise Perl objects into, especially
390as single-key JSON objects are as close to the type-tagged value concept 445as single-key JSON objects are as close to the type-tagged value concept
… …
401into the corresponding C<< $WIDGET{<id>} >> object: 456into the corresponding C<< $WIDGET{<id>} >> object:
402 457
403 # return whatever is in $WIDGET{5}: 458 # return whatever is in $WIDGET{5}:
404 JSON::XS 459 JSON::XS
405 ->new 460 ->new
406 ->filter_json_single_key_object (sub { 461 ->filter_json_single_key_object (__widget__ => sub {
407 exists $_[0]{__widget__}
408 ? $WIDGET{ $_[0]{__widget__} } 462 $WIDGET{ $_[0] }
409 : ()
410 }) 463 })
411 ->decode ('{"__widget__": 5') 464 ->decode ('{"__widget__": 5')
412 465
413 # this can be used with a TO_JSON method in some "widget" class 466 # this can be used with a TO_JSON method in some "widget" class
414 # for serialisation to json: 467 # for serialisation to json:
… …
550are represented by the same codepoints in the Perl string, so no manual 603are represented by the same codepoints in the Perl string, so no manual
551decoding is necessary. 604decoding is necessary.
552 605
553=item number 606=item number
554 607
555A JSON number becomes either an integer or numeric (floating point) 608A JSON number becomes either an integer, numeric (floating point) or
556scalar in perl, depending on its range and any fractional parts. On the 609string 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 610the Perl level, there is no difference between those as Perl handles all
558conversion details, but an integer may take slightly less memory and might 611the conversion details, but an integer may take slightly less memory and
559represent more values exactly than (floating point) numbers. 612might represent more values exactly than (floating point) numbers.
613
614If the number consists of digits only, JSON::XS will try to represent
615it as an integer value. If that fails, it will try to represent it as
616a numeric (floating point) value if that is possible without loss of
617precision. Otherwise it will preserve the number as a string value.
618
619Numbers containing a fractional or exponential part will always be
620represented as numeric (floating point) values, possibly at a loss of
621precision.
622
623This might create round-tripping problems as numbers might become strings,
624but as Perl is typeless there is no other way to do it.
560 625
561=item true, false 626=item true, false
562 627
563These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>, 628These JSON atoms become C<JSON::XS::true> and C<JSON::XS::false>,
564respectively. They are overloaded to act almost exactly like the numbers 629respectively. They are overloaded to act almost exactly like the numbers
… …
606 to_json [\0,JSON::XS::true] # yields [false,true] 671 to_json [\0,JSON::XS::true] # yields [false,true]
607 672
608=item JSON::XS::true, JSON::XS::false 673=item JSON::XS::true, JSON::XS::false
609 674
610These special values become JSON true and JSON false values, 675These special values become JSON true and JSON false values,
611respectively. You cna alos use C<\1> and C<\0> directly if you want. 676respectively. You can also use C<\1> and C<\0> directly if you want.
612 677
613=item blessed objects 678=item blessed objects
614 679
615Blessed objects are not allowed. JSON::XS currently tries to encode their 680Blessed objects are not allowed. JSON::XS currently tries to encode their
616underlying representation (hash- or arrayref), but this behaviour might 681underlying representation (hash- or arrayref), but this behaviour might
… …
875still relatively early in its development. If you keep reporting bugs they 940still relatively early in its development. If you keep reporting bugs they
876will be fixed swiftly, though. 941will be fixed swiftly, though.
877 942
878=cut 943=cut
879 944
880our $true = do { bless \(my $dummy = "1"), "JSON::XS::Boolean" }; 945our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" };
881our $false = do { bless \(my $dummy = "0"), "JSON::XS::Boolean" }; 946our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" };
882 947
883sub true() { $true } 948sub true() { $true }
884sub false() { $false } 949sub false() { $false }
885 950
886sub is_bool($) { 951sub is_bool($) {

Diff Legend

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