diff --git a/json/Makefile.PL b/json/Makefile.PL new file mode 100644 index 0000000..79fd214 --- /dev/null +++ b/json/Makefile.PL @@ -0,0 +1,143 @@ +require 5.00503; +use strict; +use ExtUtils::MakeMaker; + +use lib qw( ./lib ); + +$| = 1; + +eval q| require JSON |; + +# B module can't install? I'm not careful for such a problem. +# Leave us alone today? +if ($@) { + print "We try to look up lib/JSON.pm, but in vain. B module can't install?\n"; + print "Set the environmental variable 'PERL_DL_NONLAZY' with 0.\n"; + print "And see to ExtUtils::MM_Unix.\n"; + print "perl says : $@"; + print "We do not make Makefile by requiring Perl version 7.0.\n"; + require 7.0000; +} + + +my $version = JSON->VERSION; +my $req_xs_ver = JSON->require_xs_version; +my $has_xs = 0; +my $xs_ver_is_ok; +my $message; +my $pp_only = $ENV{ PERL_ONLY } || $ENV{ NO_XS }; + +eval q| require JSON::XS |; + +$has_xs = 1 unless ($@); + + +if ($has_xs) { + my $xs_version = JSON::XS->VERSION; + if ($xs_version >= $req_xs_ver) { + $message = "You have JSON::XS (v.$xs_version), so JSON can work very fast!!"; + $xs_ver_is_ok++; + } + else { + $message = "Your JSON::XS version is $xs_version, but if you install v.$req_xs_ver,\n" + . "JSON will work faster."; + } +} +else { + $message = "If you install JSON::XS v.$req_xs_ver, it makes JSON faster."; +} + +print < $req_xs_ver ); + } + +} + + +WriteMakefile( + 'NAME' => 'JSON', + 'VERSION_FROM' => 'lib/JSON.pm', # finds $VERSION + 'PREREQ_PM' => { + 'Test::More' => 0, + @prereq_pm, + }, + ($] >= 5.005 ? ## Add these new keywords supported since 5.005 + (ABSTRACT_FROM => 'lib/JSON.pm', # retrieve abstract from module + AUTHOR => 'Makamaka Hannyaharamitu, Emakamaka[at]cpan.orgE') : ()), + ( $ExtUtils::MakeMaker::VERSION >= 6.3002 ? ('LICENSE' => 'perl', ) : () ), + + ( $ExtUtils::MakeMaker::VERSION >= 6.46 ? ( + 'META_MERGE' => { + resources => { + repository => 'http://github.com/makamaka/JSON', + }, + } ) : () + ), +); + + +if ($] < 5.006) { # I saw to http://d.hatena.ne.jp/asakusabashi/20051231/p1 + open(IN, "Makefile"); + open(OUT,">Makefile.tmp") || die; + while() { + s/PERL_DL_NONLAZY=1//g; + print OUT; + } + close(OUT); + close(IN); + rename("Makefile.tmp" => "Makefile"); +} + + + + +sub can_auto_xs_install { + return 0 if $] < 5.008002; # JSON::XS requires + return 0 unless ( $ENV{PERL5_CPAN_IS_RUNNING} or $ENV{PERL5_CPANM_IS_RUNNING} ); # not cpan/cpanm running + return can_cc(); +} + + +# copied from http://cpansearch.perl.org/src/GBARR/Scalar-List-Utils-1.23/Makefile.PL + +use Config; + + +sub can_cc { + + require File::Spec; + + foreach my $cmd (split(/ /, $Config::Config{cc})) { + my $_cmd = $cmd; + + return $_cmd if (-x $_cmd or $_cmd = MM->maybe_command($_cmd)); + + for my $dir ((split /$Config::Config{path_sep}/, $ENV{PATH}), '.') { + my $abs = File::Spec->catfile($dir, $_[1]); + return $abs if (-x $abs or $abs = MM->maybe_command($abs)); + } + } + + return; +} diff --git a/json/README b/json/README new file mode 100644 index 0000000..f24a15b --- /dev/null +++ b/json/README @@ -0,0 +1,1552 @@ +JSON version 2.53 +================= + +JSON::PP was inculded in JSON distribution (CPAN module). +It comes to be a perl core module in Perl 5.14. +And JSON::PP well be split away it. + +This developer-versoin is for the preparation. + + * JSON distribution will inculde yet another JSON::PP modules. + They are JSNO::backportPP. So JSON.pm should work as it did at all! + +================= + +INSTALLATION + +To install this module type the following: + + perl Makefile.PL + make + make test + make install + +NAME + JSON - JSON (JavaScript Object Notation) encoder/decoder + +SYNOPSIS + use JSON; # imports encode_json, decode_json, to_json and from_json. + + # simple and fast interfaces (expect/generate UTF-8) + + $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref; + $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text; + + # OO-interface + + $json = JSON->new->allow_nonref; + + $json_text = $json->encode( $perl_scalar ); + $perl_scalar = $json->decode( $json_text ); + + $pretty_printed = $json->pretty->encode( $perl_scalar ); # pretty-printing + + # If you want to use PP only support features, call with '-support_by_pp' + # When XS unsupported feature is enable, using PP (de|en)code instead of XS ones. + + use JSON -support_by_pp; + + # option-acceptable interfaces (expect/generate UNICODE by default) + + $json_text = to_json( $perl_scalar, { ascii => 1, pretty => 1 } ); + $perl_scalar = from_json( $json_text, { utf8 => 1 } ); + + # Between (en|de)code_json and (to|from)_json, if you want to write + # a code which communicates to an outer world (encoded in UTF-8), + # recommend to use (en|de)code_json. + +VERSION + 2.53 + + This version is compatible with JSON::XS 2.27 and later. + +NOTE + JSON::PP was inculded in "JSON" distribution. It comes to be a perl core + module in Perl 5.14. And JSON::PP will be split away it. + + "JSON" distribution will inculde yet another JSON::PP modules. They are + JSNO::backportPP and so on. JSON.pm should work as it did at all. + +DESCRIPTION + ************************** CAUTION ******************************** + * This is 'JSON module version 2' and there are many differences * + * to version 1.xx * + * Please check your applications useing old version. * + * See to 'INCOMPATIBLE CHANGES TO OLD VERSION' * + ******************************************************************* + + JSON (JavaScript Object Notation) is a simple data format. See to + and + "RFC4627"(). + + This module converts Perl data structures to JSON and vice versa using + either JSON::XS or JSON::PP. + + JSON::XS is the fastest and most proper JSON module on CPAN which must + be compiled and installed in your environment. JSON::PP is a pure-Perl + module which is bundled in this distribution and has a strong + compatibility to JSON::XS. + + This module try to use JSON::XS by default and fail to it, use JSON::PP + instead. So its features completely depend on JSON::XS or JSON::PP. + + See to "BACKEND MODULE DECISION". + + To distinguish the module name 'JSON' and the format type JSON, the + former is quoted by C<> (its results vary with your using media), and + the latter is left just as it is. + + Module name : "JSON" + + Format type : JSON + + FEATURES + * correct unicode handling + + This module (i.e. backend modules) knows how to handle Unicode, + documents how and when it does so, and even documents what "correct" + means. + + Even though there are limitations, this feature is available since + Perl version 5.6. + + JSON::XS requires Perl 5.8.2 (but works correctly in 5.8.8 or + later), so in older versions "JSON" sholud call JSON::PP as the + backend which can be used since Perl 5.005. + + With Perl 5.8.x JSON::PP works, but from 5.8.0 to 5.8.2, because of + a Perl side problem, JSON::PP works slower in the versions. And in + 5.005, the Unicode handling is not available. See to "UNICODE + HANDLING ON PERLS" in JSON::PP for more information. + + See also to "A FEW NOTES ON UNICODE AND PERL" in JSON::XS and + "ENCODING/CODESET_FLAG_NOTES" in JSON::XS. + + * round-trip integrity + + When you serialise a perl data structure using only data types + supported by JSON and Perl, the deserialised data structure is + identical on the Perl level. (e.g. the string "2.0" doesn't suddenly + become "2" just because it looks like a number). There *are* minor + exceptions to this, read the "MAPPING" section below to learn about + those. + + * strict checking of JSON correctness + + There is no guessing, no generating of illegal JSON texts by + default, and only JSON is accepted as input by default (the latter + is a security feature). + + See to "FEATURES" in JSON::XS and "FEATURES" in JSON::PP. + + * fast + + This module returns a JSON::XS object itself if available. Compared + to other JSON modules and other serialisers such as Storable, + JSON::XS usually compares favourably in terms of speed, too. + + If not available, "JSON" returns a JSON::PP object instead of + JSON::XS and it is very slow as pure-Perl. + + * simple to use + + This module has both a simple functional interface as well as an + object oriented interface interface. + + * reasonably versatile output formats + + You can choose between the most compact guaranteed-single-line + format possible (nice for simple line-based protocols), a pure-ASCII + format (for when your transport is not 8-bit clean, still supports + the whole Unicode range), or a pretty-printed format (for when you + want to read that stuff). Or you can combine those features in + whatever way you like. + +FUNCTIONAL INTERFACE + Some documents are copied and modified from "FUNCTIONAL INTERFACE" in + JSON::XS. "to_json" and "from_json" are additional functions. + + encode_json + $json_text = encode_json $perl_scalar + + Converts the given Perl data structure to a UTF-8 encoded, binary + string. + + This function call is functionally identical to: + + $json_text = JSON->new->utf8->encode($perl_scalar) + + decode_json + $perl_scalar = decode_json $json_text + + The opposite of "encode_json": expects an UTF-8 (binary) string and + tries to parse that as an UTF-8 encoded JSON text, returning the + resulting reference. + + This function call is functionally identical to: + + $perl_scalar = JSON->new->utf8->decode($json_text) + + to_json + $json_text = to_json($perl_scalar) + + Converts the given Perl data structure to a json string. + + This function call is functionally identical to: + + $json_text = JSON->new->encode($perl_scalar) + + Takes a hash reference as the second. + + $json_text = to_json($perl_scalar, $flag_hashref) + + So, + + $json_text = to_json($perl_scalar, {utf8 => 1, pretty => 1}) + + equivalent to: + + $json_text = JSON->new->utf8(1)->pretty(1)->encode($perl_scalar) + + If you want to write a modern perl code which communicates to outer + world, you should use "encode_json" (supposed that JSON data are encoded + in UTF-8). + + from_json + $perl_scalar = from_json($json_text) + + The opposite of "to_json": expects a json string and tries to parse it, + returning the resulting reference. + + This function call is functionally identical to: + + $perl_scalar = JSON->decode($json_text) + + Takes a hash reference as the second. + + $perl_scalar = from_json($json_text, $flag_hashref) + + So, + + $perl_scalar = from_json($json_text, {utf8 => 1}) + + equivalent to: + + $perl_scalar = JSON->new->utf8(1)->decode($json_text) + + If you want to write a modern perl code which communicates to outer + world, you should use "decode_json" (supposed that JSON data are encoded + in UTF-8). + + JSON::is_bool + $is_boolean = JSON::is_bool($scalar) + + Returns true if the passed scalar represents either JSON::true or + JSON::false, two constants that act like 1 and 0 respectively and are + also used to represent JSON "true" and "false" in Perl strings. + + JSON::true + Returns JSON true value which is blessed object. It "isa" JSON::Boolean + object. + + JSON::false + Returns JSON false value which is blessed object. It "isa" JSON::Boolean + object. + + JSON::null + Returns "undef". + + See MAPPING, below, for more information on how JSON values are mapped + to Perl. + +HOW DO I DECODE A DATA FROM OUTER AND ENCODE TO OUTER + This section supposes that your perl vresion is 5.8 or later. + + If you know a JSON text from an outer world - a network, a file content, + and so on, is encoded in UTF-8, you should use "decode_json" or "JSON" + module object with "utf8" enable. And the decoded result will contain + UNICODE characters. + + # from network + my $json = JSON->new->utf8; + my $json_text = CGI->new->param( 'json_data' ); + my $perl_scalar = $json->decode( $json_text ); + + # from file content + local $/; + open( my $fh, '<', 'json.data' ); + $json_text = <$fh>; + $perl_scalar = decode_json( $json_text ); + + If an outer data is not encoded in UTF-8, firstly you should "decode" + it. + + use Encode; + local $/; + open( my $fh, '<', 'json.data' ); + my $encoding = 'cp932'; + my $unicode_json_text = decode( $encoding, <$fh> ); # UNICODE + + # or you can write the below code. + # + # open( my $fh, "<:encoding($encoding)", 'json.data' ); + # $unicode_json_text = <$fh>; + + In this case, $unicode_json_text is of course UNICODE string. So you + cannot use "decode_json" nor "JSON" module object with "utf8" enable. + Instead of them, you use "JSON" module object with "utf8" disable or + "from_json". + + $perl_scalar = $json->utf8(0)->decode( $unicode_json_text ); + # or + $perl_scalar = from_json( $unicode_json_text ); + + Or "encode 'utf8'" and "decode_json": + + $perl_scalar = decode_json( encode( 'utf8', $unicode_json_text ) ); + # this way is not efficient. + + And now, you want to convert your $perl_scalar into JSON data and send + it to an outer world - a network or a file content, and so on. + + Your data usually contains UNICODE strings and you want the converted + data to be encoded in UTF-8, you should use "encode_json" or "JSON" + module object with "utf8" enable. + + print encode_json( $perl_scalar ); # to a network? file? or display? + # or + print $json->utf8->encode( $perl_scalar ); + + If $perl_scalar does not contain UNICODE but $encoding-encoded strings + for some reason, then its characters are regarded as latin1 for perl + (because it does not concern with your $encoding). You cannot use + "encode_json" nor "JSON" module object with "utf8" enable. Instead of + them, you use "JSON" module object with "utf8" disable or "to_json". + Note that the resulted text is a UNICODE string but no problem to print + it. + + # $perl_scalar contains $encoding encoded string values + $unicode_json_text = $json->utf8(0)->encode( $perl_scalar ); + # or + $unicode_json_text = to_json( $perl_scalar ); + # $unicode_json_text consists of characters less than 0x100 + print $unicode_json_text; + + Or "decode $encoding" all string values and "encode_json": + + $perl_scalar->{ foo } = decode( $encoding, $perl_scalar->{ foo } ); + # ... do it to each string values, then encode_json + $json_text = encode_json( $perl_scalar ); + + This method is a proper way but probably not efficient. + + See to Encode, perluniintro. + +COMMON OBJECT-ORIENTED INTERFACE + new + $json = JSON->new + + Returns a new "JSON" object inherited from either JSON::XS or JSON::PP + that can be used to de/encode JSON strings. + + All boolean flags described below are by default *disabled*. + + The mutators for flags all return the JSON object again and thus calls + can be chained: + + my $json = JSON->new->utf8->space_after->encode({a => [1,2]}) + => {"a": [1, 2]} + + ascii + $json = $json->ascii([$enable]) + + $enabled = $json->get_ascii + + If $enable is true (or missing), then the encode method will not + generate characters outside the code range 0..127. Any Unicode + characters outside that range will be escaped using either a single + \uXXXX or a double \uHHHH\uLLLLL escape sequence, as per RFC4627. + + If $enable is false, then the encode method will not escape Unicode + characters unless required by the JSON syntax or other flags. This + results in a faster and more compact format. + + This feature depends on the used Perl version and environment. + + See to "UNICODE HANDLING ON PERLS" in JSON::PP if the backend is PP. + + JSON->new->ascii(1)->encode([chr 0x10401]) + => ["\ud801\udc01"] + + latin1 + $json = $json->latin1([$enable]) + + $enabled = $json->get_latin1 + + If $enable is true (or missing), then the encode method will encode the + resulting JSON text as latin1 (or iso-8859-1), escaping any characters + outside the code range 0..255. + + If $enable is false, then the encode method will not escape Unicode + characters unless required by the JSON syntax or other flags. + + JSON->new->latin1->encode (["\x{89}\x{abc}"] + => ["\x{89}\\u0abc"] # (perl syntax, U+abc escaped, U+89 not) + + utf8 + $json = $json->utf8([$enable]) + + $enabled = $json->get_utf8 + + If $enable is true (or missing), then the encode method will encode the + JSON result into UTF-8, as required by many protocols, while the decode + method expects to be handled an UTF-8-encoded string. Please note that + UTF-8-encoded strings do not contain any characters outside the range + 0..255, they are thus useful for bytewise/binary I/O. + + In future versions, enabling this option might enable autodetection of + the UTF-16 and UTF-32 encoding families, as described in RFC4627. + + If $enable is false, then the encode method will return the JSON string + as a (non-encoded) Unicode string, while decode expects thus a Unicode + string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs to be + done yourself, e.g. using the Encode module. + + Example, output UTF-16BE-encoded JSON: + + use Encode; + $jsontext = encode "UTF-16BE", JSON::XS->new->encode ($object); + + Example, decode UTF-32LE-encoded JSON: + + use Encode; + $object = JSON::XS->new->decode (decode "UTF-32LE", $jsontext); + + See to "UNICODE HANDLING ON PERLS" in JSON::PP if the backend is PP. + + pretty + $json = $json->pretty([$enable]) + + This enables (or disables) all of the "indent", "space_before" and + "space_after" (and in the future possibly more) flags in one call to + generate the most readable (or most compact) form possible. + + Equivalent to: + + $json->indent->space_before->space_after + + The indent space length is three and JSON::XS cannot change the indent + space length. + + indent + $json = $json->indent([$enable]) + + $enabled = $json->get_indent + + If $enable is true (or missing), then the "encode" method will use a + multiline format as output, putting every array member or object/hash + key-value pair into its own line, identing them properly. + + If $enable is false, no newlines or indenting will be produced, and the + resulting JSON text is guarenteed not to contain any "newlines". + + This setting has no effect when decoding JSON texts. + + The indent space length is three. With JSON::PP, you can also access + "indent_length" to change indent space length. + + space_before + $json = $json->space_before([$enable]) + + $enabled = $json->get_space_before + + If $enable is true (or missing), then the "encode" method will add an + extra optional space before the ":" separating keys from values in JSON + objects. + + If $enable is false, then the "encode" method will not add any extra + space at those places. + + This setting has no effect when decoding JSON texts. + + Example, space_before enabled, space_after and indent disabled: + + {"key" :"value"} + + space_after + $json = $json->space_after([$enable]) + + $enabled = $json->get_space_after + + If $enable is true (or missing), then the "encode" method will add an + extra optional space after the ":" separating keys from values in JSON + objects and extra whitespace after the "," separating key-value pairs + and array members. + + If $enable is false, then the "encode" method will not add any extra + space at those places. + + This setting has no effect when decoding JSON texts. + + Example, space_before and indent disabled, space_after enabled: + + {"key": "value"} + + relaxed + $json = $json->relaxed([$enable]) + + $enabled = $json->get_relaxed + + If $enable is true (or missing), then "decode" will accept some + extensions to normal JSON syntax (see below). "encode" will not be + affected in anyway. *Be aware that this option makes you accept invalid + JSON texts as if they were valid!*. I suggest only to use this option to + parse application-specific files written by humans (configuration files, + resource files etc.) + + If $enable is false (the default), then "decode" will only accept valid + JSON texts. + + Currently accepted extensions are: + + * list items can have an end-comma + + JSON *separates* array elements and key-value pairs with commas. + This can be annoying if you write JSON texts manually and want to be + able to quickly append elements, so this extension accepts comma at + the end of such items not just between them: + + [ + 1, + 2, <- this comma not normally allowed + ] + { + "k1": "v1", + "k2": "v2", <- this comma not normally allowed + } + + * shell-style '#'-comments + + Whenever JSON allows whitespace, shell-style comments are + additionally allowed. They are terminated by the first + carriage-return or line-feed character, after which more white-space + and comments are allowed. + + [ + 1, # this comment not allowed in JSON + # neither this one... + ] + + canonical + $json = $json->canonical([$enable]) + + $enabled = $json->get_canonical + + If $enable is true (or missing), then the "encode" method will output + JSON objects by sorting their keys. This is adding a comparatively high + overhead. + + If $enable is false, then the "encode" method will output key-value + pairs in the order Perl stores them (which will likely change between + runs of the same script). + + This option is useful if you want the same data structure to be encoded + as the same JSON text (given the same overall settings). If it is + disabled, the same hash might be encoded differently even if contains + the same data, as key-value pairs have no inherent ordering in Perl. + + This setting has no effect when decoding JSON texts. + + allow_nonref + $json = $json->allow_nonref([$enable]) + + $enabled = $json->get_allow_nonref + + If $enable is true (or missing), then the "encode" method can convert a + non-reference into its corresponding string, number or null JSON value, + which is an extension to RFC4627. Likewise, "decode" will accept those + JSON values instead of croaking. + + If $enable is false, then the "encode" method will croak if it isn't + passed an arrayref or hashref, as JSON texts must either be an object or + array. Likewise, "decode" will croak if given something that is not a + JSON object or array. + + JSON->new->allow_nonref->encode ("Hello, World!") + => "Hello, World!" + + allow_unknown + $json = $json->allow_unknown ([$enable]) + + $enabled = $json->get_allow_unknown + + If $enable is true (or missing), then "encode" will *not* throw an + exception when it encounters values it cannot represent in JSON (for + example, filehandles) but instead will encode a JSON "null" value. Note + that blessed objects are not included here and are handled separately by + c. + + If $enable is false (the default), then "encode" will throw an exception + when it encounters anything it cannot encode as JSON. + + This option does not affect "decode" in any way, and it is recommended + to leave it off unless you know your communications partner. + + allow_blessed + $json = $json->allow_blessed([$enable]) + + $enabled = $json->get_allow_blessed + + If $enable is true (or missing), then the "encode" method will not barf + when it encounters a blessed reference. Instead, the value of the + convert_blessed option will decide whether "null" ("convert_blessed" + disabled or no "TO_JSON" method found) or a representation of the object + ("convert_blessed" enabled and "TO_JSON" method found) is being encoded. + Has no effect on "decode". + + If $enable is false (the default), then "encode" will throw an exception + when it encounters a blessed object. + + convert_blessed + $json = $json->convert_blessed([$enable]) + + $enabled = $json->get_convert_blessed + + If $enable is true (or missing), then "encode", upon encountering a + blessed object, will check for the availability of the "TO_JSON" method + on the object's class. If found, it will be called in scalar context and + the resulting scalar will be encoded instead of the object. If no + "TO_JSON" method is found, the value of "allow_blessed" will decide what + to do. + + The "TO_JSON" method may safely call die if it wants. If "TO_JSON" + returns other blessed objects, those will be handled in the same way. + "TO_JSON" must take care of not causing an endless recursion cycle (== + crash) in this case. The name of "TO_JSON" was chosen because other + methods called by the Perl core (== not by the user of the object) are + usually in upper case letters and to avoid collisions with the "to_json" + function or method. + + This setting does not yet influence "decode" in any way. + + If $enable is false, then the "allow_blessed" setting will decide what + to do when a blessed object is found. + + convert_blessed_universally mode + If use "JSON" with "-convert_blessed_universally", the + "UNIVERSAL::TO_JSON" subroutine is defined as the below code: + + *UNIVERSAL::TO_JSON = sub { + my $b_obj = B::svref_2object( $_[0] ); + return $b_obj->isa('B::HV') ? { %{ $_[0] } } + : $b_obj->isa('B::AV') ? [ @{ $_[0] } ] + : undef + ; + } + + This will cause that "encode" method converts simple blessed objects + into JSON objects as non-blessed object. + + JSON -convert_blessed_universally; + $json->allow_blessed->convert_blessed->encode( $blessed_object ) + + This feature is experimental and may be removed in the future. + + filter_json_object + $json = $json->filter_json_object([$coderef]) + + When $coderef is specified, it will be called from "decode" each time it + decodes a JSON object. The only argument passed to the coderef is a + reference to the newly-created hash. If the code references returns a + single scalar (which need not be a reference), this value (i.e. a copy + of that scalar to avoid aliasing) is inserted into the deserialised data + structure. If it returns an empty list (NOTE: *not* "undef", which is a + valid scalar), the original deserialised hash will be inserted. This + setting can slow down decoding considerably. + + When $coderef is omitted or undefined, any existing callback will be + removed and "decode" will not change the deserialised hash in any way. + + Example, convert all JSON objects into the integer 5: + + my $js = JSON->new->filter_json_object (sub { 5 }); + # returns [5] + $js->decode ('[{}]'); # the given subroutine takes a hash reference. + # throw an exception because allow_nonref is not enabled + # so a lone 5 is not allowed. + $js->decode ('{"a":1, "b":2}'); + + filter_json_single_key_object + $json = $json->filter_json_single_key_object($key [=> $coderef]) + + Works remotely similar to "filter_json_object", but is only called for + JSON objects having a single key named $key. + + This $coderef is called before the one specified via + "filter_json_object", if any. It gets passed the single value in the + JSON object. If it returns a single value, it will be inserted into the + data structure. If it returns nothing (not even "undef" but the empty + list), the callback from "filter_json_object" will be called next, as if + no single-key callback were specified. + + If $coderef is omitted or undefined, the corresponding callback will be + disabled. There can only ever be one callback for a given key. + + As this callback gets called less often then the "filter_json_object" + one, decoding speed will not usually suffer as much. Therefore, + single-key objects make excellent targets to serialise Perl objects + into, especially as single-key JSON objects are as close to the + type-tagged value concept as JSON gets (it's basically an ID/VALUE + tuple). Of course, JSON does not support this in any way, so you need to + make sure your data never looks like a serialised Perl hash. + + Typical names for the single object key are "__class_whatever__", or + "$__dollars_are_rarely_used__$" or "}ugly_brace_placement", or even + things like "__class_md5sum(classname)__", to reduce the risk of + clashing with real hashes. + + Example, decode JSON objects of the form "{ "__widget__" => }" into + the corresponding $WIDGET{} object: + + # return whatever is in $WIDGET{5}: + JSON + ->new + ->filter_json_single_key_object (__widget__ => sub { + $WIDGET{ $_[0] } + }) + ->decode ('{"__widget__": 5') + + # this can be used with a TO_JSON method in some "widget" class + # for serialisation to json: + sub WidgetBase::TO_JSON { + my ($self) = @_; + + unless ($self->{id}) { + $self->{id} = ..get..some..id..; + $WIDGET{$self->{id}} = $self; + } + + { __widget__ => $self->{id} } + } + + shrink + $json = $json->shrink([$enable]) + + $enabled = $json->get_shrink + + With JSON::XS, this flag resizes strings generated by either "encode" or + "decode" to their minimum size possible. This can save memory when your + JSON texts are either very very long or you have many short strings. It + will also try to downgrade any strings to octet-form if possible: perl + stores strings internally either in an encoding called UTF-X or in + octet-form. The latter cannot store everything but uses less space in + general (and some buggy Perl or C code might even rely on that internal + representation being used). + + With JSON::PP, it is noop about resizing strings but tries + "utf8::downgrade" to the returned string by "encode". See to utf8. + + See to "OBJECT-ORIENTED INTERFACE" in JSON::XS and "METHODS" in + JSON::PP. + + max_depth + $json = $json->max_depth([$maximum_nesting_depth]) + + $max_depth = $json->get_max_depth + + Sets the maximum nesting level (default 512) accepted while encoding or + decoding. If a higher nesting level is detected in JSON text or a Perl + data structure, then the encoder and decoder will stop and croak at that + point. + + Nesting level is defined by number of hash- or arrayrefs that the + encoder needs to traverse to reach a given point or the number of "{" or + "[" characters without their matching closing parenthesis crossed to + reach a given character in a string. + + If no argument is given, the highest possible setting will be used, + which is rarely useful. + + Note that nesting is implemented by recursion in C. The default value + has been chosen to be as large as typical operating systems allow + without crashing. (JSON::XS) + + With JSON::PP as the backend, when a large value (100 or more) was set + and it de/encodes a deep nested object/text, it may raise a warning + 'Deep recursion on subroutin' at the perl runtime phase. + + See "SECURITY CONSIDERATIONS" in JSON::XS for more info on why this is + useful. + + max_size + $json = $json->max_size([$maximum_string_size]) + + $max_size = $json->get_max_size + + Set the maximum length a JSON text may have (in bytes) where decoding is + being attempted. The default is 0, meaning no limit. When "decode" is + called on a string that is longer then this many bytes, it will not + attempt to decode the string but throw an exception. This setting has no + effect on "encode" (yet). + + If no argument is given, the limit check will be deactivated (same as + when 0 is specified). + + See "SECURITY CONSIDERATIONS" in JSON::XS, below, for more info on why + this is useful. + + encode + $json_text = $json->encode($perl_scalar) + + Converts the given Perl data structure (a simple scalar or a reference + to a hash or array) to its JSON representation. Simple scalars will be + converted into JSON string or number sequences, while references to + arrays become JSON arrays and references to hashes become JSON objects. + Undefined Perl values (e.g. "undef") become JSON "null" values. + References to the integers 0 and 1 are converted into "true" and + "false". + + decode + $perl_scalar = $json->decode($json_text) + + The opposite of "encode": expects a JSON text and tries to parse it, + returning the resulting simple scalar or reference. Croaks on error. + + JSON numbers and strings become simple Perl scalars. JSON arrays become + Perl arrayrefs and JSON objects become Perl hashrefs. "true" becomes 1 + ("JSON::true"), "false" becomes 0 ("JSON::false") and "null" becomes + "undef". + + decode_prefix + ($perl_scalar, $characters) = $json->decode_prefix($json_text) + + This works like the "decode" method, but instead of raising an exception + when there is trailing garbage after the first JSON object, it will + silently stop parsing there and return the number of characters consumed + so far. + + JSON->new->decode_prefix ("[1] the tail") + => ([], 3) + + See to "OBJECT-ORIENTED INTERFACE" in JSON::XS + + property + $boolean = $json->property($property_name) + + Returns a boolean value about above some properties. + + The available properties are "ascii", "latin1", "utf8", + "indent","space_before", "space_after", "relaxed", "canonical", + "allow_nonref", "allow_unknown", "allow_blessed", "convert_blessed", + "shrink", "max_depth" and "max_size". + + $boolean = $json->property('utf8'); + => 0 + $json->utf8; + $boolean = $json->property('utf8'); + => 1 + + Sets the property with a given boolean value. + + $json = $json->property($property_name => $boolean); + + With no argumnt, it returns all the above properties as a hash + reference. + + $flag_hashref = $json->property(); + +INCREMENTAL PARSING + Most of this section are copied and modified from "INCREMENTAL PARSING" + in JSON::XS. + + In some cases, there is the need for incremental parsing of JSON texts. + This module does allow you to parse a JSON stream incrementally. It does + so by accumulating text until it has a full JSON object, which it then + can decode. This process is similar to using "decode_prefix" to see if a + full JSON object is available, but is much more efficient (and can be + implemented with a minimum of method calls). + + The backend module will only attempt to parse the JSON text once it is + sure it has enough text to get a decisive result, using a very simple + but truly incremental parser. This means that it sometimes won't stop as + early as the full parser, for example, it doesn't detect parenthese + mismatches. The only thing it guarantees is that it starts decoding as + soon as a syntactically valid JSON text has been seen. This means you + need to set resource limits (e.g. "max_size") to ensure the parser will + stop parsing in the presence if syntax errors. + + The following methods implement this incremental parser. + + incr_parse + $json->incr_parse( [$string] ) # void context + + $obj_or_undef = $json->incr_parse( [$string] ) # scalar context + + @obj_or_empty = $json->incr_parse( [$string] ) # list context + + This is the central parsing function. It can both append new text and + extract objects from the stream accumulated so far (both of these + functions are optional). + + If $string is given, then this string is appended to the already + existing JSON fragment stored in the $json object. + + After that, if the function is called in void context, it will simply + return without doing anything further. This can be used to add more text + in as many chunks as you want. + + If the method is called in scalar context, then it will try to extract + exactly *one* JSON object. If that is successful, it will return this + object, otherwise it will return "undef". If there is a parse error, + this method will croak just as "decode" would do (one can then use + "incr_skip" to skip the errornous part). This is the most common way of + using the method. + + And finally, in list context, it will try to extract as many objects + from the stream as it can find and return them, or the empty list + otherwise. For this to work, there must be no separators between the + JSON objects or arrays, instead they must be concatenated back-to-back. + If an error occurs, an exception will be raised as in the scalar context + case. Note that in this case, any previously-parsed JSON texts will be + lost. + + Example: Parse some JSON arrays/objects in a given string and return + them. + + my @objs = JSON->new->incr_parse ("[5][7][1,2]"); + + incr_text + $lvalue_string = $json->incr_text + + This method returns the currently stored JSON fragment as an lvalue, + that is, you can manipulate it. This *only* works when a preceding call + to "incr_parse" in *scalar context* successfully returned an object. + Under all other circumstances you must not call this function (I mean + it. although in simple tests it might actually work, it *will* fail + under real world conditions). As a special exception, you can also call + this method before having parsed anything. + + This function is useful in two cases: a) finding the trailing text after + a JSON object or b) parsing multiple JSON objects separated by non-JSON + text (such as commas). + + $json->incr_text =~ s/\s*,\s*//; + + In Perl 5.005, "lvalue" attribute is not available. You must write codes + like the below: + + $string = $json->incr_text; + $string =~ s/\s*,\s*//; + $json->incr_text( $string ); + + incr_skip + $json->incr_skip + + This will reset the state of the incremental parser and will remove the + parsed text from the input buffer. This is useful after "incr_parse" + died, in which case the input buffer and incremental parser state is + left unchanged, to skip the text parsed so far and to reset the parse + state. + + incr_reset + $json->incr_reset + + This completely resets the incremental parser, that is, after this call, + it will be as if the parser had never parsed anything. + + This is useful if you want ot repeatedly parse JSON objects and want to + ignore any trailing data, which means you have to reset the parser after + each successful decode. + + See to "INCREMENTAL PARSING" in JSON::XS for examples. + +JSON::PP SUPPORT METHODS + The below methods are JSON::PP own methods, so when "JSON" works with + JSON::PP (i.e. the created object is a JSON::PP object), available. See + to "JSON::PP OWN METHODS" in JSON::PP in detail. + + If you use "JSON" with additonal "-support_by_pp", some methods are + available even with JSON::XS. See to "USE PP FEATURES EVEN THOUGH XS + BACKEND". + + BEING { $ENV{PERL_JSON_BACKEND} = 'JSON::XS' } + + use JSON -support_by_pp; + + my $json = new JSON; + $json->allow_nonref->escape_slash->encode("/"); + + # functional interfaces too. + print to_json(["/"], {escape_slash => 1}); + print from_json('["foo"]', {utf8 => 1}); + + If you do not want to all functions but "-support_by_pp", use + "-no_export". + + use JSON -support_by_pp, -no_export; + # functional interfaces are not exported. + + allow_singlequote + $json = $json->allow_singlequote([$enable]) + + If $enable is true (or missing), then "decode" will accept any JSON + strings quoted by single quotations that are invalid JSON format. + + $json->allow_singlequote->decode({"foo":'bar'}); + $json->allow_singlequote->decode({'foo':"bar"}); + $json->allow_singlequote->decode({'foo':'bar'}); + + As same as the "relaxed" option, this option may be used to parse + application-specific files written by humans. + + allow_barekey + $json = $json->allow_barekey([$enable]) + + If $enable is true (or missing), then "decode" will accept bare keys of + JSON object that are invalid JSON format. + + As same as the "relaxed" option, this option may be used to parse + application-specific files written by humans. + + $json->allow_barekey->decode('{foo:"bar"}'); + + allow_bignum + $json = $json->allow_bignum([$enable]) + + If $enable is true (or missing), then "decode" will convert the big + integer Perl cannot handle as integer into a Math::BigInt object and + convert a floating number (any) into a Math::BigFloat. + + On the contary, "encode" converts "Math::BigInt" objects and + "Math::BigFloat" objects into JSON numbers with "allow_blessed" enable. + + $json->allow_nonref->allow_blessed->allow_bignum; + $bigfloat = $json->decode('2.000000000000000000000000001'); + print $json->encode($bigfloat); + # => 2.000000000000000000000000001 + + See to MAPPING aboout the conversion of JSON number. + + loose + $json = $json->loose([$enable]) + + The unescaped [\x00-\x1f\x22\x2f\x5c] strings are invalid in JSON + strings and the module doesn't allow to "decode" to these (except for + \x2f). If $enable is true (or missing), then "decode" will accept these + unescaped strings. + + $json->loose->decode(qq|["abc + def"]|); + + See to "JSON::PP OWN METHODS" in JSON::PP. + + escape_slash + $json = $json->escape_slash([$enable]) + + According to JSON Grammar, *slash* (U+002F) is escaped. But by default + JSON backend modules encode strings without escaping slash. + + If $enable is true (or missing), then "encode" will escape slashes. + + indent_length + $json = $json->indent_length($length) + + With JSON::XS, The indent space length is 3 and cannot be changed. With + JSON::PP, it sets the indent space length with the given $length. The + default is 3. The acceptable range is 0 to 15. + + sort_by + $json = $json->sort_by($function_name) + $json = $json->sort_by($subroutine_ref) + + If $function_name or $subroutine_ref are set, its sort routine are used. + + $js = $pc->sort_by(sub { $JSON::PP::a cmp $JSON::PP::b })->encode($obj); + # is($js, q|{"a":1,"b":2,"c":3,"d":4,"e":5,"f":6,"g":7,"h":8,"i":9}|); + + $js = $pc->sort_by('own_sort')->encode($obj); + # is($js, q|{"a":1,"b":2,"c":3,"d":4,"e":5,"f":6,"g":7,"h":8,"i":9}|); + + sub JSON::PP::own_sort { $JSON::PP::a cmp $JSON::PP::b } + + As the sorting routine runs in the JSON::PP scope, the given subroutine + name and the special variables $a, $b will begin with 'JSON::PP::'. + + If $integer is set, then the effect is same as "canonical" on. + + See to "JSON::PP OWN METHODS" in JSON::PP. + +MAPPING + This section is copied from JSON::XS and modified to "JSON". JSON::XS + and JSON::PP mapping mechanisms are almost equivalent. + + See to "MAPPING" in JSON::XS. + + JSON -> PERL + object + A JSON object becomes a reference to a hash in Perl. No ordering of + object keys is preserved (JSON does not preserver object key + ordering itself). + + array + A JSON array becomes a reference to an array in Perl. + + string + A JSON string becomes a string scalar in Perl - Unicode codepoints + in JSON are represented by the same codepoints in the Perl string, + so no manual decoding is necessary. + + number + A JSON number becomes either an integer, numeric (floating point) or + string scalar in perl, depending on its range and any fractional + parts. On the Perl level, there is no difference between those as + Perl handles all the conversion details, but an integer may take + slightly less memory and might represent more values exactly than + floating point numbers. + + If the number consists of digits only, "JSON" will try to represent + it as an integer value. If that fails, it will try to represent it + as a numeric (floating point) value if that is possible without loss + of precision. Otherwise it will preserve the number as a string + value (in which case you lose roundtripping ability, as the JSON + number will be re-encoded toa JSON string). + + Numbers containing a fractional or exponential part will always be + represented as numeric (floating point) values, possibly at a loss + of precision (in which case you might lose perfect roundtripping + ability, but the JSON number will still be re-encoded as a JSON + number). + + Note that precision is not accuracy - binary floating point values + cannot represent most decimal fractions exactly, and when converting + from and to floating point, "JSON" only guarantees precision up to + but not including the leats significant bit. + + If the backend is JSON::PP and "allow_bignum" is enable, the big + integers and the numeric can be optionally converted into + Math::BigInt and Math::BigFloat objects. + + true, false + These JSON atoms become "JSON::true" and "JSON::false", + respectively. They are overloaded to act almost exactly like the + numbers 1 and 0. You can check wether a scalar is a JSON boolean by + using the "JSON::is_bool" function. + + If "JSON::true" and "JSON::false" are used as strings or compared as + strings, they represent as "true" and "false" respectively. + + print JSON::true . "\n"; + => true + print JSON::true + 1; + => 1 + + ok(JSON::true eq 'true'); + ok(JSON::true eq '1'); + ok(JSON::true == 1); + + "JSON" will install these missing overloading features to the + backend modules. + + null + A JSON null atom becomes "undef" in Perl. + + "JSON::null" returns "unddef". + + PERL -> JSON + The mapping from Perl to JSON is slightly more difficult, as Perl is a + truly typeless language, so we can only guess which JSON type is meant + by a Perl value. + + hash references + Perl hash references become JSON objects. As there is no inherent + ordering in hash keys (or JSON objects), they will usually be + encoded in a pseudo-random order that can change between runs of the + same program but stays generally the same within a single run of a + program. "JSON" optionally sort the hash keys (determined by the + *canonical* flag), so the same datastructure will serialise to the + same JSON text (given same settings and version of JSON::XS), but + this incurs a runtime overhead and is only rarely useful, e.g. when + you want to compare some JSON text against another for equality. + + In future, the ordered object feature will be added to JSON::PP + using "tie" mechanism. + + array references + Perl array references become JSON arrays. + + other references + Other unblessed references are generally not allowed and will cause + an exception to be thrown, except for references to the integers 0 + and 1, which get turned into "false" and "true" atoms in JSON. You + can also use "JSON::false" and "JSON::true" to improve readability. + + to_json [\0,JSON::true] # yields [false,true] + + JSON::true, JSON::false, JSON::null + These special values become JSON true and JSON false values, + respectively. You can also use "\1" and "\0" directly if you want. + + JSON::null returns "undef". + + blessed objects + Blessed objects are not directly representable in JSON. See the + "allow_blessed" and "convert_blessed" methods on various options on + how to deal with this: basically, you can choose between throwing an + exception, encoding the reference as if it weren't blessed, or + provide your own serialiser method. + + With "convert_blessed_universally" mode, "encode" converts blessed + hash references or blessed array references (contains other blessed + references) into JSON members and arrays. + + use JSON -convert_blessed_universally; + JSON->new->allow_blessed->convert_blessed->encode( $blessed_object ); + + See to convert_blessed. + + simple scalars + Simple Perl scalars (any scalar that is not a reference) are the + most difficult objects to encode: JSON::XS and JSON::PP will encode + undefined scalars as JSON "null" values, scalars that have last been + used in a string context before encoding as JSON strings, and + anything else as number value: + + # dump as number + encode_json [2] # yields [2] + encode_json [-3.0e17] # yields [-3e+17] + my $value = 5; encode_json [$value] # yields [5] + + # used as string, so dump as string + print $value; + encode_json [$value] # yields ["5"] + + # undef becomes null + encode_json [undef] # yields [null] + + You can force the type to be a string by stringifying it: + + my $x = 3.1; # some variable containing a number + "$x"; # stringified + $x .= ""; # another, more awkward way to stringify + print $x; # perl does it for you, too, quite often + + You can force the type to be a number by numifying it: + + my $x = "3"; # some variable containing a string + $x += 0; # numify it, ensuring it will be dumped as a number + $x *= 1; # same thing, the choise is yours. + + You can not currently force the type in other, less obscure, ways. + + Note that numerical precision has the same meaning as under Perl (so + binary to decimal conversion follows the same rules as in Perl, + which can differ to other languages). Also, your perl interpreter + might expose extensions to the floating point numbers of your + platform, such as infinities or NaN's - these cannot be represented + in JSON, and it is an error to pass those in. + + Big Number + If the backend is JSON::PP and "allow_bignum" is enable, "encode" + converts "Math::BigInt" objects and "Math::BigFloat" objects into + JSON numbers. + +JSON and ECMAscript + See to "JSON and ECMAscript" in JSON::XS. + +JSON and YAML + JSON is not a subset of YAML. See to "JSON and YAML" in JSON::XS. + +BACKEND MODULE DECISION + When you use "JSON", "JSON" tries to "use" JSON::XS. If this call + failed, it will "uses" JSON::PP. The required JSON::XS version is *2.2* + or later. + + The "JSON" constructor method returns an object inherited from the + backend module, and JSON::XS object is a blessed scaler reference while + JSON::PP is a blessed hash reference. + + So, your program should not depend on the backend module, especially + returned objects should not be modified. + + my $json = JSON->new; # XS or PP? + $json->{stash} = 'this is xs object'; # this code may raise an error! + + To check the backend module, there are some methods - "backend", "is_pp" + and "is_xs". + + JSON->backend; # 'JSON::XS' or 'JSON::PP' + + JSON->backend->is_pp: # 0 or 1 + + JSON->backend->is_xs: # 1 or 0 + + $json->is_xs; # 1 or 0 + + $json->is_pp; # 0 or 1 + + If you set an enviornment variable "PERL_JSON_BACKEND", The calling + action will be changed. + + PERL_JSON_BACKEND = 0 or PERL_JSON_BACKEND = 'JSON::PP' + Always use JSON::PP + + PERL_JSON_BACKEND == 1 or PERL_JSON_BACKEND = 'JSON::XS,JSON::PP' + (The default) Use compiled JSON::XS if it is properly compiled & + installed, otherwise use JSON::PP. + + PERL_JSON_BACKEND == 2 or PERL_JSON_BACKEND = 'JSON::XS' + Always use compiled JSON::XS, die if it isn't properly compiled & + installed. + + PERL_JSON_BACKEND = 'JSON::backportPP' + Always use JSON::backportPP. JSON::backportPP is JSON::PP back port + module. "JSON" includs JSON::backportPP instead of JSON::PP. + + These ideas come from DBI::PurePerl mechanism. + + example: + + BEGIN { $ENV{PERL_JSON_BACKEND} = 'JSON::PP' } + use JSON; # always uses JSON::PP + + In future, it may be able to specify another module. + +USE PP FEATURES EVEN THOUGH XS BACKEND + Many methods are available with either JSON::XS or JSON::PP and when the + backend module is JSON::XS, if any JSON::PP specific (i.e. JSON::XS + unspported) method is called, it will "warn" and be noop. + + But If you "use" "JSON" passing the optional string "-support_by_pp", it + makes a part of those unupported methods available. This feature is + achieved by using JSON::PP in "de/encode". + + BEGIN { $ENV{PERL_JSON_BACKEND} = 2 } # with JSON::XS + use JSON -support_by_pp; + my $json = new JSON; + $json->allow_nonref->escape_slash->encode("/"); + + At this time, the returned object is a "JSON::Backend::XS::Supportable" + object (re-blessed XS object), and by checking JSON::XS unsupported + flags in de/encoding, can support some unsupported methods - "loose", + "allow_bignum", "allow_barekey", "allow_singlequote", "escape_slash" and + "indent_length". + + When any unsupported methods are not enable, "XS de/encode" will be used + as is. The switch is achieved by changing the symbolic tables. + + "-support_by_pp" is effective only when the backend module is JSON::XS + and it makes the de/encoding speed down a bit. + + See to "JSON::PP SUPPORT METHODS". + +INCOMPATIBLE CHANGES TO OLD VERSION + There are big incompatibility between new version (2.00) and old (1.xx). + If you use old "JSON" 1.xx in your code, please check it. + + See to "Transition ways from 1.xx to 2.xx." + + jsonToObj and objToJson are obsoleted. + Non Perl-style name "jsonToObj" and "objToJson" are obsoleted (but + not yet deleted from the source). If you use these functions in your + code, please replace them with "from_json" and "to_json". + + Global variables are no longer available. + "JSON" class variables - $JSON::AUTOCONVERT, $JSON::BareKey, etc... + - are not available any longer. Instead, various features can be + used through object methods. + + Package JSON::Converter and JSON::Parser are deleted. + Now "JSON" bundles with JSON::PP which can handle JSON more properly + than them. + + Package JSON::NotString is deleted. + There was "JSON::NotString" class which represents JSON value + "true", "false", "null" and numbers. It was deleted and replaced by + "JSON::Boolean". + + "JSON::Boolean" represents "true" and "false". + + "JSON::Boolean" does not represent "null". + + "JSON::null" returns "undef". + + "JSON" makes JSON::XS::Boolean and JSON::PP::Boolean is-a relation + to JSON::Boolean. + + function JSON::Number is obsoleted. + "JSON::Number" is now needless because JSON::XS and JSON::PP have + round-trip integrity. + + JSONRPC modules are deleted. + Perl implementation of JSON-RPC protocol - "JSONRPC ", + "JSONRPC::Transport::HTTP" and "Apache::JSONRPC " are deleted in + this distribution. Instead of them, there is JSON::RPC which + supports JSON-RPC protocol version 1.1. + + Transition ways from 1.xx to 2.xx. + You should set "suport_by_pp" mode firstly, because it is always + successful for the below codes even with JSON::XS. + + use JSON -support_by_pp; + + Exported jsonToObj (simple) + from_json($json_text); + + Exported objToJson (simple) + to_json($perl_scalar); + + Exported jsonToObj (advanced) + $flags = {allow_barekey => 1, allow_singlequote => 1}; + from_json($json_text, $flags); + + equivalent to: + + $JSON::BareKey = 1; + $JSON::QuotApos = 1; + jsonToObj($json_text); + + Exported objToJson (advanced) + $flags = {allow_blessed => 1, allow_barekey => 1}; + to_json($perl_scalar, $flags); + + equivalent to: + + $JSON::BareKey = 1; + objToJson($perl_scalar); + + jsonToObj as object method + $json->decode($json_text); + + objToJson as object method + $json->encode($perl_scalar); + + new method with parameters + The "new" method in 2.x takes any parameters no longer. You can set + parameters instead; + + $json = JSON->new->pretty; + + $JSON::Pretty, $JSON::Indent, $JSON::Delimiter + If "indent" is enable, that means $JSON::Pretty flag set. And + $JSON::Delimiter was substituted by "space_before" and + "space_after". In conclusion: + + $json->indent->space_before->space_after; + + Equivalent to: + + $json->pretty; + + To change indent length, use "indent_length". + + (Only with JSON::PP, if "-support_by_pp" is not used.) + + $json->pretty->indent_length(2)->encode($perl_scalar); + + $JSON::BareKey + (Only with JSON::PP, if "-support_by_pp" is not used.) + + $json->allow_barekey->decode($json_text) + + $JSON::ConvBlessed + use "-convert_blessed_universally". See to convert_blessed. + + $JSON::QuotApos + (Only with JSON::PP, if "-support_by_pp" is not used.) + + $json->allow_singlequote->decode($json_text) + + $JSON::SingleQuote + Disable. "JSON" does not make such a invalid JSON string any longer. + + $JSON::KeySort + $json->canonical->encode($perl_scalar) + + This is the ascii sort. + + If you want to use with your own sort routine, check the "sort_by" + method. + + (Only with JSON::PP, even if "-support_by_pp" is used currently.) + + $json->sort_by($sort_routine_ref)->encode($perl_scalar) + + $json->sort_by(sub { $JSON::PP::a <=> $JSON::PP::b })->encode($perl_scalar) + + Can't access $a and $b but $JSON::PP::a and $JSON::PP::b. + + $JSON::SkipInvalid + $json->allow_unknown + + $JSON::AUTOCONVERT + Needless. "JSON" backend modules have the round-trip integrity. + + $JSON::UTF8 + Needless because "JSON" (JSON::XS/JSON::PP) sets the UTF8 flag on + properly. + + # With UTF8-flagged strings + + $json->allow_nonref; + $str = chr(1000); # UTF8-flagged + + $json_text = $json->utf8(0)->encode($str); + utf8::is_utf8($json_text); + # true + $json_text = $json->utf8(1)->encode($str); + utf8::is_utf8($json_text); + # false + + $str = '"' . chr(1000) . '"'; # UTF8-flagged + + $perl_scalar = $json->utf8(0)->decode($str); + utf8::is_utf8($perl_scalar); + # true + $perl_scalar = $json->utf8(1)->decode($str); + # died because of 'Wide character in subroutine' + + See to "A FEW NOTES ON UNICODE AND PERL" in JSON::XS. + + $JSON::UnMapping + Disable. See to MAPPING. + + $JSON::SelfConvert + This option was deleted. Instead of it, if a givien blessed object + has the "TO_JSON" method, "TO_JSON" will be executed with + "convert_blessed". + + $json->convert_blessed->encode($bleesed_hashref_or_arrayref) + # if need, call allow_blessed + + Note that it was "toJson" in old version, but now not "toJson" but + "TO_JSON". + +TODO + example programs + +THREADS + No test with JSON::PP. If with JSON::XS, See to "THREADS" in JSON::XS. + +BUGS + Please report bugs relevant to "JSON" to . + +SEE ALSO + Most of the document is copied and modified from JSON::XS doc. + + JSON::XS, JSON::PP + + "RFC4627"() + +AUTHOR + Makamaka Hannyaharamitu, + + JSON::XS was written by Marc Lehmann + + The relese of this new version owes to the courtesy of Marc Lehmann. + +COPYRIGHT AND LICENSE + Copyright 2005-2011 by Makamaka Hannyaharamitu + + This library is free software; you can redistribute it and/or modify it + under the same terms as Perl itself. + diff --git a/json/perl-JSON-2.50-1.rf.src.rpm b/json/perl-JSON-2.50-1.rf.src.rpm new file mode 100644 index 0000000..64241ba Binary files /dev/null and b/json/perl-JSON-2.50-1.rf.src.rpm differ