--- JSON-XS/README 2007/06/11 03:45:26 1.13 +++ JSON-XS/README 2007/08/27 02:03:23 1.17 @@ -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,34 @@ {"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 + } + $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 +304,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 +455,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 +532,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 +590,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 @@ -577,16 +753,19 @@ pretty-printing and hashkey sorting enabled, JSON::XS/3 enables shrink). Higher is better: + Storable | 15779.925 | 14169.946 | + -----------+------------+------------+ module | encode | decode | -----------|------------|------------| - JSON | 7645.468 | 4208.613 | - JSON::DWIW | 40721.398 | 77101.176 | - JSON::PC | 65948.176 | 78251.940 | - JSON::Syck | 22844.793 | 26479.192 | - JSON::XS | 388361.481 | 199728.762 | - JSON::XS/2 | 218453.333 | 192399.266 | - JSON::XS/3 | 338250.323 | 192399.266 | - Storable | 15779.925 | 14169.946 | + 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 about five times faster than JSON::DWIW on @@ -599,14 +778,15 @@ module | encode | decode | -----------|------------|------------| - JSON | 254.685 | 37.665 | - JSON::DWIW | 843.343 | 1049.731 | - JSON::PC | 3602.116 | 2307.352 | - JSON::Syck | 505.107 | 787.899 | - JSON::XS | 5747.196 | 3690.220 | - JSON::XS/2 | 3968.121 | 3676.634 | - JSON::XS/3 | 6105.246 | 3662.508 | - Storable | 4417.337 | 5285.161 | + 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 (except for Storable which non-surprisingly @@ -631,7 +811,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 @@ -646,6 +829,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