oj 3.8.0

data/lib/oj/saj.rb

@@ -0,0 +1,66 @@
+module Oj
+  # A SAX style parse handler for JSON hence the acronym SAJ for Simple API for
+  # JSON. The Oj::Saj handler class should be subclassed and then used with the
+  # Oj::Saj key_parse() method. The Saj methods will then be called as the file
+  # is parsed.
+  #
+  # @example
+  # 
+  #  require 'oj'
+  #
+  #  class MySaj < ::Oj::Saj
+  #    def initialize()
+  #      @hash_cnt = 0
+  #    end
+  #
+  #    def hash_start(key)
+  #      @hash_cnt += 1
+  #    end
+  #  end
+  #
+  #  cnt = MySaj.new()
+  #  File.open('any.json', 'r') do |f|
+  #    Oj.saj_parse(cnt, f)
+  #  end
+  #
+  # To make the desired methods active while parsing the desired method should
+  # be made public in the subclasses. If the methods remain private they will
+  # not be called during parsing.
+  #
+  #    def hash_start(key); end
+  #    def hash_end(key); end
+  #    def array_start(key); end
+  #    def array_end(key); end
+  #    def add_value(value, key); end
+  #    def error(message, line, column); end
+  #
+  class Saj
+    # Create a new instance of the Saj handler class.
+    def initialize()
+    end
+
+    # To make the desired methods active while parsing the desired method should
+    # be made public in the subclasses. If the methods remain private they will
+    # not be called during parsing.
+    private
+
+    def hash_start(key)
+    end
+
+    def hash_end(key)
+    end
+
+    def array_start(key)
+    end
+
+    def array_end(key)
+    end
+
+    def add_value(value, key)
+    end
+
+    def error(message, line, column)
+    end
+    
+  end # Saj
+end # Oj

data/lib/oj/schandler.rb

@@ -0,0 +1,142 @@
+module Oj
+  # A Simple Callback Parser (SCP) for JSON. The Oj::ScHandler class should be
+  # subclassed and then used with the Oj.sc_parse() method. The Scp methods will
+  # then be called as the file is parsed. The handler does not have to be a
+  # subclass of the ScHandler class as long as it responds to the desired
+  # methods.
+  #
+  # @example
+  #
+  #  require 'oj'
+  #
+  #  class MyHandler < ::Oj::ScHandler
+  #    def hash_start
+  #      {}
+  #    end
+  #
+  #    def hash_set(h,k,v)
+  #      h[k] = v
+  #    end
+  #
+  #    def array_start
+  #      []
+  #    end
+  #
+  #    def array_append(a,v)
+  #      a << v
+  #    end
+  #
+  #    def add_value(v)
+  #      p v
+  #    end
+  #
+  #    def error(message, line, column)
+  #      p "ERROR: #{message}"
+  #    end
+  #  end
+  #
+  #  File.open('any.json', 'r') do |f|
+  #    Oj.sc_parse(MyHandler.new, f)
+  #  end
+  #
+  # To make the desired methods active while parsing the desired method should
+  # be made public in the subclasses. If the methods remain private they will
+  # not be called during parsing.
+  #
+  #    def hash_start(); end
+  #    def hash_end(); end
+  #    def hash_key(key); end
+  #    def hash_set(h, key, value); end
+  #    def array_start(); end
+  #    def array_end(); end
+  #    def array_append(a, value); end
+  #    def add_value(value); end
+  #
+  # As certain elements of a JSON document are reached during parsing the
+  # callbacks are called. The parser helps by keeping track of objects created
+  # by the callbacks but does not create those objects itself.
+  #
+  #    hash_start
+  #
+  # When a JSON object element starts the hash_start() callback is called if
+  # public. It should return what ever Ruby Object is to be used as the element
+  # that will later be included in the hash_set() callback.
+  #
+  #    hash_end
+  #
+  # When a hash key is encountered the hash_key method is called with the parsed
+  # hash value key. The return value from the call is then used as the key in
+  # the key-value pair that follows.
+  #
+  #    hash_key
+  #
+  # At the end of a JSON object element the hash_end() callback is called if public.
+  #
+  #    hash_set
+  #
+  # When a key value pair is encountered during parsing the hash_set() callback
+  # is called if public. The first element will be the object returned from the
+  # enclosing hash_start() callback. The second argument is the key and the last
+  # is the value.
+  #
+  #    array_start
+  #
+  # When a JSON array element is started the array_start() callback is called if
+  # public. It should return what ever Ruby Object is to be used as the element
+  # that will later be included in the array_append() callback.
+  #
+  #    array_end
+  #
+  # At the end of a JSON array element the array_end() callback is called if public.
+  #
+  #    array_append
+  #
+  # When a element is encountered that is an element of an array the
+  # array_append() callback is called if public. The first argument to the
+  # callback is the Ruby object returned from the enclosing array_start()
+  # callback.
+  #
+  #    add_value
+  #
+  # The handler is expected to handle multiple JSON elements in one stream,
+  # file, or string. When a top level JSON has been read completely the
+  # add_value() callback is called. Even if only one element was ready this
+  # callback returns the Ruby object that was constructed during the parsing.
+  #
+  class ScHandler
+    # Create a new instance of the ScHandler class.
+    def initialize()
+    end
+
+    # To make the desired methods active while parsing the desired method should
+    # be made public in the subclasses. If the methods remain private they will
+    # not be called during parsing.
+    private
+
+    def hash_start()
+    end
+
+    def hash_end()
+    end
+
+    def hash_key(key)
+      key
+    end
+
+    def hash_set(h, key, value)
+    end
+
+    def array_start()
+    end
+
+    def array_end()
+    end
+
+    def add_value(value)
+    end
+
+    def array_append(a, value)
+    end
+
+  end # ScHandler
+end # Oj

data/lib/oj/state.rb

@@ -0,0 +1,131 @@
+
+module JSON
+  module Ext
+    module Generator 
+      unless defined?(::JSON::Ext::Generator::State)
+        # This class exists for json gem compatibility only. While it can be
+        # used as the options for other than compatibility a simple Hash is
+        # recommended as it is simpler and performs better. The only bit
+        # missing by not using a state object is the depth availability which
+        # may be the depth during dumping or maybe not since it can be set and
+        # the docs for depth= is the same as max_nesting. Note: Had to make
+        # this a subclass of Object instead of Hash like EashyHash due to
+        # conflicts with the json gem.
+        class State
+
+          def self.from_state(opts)
+            s = self.new()
+            s.clear()
+            s.merge(opts)
+            s
+          end
+
+          def initialize(opts = {})
+            @attrs = {}
+
+            # Populate with all vars then merge in opts. This class deviates from
+            # the json gem in that any of the options can be set with the opts
+            # argument. The json gem limits the opts use to 7 of the options.
+            @attrs[:indent] = ''
+            @attrs[:space] = ''
+            @attrs[:space_before] = ''
+            @attrs[:array_nl] = ''
+            @attrs[:object_nl] = ''
+            @attrs[:allow_nan] = false
+            @attrs[:buffer_initial_length] = 1024 # completely ignored by Oj
+            @attrs[:depth] = 0
+            @attrs[:max_nesting] = 100
+            @attrs[:check_circular?] = true
+            @attrs[:ascii_only] = false
+
+            @attrs.merge!(opts)
+          end
+
+          def to_h()
+            return @attrs.dup
+          end
+          
+          def to_hash()
+            return @attrs.dup
+          end
+          
+          def allow_nan?()
+            @attrs[:allow_nan]
+          end
+
+          def ascii_only?()
+            @attrs[:ascii_only]
+          end
+
+          def configure(opts)
+            raise TypeError.new('expected a Hash') unless opts.respond_to?(:to_h)
+            @attrs.merge!(opts.to_h)
+          end
+
+          def generate(obj)
+            JSON.generate(obj)
+          end
+
+          def merge(opts)
+            @attrs.merge!(opts)
+          end
+
+          # special rule for this.
+          def buffer_initial_length=(len)
+            len = 1024 if 0 >= len
+            @attrs[:buffer_initial_length] = len
+          end
+
+          # Replaces the Object.respond_to?() method.
+          # @param [Symbol] m method symbol
+          # @return [Boolean] true for any method that matches an instance
+          #                   variable reader, otherwise false.
+          def respond_to?(m)
+            return true if super
+            return true if has_key?(key)
+            return true if has_key?(key.to_s)
+            has_key?(key.to_sym)
+          end
+
+          def [](key)
+            key = key.to_sym
+            @attrs.fetch(key, nil)
+          end
+
+          def []=(key, value)
+            key = key.to_sym
+            @attrs[key] = value
+          end
+
+          def clear()
+            @attrs.clear()
+          end
+
+          def has_key?(k)
+            @attrs.has_key?(key.to_sym)
+          end
+          
+          # Handles requests for Hash values. Others cause an Exception to be raised.
+          # @param [Symbol|String] m method symbol
+          # @return [Boolean] the value of the specified instance variable.
+          # @raise [ArgumentError] if an argument is given. Zero arguments expected.
+          # @raise [NoMethodError] if the instance variable is not defined.
+          def method_missing(m, *args, &block)
+            if m.to_s.end_with?('=')
+              raise ArgumentError.new("wrong number of arguments (#{args.size} for 1 with #{m}) to method #{m}") if args.nil? or 1 != args.length
+              m = m.to_s[0..-2]
+              m = m.to_sym
+              return @attrs.store(m, args[0])
+            else
+              raise ArgumentError.new("wrong number of arguments (#{args.size} for 0 with #{m}) to method #{m}") unless args.nil? or args.empty?
+              return @attrs[m.to_sym]
+            end
+            raise NoMethodError.new("undefined method #{m}", m)
+          end
+
+        end # State
+      end # defined check
+    end # Generator
+  end # Ext
+
+end # JSON

data/lib/oj/version.rb

@@ -0,0 +1,5 @@
+
+module Oj
+  # Current version of the module.
+  VERSION = '3.8.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 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 preceding `':'` 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 preceding `'@'`. 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 preceded 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]`.