0002-Adds-some-basic-documentation-to-JSON-module.patch

Cory Monty, 05/16/2011 08:26 AM

Download (8.72 KB)

View differences:

ext/json/generator/generator.c
556 556
/*
557 557
 * call-seq: to_json(*)
558 558
 *
559
 * Returns a JSON string for nil: 'null'.
559 560
 */
560 561
static VALUE mNilClass_to_json(int argc, VALUE *argv, VALUE self)
561 562
{
ext/json/lib/json.rb
1
##
2
# = JavaScript Object Notation (JSON)
3
#
4
# JSON is a lightweight data-interchange format. It is easy for us
5
# humans to read and write. Plus, equally simple for machines to generate or parse.
6
# JSON is completely language agnostic, making it the ideal interchange format.
7
#
8
# Built on two universally available structures:
9
#   1. A collection of name/value pairs. Often referred to as an _object_, hash table, record, struct, keyed list, or associative array.
10
#   2. An orderd list of values. More commonly named as an _array_, vector, sequence, or list.
11
#
12
# To read more about JSON visit: http://json.org
13
#
14
# == Parsing JSON
15
#
16
# To parse a JSON string received by another application, or generated within
17
# your existing application:
18
#   
19
#   require 'json'
20
#
21
#   my_hash = JSON.parse('{"hello": "goodbye"}')
22
#   puts my_hash["hello"] => "goodbye"
23
#
24
# Notice the extra quotes <tt>''</tt> around the hash notation. Ruby expects
25
# the argument to be a string and can't convert objects like a hash or array.
26
#
27
# Ruby converts your string into a hash
28
#
29
# == Generating JSON
30
#
31
# Creating a JSON string for communication or serialization is
32
# just as simple.
33
#
34
#   require 'json'
35
#   
36
#   my_hash = {:hello => "goodbye"}
37
#   puts JSON.generate(my_hash) => "{\"hello\":\"goodbye\"}"
38
#
39
# Or an alternative way:
40
#
41
#   require 'json'
42
#   puts {:hello => "goodbye"}.to_json => "{\"hello\":\"goodbye\"}"
43
#
44
# <tt>JSON.generate</tt> only allows objects or arrays to be converted 
45
# to JSON syntax. While <tt>to_json</tt> accepts many Ruby classes 
46
# even though it only acts a method for serialization:
47
#
48
#   require 'json'
49
#
50
#   1.to_json => "1"
51
#
52

  
1 53
require 'json/common'
2 54
module JSON
3 55
  require 'json/version'
ext/json/lib/json/add/core.rb
7 7
end
8 8
require 'date'
9 9

  
10
# Symbol serialization/deserialization
10 11
class Symbol
12
  # Stores class name (Symbol) with String representation of Symbol as a JSON string.
11 13
  def to_json(*a)
12 14
    {
13 15
      JSON.create_id => self.class.name,
14 16
      's' => to_s,
15 17
    }.to_json(*a)
16 18
  end
17

  
19
  
20
  # Deserializes JSON string by converting the <tt>string</tt> value stored in the object to a Symbol
18 21
  def self.json_create(o)
19 22
    o['s'].to_sym
20 23
  end
21 24
end
22 25

  
26
# Time serialization/deserialization
23 27
class Time
28

  
29
  # Deserializes JSON string by converting time since epoch to Time
24 30
  def self.json_create(object)
25 31
    if usec = object.delete('u') # used to be tv_usec -> tv_nsec
26 32
      object['n'] = usec * 1000
......
31 37
      at(object['s'], object['n'] / 1000)
32 38
    end
33 39
  end
34

  
40
  
41
  # Stores class name (Time) with number of seconds since epoch and number of microseconds for Time as JSON string
35 42
  def to_json(*args)
36 43
    {
37 44
      JSON.create_id => self.class.name,
......
41 48
  end
42 49
end
43 50

  
51
# Date serialization/deserialization
44 52
class Date
53
  
54
  # Deserializes JSON string by converting Julian year <tt>y</tt>, month <tt>m</tt>, day <tt>d</tt> and Day of Calendar Reform <tt>sg</tt> to Date.
45 55
  def self.json_create(object)
46 56
    civil(*object.values_at('y', 'm', 'd', 'sg'))
47 57
  end
48 58

  
49 59
  alias start sg unless method_defined?(:start)
50

  
60
  
61
  # Stores class name (Date) with Julian year <tt>y</tt>, month <tt>m</tt>, day <tt>d</tt> and Day of Calendar Reform <tt>sg</tt> as JSON string
51 62
  def to_json(*args)
52 63
    {
53 64
      JSON.create_id => self.class.name,
......
59 70
  end
60 71
end
61 72

  
73
# DateTime serialization/deserialization
62 74
class DateTime
75

  
76
  # Deserializes JSON string by converting year <tt>y</tt>, month <tt>m</tt>, day <tt>d</tt>, hour <tt>H</tt>, minute <tt>M</tt>, second <tt>S</tt>, offset <tt>of</tt> and Day of Calendar Reform <tt>sg</tt> to DateTime.
63 77
  def self.json_create(object)
64 78
    args = object.values_at('y', 'm', 'd', 'H', 'M', 'S')
65 79
    of_a, of_b = object['of'].split('/')
......
73 87
  end
74 88

  
75 89
  alias start sg unless method_defined?(:start)
76

  
90
  
91
  # Stores class name (DateTime) with Julian year <tt>y</tt>, month <tt>m</tt>, day <tt>d</tt>, hour <tt>H</tt>, minute <tt>M</tt>, second <tt>S</tt>, offset <tt>of</tt> and Day of Calendar Reform <tt>sg</tt> as JSON string
77 92
  def to_json(*args)
78 93
    {
79 94
      JSON.create_id => self.class.name,
......
89 104
  end
90 105
end
91 106

  
107
# Range serialization/deserialization
92 108
class Range
109
  
110
  # Deserializes JSON string by constructing new Range object with arguments <tt>a</tt> serialized by <tt>to_json</tt>.
93 111
  def self.json_create(object)
94 112
    new(*object['a'])
95 113
  end
96 114

  
115
  # Stores class name (Range) with JSON array of arguments <tt>a</tt> which include <tt>first</tt> (integer), <tt>last</tt> (integer), and <tt>exclude_end?</tt> (boolean) as JSON string.
97 116
  def to_json(*args)
98 117
    {
99 118
      JSON.create_id   => self.class.name,
......
102 121
  end
103 122
end
104 123

  
124
# Struct serialization/deserialization
105 125
class Struct
126
  
127
  # Deserializes JSON string by constructing new Struct object with values <tt>v</tt> serialized by <tt>to_json</tt>.
106 128
  def self.json_create(object)
107 129
    new(*object['v'])
108 130
  end
109 131

  
132
  # Stores class name (Struct) with Struct values <tt>v</tt> as a JSON string. Only named structs are supported.
110 133
  def to_json(*args)
111 134
    klass = self.class.name
112 135
    klass.to_s.empty? and raise JSON::JSONError, "Only named structs are supported!"
......
117 140
  end
118 141
end
119 142

  
143
# Exception serialization/deserialization
120 144
class Exception
145

  
146
  # Deserializes JSON string by constructing new Exception object with message <tt>m</tt> and backtrace <tt>b</tt> serialized with <tt>to_json</tt>
121 147
  def self.json_create(object)
122 148
    result = new(object['m'])
123 149
    result.set_backtrace object['b']
124 150
    result
125 151
  end
126 152

  
153
  # Stores class name (Exception) with message <tt>m</tt> and backtrace array <tt>b</tt> as JSON string
127 154
  def to_json(*args)
128 155
    {
129 156
      JSON.create_id => self.class.name,
......
133 160
  end
134 161
end
135 162

  
163
# Regexp serialization/deserialization
136 164
class Regexp
165

  
166
  # Deserializes JSON string by constructing new Regexp object with source <tt>s</tt> (Regexp or String) and options <tt>o</tt> serialized by <tt>to_json</tt>
137 167
  def self.json_create(object)
138 168
    new(object['s'], object['o'])
139 169
  end
140 170

  
171
  # Stores class name (Regexp) with options <tt>o</tt> and source <tt>s</tt> (Regexp or String) as JSON string
141 172
  def to_json(*)
142 173
    {
143 174
      JSON.create_id => self.class.name,
ext/json/lib/json/common.rb
291 291
    recurse_proc(result, &proc) if proc
292 292
    result
293 293
  end
294

  
294
  
295
  # Recursively calls passed _Proc_ if the parsed data structure is an _Array_ or _Hash_
295 296
  def recurse_proc(result, &proc)
296 297
    case result
297 298
    when Array
......
342 343

  
343 344
  # Shortuct for iconv.
344 345
  if String.method_defined?(:encode)
346
    # Encodes string using Ruby's _String.encode_
345 347
    def self.iconv(to, from, string)
346 348
      string.encode(to, from)
347 349
    end
348 350
  else
349 351
    require 'iconv'
352
    # Encodes string using _iconv_ library
350 353
    def self.iconv(to, from, string)
351 354
      Iconv.conv(to, from, string)
352 355
    end
......
389 392
  end
390 393
end
391 394

  
395
# Extends any Class to include _json_creatable?_ method.
392 396
class ::Class
393 397
  # Returns true, if this class can be used to create an instance
394 398
  # from a serialised JSON string. The class has to implement a class
395
-