oj 3.8.1

data/pages/JsonGem.md

@@ -0,0 +1,79 @@
+# Oj JSON Gem Compatibility
+
+The `:compat` mode mimics the json gem. The json gem is built around the use
+of the `to_json(*)` method defined for a class. Oj attempts to provide the
+same functionality by being a drop in replacement for the 2.0.x version of the
+json gem with a few exceptions. First a description of the json gem behavior
+and then the differences between the json gem and the Oj.mimic_JSON behavior.
+
+```ruby
+require 'oj'
+
+Oj.mimic_JSON()
+Oj.add_to_json(Array, BigDecimal, Complex, Date, DateTime, Exception, Hash, Integer, OpenStruct, Range, Rational, Regexp, Struct, Time)
+# Alternativel just call without arguments to add all available.
+# Oj.add_to_json()
+```
+
+The json gem monkey patches core and base library classes with a `to_json(*)`
+method. This allows calls such as `obj.to_json()` to be used to generate a
+JSON string. The json gem also provides the JSON.generate(), JSON.dump(), and
+JSON() functions. These functions generally act the same with some exceptions
+such as JSON.generate(), JSON(), and to_json raise an exception when
+attempting to encode infinity while JSON.dump() returns a the string
+"Infinity". The String class is also monkey patched with to_json_raw() and
+to_json_raw_object(). Oj in mimic mode mimics this behavior including the
+seemly inconsistent behavior with NaN and Infinity.
+
+Any class can define a to_json() method and JSON.generate(), JSON.dump(), and
+JSON() functions will call that method when an object of that type is
+encountered when traversing a Hash or Array. The core classes monkey patches
+can be over-ridden but unless the to_json() method is called directory the
+to_json() method will be ignored. Oj in mimic mode follow the same logic,
+
+The json gem includes additions. These additions change the behavior of some
+library and core classes. These additions also add the as_json() method and
+json_create() class method. They are activated by requiring the appropriate
+files. As an example, to get the modified to_json() for the Rational class
+this line would be added.
+
+```ruby
+require 'json/add/rational'
+```
+
+Oj in mimic mode does not include these files although it will support the
+modified to_json() methods. In keeping with the goal of providing a faster
+encoder Oj offers an alternative. To activate faster addition version of the
+to_json() method call
+
+```ruby
+Oj.add_to_json(Rational)
+```
+
+To revert back to the unoptimized version, just remove the Oj flag on that
+class.
+
+```ruby
+Oj.remove_to_json(Rational)
+```
+
+The classes that can be added are:
+
+ * Array
+ * BigDecimal
+ * Complex
+ * Date
+ * DateTime
+ * Exception
+ * Hash
+ * Integer
+ * OpenStruct
+ * Range
+ * Rational
+ * Regexp
+ * Struct
+ * Time
+
+The compatibility target version is 2.0.3. The json gem unit tests were used
+to verify compatibility with a few changes to use Oj instead of the original
+gem.

data/pages/Modes.md

@@ -0,0 +1,155 @@
+# Oj Modes
+
+Oj uses modes to switch the load and dump behavior. Initially Oj supported on
+the :object mode which uses a format that allows Ruby object encoding and
+decoding in a manner that lets almost any Ruby object be encoded and decoded
+without monkey patching the object classes. From that start other demands were
+made the were best met by giving Oj multiple modes of operation. The current
+modes are:
+
+ - `:strict`
+ - `:null`
+ - `:compat` or `:json`
+ - `:rails`
+ - `:object`
+ - `:custom`
+
+Since modes determine what the JSON output will look like and alternatively
+what Oj expects when the `Oj.load()` method is called, mixing the output and
+input mode formats will most likely not behave as intended. If the object mode
+is used for producing JSON then use object mode for reading. The same is true
+for each mode. It is possible to mix but only for advanced users.
+
+## :strict Mode
+
+Strict mode follows the JSON specifications and only supports the JSON native
+types, Boolean, nil, String, Hash, Array, and Numbers are encoded as
+expected. Encountering any other type causes an Exception to be raised. This
+is the safest mode as it is just simple translation, no code outside Oj or the
+core Ruby is execution on loading. Very few options are supported by this mode
+other than formatting options.
+
+## :null Mode
+
+Null mode is similar to the :strict mode except that a JSON null is inserted
+if a non-native type is encountered instead of raising an Exception.
+
+## :compat or :json Mode
+
+The `:compat` mode mimics the json gem. The json gem is built around the use
+of the `to_json(*)` method defined for a class. Oj attempts to provide the
+same functionality by being a drop in replacement with a few
+exceptions. [{file:JsonGem.md}](JsonGem.md) includes more details on
+compatibility and use.
+
+## :rails Mode
+
+The `:rails` mode mimics the ActiveSupport version 5 encoder. Rails and
+ActiveSupport are built around the use of the `as_json(*)` method defined for
+a class. Oj attempts to provide the same functionality by being a drop in
+replacement with a few exceptions. [{file:Rails.md}](Rails.md) includes
+more details on compatibility and use.
+
+## :object Mode
+
+Object mode is for fast Ruby object serialization and deserialization. That
+was the primary purpose of Oj when it was first developed. As such it is the
+default mode unless changed in the Oj default options. In :object mode Oj
+generates JSON that follows conventions which allow Class and other
+information such as Object IDs for circular reference detection to be encoded
+in a JSON document. The formatting follows the rules describe on the
+[{file:Encoding.md}](Encoding.md) page.
+
+## :custom Mode
+
+Custom mode honors all options. It provides the most flexibility although it
+can not be configured to be exactly like any of the other modes. Each mode has
+some special aspect that makes it unique. For example, the `:object` mode has
+it's own unique format for object dumping and loading. The `:compat` mode
+mimic the json gem including methods called for encoding and inconsistencies
+between `JSON.dump()`, `JSON.generate()`, and `JSON()`. More details on the
+[{file:Custom.md}](Custom.md) page.
+
+## :wab Mode
+
+WAB mode ignores all options except the indent option. Performance of this
+mode is on slightly better than the :strict and :null modes. It is included to
+support the [WABuR](https://github.com/ohler55/wabur) project. More details on
+the [{file:WAB.md}](WAB.md) page.
+
+## Options Matrix
+
+Not all options are available in all modes. The options matrix identifies the
+options available in each mode. An `x` in the matrix indicates the option is
+supported in that mode. A number indicates the footnotes describe additional
+information.
+
+| Option                 | type    | :null   | :strict | :compat | :rails  | :object | :custom |  :wab   |
+| ---------------------- | ------- | ------- | ------- | ------- | ------- | ------- | ------- | ------- |
+| :allow_blank           | Boolean |         |         |       1 |       1 |         |       x |         |
+| :allow_gc              | Boolean |       x |       x |       x |       x |       x |       x |         |
+| :allow_invalid_unicode | Boolean |         |         |         |         |       x |       x |         |
+| :allow_nan             | Boolean |         |         |       x |         |       x |       x |         |
+| :array_class           | Class   |         |         |       x |       x |         |       x |         |
+| :array_nl              | String  |         |         |         |         |         |       x |         |
+| :ascii_only            | Boolean |       x |       x |       2 |       2 |       x |       x |         |
+| :auto_define           | Boolean |         |         |         |         |       x |       x |         |
+| :bigdecimal_as_decimal | Boolean |         |         |         |       3 |       x |       x |         |
+| :bigdecimal_load       | Boolean |         |         |         |         |         |       x |         |
+| :circular              | Boolean |       x |       x |       x |       x |       x |       x |         |
+| :class_cache           | Boolean |         |         |         |         |       x |       x |         |
+| :create_additions      | Boolean |         |         |       x |       x |         |       x |         |
+| :create_id             | String  |         |         |       x |       x |         |       x |         |
+| :empty_string          | Boolean |         |         |         |         |         |       x |         |
+| :escape_mode           | Symbol  |         |         |         |         |         |       x |         |
+| :float_precision       | Fixnum  |       x |       x |         |         |         |       x |         |
+| :hash_class            | Class   |         |         |       x |       x |         |       x |         |
+| :ignore                | Array   |         |         |         |         |       x |       x |         |
+| :indent                | Integer |       x |       x |       3 |       4 |       x |       x |       x |
+| :indent_str            | String  |         |         |       x |       x |         |       x |         |
+| :integer_range         | Range   |       x |       x |       x |       x |       x |       x |       x |
+| :match_string          | Hash    |         |         |       x |       x |         |       x |         |
+| :max_nesting           | Fixnum  |       4 |       4 |       x |         |       5 |       4 |         |
+| :mode                  | Symbol  |       - |       - |       - |       - |       - |       - |         |
+| :nan                   | Symbol  |         |         |         |         |         |       x |         |
+| :nilnil                | Boolean |         |         |         |         |         |       x |         |
+| :object_class          | Class   |         |         |       x |         |         |       x |         |
+| :object_nl             | String  |         |         |       x |       x |         |       x |         |
+| :omit_nil              | Boolean |       x |       x |       x |       x |       x |       x |         |
+| :quirks_mode           | Boolean |         |         |       6 |         |         |       x |         |
+| :safe                  | String  |         |         |       x |         |         |         |         |
+| :second_precision      | Fixnum  |         |         |         |         |       x |       x |         |
+| :space                 | String  |         |         |       x |       x |         |       x |         |
+| :space_before          | String  |         |         |       x |       x |         |       x |         |
+| :symbol_keys           | Boolean |       x |       x |       x |       x |       x |       x |         |
+| :trace                 | Boolean |       x |       x |       x |       x |       x |       x |       x |
+| :time_format           | Symbol  |         |         |         |         |       x |       x |         |
+| :use_as_json           | Boolean |         |         |         |         |         |       x |         |
+| :use_raw_json          | Boolean |         |         |       x |       x |       x |       x |         |
+| :use_to_hash           | Boolean |         |         |         |         |         |       x |         |
+| :use_to_json           | Boolean |         |         |         |         |         |       x |         |
+ --------------------------------------------------------------------------------------------------------
+
+ 1. :allow_blank an alias for :nilnil.
+
+ 2. The :ascii_only options is an undocumented json gem option.
+
+ 3. By default the bigdecimal_as decimal is not set and the default encoding
+    for Rails is as a string. Setting the value to true will encode a
+    BigDecimal as a number which breaks compatibility.
+
+ 4. The integer indent value in the default options will be honored by since
+    the json gem expects a String type the indent in calls to 'to_json()',
+    'Oj.generate()', or 'Oj.generate_fast()' expect a String and not an
+    integer.
+
+ 5. The max_nesting option is for the json gem and rails only. It exists for
+    compatibility. For other Oj dump modes the maximum nesting is set to over
+    1000. If reference loops exist in the object being dumped then using the
+    `:circular` option is a far better choice. It adds a slight overhead but
+    detects an object that appears more than once in a dump and does not dump
+    that object a second time.
+
+ 6. The quirks mode option is no longer supported in the most recent json
+    gem. It is supported by Oj for backward compatibility with older json gem
+    versions.

data/pages/Options.md

@@ -0,0 +1,283 @@
+# Oj Options
+
+To change default serialization mode use the following form. Attempting to
+modify the Oj.default_options Hash directly will not set the changes on the
+actual default options but on a copy of the Hash:
+
+```ruby
+Oj.default_options = {:mode => :compat }
+```
+
+Another way to make use of options when calling load or dump methods is to
+pass in a Hash with the options already set in the Hash. This is slightly less
+efficient than setting the globals for many smaller JSON documents but does
+provide a more thread safe approach to using custom options for loading and
+dumping.
+
+### Options for serializer and parser
+
+### :allow_blank [Boolean]
+
+If true a nil input to load will return nil and not raise an Exception.
+
+### :allow_gc [Boolean]
+
+Allow or prohibit GC during parsing, default is true (allow).
+
+### :allow_invalid_unicode [Boolean]
+
+Allow invalid unicode, default is false (don't allow).
+
+### :allow_nan
+
+Alias for the :nan option.
+
+### :array_class [Class]
+
+Class to use instead of Array on load.
+
+### :array_nl
+
+Trailer appended to the end of an array dump. The default is an empty
+string. Primarily intended for json gem compatibility. Using just indent as an
+integer gives better performance.
+
+### :ascii_only
+
+If true all non-ASCII character are escaped when dumping. This is the same as
+setting the :escape_mode options to :ascii and exists for json gem
+compatibility.
+
+### :auto_define [Boolean]
+
+Automatically define classes if they do not exist.
+
+### :bigdecimal_as_decimal [Boolean]
+
+If true dump BigDecimal as a decimal number otherwise as a String
+
+### :bigdecimal_load [Symbol]
+
+Determines how to load decimals.
+
+ - `:bigdecimal` convert all decimal numbers to BigDecimal.
+
+ - `:float` convert all decimal numbers to Float.
+
+ - `:auto` the most precise for the number of digits is used.
+
+### :circular [Boolean]
+
+Detect circular references while dumping. In :compat mode raise a
+NestingError. For other modes except the :object mode place a null in the
+output. For :object mode place references in the output that will be used to
+recreate the looped references on load.
+
+### :class_cache [Boolean]
+
+Cache classes for faster parsing. This option should not be used if
+dynamically modifying classes or reloading classes then don't use this.
+
+### :create_additions
+
+A flag indicating the :create_id key when encountered during parsing should
+creating an Object mactching the class name specified in the value associated
+with the key.
+
+### :create_id [String]
+
+The :create_id option specifies that key is used for dumping and loading when
+specifying the class for an encoded object. The default is `json_create`.
+
+### :empty_string [Boolean]
+
+If true an empty or all whitespace input will not raise an Exception. The
+default_options will be honored for :null, :strict, and :custom modes. Ignored
+for :custom and :wab. The :compat has a more complex set of rules. The JSON
+gem compatibility is best described by examples.
+
+```
+JSON.parse('') => raise
+JSON.parse(' ') => raise
+JSON.load('') => nil
+JSON.load('', nil, allow_blank: false) => raise
+JSON.load('', nil, allow_blank: true) => nil
+JSON.load(' ') => raise
+JSON.load(' ', nil, allow_blank: false) => raise
+JSON.load(' ', nil, allow_blank: true) => raise
+```
+
+### :escape_mode [Symbol]
+
+Determines the characters to escape when dumping. Only the :ascii and
+:json modes are supported in :compat mode.
+
+ - `:newline` allows unescaped newlines in the output.
+
+ - `:json` follows the JSON specification. This is the default mode.
+
+ - `:xss_safe` escapes HTML and XML characters such as `&` and `<`.
+
+ - `:ascii` escapes all non-ascii or characters with the hi-bit set.
+
+ - `:unicode_xss` escapes a special unicodes and is xss safe.
+
+### :float_precision [Fixnum]
+
+The number of digits of precision when dumping floats, 0 indicates use Ruby directly.
+
+### :hash_class [Class]
+
+Class to use instead of Hash on load. This is the same as the :object_class.
+
+### :ignore [Array]
+
+Ignore all the classes in the Array when dumping. A value of nil indicates
+ignore nothing.
+
+### :indent [Fixnum]
+
+Number of spaces to indent each element in a JSON document, zero is no newline
+between JSON elements, negative indicates no newline between top level JSON
+elements in a stream.
+
+### :indent_str
+
+Indentation for each element when dumping. The default is an empty
+string. Primarily intended for json gem compatibility. Using just indent as an
+integer gives better performance.
+
+### :integer_range [Range]
+
+Dump integers outside range as strings.
+Note: range bounds must be Fixnum.
+
+### :match_string
+
+Provides a means to detect strings that should be used to create non-String
+objects. The value to the option must be a Hash with keys that are regular
+expressions and values are class names. For strict json gem compatibility a
+RegExp should be used. For better performance but sacrificing some regexp
+options a string can be used and the C version of regex will be used instead.
+
+### :max_nesting
+
+The maximum nesting depth on both dump and load that is allowed. This exists
+for json gem compatibility.
+
+### :mode [Symbol]
+
+Primary behavior for loading and dumping. The :mode option controls which
+other options are in effect. For more details see the {file:Modes.md} page. By
+default Oj uses the :custom mode which is provides the highest degree of
+customization.
+
+### :nan [Symbol]
+
+How to dump Infinity, -Infinity, and NaN in :null, :strict, and :compat
+mode. Default is :auto but is ignored in the :compat and :rails mode.
+
+ - `:null` places a null
+
+ - `:huge` places a huge number
+
+ - `:word` places Infinity or NaN
+
+ - `:raise` raises and exception
+
+ - `:auto` uses default for each mode which are `:raise` for `:strict`, `:null` for `:null`, and `:word` for `:compat`.
+
+### :nilnil [Boolean]
+
+If true a nil input to load will return nil and not raise an Exception.
+
+### :object_class
+
+The class to use when creating a Hash on load instead of the Hash class.
+
+### :object_nl
+
+Trailer appended to the end of an object dump. The default is an empty
+string. Primarily intended for json gem compatibility. Using just indent as an
+integer gives better performance.
+
+### :omit_nil [Boolean]
+
+If true, Hash and Object attributes with nil values are omitted.
+
+### :quirks_mode [Boolean]
+
+Allow single JSON values instead of documents, default is true (allow). This
+can also be used in :compat mode to be backward compatible with older versions
+of the json gem.
+
+### :safe
+
+The JSON gem includes the complete JSON in parse errors with no limit
+on size. To break from the JSON gem behavior for this case set `:safe`
+to true.
+
+### :second_precision [Fixnum]
+
+The number of digits after the decimal when dumping the seconds of time.
+
+### :space
+
+String inserted after the ':' character when dumping a JSON object. The
+default is an empty string. Primarily intended for json gem
+compatibility. Using just indent as an integer gives better performance.
+
+### :space_before
+
+String inserted before the ':' character when dumping a JSON object. The
+default is an empty string. Primarily intended for json gem
+compatibility. Using just indent as an integer gives better performance.
+
+### :symbol_keys [Boolean]
+
+Use symbols instead of strings for hash keys. :symbolize_names is an alias.
+
+### :trace
+
+When true dump and load functions are traced by printing beginning and ending
+of blocks and of specific calls.
+
+### :time_format [Symbol]
+
+The :time_format when dumping.
+
+ - `:unix` time is output as a decimal number in seconds since epoch including fractions of a second.
+
+ - `:unix_zone` similar to the `:unix` format but with the timezone encoded in
+   the exponent of the decimal number of seconds since epoch.
+
+ - `:xmlschema` time is output as a string that follows the XML schema definition.
+
+ - `:ruby` time is output as a string formatted using the Ruby `to_s` conversion.
+
+### :use_as_json [Boolean]
+
+Call `as_json()` methods on dump, default is false. The option is ignored in
+the :compat and :rails mode.
+
+
+### :use_raw_json [Boolean]
+
+Call `raw_json()` methods on dump, default is false. The option is
+accepted in the :compat and :rails mode even though it is not
+supported by other JSON gems. It provides a means to optimize dump or
+generate performance. The `raw_json(depth, indent)` method should be
+called only by Oj. It is not intended for any other use. This is mean
+to replace the abused `to_json` methods. Calling `Oj.dump` inside the
+`raw_json` with the object itself when `:use_raw_json` is true will
+result in an infinite loop.
+
+### :use_to_hash [Boolean]
+
+Call `to_hash()` methods on dump, default is false. The option is ignored in
+the :compat and :rails mode.
+
+### :use_to_json [Boolean]
+
+Call `to_json()` methods on dump, default is false. The option is ignored in
+the :compat and :rails mode.