Skip to content
Newer
Older
100644 430 lines (329 sloc) 19.5 KB
6248665 ready for use with limitations
Peter Ohler authored Feb 19, 2012
1 # Oj gem
2 A fast JSON parser and Object marshaller as a Ruby gem.
3
4 ## <a name="installation">Installation</a>
5 gem install oj
6
7 ## <a name="source">Source</a>
8
9 *GitHub* *repo*: https://github.com/ohler55/oj
10
11 *RubyGems* *repo*: https://rubygems.org/gems/oj
12
13 ## <a name="build_status">Build Status</a>
14
da0330c getting the travis image to show status
Peter Ohler authored Feb 19, 2012
15 [![Build Status](https://secure.travis-ci.org/ohler55/oj.png?branch=master)](http://travis-ci.org/ohler55/oj)
6248665 ready for use with limitations
Peter Ohler authored Feb 19, 2012
16
17 ## <a name="links">Links of Interest</a>
18
f5aae61 docs completed, ready for a release
Peter Ohler authored Mar 13, 2012
19 [Need for Speed](http://www.ohler.com/software/thoughts/Blog/Entries/2012/3/13_Need_for_Speed.html) for an overview of how Oj::Doc was designed.
20
afe4e99 changed json object format
Peter Ohler authored Feb 25, 2012
21 *Fast XML parser and marshaller on RubyGems*: https://rubygems.org/gems/ox
6248665 ready for use with limitations
Peter Ohler authored Feb 19, 2012
22
afe4e99 changed json object format
Peter Ohler authored Feb 25, 2012
23 *Fast XML parser and marshaller on GitHub*: https://rubygems.org/gems/ox
57afd74 fixed a few bugs and added options
Peter Ohler authored Feb 19, 2012
24
afe4e99 changed json object format
Peter Ohler authored Feb 25, 2012
25 ## <a name="release">Release Notes</a>
6248665 ready for use with limitations
Peter Ohler authored Feb 19, 2012
26
db2a9be JSON generate mimiced
Peter Ohler authored Mar 24, 2012
27 ### Release 1.1.0
8711c85 serializes any Object now. Tests added as well.
Peter Ohler authored Feb 22, 2012
28
db2a9be JSON generate mimiced
Peter Ohler authored Mar 24, 2012
29 - Errors are not longer raised when comments are encountered in JSON documents.
30
31 - Oj can now mimic JSON. With some expections calling JSON.mimic_JSON will allow all JSON calls to use OJ instead of JSON. This gives a speedup of more than 2x on parsing and 5x for generating over the JSON::Ext module.
6248665 ready for use with limitations
Peter Ohler authored Feb 19, 2012
32
12ea8e6 ready for 1.1.0 release
Peter Ohler authored Mar 26, 2012
33 - Oj::Doc now allows a document to be left open and then closed with the Oj::Doc.close() class.
34
7f6d49e made UTF-8 the default encoding instead of the Ruby default encoding
Peter Ohler authored Mar 27, 2012
35 - Changed the default encoding to UTF-8 instead of the Ruby default String encoding.
36
6248665 ready for use with limitations
Peter Ohler authored Feb 19, 2012
37 ## <a name="description">Description</a>
38
39 Optimized JSON (Oj), as the name implies was written to provide speed
40 optimized JSON handling. It was designed as a faster alternative to Yajl and
41 other the common Ruby JSON parsers. So far is has achieved that at about 2
42 time faster than Yajl for parsing and 3 or more times faster writing JSON.
43
8711c85 serializes any Object now. Tests added as well.
Peter Ohler authored Feb 22, 2012
44 Oj has several dump or serialization modes which control how Objects are
45 converted to JSON. These modes are set with the :effort option in either the
e0fb1d3 updatings docs and notes
Peter Ohler authored Feb 26, 2012
46 default options or as one of the options to the dump() method.
47
48 - :strict mode will only allow the 7 basic JSON types to be serialized. Any other Object
49 will raise and Exception.
50
51 - :null mode replaces any Object that is not one of the JSON types is replaced by a JSON null.
52
53 - :object mode will dump any Object as a JSON Object with keys that match the
54 Ruby Object's variable names without the '@' character. This is the highest
55 performance mode.
56
57 - :compat mode is is the compatible with other systems. It will serialize any
58 Object but will check to see if the Object implements a to_hash() or to_json()
59 method. If either exists that method is used for serializing the Object. The
60 to_hash() is more flexible and produces more consistent output so it has a
61 preference over the to_json() method. If neither the to_json() or to_hash()
62 methods exist then the Oj internal Object variable encoding is used.
8711c85 serializes any Object now. Tests added as well.
Peter Ohler authored Feb 22, 2012
63
5b248cc added Bag class and auto_define flag
Peter Ohler authored Feb 27, 2012
64 Oj is compatible with Ruby 1.8.7, 1.9.2, 1.9.3, JRuby, and RBX.
65
66 ## <a name="plans">Planned Releases</a>
6248665 ready for use with limitations
Peter Ohler authored Feb 19, 2012
67
f5aae61 docs completed, ready for a release
Peter Ohler authored Mar 13, 2012
68 - Release 1.0.1: Optimize the Oj::Doc dump() method to be native.
69
70 - Release 1.1: A JSON stream parser. Pushed out for the Oj::Doc parser.
6248665 ready for use with limitations
Peter Ohler authored Feb 19, 2012
71
6669206 ready for 0.6.0 release
Peter Ohler authored Feb 22, 2012
72 ## <a name="compare">Comparisons</a>
73
f5aae61 docs completed, ready for a release
Peter Ohler authored Mar 13, 2012
74 ### Fast Oj::Doc parser comparisons
75
76 The fast Oj::Doc parser is compared to the Yajl and JSON::Pure parsers with
77 strict JSON documents. No object conversions are included, just simple JSON.
78
79 Since the Oj::Doc deviation from the conventional parsers comparisons of not
80 only parsing but data access is also included. These tests use the
81 perf_fast.rb test file. The first benchmark is for just parsing. The second is
82 for doing a get on every leaf value in the JSON data structure. The third
83 fetchs a value from a specific spot in the document. With Yajl and JSON this
84 is done with a set of calls to fetch() for each level in the document. For
85 Oj::Doc a single fetch with a path is used.
86
87 The benchmark results are:
88
89 > perf_fast.rb -g 1 -f
90 --------------------------------------------------------------------------------
91 Parse Performance
92 Oj::Doc.parse 100000 times in 0.164 seconds or 609893.696 parse/sec.
93 Yajl.parse 100000 times in 3.168 seconds or 31569.902 parse/sec.
94 JSON::Ext.parse 100000 times in 3.282 seconds or 30464.826 parse/sec.
95
96 Summary:
97 System time (secs) rate (ops/sec)
98 --------- ----------- --------------
99 Oj::Doc 0.164 609893.696
100 Yajl 3.168 31569.902
101 JSON::Ext 3.282 30464.826
102
103 Comparison Matrix
104 (performance factor, 2.0 row is means twice as fast as column)
105 Oj::Doc Yajl JSON::Ext
106 --------- --------- --------- ---------
107 Oj::Doc 1.00 19.32 20.02
108 Yajl 0.05 1.00 1.04
109 JSON::Ext 0.05 0.96 1.00
110
111 --------------------------------------------------------------------------------
112 Parse and get all values Performance
113 Oj::Doc.parse 100000 times in 0.417 seconds or 240054.540 parse/sec.
114 Yajl.parse 100000 times in 5.159 seconds or 19384.191 parse/sec.
115 JSON::Ext.parse 100000 times in 5.269 seconds or 18978.638 parse/sec.
116
117 Summary:
118 System time (secs) rate (ops/sec)
119 --------- ----------- --------------
120 Oj::Doc 0.417 240054.540
121 Yajl 5.159 19384.191
122 JSON::Ext 5.269 18978.638
123
124 Comparison Matrix
125 (performance factor, 2.0 row is means twice as fast as column)
126 Oj::Doc Yajl JSON::Ext
127 --------- --------- --------- ---------
128 Oj::Doc 1.00 12.38 12.65
129 Yajl 0.08 1.00 1.02
130 JSON::Ext 0.08 0.98 1.00
131
132 --------------------------------------------------------------------------------
133 fetch nested Performance
134 Oj::Doc.fetch 100000 times in 0.094 seconds or 1059995.760 fetch/sec.
135 Ruby.fetch 100000 times in 0.503 seconds or 198851.434 fetch/sec.
136
137 Summary:
138 System time (secs) rate (ops/sec)
139 ------- ----------- --------------
140 Oj::Doc 0.094 1059995.760
141 Ruby 0.503 198851.434
142
143 Comparison Matrix
144 (performance factor, 2.0 row is means twice as fast as column)
145 Oj::Doc Ruby
146 ------- ------- -------
147 Oj::Doc 1.00 5.33
148 Ruby 0.19 1.00
149
150 What the results mean are that for getting just a few values from a JSON
151 document Oj::Doc is 20 times faster than any other parser and for accessing
152 all values it is still over 12 times faster than any other Ruby JSON parser.
153
154 ### Conventional Oj parser comparisons
155
6669206 ready for 0.6.0 release
Peter Ohler authored Feb 22, 2012
156 The following table shows the difference is speeds between several
f5aae61 docs completed, ready for a release
Peter Ohler authored Mar 13, 2012
157 serialization packages compared to the more conventional Oj parser. The tests
158 had to be scaled back due to limitation of some of the gems. I finally gave up
159 trying to get JSON Pure to serialize without errors with Ruby 1.9.3. It had
160 internal errors on anything other than a simple JSON structure. The errors
161 encountered were:
6669206 ready for 0.6.0 release
Peter Ohler authored Feb 22, 2012
162
163 - MessagePack fails to convert Bignum to JSON
164
e0fb1d3 updatings docs and notes
Peter Ohler authored Feb 26, 2012
165 - JSON Pure fails to serialize any numbers or Objects with the to_json() method
6669206 ready for 0.6.0 release
Peter Ohler authored Feb 22, 2012
166
e0fb1d3 updatings docs and notes
Peter Ohler authored Feb 26, 2012
167 Options were added to the test/perf_strict.rb test to run the test without
168 Object encoding and without Bignums.
6669206 ready for 0.6.0 release
Peter Ohler authored Feb 22, 2012
169
170 None of the packages except Oj were able to serialize Ruby Objects that did
171 not have a to_json() method or were of the 7 native JSON types.
172
5b248cc added Bag class and auto_define flag
Peter Ohler authored Feb 27, 2012
173 A perf_obj.rb file was added for comparing different Object marshalling
174 packages.
175
6669206 ready for 0.6.0 release
Peter Ohler authored Feb 22, 2012
176 It is also worth noting that although Oj is slightly behind MessagePack for
177 parsing, Oj serialization is much faster than MessagePack even though Oj uses
178 human readable JSON vs the binary MessagePack format.
179
f5aae61 docs completed, ready for a release
Peter Ohler authored Mar 13, 2012
180 Oj supports circular references when in :object mode and when the :circular
6b22c57 finishing off circular reference implementation
Peter Ohler authored Mar 5, 2012
181 flag is true. None of the other gems tested supported circular
182 references. They failed in the following manners when the input included
183 circular references.
184
185 - Yajl core dumps Ruby
186
187 - JSON fails and raises an Exception
188
189 - MessagePack fails and raises an Exception
190
191 The benchmark results are:
6669206 ready for 0.6.0 release
Peter Ohler authored Feb 22, 2012
192
193 with Object and Bignum encoding:
194
53e3bbc added benchmarks
Peter Ohler authored Mar 5, 2012
195 > perf_strict.rb
6234873 ready for a release
Peter Ohler authored Feb 26, 2012
196 --------------------------------------------------------------------------------
197 Load/Parse Performance
53e3bbc added benchmarks
Peter Ohler authored Mar 5, 2012
198 Oj:compat.load 100000 times in 1.481 seconds or 67513.146 load/sec.
199 Oj.load 100000 times in 1.066 seconds or 93796.400 load/sec.
200 JSON::Ext.parse 100000 times in 3.023 seconds or 33074.875 parse/sec.
201 JSON::Pure.parse 100000 times in 18.908 seconds or 5288.799 parse/sec.
202 Ox.load 100000 times in 1.240 seconds or 80671.900 load/sec.
6234873 ready for a release
Peter Ohler authored Feb 26, 2012
203
204 Summary:
205 System time (secs) rate (ops/sec)
206 ---------- ----------- --------------
53e3bbc added benchmarks
Peter Ohler authored Mar 5, 2012
207 Oj 1.066 93796.400
208 Ox 1.240 80671.900
209 Oj:compat 1.481 67513.146
210 JSON::Ext 3.023 33074.875
211 JSON::Pure 18.908 5288.799
6234873 ready for a release
Peter Ohler authored Feb 26, 2012
212
213 Comparison Matrix
214 (performance factor, 2.0 row is means twice as fast as column)
53e3bbc added benchmarks
Peter Ohler authored Mar 5, 2012
215 Oj Ox Oj:compat JSON::Ext JSON::Pure
6234873 ready for a release
Peter Ohler authored Feb 26, 2012
216 ---------- ---------- ---------- ---------- ---------- ----------
53e3bbc added benchmarks
Peter Ohler authored Mar 5, 2012
217 Oj 1.00 1.16 1.39 2.84 17.73
218 Ox 0.86 1.00 1.19 2.44 15.25
219 Oj:compat 0.72 0.84 1.00 2.04 12.77
220 JSON::Ext 0.35 0.41 0.49 1.00 6.25
221 JSON::Pure 0.06 0.07 0.08 0.16 1.00
6234873 ready for a release
Peter Ohler authored Feb 26, 2012
222
223
224 --------------------------------------------------------------------------------
225 Dump/Encode/Generate Performance
53e3bbc added benchmarks
Peter Ohler authored Mar 5, 2012
226 Oj:compat.dump 100000 times in 0.789 seconds or 126715.249 dump/sec.
227 Oj.dump 100000 times in 0.457 seconds or 218798.751 dump/sec.
228 JSON::Ext.generate 100000 times in 4.371 seconds or 22878.630 generate/sec.
229 Ox.dump 100000 times in 0.501 seconds or 199425.256 dump/sec.
6234873 ready for a release
Peter Ohler authored Feb 26, 2012
230
231 Summary:
232 System time (secs) rate (ops/sec)
233 --------- ----------- --------------
53e3bbc added benchmarks
Peter Ohler authored Mar 5, 2012
234 Oj 0.457 218798.751
235 Ox 0.501 199425.256
236 Oj:compat 0.789 126715.249
237 JSON::Ext 4.371 22878.630
6234873 ready for a release
Peter Ohler authored Feb 26, 2012
238
239 Comparison Matrix
240 (performance factor, 2.0 row is means twice as fast as column)
53e3bbc added benchmarks
Peter Ohler authored Mar 5, 2012
241 Oj Ox Oj:compat JSON::Ext
6234873 ready for a release
Peter Ohler authored Feb 26, 2012
242 --------- --------- --------- --------- ---------
53e3bbc added benchmarks
Peter Ohler authored Mar 5, 2012
243 Oj 1.00 1.10 1.73 9.56
244 Ox 0.91 1.00 1.57 8.72
245 Oj:compat 0.58 0.64 1.00 5.54
246 JSON::Ext 0.10 0.11 0.18 1.00
247
248
249 The following packages were not included for the reason listed
250 ***** MessagePack: RangeError: bignum too big to convert into `unsigned long long'
251 ***** Yajl: RuntimeError: Yajl parse and encode did not return the same object as the original.
252 ***** JSON::Pure: TypeError: wrong argument type JSON::Pure::Generator::State (expected Data)
6669206 ready for 0.6.0 release
Peter Ohler authored Feb 22, 2012
253
53e3bbc added benchmarks
Peter Ohler authored Mar 5, 2012
254 without Objects or numbers (for JSON Pure, Yajl, and Messagepack) JSON:
6669206 ready for 0.6.0 release
Peter Ohler authored Feb 22, 2012
255
6234873 ready for a release
Peter Ohler authored Feb 26, 2012
256 --------------------------------------------------------------------------------
257 Load/Parse Performance
53e3bbc added benchmarks
Peter Ohler authored Mar 5, 2012
258 Oj:compat.load 100000 times in 0.806 seconds or 124051.164 load/sec.
259 Oj.load 100000 times in 0.810 seconds or 123384.587 load/sec.
260 Yajl.parse 100000 times in 1.441 seconds or 69385.996 parse/sec.
261 JSON::Ext.parse 100000 times in 1.567 seconds or 63797.848 parse/sec.
262 JSON::Pure.parse 100000 times in 13.500 seconds or 7407.247 parse/sec.
263 Ox.load 100000 times in 0.954 seconds or 104836.748 load/sec.
264 MessagePack.unpack 100000 times in 0.651 seconds or 153707.817 unpack/sec.
6234873 ready for a release
Peter Ohler authored Feb 26, 2012
265
266 Summary:
267 System time (secs) rate (ops/sec)
268 ----------- ----------- --------------
53e3bbc added benchmarks
Peter Ohler authored Mar 5, 2012
269 MessagePack 0.651 153707.817
270 Oj:compat 0.806 124051.164
271 Oj 0.810 123384.587
272 Ox 0.954 104836.748
273 Yajl 1.441 69385.996
274 JSON::Ext 1.567 63797.848
275 JSON::Pure 13.500 7407.247
6234873 ready for a release
Peter Ohler authored Feb 26, 2012
276
277 Comparison Matrix
278 (performance factor, 2.0 row is means twice as fast as column)
53e3bbc added benchmarks
Peter Ohler authored Mar 5, 2012
279 MessagePack Oj:compat Oj Ox Yajl JSON::Ext JSON::Pure
280 ----------- ----------- ----------- ----------- ----------- ----------- ----------- -----------
281 MessagePack 1.00 1.24 1.25 1.47 2.22 2.41 20.75
282 Oj:compat 0.81 1.00 1.01 1.18 1.79 1.94 16.75
283 Oj 0.80 0.99 1.00 1.18 1.78 1.93 16.66
284 Ox 0.68 0.85 0.85 1.00 1.51 1.64 14.15
285 Yajl 0.45 0.56 0.56 0.66 1.00 1.09 9.37
286 JSON::Ext 0.42 0.51 0.52 0.61 0.92 1.00 8.61
287 JSON::Pure 0.05 0.06 0.06 0.07 0.11 0.12 1.00
6234873 ready for a release
Peter Ohler authored Feb 26, 2012
288
289
290 --------------------------------------------------------------------------------
291 Dump/Encode/Generate Performance
53e3bbc added benchmarks
Peter Ohler authored Mar 5, 2012
292 Oj:compat.dump 100000 times in 0.173 seconds or 578526.262 dump/sec.
293 Oj.dump 100000 times in 0.179 seconds or 558362.880 dump/sec.
294 Yajl.encode 100000 times in 0.776 seconds or 128794.279 encode/sec.
295 JSON::Ext.generate 100000 times in 3.511 seconds or 28483.812 generate/sec.
296 JSON::Pure.generate 100000 times in 7.389 seconds or 13533.717 generate/sec.
297 Ox.dump 100000 times in 0.196 seconds or 510589.629 dump/sec.
298 MessagePack.pack 100000 times in 0.317 seconds or 315307.220 pack/sec.
6234873 ready for a release
Peter Ohler authored Feb 26, 2012
299
300 Summary:
301 System time (secs) rate (ops/sec)
302 ----------- ----------- --------------
53e3bbc added benchmarks
Peter Ohler authored Mar 5, 2012
303 Oj:compat 0.173 578526.262
304 Oj 0.179 558362.880
305 Ox 0.196 510589.629
306 MessagePack 0.317 315307.220
307 Yajl 0.776 128794.279
308 JSON::Ext 3.511 28483.812
309 JSON::Pure 7.389 13533.717
6234873 ready for a release
Peter Ohler authored Feb 26, 2012
310
311 Comparison Matrix
312 (performance factor, 2.0 row is means twice as fast as column)
53e3bbc added benchmarks
Peter Ohler authored Mar 5, 2012
313 Oj:compat Oj Ox MessagePack Yajl JSON::Ext JSON::Pure
314 ----------- ----------- ----------- ----------- ----------- ----------- ----------- -----------
315 Oj:compat 1.00 1.04 1.13 1.83 4.49 20.31 42.75
316 Oj 0.97 1.00 1.09 1.77 4.34 19.60 41.26
317 Ox 0.88 0.91 1.00 1.62 3.96 17.93 37.73
318 MessagePack 0.55 0.56 0.62 1.00 2.45 11.07 23.30
319 Yajl 0.22 0.23 0.25 0.41 1.00 4.52 9.52
320 JSON::Ext 0.05 0.05 0.06 0.09 0.22 1.00 2.10
321 JSON::Pure 0.02 0.02 0.03 0.04 0.11 0.48 1.00
6234873 ready for a release
Peter Ohler authored Feb 26, 2012
322
6248665 ready for use with limitations
Peter Ohler authored Feb 19, 2012
323 ### Simple JSON Writing and Parsing:
324
325 require 'oj'
326
327 h = { 'one' => 1, 'array' => [ true, false ] }
328 json = Oj.dump(h)
329
330 # json =
331 # {
332 # "one":1,
333 # "array":[
334 # true,
335 # false
336 # ]
337 # }
338
9b9a86f @sferik Fix typo
sferik authored Mar 14, 2012
339 h2 = Oj.load(json)
6248665 ready for use with limitations
Peter Ohler authored Feb 19, 2012
340 puts "Same? #{h == h2}"
341 # true
4d28d2c updated readme with message format for object encoding
Peter Ohler authored Feb 27, 2012
342
343 ### Object JSON format:
344
345 In :object mode Oj generates JSON that follows conventions which allow Class
346 and other information such as Object IDs for circular reference detection. The
347 formating follows the following rules.
348
349 1. JSON native types, true, false, nil, String, Hash, Array, and Number are
350 encoded normally.
351
6b22c57 finishing off circular reference implementation
Peter Ohler authored Mar 5, 2012
352 2. A Symbol is encoded as a JSON string with a preceeding `:` character.
4d28d2c updated readme with message format for object encoding
Peter Ohler authored Feb 27, 2012
353
6b22c57 finishing off circular reference implementation
Peter Ohler authored Mar 5, 2012
354 3. The `^` character denotes a special key value when in a JSON Object sequence.
4d28d2c updated readme with message format for object encoding
Peter Ohler authored Feb 27, 2012
355
6b22c57 finishing off circular reference implementation
Peter Ohler authored Mar 5, 2012
356 4. A Ruby String that starts with `:` or the sequence `^i` or `^r` are encoded by
357 excaping the first character so that it appears as `\u005e` or `\u003a` instead of
358 `:` or `^`.
4d28d2c updated readme with message format for object encoding
Peter Ohler authored Feb 27, 2012
359
6b22c57 finishing off circular reference implementation
Peter Ohler authored Mar 5, 2012
360 5. A `"^c"` JSON Object key indicates the value should be converted to a Ruby
361 class. The sequence `{"^c":"Oj::Bag"}` is read as the Oj::Bag class.
4d28d2c updated readme with message format for object encoding
Peter Ohler authored Feb 27, 2012
362
6b22c57 finishing off circular reference implementation
Peter Ohler authored Mar 5, 2012
363 6. A `"^t"` JSON Object key indicates the value should be converted to a Ruby
364 Time. The sequence `{"^t":1325775487.000000}` is read as Jan 5, 2012 at 23:58:07.
4d28d2c updated readme with message format for object encoding
Peter Ohler authored Feb 27, 2012
365
6b22c57 finishing off circular reference implementation
Peter Ohler authored Mar 5, 2012
366 87. A `"^o"` JSON Object key indicates the value should be converted to a Ruby
367 Object. The first entry in the JSON Object must be a class with the `"^o"`
4d28d2c updated readme with message format for object encoding
Peter Ohler authored Feb 27, 2012
368 key. After that each entry is treated as a variable of the Object where the
6b22c57 finishing off circular reference implementation
Peter Ohler authored Mar 5, 2012
369 key is the variable name without the preceeding `@`. An example is
370 `{"^o":"Oj::Bag","x":58,"y":"marbles"}`.
4d28d2c updated readme with message format for object encoding
Peter Ohler authored Feb 27, 2012
371
6b22c57 finishing off circular reference implementation
Peter Ohler authored Mar 5, 2012
372 8. A `"^u"` JSON Object key indicates the value should be converted to a Ruby
373 Struct. The first entry in the JSON Object must be a class with the `"^u"`
0dfa515 now dumping struct in the correct format. Loading still unimplemented
Peter Ohler authored Feb 28, 2012
374 key. After that each entry is is given a numeric position in the struct and
6b22c57 finishing off circular reference implementation
Peter Ohler authored Mar 5, 2012
375 that is used as the key in the JSON Object. An example is `{"^u":["Range",1,7,false]}`.
0dfa515 now dumping struct in the correct format. Loading still unimplemented
Peter Ohler authored Feb 28, 2012
376
6b22c57 finishing off circular reference implementation
Peter Ohler authored Mar 5, 2012
377 9. When encoding an Object, if the variable name does not begin with an `@`
378 character then the name preceeded by a `~` character. This occurs in the
379 Exception class. An example is `{"^o":"StandardError","~mesg":"A Message","~bt":[".\/tests.rb:345:in `test_exception'"]}`.
4d28d2c updated readme with message format for object encoding
Peter Ohler authored Feb 27, 2012
380
6b22c57 finishing off circular reference implementation
Peter Ohler authored Mar 5, 2012
381 10. If a Hash entry has a key that is not a String or Symbol then the entry is
382 encoded with a key of the form `"^#n"` where n is a hex number. The value that
4d28d2c updated readme with message format for object encoding
Peter Ohler authored Feb 27, 2012
383 is an Array where the first element is the key in the Hash and the second is
6b22c57 finishing off circular reference implementation
Peter Ohler authored Mar 5, 2012
384 the value. An example is `{"^#3":[2,5]}`.
4d28d2c updated readme with message format for object encoding
Peter Ohler authored Feb 27, 2012
385
6b22c57 finishing off circular reference implementation
Peter Ohler authored Mar 5, 2012
386 11. A `"^i"` JSON entry in either an Object or Array is the ID of the Ruby
4d28d2c updated readme with message format for object encoding
Peter Ohler authored Feb 27, 2012
387 Object being encoded. It is used when the :circular flag is set. It can appear
6b22c57 finishing off circular reference implementation
Peter Ohler authored Mar 5, 2012
388 in either a JSON Object or in a JSON Array. In an Object the `"^i"` key has a
fdacd8d added hash circular support
Peter Ohler authored Mar 3, 2012
389 corresponding reference Fixnum. In an array the sequence will include an
390 embedded reference number. An example is
6b22c57 finishing off circular reference implementation
Peter Ohler authored Mar 5, 2012
391 `{"^o":"Oj::Bag","^i":1,"x":["^i2",true],"me":"^r1"}`.
392
393 12. A `"^r"` JSON entry in an Object is a references to a Object or Array that
394 already appears in the JSON String. It must match up with a previous `"^i"`
395 ID. An example is `{"^o":"Oj::Bag","^i":1,"x":3,"me":"^r1"}`.
fdacd8d added hash circular support
Peter Ohler authored Mar 3, 2012
396
6b22c57 finishing off circular reference implementation
Peter Ohler authored Mar 5, 2012
397 13. If an Array element is a String and starts with `"^i"` then the first
398 character, the `^` is encoded as a hex character sequence. An example is
399 `["\u005ei37",3]`.
fdacd8d added hash circular support
Peter Ohler authored Mar 3, 2012
400
6b22c57 finishing off circular reference implementation
Peter Ohler authored Mar 5, 2012
401 ### License:
402
403 Copyright (c) 2012, Peter Ohler
404 All rights reserved.
405
406 Redistribution and use in source and binary forms, with or without
407 modification, are permitted provided that the following conditions are met:
408
409 - Redistributions of source code must retain the above copyright notice, this
410 list of conditions and the following disclaimer.
411
412 - Redistributions in binary form must reproduce the above copyright notice,
413 this list of conditions and the following disclaimer in the documentation
414 and/or other materials provided with the distribution.
415
416 - Neither the name of Peter Ohler nor the names of its contributors may be
417 used to endorse or promote products derived from this software without
418 specific prior written permission.
419
420 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
421 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
422 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
423 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
424 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
425 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
426 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
427 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
428 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
429 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Something went wrong with that request. Please try again.