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