README.md in json_pure-2.1.0 vs README.md in json_pure-2.2.0

- old
+ new

@@ -1,8 +1,9 @@ -# JSON implementation for Ruby ![Travis Widget] -[Travis Widget]: http://travis-ci.org/flori/json.svg?branch=master +# JSON implementation for Ruby +[![Travis Widget](http://travis-ci.org/flori/json.svg?branch=master)](https://travis-ci.org/flori/json) + ## Description This is a implementation of the JSON specification according to RFC 7159 http://www.ietf.org/rfc/rfc7159.txt . Starting from version 1.0.0 on there will be two variants available: @@ -148,10 +149,22 @@ ``` Both of the additions attempt to require `'json'` (like above) first, if it has not been required yet. +## Serializing exceptions + +The JSON module doesn't extend `Exception` by default. If you convert an `Exception` +object to JSON, it will by default only include the exception message. + +To include the full details, you must either load the `json/add/core` mentioned +above, or specifically load the exception addition: + +```ruby +require 'json/add/exception' +``` + ## More Examples To create a JSON document from a ruby data structure, you can call `JSON.generate` like that: @@ -177,44 +190,48 @@ simply implementing a more specialized version of the `#to_json method`, that should return a JSON object (a hash converted to JSON with `#to_json`) like this (don't forget the `*a` for all the arguments): ```ruby - class Range - def to_json(*a) - { - 'json_class' => self.class.name, # = 'Range' - 'data' => [ first, last, exclude_end? ] - }.to_json(*a) - end - end +class Range + def to_json(*a) + { + 'json_class' => self.class.name, # = 'Range' + 'data' => [ first, last, exclude_end? ] + }.to_json(*a) + end +end ``` The hash key `json_class` is the class, that will be asked to deserialise the JSON representation later. In this case it's `Range`, but any namespace of the form `A::B` or `::A::B` will do. All other keys are arbitrary and can be used to store the necessary data to configure the object to be deserialised. -If a the key `json_class` is found in a JSON object, the JSON parser checks +If the key `json_class` is found in a JSON object, the JSON parser checks if the given class responds to the `json_create` class method. If so, it is called with the JSON object converted to a Ruby hash. So a range can be deserialised by implementing `Range.json_create` like this: ```ruby - class Range - def self.json_create(o) - new(*o['data']) - end - end +class Range + def self.json_create(o) + new(*o['data']) + end +end ``` Now it possible to serialise/deserialise ranges as well: ```ruby - json = JSON.generate [1, 2, {"a"=>3.141}, false, true, nil, 4..10] - # => "[1,2,{\"a\":3.141},false,true,null,{\"json_class\":\"Range\",\"data\":[4,10,false]}]" - JSON.parse json - # => [1, 2, {"a"=>3.141}, false, true, nil, 4..10] +json = JSON.generate [1, 2, {"a"=>3.141}, false, true, nil, 4..10] +# => "[1,2,{\"a\":3.141},false,true,null,{\"json_class\":\"Range\",\"data\":[4,10,false]}]" +JSON.parse json +# => [1, 2, {"a"=>3.141}, false, true, nil, 4..10] +json = JSON.generate [1, 2, {"a"=>3.141}, false, true, nil, 4..10] +# => "[1,2,{\"a\":3.141},false,true,null,{\"json_class\":\"Range\",\"data\":[4,10,false]}]" +JSON.parse json, :create_additions => true +# => [1, 2, {"a"=>3.141}, false, true, nil, 4..10] ``` `JSON.generate` always creates the shortest possible string representation of a ruby data structure in one line. This is good for data storage or network protocols, but not so good for humans to read. Fortunately there's also