--- JSON-XS/README 2007/05/09 16:35:21 1.11 +++ JSON-XS/README 2007/08/28 02:06:06 1.18 @@ -10,10 +10,6 @@ $utf8_encoded_json_text = to_json $perl_hash_or_arrayref; $perl_hash_or_arrayref = from_json $utf8_encoded_json_text; - # objToJson and jsonToObj aliases to to_json and from_json - # are exported for compatibility to the JSON module, - # but should not be used in new code. - # OO-interface $coder = JSON::XS->new->ascii->pretty->allow_nonref; @@ -94,6 +90,15 @@ except being faster. + $is_boolean = JSON::XS::is_bool $scalar + Returns true if the passed scalar represents either JSON::XS::true + or JSON::XS::false, two constants that act like 1 and 0, + respectively and are used to represent JSON "true" and "false" + values in Perl. + + See MAPPING, below, for more information on how JSON values are + mapped to Perl. + OBJECT-ORIENTED INTERFACE The object oriented interface lets you configure your own encoding or decoding style, within the limits of supported formats. @@ -237,6 +242,45 @@ {"key": "value"} + $json = $json->relaxed ([$enable]) + 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... + ] + $json = $json->canonical ([$enable]) If $enable is true (or missing), then the "encode" method will output JSON objects by sorting their keys. This is adding a @@ -271,6 +315,116 @@ JSON::XS->new->allow_nonref->encode ("Hello, World!") => "Hello, World!" + $json = $json->allow_blessed ([$enable]) + 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 wether "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. + + $json = $json->convert_blessed ([$enable]) + 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. + + This setting does not yet influence "decode" in any way, but in the + future, global hooks might get installed that influence "decode" and + are enabled by this setting. + + If $enable is false, then the "allow_blessed" setting will decide + what to do when a blessed object is found. + + $json = $json->filter_json_object ([$coderef->($hashref)]) + When $coderef is specified, it will be called from "decode" each + time it decodes a JSON object. The only argument 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::XS->new->filter_json_object (sub { 5 }); + # returns [5] + $js->decode ('[{}]') + # throw an exception because allow_nonref is not enabled + # so a lone 5 is not allowed. + $js->decode ('{"a":1, "b":2}'); + + $json = $json->filter_json_single_key_object ($key [=> + $coderef->($value)]) + 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 (its + 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::XS + ->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} } + } + $json = $json->shrink ([$enable]) Perl usually over-allocates memory a bit when allocating space for strings. This flag optionally resizes strings generated by either @@ -312,8 +466,24 @@ Setting the maximum depth to one disallows any nesting, so that ensures that the object is only a single hash/object or array. - The argument to "max_depth" will be rounded up to the next nearest - power of two. + The argument to "max_depth" will be rounded up to the next highest + power of two. If no argument is given, the highest possible setting + will be used, which is rarely useful. + + See SECURITY CONSIDERATIONS, below, for more info on why this is + useful. + + $json = $json->max_size ([$maximum_string_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 longer then this number of + characters it will not attempt to decode the string but throw an + exception. This setting has no effect on "encode" (yet). + + The argument to "max_size" will be rounded up to the next highest + power of two (so may be more than requested). If no argument is + given, the limit check will be deactivated (same as when 0 is + specified). See SECURITY CONSIDERATIONS, below, for more info on why this is useful. @@ -373,18 +543,31 @@ so no manual decoding is necessary. number - A JSON number becomes either an integer or numeric (floating point) - 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. + 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::XS 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. + + Numbers containing a fractional or exponential part will always be + represented as numeric (floating point) values, possibly at a loss + of precision. + + This might create round-tripping problems as numbers might become + strings, but as Perl is typeless there is no other way to do it. true, false - These JSON atoms become 0, 1, respectively. Information is lost in - this process. Future versions might represent those values - differently, but they will be guarenteed to act like these integers - would normally in Perl. + These JSON atoms become "JSON::XS::true" and "JSON::XS::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::XS::is_bool" function. null A JSON null atom becomes "undef" in Perl. @@ -418,6 +601,10 @@ to_json [\0,JSON::XS::true] # yields [false,true] + JSON::XS::true, JSON::XS::false + These special values become JSON true and JSON false values, + respectively. You cna alos use "\1" and "\0" directly if you want. + blessed objects Blessed objects are not allowed. JSON::XS currently tries to encode their underlying representation (hash- or arrayref), but this @@ -537,49 +724,84 @@ Does not check input for validity. + JSON and YAML + You often hear that JSON is a subset (or a close subset) of YAML. This + is, however, a mass hysteria and very far from the truth. In general, + there is no way to configure JSON::XS to output a data structure as + valid YAML. + + If you really must use JSON::XS to generate YAML, you should use this + algorithm (subject to change in future versions): + + my $to_yaml = JSON::XS->new->utf8->space_after (1); + my $yaml = $to_yaml->encode ($ref) . "\n"; + + This will usually generate JSON texts that also parse as valid YAML. + Please note that YAML has hardcoded limits on (simple) object key + lengths that JSON doesn't have, so you should make sure that your hash + keys are noticably shorter than the 1024 characters YAML allows. + + There might be other incompatibilities that I am not aware of. In + general you should not try to generate YAML with a JSON generator or + vice versa, or try to parse JSON with a YAML parser or vice versa: + chances are high that you will run into severe interoperability + problems. + SPEED It seems that JSON::XS is surprisingly fast, as shown in the following tables. They have been generated with the help of the "eg/bench" program in the JSON::XS distribution, to make it easy to compare on your own system. - First comes a comparison between various modules using a very short JSON - string: + First comes a comparison between various modules using a very short + single-line JSON string: - {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null} + {"method": "handleMessage", "params": ["user1", "we were just talking"], \ + "id": null, "array":[1,11,234,-5,1e5,1e7, true, false]} It shows the number of encodes/decodes per second (JSON::XS uses the functional interface, while JSON::XS/2 uses the OO interface with - pretty-printing and hashkey sorting enabled). Higher is better: + pretty-printing and hashkey sorting enabled, JSON::XS/3 enables shrink). + Higher is better: + Storable | 15779.925 | 14169.946 | + -----------+------------+------------+ module | encode | decode | -----------|------------|------------| - JSON | 11488.516 | 7823.035 | - JSON::DWIW | 94708.054 | 129094.260 | - JSON::PC | 63884.157 | 128528.212 | - JSON::Syck | 34898.677 | 42096.911 | - JSON::XS | 654027.064 | 396423.669 | - JSON::XS/2 | 371564.190 | 371725.613 | + JSON | 4990.842 | 4088.813 | + JSON::DWIW | 51653.990 | 71575.154 | + JSON::PC | 65948.176 | 74631.744 | + JSON::PP | 8931.652 | 3817.168 | + JSON::Syck | 24877.248 | 27776.848 | + JSON::XS | 388361.481 | 227951.304 | + JSON::XS/2 | 227951.304 | 218453.333 | + JSON::XS/3 | 338250.323 | 218453.333 | + Storable | 16500.016 | 135300.129 | -----------+------------+------------+ - That is, JSON::XS is more than six times faster than JSON::DWIW on - encoding, more than three times faster on decoding, and about thirty - times faster than JSON, even with pretty-printing and key sorting. + That is, JSON::XS is about five times faster than JSON::DWIW on + encoding, about three times faster on decoding, and over fourty times + faster than JSON, even with pretty-printing and key sorting. It also + compares favourably to Storable for small amounts of data. Using a longer test string (roughly 18KB, generated from Yahoo! Locals search API (http://nanoref.com/yahooapis/mgPdGg): module | encode | decode | -----------|------------|------------| - JSON | 273.023 | 44.674 | - JSON::DWIW | 1089.383 | 1145.704 | - JSON::PC | 3097.419 | 2393.921 | - JSON::Syck | 514.060 | 843.053 | - JSON::XS | 6479.668 | 3636.364 | - JSON::XS/2 | 3774.221 | 3599.124 | + JSON | 55.260 | 34.971 | + JSON::DWIW | 825.228 | 1082.513 | + JSON::PC | 3571.444 | 2394.829 | + JSON::PP | 210.987 | 32.574 | + JSON::Syck | 552.551 | 787.544 | + JSON::XS | 5780.463 | 4854.519 | + JSON::XS/2 | 3869.998 | 4798.975 | + JSON::XS/3 | 5862.880 | 4798.975 | + Storable | 4445.002 | 5235.027 | -----------+------------+------------+ - Again, JSON::XS leads by far. + Again, JSON::XS leads by far (except for Storable which non-surprisingly + decodes faster). On large strings containing lots of high unicode characters, some modules (such as JSON::PC) seem to decode faster than JSON::XS, but the @@ -600,7 +822,10 @@ your resources run out, thats just fine (e.g. by using a separate process that can crash safely). The size of a JSON text in octets or characters is usually a good indication of the size of the resources - required to decode it into a Perl structure. + required to decode it into a Perl structure. While JSON::XS can check + the size of the JSON text, it might be too late when you already have it + in memory, so you might want to check the size before you accept the + string. Third, JSON::XS recurses using the C stack when decoding objects and arrays. The C stack is a limited resource: for instance, on my amd64 @@ -615,6 +840,14 @@ of. In that case, you get to keep the pieces. I am always open for hints, though... + If you are using JSON::XS to return packets to consumption by javascript + scripts in a browser you should have a look at + to see wether + you are vulnerable to some common attack vectors (which really are + browser design bugs, but it is still you who will have to deal with it, + as major browser developers care only for features, not about doing + security right). + BUGS While the goal of this module is to be correct, that unfortunately does not mean its bug-free, only that I think its design is bug-free. It is