oj 2.18.5 → 3.0.0

data/lib/oj/version.rb

@@ -1,5 +1,5 @@
 
 module Oj
   # Current version of the module. 
-  VERSION = '2.18.5'
+  VERSION = '3.0.0'
 end

data/pages/Advanced.md

@@ -0,0 +1,22 @@
+# Advanced Features
+
+Optimized JSON (Oj), as the name implies, was written to provide speed optimized
+JSON handling. It was designed as a faster alternative to Yajl and other
+common Ruby JSON parsers. So far it has achieved that, and is about 2 times faster
+than any other Ruby JSON parser, and 3 or more times faster at serializing JSON.
+
+Oj has several `dump` or serialization modes which control how Ruby `Object`s are
+converted to JSON. These modes are set with the `:mode` option in either the
+default options or as one of the options to the `dump` method. In addition to
+the various options there are also alternative APIs for parsing JSON.
+
+The fastest alternative parser API is the `Oj::Doc` API. The `Oj::Doc` API takes
+a completely different approach by opening a JSON document and providing calls
+to navigate around the JSON while it is open. With this approach, JSON access
+can be well over 20 times faster than conventional JSON parsing.
+
+The `Oj::Saj` and `Oj::ScHandler` APIs are callback parsers that
+walk the JSON document depth first and makes callbacks for each element.
+Both callback parser are useful when only portions of the JSON are of
+interest. Performance up to 20 times faster than conventional JSON is
+possible if only a few elements of the JSON are of interest.

data/pages/Compatibility.md

@@ -0,0 +1,25 @@
+# Compatibility
+
+**Ruby**
+
+Oj is compatible with Ruby 1.9.3, 2.0.0, 2.1, 2.2, 2.3, 2.4 and RBX.
+Support for JRuby has been removed as JRuby no longer supports C extensions and
+there are bugs in the older versions that are not being fixed.
+
+**Rails**
+
+Although up until 4.1 Rails uses [multi_json](https://github.com/intridea/multi_json), an [issue in Rails](https://github.com/rails/rails/issues/9212) causes ActiveSupport to fail to make use Oj for JSON handling.
+There is a
+[gem to patch this](https://github.com/GoodLife/rails-patch-json-encode) for
+Rails 3.2 and 4.0. As of the Oj 2.6.0 release the default behavior is to not use
+the `to_json()` method unless the `:use_to_json` option is set. This provides
+another work around to the rails older and newer behavior.
+
+The latest ActiveRecord is able to work with Oj by simply using the line:
+
+```
+serialize :metadata, Oj
+```
+
+In version Rails 4.1, multi_json has been removed, and this patch is unnecessary and will no longer work.
+See {file:Rails.md}.

data/pages/Custom.md

@@ -0,0 +1,23 @@
+# Custom mode
+
+The `:custom` mode is the most configurable mode and honors almost 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()`.
+
+The `:custom` mode is the default mode. It can be configured either by passing
+options to the `Oj.dump()` and `Oj.load()` methods or by modifying the default
+options.
+
+The ability to create objects from JSON object elements is supported and
+considers the `:create_additions` option. Special treatment is given to the
+`:create_id` though. If the `:create_id` is set to `"^o"` then the Oj internal
+encoding and decoding is used. These are more efficient than calling out to a
+`to_json` method or `create_json` method on the classes. Those method do not
+have to exist for the `"^o"` behavior to be utilized. Any other `:create_id`
+value behaves similar to the json gem by calling `to_json` and `create_json`
+as appropriate.
+

data/pages/Encoding.md

@@ -0,0 +1,65 @@
+# Oj `:object` Mode Encoding
+
+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 these rules.
+
+ * JSON native types, true, false, nil, String, Hash, Array, and Number are
+   encoded normally.
+
+ * A Symbol is encoded as a JSON string with a preceeding `':'` character.
+
+ * The `'^'` character denotes a special key value when in a JSON Object sequence.
+
+ * A Ruby String that starts with `':'`or the sequence `'^i'` or `'^r'` are
+   encoded by excaping the first character so that it appears as `'\u005e'` or
+   `'\u003a'` instead of `':'` or `'^'`.
+
+ * A `"^c"` JSON Object key indicates the value should be converted to a Ruby
+   class. The sequence `{"^c":"Oj::Bag"}` is read as the Oj::Bag class.
+
+ * A `"^t"` JSON Object key indicates the value should be converted to a Ruby
+   Time. The sequence `{"^t":1325775487.000000}` is read as Jan 5, 2012 at
+   23:58:07.
+
+ * A `"^o"` JSON Object key indicates the value should be converted to a Ruby
+   Object. The first entry in the JSON Object must be a class with the `"^o"`
+   key. After that each entry is treated as a variable of the Object where the
+   key is the variable name without the preceeding `'@'`. An example is
+   `{"^o":"Oj::Bag","x":58,"y":"marbles"}`. `"^O"`is the same except that it
+   is for built in or odd classes that don't obey the normal Ruby
+   rules. Examples are Rational, Date, and DateTime.
+
+ * A `"^u"` JSON Object key indicates the value should be converted to a Ruby
+   Struct. The first entry in the JSON Object must be a class with the
+   `"^u"` key. After that each entry is is given a numeric position in the
+   struct and that is used as the key in the JSON Object. An example is
+   `{"^u":["Range",1,7,false]}`.
+
+ * When encoding an Object, if the variable name does not begin with an
+   `'@'`character then the name preceeded by a `'~'` character. This occurs in
+   the Exception class. An example is `{"^o":"StandardError","~mesg":"A
+   Message","~bt":[".\/tests.rb:345:in 'test_exception'"]}`.
+
+ * If a Hash entry has a key that is not a String or Symbol then the entry is
+   encoded with a key of the form `"^#n"` where n is a hex number. The value
+   is an Array where the first element is the key in the Hash and the second
+   is the value. An example is `{"^#3":[2,5]}`.
+
+ * A `"^i"` JSON entry in either an Object or Array is the ID of the Ruby
+   Object being encoded. It is used when the :circular flag is set. It can
+   appear in either a JSON Object or in a JSON Array. In an Object the
+   `"^i"` key has a corresponding reference Fixnum. In an array the sequence
+   will include an embedded reference number. An example is
+   `{"^o":"Oj::Bag","^i":1,"x":["^i2",true],"me":"^r1"}`.
+
+ * A `"^r"`JSON entry in an Object is a references to a Object or Array that
+   already appears in the JSON String. It must match up with a previous
+   `"^i"` ID. An example is `{"^o":"Oj::Bag","^i":1,"x":3,"me":"^r1"}`.
+
+ * If an Array element is a String and starts with `"^i"` then the first
+   character, the `'^'` is encoded as a hex character sequence. An example is
+   `["\u005ei37",3]`.

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,140 @@
+# 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 Juby 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 detemine 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}](pages/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}](pages/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}](pages/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}](pages/Custom.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 |
+    | ---------------------- | ------- | ------- | ------- | ------- | ------- | ------- | ------- |
+    | :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 |         |         |         |         |       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 |
+    | :indent                | Integer |       x |       x |       3 |       3 |       x |       x |
+    | :indent_str            | String  |         |         |       x |       x |         |       x |
+    | :match_string          | Hash    |         |         |       x |       x |         |       x |
+    | :max_nesting           | Fixnum  |       4 |       4 |       x |         |       4 |       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 |         |         |       5 |         |         |       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 |
+    | :time_format           | Symbol  |         |         |         |         |       x |       x |
+    | :use_as_json           | Boolean |         |         |         |         |         |       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. 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.
+
+ 4. 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.
+
+ 5. 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,250 @@
+# 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 encounterd 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 input will not raise an Exception. The default differs
+according to the mode and in some cases the function used to load or dump. The
+defaults are:
+
+ - :null - true
+ - :strict - true
+ - :compat or :json - true
+    - JSON.parse() - false
+    - JSON.load() - true (or what ever is set in the defaults)
+ - :rails - TBD
+ - :object - true
+ - :custom - true
+
+### :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.
+
+### :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.
+
+### :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.
+
+### :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.
+
+### :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_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.
+
+
+