oj 2.0.0 → 3.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (133) hide show
  1. checksums.yaml +7 -0
  2. data/LICENSE +17 -23
  3. data/README.md +74 -425
  4. data/ext/oj/buf.h +103 -0
  5. data/ext/oj/cache8.c +4 -0
  6. data/ext/oj/circarray.c +68 -0
  7. data/ext/oj/circarray.h +23 -0
  8. data/ext/oj/code.c +227 -0
  9. data/ext/oj/code.h +40 -0
  10. data/ext/oj/compat.c +243 -0
  11. data/ext/oj/custom.c +1097 -0
  12. data/ext/oj/dump.c +766 -1534
  13. data/ext/oj/dump.h +92 -0
  14. data/ext/oj/dump_compat.c +937 -0
  15. data/ext/oj/dump_leaf.c +254 -0
  16. data/ext/oj/dump_object.c +810 -0
  17. data/ext/oj/dump_rails.c +329 -0
  18. data/ext/oj/dump_strict.c +416 -0
  19. data/ext/oj/encode.h +51 -0
  20. data/ext/oj/err.c +57 -0
  21. data/ext/oj/err.h +70 -0
  22. data/ext/oj/extconf.rb +17 -7
  23. data/ext/oj/fast.c +213 -180
  24. data/ext/oj/hash.c +163 -0
  25. data/ext/oj/hash.h +46 -0
  26. data/ext/oj/hash_test.c +512 -0
  27. data/ext/oj/mimic_json.c +817 -0
  28. data/ext/oj/mimic_rails.c +806 -0
  29. data/ext/oj/mimic_rails.h +17 -0
  30. data/ext/oj/object.c +752 -0
  31. data/ext/oj/odd.c +230 -0
  32. data/ext/oj/odd.h +44 -0
  33. data/ext/oj/oj.c +1288 -929
  34. data/ext/oj/oj.h +240 -69
  35. data/ext/oj/parse.c +1014 -0
  36. data/ext/oj/parse.h +92 -0
  37. data/ext/oj/reader.c +223 -0
  38. data/ext/oj/reader.h +151 -0
  39. data/ext/oj/resolve.c +127 -0
  40. data/ext/oj/{cache.h → resolve.h} +6 -13
  41. data/ext/oj/rxclass.c +133 -0
  42. data/ext/oj/rxclass.h +27 -0
  43. data/ext/oj/saj.c +77 -175
  44. data/ext/oj/scp.c +224 -0
  45. data/ext/oj/sparse.c +911 -0
  46. data/ext/oj/stream_writer.c +301 -0
  47. data/ext/oj/strict.c +162 -0
  48. data/ext/oj/string_writer.c +480 -0
  49. data/ext/oj/val_stack.c +98 -0
  50. data/ext/oj/val_stack.h +188 -0
  51. data/lib/oj/active_support_helper.rb +41 -0
  52. data/lib/oj/bag.rb +6 -10
  53. data/lib/oj/easy_hash.rb +52 -0
  54. data/lib/oj/json.rb +172 -0
  55. data/lib/oj/mimic.rb +260 -5
  56. data/lib/oj/saj.rb +13 -10
  57. data/lib/oj/schandler.rb +142 -0
  58. data/lib/oj/state.rb +131 -0
  59. data/lib/oj/version.rb +1 -1
  60. data/lib/oj.rb +11 -23
  61. data/pages/Advanced.md +22 -0
  62. data/pages/Compatibility.md +25 -0
  63. data/pages/Custom.md +23 -0
  64. data/pages/Encoding.md +65 -0
  65. data/pages/JsonGem.md +79 -0
  66. data/pages/Modes.md +140 -0
  67. data/pages/Options.md +250 -0
  68. data/pages/Rails.md +60 -0
  69. data/pages/Security.md +20 -0
  70. data/test/_test_active.rb +76 -0
  71. data/test/_test_active_mimic.rb +96 -0
  72. data/test/_test_mimic_rails.rb +126 -0
  73. data/test/activesupport4/decoding_test.rb +105 -0
  74. data/test/activesupport4/encoding_test.rb +531 -0
  75. data/test/activesupport4/test_helper.rb +41 -0
  76. data/test/activesupport5/decoding_test.rb +125 -0
  77. data/test/activesupport5/encoding_test.rb +483 -0
  78. data/test/activesupport5/encoding_test_cases.rb +90 -0
  79. data/test/activesupport5/test_helper.rb +50 -0
  80. data/test/activesupport5/time_zone_test_helpers.rb +24 -0
  81. data/test/helper.rb +27 -0
  82. data/test/isolated/shared.rb +310 -0
  83. data/test/isolated/test_mimic_after.rb +13 -0
  84. data/test/isolated/test_mimic_alone.rb +12 -0
  85. data/test/isolated/test_mimic_as_json.rb +45 -0
  86. data/test/isolated/test_mimic_before.rb +13 -0
  87. data/test/isolated/test_mimic_define.rb +28 -0
  88. data/test/isolated/test_mimic_rails_after.rb +22 -0
  89. data/test/isolated/test_mimic_rails_before.rb +21 -0
  90. data/test/isolated/test_mimic_redefine.rb +15 -0
  91. data/test/json_gem/json_addition_test.rb +216 -0
  92. data/test/json_gem/json_common_interface_test.rb +143 -0
  93. data/test/json_gem/json_encoding_test.rb +109 -0
  94. data/test/json_gem/json_ext_parser_test.rb +20 -0
  95. data/test/json_gem/json_fixtures_test.rb +35 -0
  96. data/test/json_gem/json_generator_test.rb +383 -0
  97. data/test/json_gem/json_generic_object_test.rb +90 -0
  98. data/test/json_gem/json_parser_test.rb +470 -0
  99. data/test/json_gem/json_string_matching_test.rb +42 -0
  100. data/test/json_gem/test_helper.rb +18 -0
  101. data/test/perf_compat.rb +130 -0
  102. data/test/perf_fast.rb +9 -9
  103. data/test/perf_file.rb +64 -0
  104. data/test/{perf_obj.rb → perf_object.rb} +24 -10
  105. data/test/perf_scp.rb +151 -0
  106. data/test/perf_strict.rb +32 -113
  107. data/test/sample.rb +2 -3
  108. data/test/test_compat.rb +474 -0
  109. data/test/test_custom.rb +355 -0
  110. data/test/test_debian.rb +53 -0
  111. data/test/test_fast.rb +66 -16
  112. data/test/test_file.rb +237 -0
  113. data/test/test_gc.rb +49 -0
  114. data/test/test_hash.rb +29 -0
  115. data/test/test_null.rb +376 -0
  116. data/test/test_object.rb +1010 -0
  117. data/test/test_saj.rb +16 -16
  118. data/test/test_scp.rb +417 -0
  119. data/test/test_strict.rb +410 -0
  120. data/test/test_various.rb +815 -0
  121. data/test/test_writer.rb +308 -0
  122. data/test/tests.rb +9 -902
  123. data/test/tests_mimic.rb +14 -0
  124. data/test/tests_mimic_addition.rb +7 -0
  125. metadata +253 -38
  126. data/ext/oj/cache.c +0 -148
  127. data/ext/oj/foo.rb +0 -6
  128. data/ext/oj/load.c +0 -1049
  129. data/test/a.rb +0 -38
  130. data/test/perf1.rb +0 -64
  131. data/test/perf2.rb +0 -76
  132. data/test/perf_obj_old.rb +0 -213
  133. data/test/test_mimic.rb +0 -208
data/pages/Custom.md ADDED
@@ -0,0 +1,23 @@
1
+ # Custom mode
2
+
3
+ The `:custom` mode is the most configurable mode and honors almost all
4
+ options. It provides the most flexibility although it can not be configured to
5
+ be exactly like any of the other modes. Each mode has some special aspect that
6
+ makes it unique. For example, the `:object` mode has it's own unique format
7
+ for object dumping and loading. The `:compat` mode mimic the json gem
8
+ including methods called for encoding and inconsistencies between
9
+ `JSON.dump()`, `JSON.generate()`, and `JSON()`.
10
+
11
+ The `:custom` mode is the default mode. It can be configured either by passing
12
+ options to the `Oj.dump()` and `Oj.load()` methods or by modifying the default
13
+ options.
14
+
15
+ The ability to create objects from JSON object elements is supported and
16
+ considers the `:create_additions` option. Special treatment is given to the
17
+ `:create_id` though. If the `:create_id` is set to `"^o"` then the Oj internal
18
+ encoding and decoding is used. These are more efficient than calling out to a
19
+ `to_json` method or `create_json` method on the classes. Those method do not
20
+ have to exist for the `"^o"` behavior to be utilized. Any other `:create_id`
21
+ value behaves similar to the json gem by calling `to_json` and `create_json`
22
+ as appropriate.
23
+
data/pages/Encoding.md ADDED
@@ -0,0 +1,65 @@
1
+ # Oj `:object` Mode Encoding
2
+
3
+ Object mode is for fast Ruby object serialization and deserialization. That
4
+ was the primary purpose of Oj when it was first developed. As such it is the
5
+ default mode unless changed in the Oj default options. In :object mode Oj
6
+ generates JSON that follows conventions which allow Class and other
7
+ information such as Object IDs for circular reference detection to be encoded
8
+ in a JSON document. The formatting follows these rules.
9
+
10
+ * JSON native types, true, false, nil, String, Hash, Array, and Number are
11
+ encoded normally.
12
+
13
+ * A Symbol is encoded as a JSON string with a preceeding `':'` character.
14
+
15
+ * The `'^'` character denotes a special key value when in a JSON Object sequence.
16
+
17
+ * A Ruby String that starts with `':'`or the sequence `'^i'` or `'^r'` are
18
+ encoded by excaping the first character so that it appears as `'\u005e'` or
19
+ `'\u003a'` instead of `':'` or `'^'`.
20
+
21
+ * A `"^c"` JSON Object key indicates the value should be converted to a Ruby
22
+ class. The sequence `{"^c":"Oj::Bag"}` is read as the Oj::Bag class.
23
+
24
+ * A `"^t"` JSON Object key indicates the value should be converted to a Ruby
25
+ Time. The sequence `{"^t":1325775487.000000}` is read as Jan 5, 2012 at
26
+ 23:58:07.
27
+
28
+ * A `"^o"` JSON Object key indicates the value should be converted to a Ruby
29
+ Object. The first entry in the JSON Object must be a class with the `"^o"`
30
+ key. After that each entry is treated as a variable of the Object where the
31
+ key is the variable name without the preceeding `'@'`. An example is
32
+ `{"^o":"Oj::Bag","x":58,"y":"marbles"}`. `"^O"`is the same except that it
33
+ is for built in or odd classes that don't obey the normal Ruby
34
+ rules. Examples are Rational, Date, and DateTime.
35
+
36
+ * A `"^u"` JSON Object key indicates the value should be converted to a Ruby
37
+ Struct. The first entry in the JSON Object must be a class with the
38
+ `"^u"` key. After that each entry is is given a numeric position in the
39
+ struct and that is used as the key in the JSON Object. An example is
40
+ `{"^u":["Range",1,7,false]}`.
41
+
42
+ * When encoding an Object, if the variable name does not begin with an
43
+ `'@'`character then the name preceeded by a `'~'` character. This occurs in
44
+ the Exception class. An example is `{"^o":"StandardError","~mesg":"A
45
+ Message","~bt":[".\/tests.rb:345:in 'test_exception'"]}`.
46
+
47
+ * If a Hash entry has a key that is not a String or Symbol then the entry is
48
+ encoded with a key of the form `"^#n"` where n is a hex number. The value
49
+ is an Array where the first element is the key in the Hash and the second
50
+ is the value. An example is `{"^#3":[2,5]}`.
51
+
52
+ * A `"^i"` JSON entry in either an Object or Array is the ID of the Ruby
53
+ Object being encoded. It is used when the :circular flag is set. It can
54
+ appear in either a JSON Object or in a JSON Array. In an Object the
55
+ `"^i"` key has a corresponding reference Fixnum. In an array the sequence
56
+ will include an embedded reference number. An example is
57
+ `{"^o":"Oj::Bag","^i":1,"x":["^i2",true],"me":"^r1"}`.
58
+
59
+ * A `"^r"`JSON entry in an Object is a references to a Object or Array that
60
+ already appears in the JSON String. It must match up with a previous
61
+ `"^i"` ID. An example is `{"^o":"Oj::Bag","^i":1,"x":3,"me":"^r1"}`.
62
+
63
+ * If an Array element is a String and starts with `"^i"` then the first
64
+ character, the `'^'` is encoded as a hex character sequence. An example is
65
+ `["\u005ei37",3]`.
data/pages/JsonGem.md ADDED
@@ -0,0 +1,79 @@
1
+ # Oj JSON Gem Compatibility
2
+
3
+ The `:compat` mode mimics the json gem. The json gem is built around the use
4
+ of the `to_json(*)` method defined for a class. Oj attempts to provide the
5
+ same functionality by being a drop in replacement for the 2.0.x version of the
6
+ json gem with a few exceptions. First a description of the json gem behavior
7
+ and then the differences between the json gem and the Oj.mimic_JSON behavior.
8
+
9
+ ```ruby
10
+ require 'oj'
11
+
12
+ Oj.mimic_JSON()
13
+ Oj.add_to_json(Array, BigDecimal, Complex, Date, DateTime, Exception, Hash, Integer, OpenStruct, Range, Rational, Regexp, Struct, Time)
14
+ # Alternativel just call without arguments to add all available.
15
+ # Oj.add_to_json()
16
+ ```
17
+
18
+ The json gem monkey patches core and base library classes with a `to_json(*)`
19
+ method. This allows calls such as `obj.to_json()` to be used to generate a
20
+ JSON string. The json gem also provides the JSON.generate(), JSON.dump(), and
21
+ JSON() functions. These functions generally act the same with some exceptions
22
+ such as JSON.generate(), JSON(), and to_json raise an exception when
23
+ attempting to encode infinity while JSON.dump() returns a the string
24
+ "Infinity". The String class is also monkey patched with to_json_raw() and
25
+ to_json_raw_object(). Oj in mimic mode mimics this behavior including the
26
+ seemly inconsistent behavior with NaN and Infinity.
27
+
28
+ Any class can define a to_json() method and JSON.generate(), JSON.dump(), and
29
+ JSON() functions will call that method when an object of that type is
30
+ encountered when traversing a Hash or Array. The core classes monkey patches
31
+ can be over-ridden but unless the to_json() method is called directory the
32
+ to_json() method will be ignored. Oj in mimic mode follow the same logic,
33
+
34
+ The json gem includes additions. These additions change the behavior of some
35
+ library and core classes. These additions also add the as_json() method and
36
+ json_create() class method. They are activated by requiring the appropriate
37
+ files. As an example, to get the modified to_json() for the Rational class
38
+ this line would be added.
39
+
40
+ ```ruby
41
+ require 'json/add/rational'
42
+ ```
43
+
44
+ Oj in mimic mode does not include these files although it will support the
45
+ modified to_json() methods. In keeping with the goal of providing a faster
46
+ encoder Oj offers an alternative. To activate faster addition version of the
47
+ to_json() method call
48
+
49
+ ```ruby
50
+ Oj.add_to_json(Rational)
51
+ ```
52
+
53
+ To revert back to the unoptimized version, just remove the Oj flag on that
54
+ class.
55
+
56
+ ```ruby
57
+ Oj.remove_to_json(Rational)
58
+ ```
59
+
60
+ The classes that can be added are:
61
+
62
+ * Array
63
+ * BigDecimal
64
+ * Complex
65
+ * Date
66
+ * DateTime
67
+ * Exception
68
+ * Hash
69
+ * Integer
70
+ * OpenStruct
71
+ * Range
72
+ * Rational
73
+ * Regexp
74
+ * Struct
75
+ * Time
76
+
77
+ The compatibility target version is 2.0.3. The json gem unit tests were used
78
+ to verify compatibility with a few changes to use Oj instead of the original
79
+ gem.
data/pages/Modes.md ADDED
@@ -0,0 +1,140 @@
1
+ # Oj Modes
2
+
3
+ Oj uses modes to switch the load and dump behavior. Initially Oj supported on
4
+ the :object mode which uses a format that allows Juby object encoding and
5
+ decoding in a manner that lets almost any Ruby object be encoded and decoded
6
+ without monkey patching the object classes. From that start other demands were
7
+ made the were best met by giving Oj multiple modes of operation. The current
8
+ modes are:
9
+
10
+ - `:strict`
11
+ - `:null`
12
+ - `:compat` or `:json`
13
+ - `:rails`
14
+ - `:object`
15
+ - `:custom`
16
+
17
+ Since modes detemine what the JSON output will look like and alternatively
18
+ what Oj expects when the `Oj.load()` method is called, mixing the output and
19
+ input mode formats will most likely not behave as intended. If the object mode
20
+ is used for producing JSON then use object mode for reading. The same is true
21
+ for each mode. It is possible to mix but only for advanced users.
22
+
23
+ ## :strict Mode
24
+
25
+ Strict mode follows the JSON specifications and only supports the JSON native
26
+ types, Boolean, nil, String, Hash, Array, and Numbers are encoded as
27
+ expected. Encountering any other type causes an Exception to be raised. This
28
+ is the safest mode as it is just simple translation, no code outside Oj or the
29
+ core Ruby is execution on loading. Very few options are supported by this mode
30
+ other than formatting options.
31
+
32
+ ## :null Mode
33
+
34
+ Null mode is similar to the :strict mode except that a JSON null is inserted
35
+ if a non-native type is encountered instead of raising an Exception.
36
+
37
+ ## :compat or :json Mode
38
+
39
+ The `:compat` mode mimics the json gem. The json gem is built around the use
40
+ of the `to_json(*)` method defined for a class. Oj attempts to provide the
41
+ same functionality by being a drop in replacement with a few
42
+ exceptions. [{file:JsonGem.md}](pages/JsonGem.md) includes more details on
43
+ compatibility and use.
44
+
45
+ ## :rails Mode
46
+
47
+ The `:rails` mode mimics the ActiveSupport version 5 encoder. Rails and
48
+ ActiveSupport are built around the use of the `as_json(*)` method defined for
49
+ a class. Oj attempts to provide the same functionality by being a drop in
50
+ replacement with a few exceptions. [{file:Rails.md}](pages/Rails.md) includes
51
+ more details on compatibility and use.
52
+
53
+ ## :object Mode
54
+
55
+ Object mode is for fast Ruby object serialization and deserialization. That
56
+ was the primary purpose of Oj when it was first developed. As such it is the
57
+ default mode unless changed in the Oj default options. In :object mode Oj
58
+ generates JSON that follows conventions which allow Class and other
59
+ information such as Object IDs for circular reference detection to be encoded
60
+ in a JSON document. The formatting follows the rules describe on the
61
+ [{file:Encoding.md}](pages/Encoding.md) page.
62
+
63
+ ## :custom Mode
64
+
65
+ Custom mode honors all options. It provides the most flexibility although it
66
+ can not be configured to be exactly like any of the other modes. Each mode has
67
+ some special aspect that makes it unique. For example, the `:object` mode has
68
+ it's own unique format for object dumping and loading. The `:compat` mode
69
+ mimic the json gem including methods called for encoding and inconsistencies
70
+ between `JSON.dump()`, `JSON.generate()`, and `JSON()`. More details on the
71
+ [{file:Custom.md}](pages/Custom.md) page.
72
+
73
+ ## Options Matrix
74
+
75
+ Not all options are available in all modes. The options matrix identifies the
76
+ options available in each mode. An `x` in the matrix indicates the option is
77
+ supported in that mode. A number indicates the footnotes describe additional
78
+ information.
79
+
80
+ | Option | type | :null | :strict | :compat | :rails | :object | :custom |
81
+ | ---------------------- | ------- | ------- | ------- | ------- | ------- | ------- | ------- |
82
+ | :allow_blank | Boolean | | | 1 | 1 | | x |
83
+ | :allow_gc | Boolean | x | x | x | x | x | x |
84
+ | :allow_invalid_unicode | Boolean | | | | | x | x |
85
+ | :allow_nan | Boolean | | | x | | x | x |
86
+ | :array_class | Class | | | x | x | | x |
87
+ | :array_nl | String | | | | | | x |
88
+ | :ascii_only | Boolean | x | x | 2 | 2 | x | x |
89
+ | :auto_define | Boolean | | | | | x | x |
90
+ | :bigdecimal_as_decimal | Boolean | | | | | x | x |
91
+ | :bigdecimal_load | Boolean | | | | | | x |
92
+ | :circular | Boolean | x | x | x | x | x | x |
93
+ | :class_cache | Boolean | | | | | x | x |
94
+ | :create_additions | Boolean | | | x | x | | x |
95
+ | :create_id | String | | | x | x | | x |
96
+ | :empty_string | Boolean | | | | | | x |
97
+ | :escape_mode | Symbol | | | | | | x |
98
+ | :float_precision | Fixnum | x | x | | | | x |
99
+ | :hash_class | Class | | | x | x | | x |
100
+ | :indent | Integer | x | x | 3 | 3 | x | x |
101
+ | :indent_str | String | | | x | x | | x |
102
+ | :match_string | Hash | | | x | x | | x |
103
+ | :max_nesting | Fixnum | 4 | 4 | x | | 4 | 4 |
104
+ | :mode | Symbol | - | - | - | - | - | - |
105
+ | :nan | Symbol | | | | | | x |
106
+ | :nilnil | Boolean | | | | | | x |
107
+ | :object_class | Class | | | x | | | x |
108
+ | :object_nl | String | | | x | x | | x |
109
+ | :omit_nil | Boolean | x | x | x | x | x | x |
110
+ | :quirks_mode | Boolean | | | 5 | | | x |
111
+ | :second_precision | Fixnum | | | | | x | x |
112
+ | :space | String | | | x | x | | x |
113
+ | :space_before | String | | | x | x | | x |
114
+ | :symbol_keys | Boolean | x | x | x | x | x | x |
115
+ | :time_format | Symbol | | | | | x | x |
116
+ | :use_as_json | Boolean | | | | | | x |
117
+ | :use_to_hash | Boolean | | | | | | x |
118
+ | :use_to_json | Boolean | | | | | | x |
119
+ ----------------------------------------------------------------------------------------------
120
+
121
+ 1. :allow_blank an alias for :nilnil.
122
+
123
+ 2. The :ascii_only options is an undocumented json gem option.
124
+
125
+ 3. The integer indent value in the default options will be honored by since
126
+ the json gem expects a String type the indent in calls to 'to_json()',
127
+ 'Oj.generate()', or 'Oj.generate_fast()' expect a String and not an
128
+ integer.
129
+
130
+ 4. The max_nesting option is for the json gem and rails only. It exists for
131
+ compatibility. For other Oj dump modes the maximum nesting is set to over
132
+ 1000. If reference loops exist in the object being dumped then using the
133
+ `:circular` option is a far better choice. It adds a slight overhead but
134
+ detects an object that appears more than once in a dump and does not dump
135
+ that object a second time.
136
+
137
+ 5. The quirks mode option is no longer supported in the most recent json
138
+ gem. It is supported by Oj for backward compatibility with older json gem
139
+ versions.
140
+
data/pages/Options.md ADDED
@@ -0,0 +1,250 @@
1
+ # Oj Options
2
+
3
+ To change default serialization mode use the following form. Attempting to
4
+ modify the Oj.default_options Hash directly will not set the changes on the
5
+ actual default options but on a copy of the Hash:
6
+
7
+ ```ruby
8
+ Oj.default_options = {:mode => :compat }
9
+ ```
10
+
11
+ Another way to make use of options when calling load or dump methods is to
12
+ pass in a Hash with the options already set in the Hash. This is slightly less
13
+ efficient than setting the globals for many smaller JSON documents but does
14
+ provide a more thread safe approach to using custom options for loading and
15
+ dumping.
16
+
17
+ ### Options for serializer and parser
18
+
19
+ ### :allow_blank [Boolean]
20
+
21
+ If true a nil input to load will return nil and not raise an Exception.
22
+
23
+ ### :allow_gc [Boolean]
24
+
25
+ Allow or prohibit GC during parsing, default is true (allow).
26
+
27
+ ### :allow_invalid_unicode [Boolean]
28
+
29
+ Allow invalid unicode, default is false (don't allow).
30
+
31
+ ### :allow_nan
32
+
33
+ Alias for the :nan option.
34
+
35
+ ### :array_class [Class]
36
+
37
+ Class to use instead of Array on load.
38
+
39
+ ### :array_nl
40
+
41
+ Trailer appended to the end of an array dump. The default is an empty
42
+ string. Primarily intended for json gem compatibility. Using just indent as an
43
+ integer gives better performance.
44
+
45
+ ### :ascii_only
46
+
47
+ If true all non-ASCII character are escaped when dumping. This is the same as
48
+ setting the :escape_mode options to :ascii and exists for json gem
49
+ compatibility.
50
+
51
+ ### :auto_define [Boolean]
52
+
53
+ Automatically define classes if they do not exist.
54
+
55
+ ### :bigdecimal_as_decimal [Boolean]
56
+
57
+ If true dump BigDecimal as a decimal number otherwise as a String
58
+
59
+ ### :bigdecimal_load [Symbol]
60
+
61
+ Determines how to load decimals.
62
+
63
+ - `:bigdecimal` convert all decimal numbers to BigDecimal.
64
+
65
+ - `:float` convert all decimal numbers to Float.
66
+
67
+ - `:auto` the most precise for the number of digits is used.
68
+
69
+ ### :circular [Boolean]
70
+
71
+ Detect circular references while dumping. In :compat mode raise a
72
+ NestingError. For other modes except the :object mode place a null in the
73
+ output. For :object mode place references in the output that will be used to
74
+ recreate the looped references on load.
75
+
76
+ ### :class_cache [Boolean]
77
+
78
+ Cache classes for faster parsing. This option should not be used if
79
+ dynamically modifying classes or reloading classes then don't use this.
80
+
81
+ ### :create_additions
82
+
83
+ A flag indicating the :create_id key when encounterd during parsing should
84
+ creating an Object mactching the class name specified in the value associated
85
+ with the key.
86
+
87
+ ### :create_id [String]
88
+
89
+ The :create_id option specifies that key is used for dumping and loading when
90
+ specifying the class for an encoded object. The default is `json_create`.
91
+
92
+ ### :empty_string [Boolean]
93
+
94
+ If true an empty input will not raise an Exception. The default differs
95
+ according to the mode and in some cases the function used to load or dump. The
96
+ defaults are:
97
+
98
+ - :null - true
99
+ - :strict - true
100
+ - :compat or :json - true
101
+ - JSON.parse() - false
102
+ - JSON.load() - true (or what ever is set in the defaults)
103
+ - :rails - TBD
104
+ - :object - true
105
+ - :custom - true
106
+
107
+ ### :escape_mode [Symbol]
108
+
109
+ Determines the characters to escape when dumping. Only the :ascii and
110
+ :json modes are supported in :compat mode.
111
+
112
+ - `:newline` allows unescaped newlines in the output.
113
+
114
+ - `:json` follows the JSON specification. This is the default mode.
115
+
116
+ - `:xss_safe` escapes HTML and XML characters such as `&` and `<`.
117
+
118
+ - `:ascii` escapes all non-ascii or characters with the hi-bit set.
119
+
120
+ - `:unicode_xss` escapes a special unicodes and is xss safe.
121
+
122
+ ### :float_precision [Fixnum]
123
+
124
+ The number of digits of precision when dumping floats, 0 indicates use Ruby directly.
125
+
126
+ ### :hash_class [Class]
127
+
128
+ Class to use instead of Hash on load. This is the same as the :object_class.
129
+
130
+ ### :indent [Fixnum]
131
+
132
+ Number of spaces to indent each element in a JSON document, zero is no newline
133
+ between JSON elements, negative indicates no newline between top level JSON
134
+ elements in a stream.
135
+
136
+ ### :indent_str
137
+
138
+ Indentation for each element when dumping. The default is an empty
139
+ string. Primarily intended for json gem compatibility. Using just indent as an
140
+ integer gives better performance.
141
+
142
+ ### :match_string
143
+
144
+ Provides a means to detect strings that should be used to create non-String
145
+ objects. The value to the option must be a Hash with keys that are regular
146
+ expressions and values are class names. For strict json gem compatibility a
147
+ RegExp should be used. For better performance but sacrificing some regexp
148
+ options a string can be used and the C version of regex will be used instead.
149
+
150
+ ### :max_nesting
151
+
152
+ The maximum nesting depth on both dump and load that is allowed. This exists
153
+ for json gem compatibility.
154
+
155
+ ### :mode [Symbol]
156
+
157
+ Primary behavior for loading and dumping. The :mode option controls which
158
+ other options are in effect. For more details see the {file:Modes.md} page. By
159
+ default Oj uses the :custom mode which is provides the highest degree of
160
+ customization.
161
+
162
+ ### :nan [Symbol]
163
+
164
+ How to dump Infinity, -Infinity, and NaN in :null, :strict, and :compat
165
+ mode. Default is :auto but is ignored in the :compat and :rails mode.
166
+
167
+ - `:null` places a null
168
+
169
+ - `:huge` places a huge number
170
+
171
+ - `:word` places Infinity or NaN
172
+
173
+ - `:raise` raises and exception
174
+
175
+ - `:auto` uses default for each mode which are `:raise` for `:strict`, `:null` for `:null`, and `:word` for `:compat`.
176
+
177
+ ### :nilnil [Boolean]
178
+
179
+ If true a nil input to load will return nil and not raise an Exception.
180
+
181
+ ### :object_class
182
+
183
+ The class to use when creating a Hash on load instead of the Hash class.
184
+
185
+ ### :object_nl
186
+
187
+ Trailer appended to the end of an object dump. The default is an empty
188
+ string. Primarily intended for json gem compatibility. Using just indent as an
189
+ integer gives better performance.
190
+
191
+ ### :omit_nil [Boolean]
192
+
193
+ If true, Hash and Object attributes with nil values are omitted.
194
+
195
+ ### :quirks_mode [Boolean]
196
+
197
+ Allow single JSON values instead of documents, default is true (allow). This
198
+ can also be used in :compat mode to be backward compatible with older versions
199
+ of the json gem.
200
+
201
+ ### :second_precision [Fixnum]
202
+
203
+ The number of digits after the decimal when dumping the seconds of time.
204
+
205
+ ### :space
206
+
207
+ String inserted after the ':' character when dumping a JSON object. The
208
+ default is an empty string. Primarily intended for json gem
209
+ compatibility. Using just indent as an integer gives better performance.
210
+
211
+ ### :space_before
212
+
213
+ String inserted before the ':' character when dumping a JSON object. The
214
+ default is an empty string. Primarily intended for json gem
215
+ compatibility. Using just indent as an integer gives better performance.
216
+
217
+ ### :symbol_keys [Boolean]
218
+
219
+ Use symbols instead of strings for hash keys. :symbolize_names is an alias.
220
+
221
+ ### :time_format [Symbol]
222
+
223
+ The :time_format when dumping.
224
+
225
+ - `:unix` time is output as a decimal number in seconds since epoch including fractions of a second.
226
+
227
+ - `:unix_zone` similar to the `:unix` format but with the timezone encoded in
228
+ the exponent of the decimal number of seconds since epoch.
229
+
230
+ - `:xmlschema` time is output as a string that follows the XML schema definition.
231
+
232
+ - `:ruby` time is output as a string formatted using the Ruby `to_s` conversion.
233
+
234
+ ### :use_as_json [Boolean]
235
+
236
+ Call `as_json()` methods on dump, default is false. The option is ignored in
237
+ the :compat and :rails mode.
238
+
239
+ ### :use_to_hash [Boolean]
240
+
241
+ Call `to_hash()` methods on dump, default is false. The option is ignored in
242
+ the :compat and :rails mode.
243
+
244
+ ### :use_to_json [Boolean]
245
+
246
+ Call `to_json()` methods on dump, default is false. The option is ignored in
247
+ the :compat and :rails mode.
248
+
249
+
250
+
data/pages/Rails.md ADDED
@@ -0,0 +1,60 @@
1
+ # Oj Rails Compatibility
2
+
3
+ The `:rails` mode mimics the ActiveSupport version 5 encoder. Rails and
4
+ ActiveSupport are built around the use of the `as_json(*)` method defined for
5
+ a class. Oj attempts to provide the same functionality by being a drop in
6
+ replacement with a few exceptions.
7
+
8
+ ```ruby
9
+ require 'oj'
10
+
11
+ Oj::Rails.set_encoder()
12
+ Oj::Rails.set_decoder()
13
+ Oj::Rails.optimize(Array, BigDecimal, Hash, Range, Regexp, Time)
14
+ ```
15
+
16
+ Some of the Oj options are supported as arguments to the encoder if called
17
+ from Oj::Rails.encode() but when using the Oj::Rails::Encoder class the
18
+ encode() method does not support optional arguments as required by the
19
+ ActiveSupport compliance guidelines. The general approach Rails takes for
20
+ configuring encoding options is to either set global values or to create a new
21
+ instance of the Encoder class and provide options in the initializer.
22
+
23
+ The globals that ActiveSupport uses for encoding are:
24
+
25
+ * ActiveSupport::JSON::Encoding.use_standard_json_time_format
26
+ * ActiveSupport::JSON::Encoding.escape_html_entities_in_json
27
+ * ActiveSupport::JSON::Encoding.time_precision
28
+ * ActiveSupport::JSON::Encoding.json_encoder
29
+
30
+ Those globals are aliased to also be accessed from the ActiveSupport module
31
+ directly so ActiveSupport::JSON::Encoding.time_precision can also be accessed
32
+ from ActiveSupport.time_precision. Oj makes use of these globals in mimicing
33
+ Rails after the Oj::Rails.set_encode() method is called. That also sets the
34
+ ActiveSupport.json_encoder to the Oj::Rails::Encoder class.
35
+
36
+ Options passed into a call to to_json() are passed to the as_json()
37
+ methods. These are mostly ignored by Oj and simply passed on without
38
+ modifications as per the guidelines. The exception to this are the options
39
+ specific to Oj such as the :circular option which it used to detect circular
40
+ references while encoding.
41
+
42
+ By default Oj acts like the ActiveSupport encoder and honors any changes in
43
+ the as_json() methods. There are also optimized encoders for some
44
+ classes. When the optimized encoder it toggled the as_json() methods will not
45
+ be called for that class but instead the optimized version will be called. The
46
+ optimized version is the same as the ActiveSupport default encoding for a
47
+ given class. The optimized versions are toggled with the optimize() and
48
+ deoptimize() methods.
49
+
50
+ The classes that can be put in optimized mode are:
51
+
52
+ * Array
53
+ * BigDecimal
54
+ * Hash
55
+ * Range
56
+ * Regexp
57
+ * Time
58
+
59
+ The ActiveSupport decoder is the JSON.parse() method. Calling the
60
+ Oj::Rails.set_decoder() method replaces that method with the Oj equivelant.
data/pages/Security.md ADDED
@@ -0,0 +1,20 @@
1
+ # Security and Optimization
2
+
3
+ Two settings in Oj are useful for parsing but do expose a vulnerability if used
4
+ from an untrusted source. Symbolized keys can cause memory to be filled with
5
+ previous versions of ruby. Ruby 2.1 and below does not garbage collect
6
+ Symbols. The same is true for auto defining classes in all versions of ruby;
7
+ memory will also be exhausted if too many classes are automatically
8
+ defined. Auto defining is a useful feature during development and from trusted
9
+ sources but it allows too many classes to be created in the object load mode and
10
+ auto defined is used with an untrusted source. The `Oj.strict_load()` method
11
+ sets and uses the most strict and safest options. It should be used by
12
+ developers who find it difficult to understand the options available in Oj.
13
+
14
+ The options in Oj are designed to provide flexibility to the developer. This
15
+ flexibility allows Objects to be serialized and deserialized. No methods are
16
+ ever called on these created Objects but that does not stop the developer from
17
+ calling methods on them. As in any system, check your inputs before working with
18
+ them. Taking an arbitrary `String` from a user and evaluating it is never a good
19
+ idea from an unsecure source. The same is true for `Object` attributes as they
20
+ are not more than `String`s. Always check inputs from untrusted sources.