json 2.1.0-java → 2.4.1-java

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
- SHA1:
3
- metadata.gz: 634b7c9d77f51f54770f912bce42e4a6765ad87f
4
- data.tar.gz: 67189aeb4ed037c326096522f03d5455d875c5e0
2
+ SHA256:
3
+ metadata.gz: fed15e5faa6073f7a0cb94e7b3a8c06f2dff0ea9817bdb82a43604276e5c0fda
4
+ data.tar.gz: d455529a5083881f2f33b944445369bb1268dc882b4ec46961d1850f3828f14e
5
5
  SHA512:
6
- metadata.gz: 7f4402403159951b48a71ae16f990e5a273f89bd249d27d8fc1b965c2017de88480941e3d3f73bb068e5f4e7a91f05dcd46f077f3149c26acada386752e7d796
7
- data.tar.gz: '082bde17c11b76f51ae1fd60df8dd72bdee08c31aae7495d436f1a12d0c2f5b29c028ac2e151921ae8cbe0a027f135a21dd703fea39243dfd5cdfb2667ba2fbd'
6
+ metadata.gz: 633801440c937cab3c0d0967a87e9c9709852b106c53ca88cf7a2b50f4a15d4e0c3ac5771c2336c3f5fcafffe8c4df5d3fd2709cfc5e11f8ba32a1ab273cfc7f
7
+ data.tar.gz: ef3b787e64c65cca6b6c5b04a9ab7b14e98781c416d73ab77437dacc6f7cc4b82fd1a6eb6c5f60a6e04ff7aeec8ae384777348f18082c82abb4ceeb9e4c5babc
data/LICENSE ADDED
@@ -0,0 +1,56 @@
1
+ Ruby is copyrighted free software by Yukihiro Matsumoto <matz@netlab.jp>.
2
+ You can redistribute it and/or modify it under either the terms of the
3
+ 2-clause BSDL (see the file BSDL), or the conditions below:
4
+
5
+ 1. You may make and give away verbatim copies of the source form of the
6
+ software without restriction, provided that you duplicate all of the
7
+ original copyright notices and associated disclaimers.
8
+
9
+ 2. You may modify your copy of the software in any way, provided that
10
+ you do at least ONE of the following:
11
+
12
+ a) place your modifications in the Public Domain or otherwise
13
+ make them Freely Available, such as by posting said
14
+ modifications to Usenet or an equivalent medium, or by allowing
15
+ the author to include your modifications in the software.
16
+
17
+ b) use the modified software only within your corporation or
18
+ organization.
19
+
20
+ c) give non-standard binaries non-standard names, with
21
+ instructions on where to get the original software distribution.
22
+
23
+ d) make other distribution arrangements with the author.
24
+
25
+ 3. You may distribute the software in object code or binary form,
26
+ provided that you do at least ONE of the following:
27
+
28
+ a) distribute the binaries and library files of the software,
29
+ together with instructions (in the manual page or equivalent)
30
+ on where to get the original distribution.
31
+
32
+ b) accompany the distribution with the machine-readable source of
33
+ the software.
34
+
35
+ c) give non-standard binaries non-standard names, with
36
+ instructions on where to get the original software distribution.
37
+
38
+ d) make other distribution arrangements with the author.
39
+
40
+ 4. You may modify and include the part of the software into any other
41
+ software (possibly commercial). But some files in the distribution
42
+ are not written by the author, so that they are not under these terms.
43
+
44
+ For the list of those files and their copying conditions, see the
45
+ file LEGAL.
46
+
47
+ 5. The scripts and library files supplied as input to or produced as
48
+ output from the software do not automatically fall under the
49
+ copyright of the software, but belong to whomever generated them,
50
+ and may be sold commercially, and may be aggregated with this
51
+ software.
52
+
53
+ 6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
54
+ IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
55
+ WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
56
+ PURPOSE.
@@ -2,55 +2,575 @@
2
2
  require 'json/common'
3
3
 
4
4
  ##
5
- # = JavaScript Object Notation (JSON)
5
+ # = JavaScript \Object Notation (\JSON)
6
6
  #
7
- # JSON is a lightweight data-interchange format. It is easy for us
8
- # humans to read and write. Plus, equally simple for machines to generate or parse.
9
- # JSON is completely language agnostic, making it the ideal interchange format.
7
+ # \JSON is a lightweight data-interchange format.
10
8
  #
11
- # Built on two universally available structures:
12
- # 1. A collection of name/value pairs. Often referred to as an _object_, hash table, record, struct, keyed list, or associative array.
13
- # 2. An ordered list of values. More commonly called an _array_, vector, sequence or list.
9
+ # A \JSON value is one of the following:
10
+ # - Double-quoted text: <tt>"foo"</tt>.
11
+ # - Number: +1+, +1.0+, +2.0e2+.
12
+ # - Boolean: +true+, +false+.
13
+ # - Null: +null+.
14
+ # - \Array: an ordered list of values, enclosed by square brackets:
15
+ # ["foo", 1, 1.0, 2.0e2, true, false, null]
14
16
  #
15
- # To read more about JSON visit: http://json.org
17
+ # - \Object: a collection of name/value pairs, enclosed by curly braces;
18
+ # each name is double-quoted text;
19
+ # the values may be any \JSON values:
20
+ # {"a": "foo", "b": 1, "c": 1.0, "d": 2.0e2, "e": true, "f": false, "g": null}
16
21
  #
17
- # == Parsing JSON
22
+ # A \JSON array or object may contain nested arrays, objects, and scalars
23
+ # to any depth:
24
+ # {"foo": {"bar": 1, "baz": 2}, "bat": [0, 1, 2]}
25
+ # [{"foo": 0, "bar": 1}, ["baz", 2]]
18
26
  #
19
- # To parse a JSON string received by another application or generated within
20
- # your existing application:
27
+ # == Using \Module \JSON
21
28
  #
29
+ # To make module \JSON available in your code, begin with:
22
30
  # require 'json'
23
31
  #
24
- # my_hash = JSON.parse('{"hello": "goodbye"}')
25
- # puts my_hash["hello"] => "goodbye"
32
+ # All examples here assume that this has been done.
26
33
  #
27
- # Notice the extra quotes <tt>''</tt> around the hash notation. Ruby expects
28
- # the argument to be a string and can't convert objects like a hash or array.
34
+ # === Parsing \JSON
29
35
  #
30
- # Ruby converts your string into a hash
36
+ # You can parse a \String containing \JSON data using
37
+ # either of two methods:
38
+ # - <tt>JSON.parse(source, opts)</tt>
39
+ # - <tt>JSON.parse!(source, opts)</tt>
31
40
  #
32
- # == Generating JSON
41
+ # where
42
+ # - +source+ is a Ruby object.
43
+ # - +opts+ is a \Hash object containing options
44
+ # that control both input allowed and output formatting.
33
45
  #
34
- # Creating a JSON string for communication or serialization is
35
- # just as simple.
46
+ # The difference between the two methods
47
+ # is that JSON.parse! omits some checks
48
+ # and may not be safe for some +source+ data;
49
+ # use it only for data from trusted sources.
50
+ # Use the safer method JSON.parse for less trusted sources.
36
51
  #
37
- # require 'json'
52
+ # ==== Parsing \JSON Arrays
38
53
  #
39
- # my_hash = {:hello => "goodbye"}
40
- # puts JSON.generate(my_hash) => "{\"hello\":\"goodbye\"}"
54
+ # When +source+ is a \JSON array, JSON.parse by default returns a Ruby \Array:
55
+ # json = '["foo", 1, 1.0, 2.0e2, true, false, null]'
56
+ # ruby = JSON.parse(json)
57
+ # ruby # => ["foo", 1, 1.0, 200.0, true, false, nil]
58
+ # ruby.class # => Array
41
59
  #
42
- # Or an alternative way:
60
+ # The \JSON array may contain nested arrays, objects, and scalars
61
+ # to any depth:
62
+ # json = '[{"foo": 0, "bar": 1}, ["baz", 2]]'
63
+ # JSON.parse(json) # => [{"foo"=>0, "bar"=>1}, ["baz", 2]]
43
64
  #
44
- # require 'json'
45
- # puts {:hello => "goodbye"}.to_json => "{\"hello\":\"goodbye\"}"
65
+ # ==== Parsing \JSON \Objects
66
+ #
67
+ # When the source is a \JSON object, JSON.parse by default returns a Ruby \Hash:
68
+ # json = '{"a": "foo", "b": 1, "c": 1.0, "d": 2.0e2, "e": true, "f": false, "g": null}'
69
+ # ruby = JSON.parse(json)
70
+ # ruby # => {"a"=>"foo", "b"=>1, "c"=>1.0, "d"=>200.0, "e"=>true, "f"=>false, "g"=>nil}
71
+ # ruby.class # => Hash
72
+ #
73
+ # The \JSON object may contain nested arrays, objects, and scalars
74
+ # to any depth:
75
+ # json = '{"foo": {"bar": 1, "baz": 2}, "bat": [0, 1, 2]}'
76
+ # JSON.parse(json) # => {"foo"=>{"bar"=>1, "baz"=>2}, "bat"=>[0, 1, 2]}
77
+ #
78
+ # ==== Parsing \JSON Scalars
79
+ #
80
+ # When the source is a \JSON scalar (not an array or object),
81
+ # JSON.parse returns a Ruby scalar.
82
+ #
83
+ # \String:
84
+ # ruby = JSON.parse('"foo"')
85
+ # ruby # => 'foo'
86
+ # ruby.class # => String
87
+ # \Integer:
88
+ # ruby = JSON.parse('1')
89
+ # ruby # => 1
90
+ # ruby.class # => Integer
91
+ # \Float:
92
+ # ruby = JSON.parse('1.0')
93
+ # ruby # => 1.0
94
+ # ruby.class # => Float
95
+ # ruby = JSON.parse('2.0e2')
96
+ # ruby # => 200
97
+ # ruby.class # => Float
98
+ # Boolean:
99
+ # ruby = JSON.parse('true')
100
+ # ruby # => true
101
+ # ruby.class # => TrueClass
102
+ # ruby = JSON.parse('false')
103
+ # ruby # => false
104
+ # ruby.class # => FalseClass
105
+ # Null:
106
+ # ruby = JSON.parse('null')
107
+ # ruby # => nil
108
+ # ruby.class # => NilClass
109
+ #
110
+ # ==== Parsing Options
111
+ #
112
+ # ====== Input Options
113
+ #
114
+ # Option +max_nesting+ (\Integer) specifies the maximum nesting depth allowed;
115
+ # defaults to +100+; specify +false+ to disable depth checking.
116
+ #
117
+ # With the default, +false+:
118
+ # source = '[0, [1, [2, [3]]]]'
119
+ # ruby = JSON.parse(source)
120
+ # ruby # => [0, [1, [2, [3]]]]
121
+ # Too deep:
122
+ # # Raises JSON::NestingError (nesting of 2 is too deep):
123
+ # JSON.parse(source, {max_nesting: 1})
124
+ # Bad value:
125
+ # # Raises TypeError (wrong argument type Symbol (expected Fixnum)):
126
+ # JSON.parse(source, {max_nesting: :foo})
127
+ #
128
+ # ---
129
+ #
130
+ # Option +allow_nan+ (boolean) specifies whether to allow
131
+ # NaN, Infinity, and MinusInfinity in +source+;
132
+ # defaults to +false+.
133
+ #
134
+ # With the default, +false+:
135
+ # # Raises JSON::ParserError (225: unexpected token at '[NaN]'):
136
+ # JSON.parse('[NaN]')
137
+ # # Raises JSON::ParserError (232: unexpected token at '[Infinity]'):
138
+ # JSON.parse('[Infinity]')
139
+ # # Raises JSON::ParserError (248: unexpected token at '[-Infinity]'):
140
+ # JSON.parse('[-Infinity]')
141
+ # Allow:
142
+ # source = '[NaN, Infinity, -Infinity]'
143
+ # ruby = JSON.parse(source, {allow_nan: true})
144
+ # ruby # => [NaN, Infinity, -Infinity]
145
+ #
146
+ # ====== Output Options
147
+ #
148
+ # Option +symbolize_names+ (boolean) specifies whether returned \Hash keys
149
+ # should be Symbols;
150
+ # defaults to +false+ (use Strings).
151
+ #
152
+ # With the default, +false+:
153
+ # source = '{"a": "foo", "b": 1.0, "c": true, "d": false, "e": null}'
154
+ # ruby = JSON.parse(source)
155
+ # ruby # => {"a"=>"foo", "b"=>1.0, "c"=>true, "d"=>false, "e"=>nil}
156
+ # Use Symbols:
157
+ # ruby = JSON.parse(source, {symbolize_names: true})
158
+ # ruby # => {:a=>"foo", :b=>1.0, :c=>true, :d=>false, :e=>nil}
159
+ #
160
+ # ---
161
+ #
162
+ # Option +object_class+ (\Class) specifies the Ruby class to be used
163
+ # for each \JSON object;
164
+ # defaults to \Hash.
165
+ #
166
+ # With the default, \Hash:
167
+ # source = '{"a": "foo", "b": 1.0, "c": true, "d": false, "e": null}'
168
+ # ruby = JSON.parse(source)
169
+ # ruby.class # => Hash
170
+ # Use class \OpenStruct:
171
+ # ruby = JSON.parse(source, {object_class: OpenStruct})
172
+ # ruby # => #<OpenStruct a="foo", b=1.0, c=true, d=false, e=nil>
173
+ #
174
+ # ---
175
+ #
176
+ # Option +array_class+ (\Class) specifies the Ruby class to be used
177
+ # for each \JSON array;
178
+ # defaults to \Array.
179
+ #
180
+ # With the default, \Array:
181
+ # source = '["foo", 1.0, true, false, null]'
182
+ # ruby = JSON.parse(source)
183
+ # ruby.class # => Array
184
+ # Use class \Set:
185
+ # ruby = JSON.parse(source, {array_class: Set})
186
+ # ruby # => #<Set: {"foo", 1.0, true, false, nil}>
187
+ #
188
+ # ---
189
+ #
190
+ # Option +create_additions+ (boolean) specifies whether to use \JSON additions in parsing.
191
+ # See {\JSON Additions}[#module-JSON-label-JSON+Additions].
192
+ #
193
+ # === Generating \JSON
194
+ #
195
+ # To generate a Ruby \String containing \JSON data,
196
+ # use method <tt>JSON.generate(source, opts)</tt>, where
197
+ # - +source+ is a Ruby object.
198
+ # - +opts+ is a \Hash object containing options
199
+ # that control both input allowed and output formatting.
200
+ #
201
+ # ==== Generating \JSON from Arrays
202
+ #
203
+ # When the source is a Ruby \Array, JSON.generate returns
204
+ # a \String containing a \JSON array:
205
+ # ruby = [0, 's', :foo]
206
+ # json = JSON.generate(ruby)
207
+ # json # => '[0,"s","foo"]'
208
+ #
209
+ # The Ruby \Array array may contain nested arrays, hashes, and scalars
210
+ # to any depth:
211
+ # ruby = [0, [1, 2], {foo: 3, bar: 4}]
212
+ # json = JSON.generate(ruby)
213
+ # json # => '[0,[1,2],{"foo":3,"bar":4}]'
214
+ #
215
+ # ==== Generating \JSON from Hashes
216
+ #
217
+ # When the source is a Ruby \Hash, JSON.generate returns
218
+ # a \String containing a \JSON object:
219
+ # ruby = {foo: 0, bar: 's', baz: :bat}
220
+ # json = JSON.generate(ruby)
221
+ # json # => '{"foo":0,"bar":"s","baz":"bat"}'
222
+ #
223
+ # The Ruby \Hash array may contain nested arrays, hashes, and scalars
224
+ # to any depth:
225
+ # ruby = {foo: [0, 1], bar: {baz: 2, bat: 3}, bam: :bad}
226
+ # json = JSON.generate(ruby)
227
+ # json # => '{"foo":[0,1],"bar":{"baz":2,"bat":3},"bam":"bad"}'
228
+ #
229
+ # ==== Generating \JSON from Other Objects
230
+ #
231
+ # When the source is neither an \Array nor a \Hash,
232
+ # the generated \JSON data depends on the class of the source.
233
+ #
234
+ # When the source is a Ruby \Integer or \Float, JSON.generate returns
235
+ # a \String containing a \JSON number:
236
+ # JSON.generate(42) # => '42'
237
+ # JSON.generate(0.42) # => '0.42'
238
+ #
239
+ # When the source is a Ruby \String, JSON.generate returns
240
+ # a \String containing a \JSON string (with double-quotes):
241
+ # JSON.generate('A string') # => '"A string"'
242
+ #
243
+ # When the source is +true+, +false+ or +nil+, JSON.generate returns
244
+ # a \String containing the corresponding \JSON token:
245
+ # JSON.generate(true) # => 'true'
246
+ # JSON.generate(false) # => 'false'
247
+ # JSON.generate(nil) # => 'null'
248
+ #
249
+ # When the source is none of the above, JSON.generate returns
250
+ # a \String containing a \JSON string representation of the source:
251
+ # JSON.generate(:foo) # => '"foo"'
252
+ # JSON.generate(Complex(0, 0)) # => '"0+0i"'
253
+ # JSON.generate(Dir.new('.')) # => '"#<Dir>"'
254
+ #
255
+ # ==== Generating Options
256
+ #
257
+ # ====== Input Options
46
258
  #
47
- # <tt>JSON.generate</tt> only allows objects or arrays to be converted
48
- # to JSON syntax. <tt>to_json</tt>, however, accepts many Ruby classes
49
- # even though it acts only as a method for serialization:
259
+ # Option +allow_nan+ (boolean) specifies whether
260
+ # +NaN+, +Infinity+, and <tt>-Infinity</tt> may be generated;
261
+ # defaults to +false+.
50
262
  #
263
+ # With the default, +false+:
264
+ # # Raises JSON::GeneratorError (920: NaN not allowed in JSON):
265
+ # JSON.generate(JSON::NaN)
266
+ # # Raises JSON::GeneratorError (917: Infinity not allowed in JSON):
267
+ # JSON.generate(JSON::Infinity)
268
+ # # Raises JSON::GeneratorError (917: -Infinity not allowed in JSON):
269
+ # JSON.generate(JSON::MinusInfinity)
270
+ #
271
+ # Allow:
272
+ # ruby = [Float::NaN, Float::Infinity, Float::MinusInfinity]
273
+ # JSON.generate(ruby, allow_nan: true) # => '[NaN,Infinity,-Infinity]'
274
+ #
275
+ # ---
276
+ #
277
+ # Option +max_nesting+ (\Integer) specifies the maximum nesting depth
278
+ # in +obj+; defaults to +100+.
279
+ #
280
+ # With the default, +100+:
281
+ # obj = [[[[[[0]]]]]]
282
+ # JSON.generate(obj) # => '[[[[[[0]]]]]]'
283
+ #
284
+ # Too deep:
285
+ # # Raises JSON::NestingError (nesting of 2 is too deep):
286
+ # JSON.generate(obj, max_nesting: 2)
287
+ #
288
+ # ====== Output Options
289
+ #
290
+ # The default formatting options generate the most compact
291
+ # \JSON data, all on one line and with no whitespace.
292
+ #
293
+ # You can use these formatting options to generate
294
+ # \JSON data in a more open format, using whitespace.
295
+ # See also JSON.pretty_generate.
296
+ #
297
+ # - Option +array_nl+ (\String) specifies a string (usually a newline)
298
+ # to be inserted after each \JSON array; defaults to the empty \String, <tt>''</tt>.
299
+ # - Option +object_nl+ (\String) specifies a string (usually a newline)
300
+ # to be inserted after each \JSON object; defaults to the empty \String, <tt>''</tt>.
301
+ # - Option +indent+ (\String) specifies the string (usually spaces) to be
302
+ # used for indentation; defaults to the empty \String, <tt>''</tt>;
303
+ # defaults to the empty \String, <tt>''</tt>;
304
+ # has no effect unless options +array_nl+ or +object_nl+ specify newlines.
305
+ # - Option +space+ (\String) specifies a string (usually a space) to be
306
+ # inserted after the colon in each \JSON object's pair;
307
+ # defaults to the empty \String, <tt>''</tt>.
308
+ # - Option +space_before+ (\String) specifies a string (usually a space) to be
309
+ # inserted before the colon in each \JSON object's pair;
310
+ # defaults to the empty \String, <tt>''</tt>.
311
+ #
312
+ # In this example, +obj+ is used first to generate the shortest
313
+ # \JSON data (no whitespace), then again with all formatting options
314
+ # specified:
315
+ #
316
+ # obj = {foo: [:bar, :baz], bat: {bam: 0, bad: 1}}
317
+ # json = JSON.generate(obj)
318
+ # puts 'Compact:', json
319
+ # opts = {
320
+ # array_nl: "\n",
321
+ # object_nl: "\n",
322
+ # indent: ' ',
323
+ # space_before: ' ',
324
+ # space: ' '
325
+ # }
326
+ # puts 'Open:', JSON.generate(obj, opts)
327
+ #
328
+ # Output:
329
+ # Compact:
330
+ # {"foo":["bar","baz"],"bat":{"bam":0,"bad":1}}
331
+ # Open:
332
+ # {
333
+ # "foo" : [
334
+ # "bar",
335
+ # "baz"
336
+ # ],
337
+ # "bat" : {
338
+ # "bam" : 0,
339
+ # "bad" : 1
340
+ # }
341
+ # }
342
+ #
343
+ # == \JSON Additions
344
+ #
345
+ # When you "round trip" a non-\String object from Ruby to \JSON and back,
346
+ # you have a new \String, instead of the object you began with:
347
+ # ruby0 = Range.new(0, 2)
348
+ # json = JSON.generate(ruby0)
349
+ # json # => '0..2"'
350
+ # ruby1 = JSON.parse(json)
351
+ # ruby1 # => '0..2'
352
+ # ruby1.class # => String
353
+ #
354
+ # You can use \JSON _additions_ to preserve the original object.
355
+ # The addition is an extension of a ruby class, so that:
356
+ # - \JSON.generate stores more information in the \JSON string.
357
+ # - \JSON.parse, called with option +create_additions+,
358
+ # uses that information to create a proper Ruby object.
359
+ #
360
+ # This example shows a \Range being generated into \JSON
361
+ # and parsed back into Ruby, both without and with
362
+ # the addition for \Range:
363
+ # ruby = Range.new(0, 2)
364
+ # # This passage does not use the addition for Range.
365
+ # json0 = JSON.generate(ruby)
366
+ # ruby0 = JSON.parse(json0)
367
+ # # This passage uses the addition for Range.
368
+ # require 'json/add/range'
369
+ # json1 = JSON.generate(ruby)
370
+ # ruby1 = JSON.parse(json1, create_additions: true)
371
+ # # Make a nice display.
372
+ # display = <<EOT
373
+ # Generated JSON:
374
+ # Without addition: #{json0} (#{json0.class})
375
+ # With addition: #{json1} (#{json1.class})
376
+ # Parsed JSON:
377
+ # Without addition: #{ruby0.inspect} (#{ruby0.class})
378
+ # With addition: #{ruby1.inspect} (#{ruby1.class})
379
+ # EOT
380
+ # puts display
381
+ #
382
+ # This output shows the different results:
383
+ # Generated JSON:
384
+ # Without addition: "0..2" (String)
385
+ # With addition: {"json_class":"Range","a":[0,2,false]} (String)
386
+ # Parsed JSON:
387
+ # Without addition: "0..2" (String)
388
+ # With addition: 0..2 (Range)
389
+ #
390
+ # The \JSON module includes additions for certain classes.
391
+ # You can also craft custom additions.
392
+ # See {Custom \JSON Additions}[#module-JSON-label-Custom+JSON+Additions].
393
+ #
394
+ # === Built-in Additions
395
+ #
396
+ # The \JSON module includes additions for certain classes.
397
+ # To use an addition, +require+ its source:
398
+ # - BigDecimal: <tt>require 'json/add/bigdecimal'</tt>
399
+ # - Complex: <tt>require 'json/add/complex'</tt>
400
+ # - Date: <tt>require 'json/add/date'</tt>
401
+ # - DateTime: <tt>require 'json/add/date_time'</tt>
402
+ # - Exception: <tt>require 'json/add/exception'</tt>
403
+ # - OpenStruct: <tt>require 'json/add/ostruct'</tt>
404
+ # - Range: <tt>require 'json/add/range'</tt>
405
+ # - Rational: <tt>require 'json/add/rational'</tt>
406
+ # - Regexp: <tt>require 'json/add/regexp'</tt>
407
+ # - Set: <tt>require 'json/add/set'</tt>
408
+ # - Struct: <tt>require 'json/add/struct'</tt>
409
+ # - Symbol: <tt>require 'json/add/symbol'</tt>
410
+ # - Time: <tt>require 'json/add/time'</tt>
411
+ #
412
+ # To reduce punctuation clutter, the examples below
413
+ # show the generated \JSON via +puts+, rather than the usual +inspect+,
414
+ #
415
+ # \BigDecimal:
416
+ # require 'json/add/bigdecimal'
417
+ # ruby0 = BigDecimal(0) # 0.0
418
+ # json = JSON.generate(ruby0) # {"json_class":"BigDecimal","b":"27:0.0"}
419
+ # ruby1 = JSON.parse(json, create_additions: true) # 0.0
420
+ # ruby1.class # => BigDecimal
421
+ #
422
+ # \Complex:
423
+ # require 'json/add/complex'
424
+ # ruby0 = Complex(1+0i) # 1+0i
425
+ # json = JSON.generate(ruby0) # {"json_class":"Complex","r":1,"i":0}
426
+ # ruby1 = JSON.parse(json, create_additions: true) # 1+0i
427
+ # ruby1.class # Complex
428
+ #
429
+ # \Date:
430
+ # require 'json/add/date'
431
+ # ruby0 = Date.today # 2020-05-02
432
+ # json = JSON.generate(ruby0) # {"json_class":"Date","y":2020,"m":5,"d":2,"sg":2299161.0}
433
+ # ruby1 = JSON.parse(json, create_additions: true) # 2020-05-02
434
+ # ruby1.class # Date
435
+ #
436
+ # \DateTime:
437
+ # require 'json/add/date_time'
438
+ # ruby0 = DateTime.now # 2020-05-02T10:38:13-05:00
439
+ # json = JSON.generate(ruby0) # {"json_class":"DateTime","y":2020,"m":5,"d":2,"H":10,"M":38,"S":13,"of":"-5/24","sg":2299161.0}
440
+ # ruby1 = JSON.parse(json, create_additions: true) # 2020-05-02T10:38:13-05:00
441
+ # ruby1.class # DateTime
442
+ #
443
+ # \Exception (and its subclasses including \RuntimeError):
444
+ # require 'json/add/exception'
445
+ # ruby0 = Exception.new('A message') # A message
446
+ # json = JSON.generate(ruby0) # {"json_class":"Exception","m":"A message","b":null}
447
+ # ruby1 = JSON.parse(json, create_additions: true) # A message
448
+ # ruby1.class # Exception
449
+ # ruby0 = RuntimeError.new('Another message') # Another message
450
+ # json = JSON.generate(ruby0) # {"json_class":"RuntimeError","m":"Another message","b":null}
451
+ # ruby1 = JSON.parse(json, create_additions: true) # Another message
452
+ # ruby1.class # RuntimeError
453
+ #
454
+ # \OpenStruct:
455
+ # require 'json/add/ostruct'
456
+ # ruby0 = OpenStruct.new(name: 'Matz', language: 'Ruby') # #<OpenStruct name="Matz", language="Ruby">
457
+ # json = JSON.generate(ruby0) # {"json_class":"OpenStruct","t":{"name":"Matz","language":"Ruby"}}
458
+ # ruby1 = JSON.parse(json, create_additions: true) # #<OpenStruct name="Matz", language="Ruby">
459
+ # ruby1.class # OpenStruct
460
+ #
461
+ # \Range:
462
+ # require 'json/add/range'
463
+ # ruby0 = Range.new(0, 2) # 0..2
464
+ # json = JSON.generate(ruby0) # {"json_class":"Range","a":[0,2,false]}
465
+ # ruby1 = JSON.parse(json, create_additions: true) # 0..2
466
+ # ruby1.class # Range
467
+ #
468
+ # \Rational:
469
+ # require 'json/add/rational'
470
+ # ruby0 = Rational(1, 3) # 1/3
471
+ # json = JSON.generate(ruby0) # {"json_class":"Rational","n":1,"d":3}
472
+ # ruby1 = JSON.parse(json, create_additions: true) # 1/3
473
+ # ruby1.class # Rational
474
+ #
475
+ # \Regexp:
476
+ # require 'json/add/regexp'
477
+ # ruby0 = Regexp.new('foo') # (?-mix:foo)
478
+ # json = JSON.generate(ruby0) # {"json_class":"Regexp","o":0,"s":"foo"}
479
+ # ruby1 = JSON.parse(json, create_additions: true) # (?-mix:foo)
480
+ # ruby1.class # Regexp
481
+ #
482
+ # \Set:
483
+ # require 'json/add/set'
484
+ # ruby0 = Set.new([0, 1, 2]) # #<Set: {0, 1, 2}>
485
+ # json = JSON.generate(ruby0) # {"json_class":"Set","a":[0,1,2]}
486
+ # ruby1 = JSON.parse(json, create_additions: true) # #<Set: {0, 1, 2}>
487
+ # ruby1.class # Set
488
+ #
489
+ # \Struct:
490
+ # require 'json/add/struct'
491
+ # Customer = Struct.new(:name, :address) # Customer
492
+ # ruby0 = Customer.new("Dave", "123 Main") # #<struct Customer name="Dave", address="123 Main">
493
+ # json = JSON.generate(ruby0) # {"json_class":"Customer","v":["Dave","123 Main"]}
494
+ # ruby1 = JSON.parse(json, create_additions: true) # #<struct Customer name="Dave", address="123 Main">
495
+ # ruby1.class # Customer
496
+ #
497
+ # \Symbol:
498
+ # require 'json/add/symbol'
499
+ # ruby0 = :foo # foo
500
+ # json = JSON.generate(ruby0) # {"json_class":"Symbol","s":"foo"}
501
+ # ruby1 = JSON.parse(json, create_additions: true) # foo
502
+ # ruby1.class # Symbol
503
+ #
504
+ # \Time:
505
+ # require 'json/add/time'
506
+ # ruby0 = Time.now # 2020-05-02 11:28:26 -0500
507
+ # json = JSON.generate(ruby0) # {"json_class":"Time","s":1588436906,"n":840560000}
508
+ # ruby1 = JSON.parse(json, create_additions: true) # 2020-05-02 11:28:26 -0500
509
+ # ruby1.class # Time
510
+ #
511
+ #
512
+ # === Custom \JSON Additions
513
+ #
514
+ # In addition to the \JSON additions provided,
515
+ # you can craft \JSON additions of your own,
516
+ # either for Ruby built-in classes or for user-defined classes.
517
+ #
518
+ # Here's a user-defined class +Foo+:
519
+ # class Foo
520
+ # attr_accessor :bar, :baz
521
+ # def initialize(bar, baz)
522
+ # self.bar = bar
523
+ # self.baz = baz
524
+ # end
525
+ # end
526
+ #
527
+ # Here's the \JSON addition for it:
528
+ # # Extend class Foo with JSON addition.
529
+ # class Foo
530
+ # # Serialize Foo object with its class name and arguments
531
+ # def to_json(*args)
532
+ # {
533
+ # JSON.create_id => self.class.name,
534
+ # 'a' => [ bar, baz ]
535
+ # }.to_json(*args)
536
+ # end
537
+ # # Deserialize JSON string by constructing new Foo object with arguments.
538
+ # def self.json_create(object)
539
+ # new(*object['a'])
540
+ # end
541
+ # end
542
+ #
543
+ # Demonstration:
51
544
  # require 'json'
545
+ # # This Foo object has no custom addition.
546
+ # foo0 = Foo.new(0, 1)
547
+ # json0 = JSON.generate(foo0)
548
+ # obj0 = JSON.parse(json0)
549
+ # # Lood the custom addition.
550
+ # require_relative 'foo_addition'
551
+ # # This foo has the custom addition.
552
+ # foo1 = Foo.new(0, 1)
553
+ # json1 = JSON.generate(foo1)
554
+ # obj1 = JSON.parse(json1, create_additions: true)
555
+ # # Make a nice display.
556
+ # display = <<EOT
557
+ # Generated JSON:
558
+ # Without custom addition: #{json0} (#{json0.class})
559
+ # With custom addition: #{json1} (#{json1.class})
560
+ # Parsed JSON:
561
+ # Without custom addition: #{obj0.inspect} (#{obj0.class})
562
+ # With custom addition: #{obj1.inspect} (#{obj1.class})
563
+ # EOT
564
+ # puts display
565
+ #
566
+ # Output:
52
567
  #
53
- # 1.to_json => "1"
568
+ # Generated JSON:
569
+ # Without custom addition: "#<Foo:0x0000000006534e80>" (String)
570
+ # With custom addition: {"json_class":"Foo","a":[0,1]} (String)
571
+ # Parsed JSON:
572
+ # Without custom addition: "#<Foo:0x0000000006534e80>" (String)
573
+ # With custom addition: #<Foo:0x0000000006473bb8 @bar=0, @baz=1> (Foo)
54
574
  #
55
575
  module JSON
56
576
  require 'json/version'