bson 1.12.5 → 2.0.0.alpha

data/lib/bson/array.rb

@@ -0,0 +1,74 @@
+# encoding: utf-8
+module BSON
+
+  # Injects behaviour for encoding and decoding arrays to
+  # and from raw bytes as specified by the BSON spec.
+  #
+  # @see http://bsonspec.org/#/specification
+  #
+  # @since 2.0.0
+  module Array
+    include Encodable
+
+    # An array is type 0x04 in the BSON spec.
+    #
+    # @since 2.0.0
+    BSON_TYPE = 4.chr.force_encoding(BINARY).freeze
+
+    # Get the array as encoded BSON.
+    #
+    # @example Get the array as encoded BSON.
+    #   [ 1, 2, 3 ].to_bson
+    #
+    # @note Arrays are encoded as documents, where the index of the value in
+    #   the array is the actual key.
+    #
+    # @return [ String ] The encoded string.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def to_bson(encoded = ''.force_encoding(BINARY))
+      encode_with_placeholder_and_null(BSON_ADJUST, encoded) do |encoded|
+        each_with_index do |value, index|
+          encoded << value.bson_type
+          index.to_bson_key(encoded)
+          value.to_bson(encoded)
+        end
+      end
+    end
+
+    module ClassMethods
+
+      # Deserialize the array from BSON.
+      #
+      # @param [ BSON ] bson The bson representing an array.
+      #
+      # @return [ Array ] The decoded array.
+      #
+      # @see http://bsonspec.org/#/specification
+      #
+      # @since 2.0.0
+      def from_bson(bson)
+        array = new
+        bson.read(4) # throw away the length
+        while (type = bson.readbyte.chr) != NULL_BYTE
+          bson.gets(NULL_BYTE)
+          array << BSON::Registry.get(type).from_bson(bson)
+        end
+        array
+      end
+    end
+
+    # Register this type when the module is loaded.
+    #
+    # @since 2.0.0
+    Registry.register(BSON_TYPE, ::Array)
+  end
+
+  # Enrich the core Array class with this module.
+  #
+  # @since 2.0.0
+  ::Array.send(:include, Array)
+  ::Array.send(:extend, Array::ClassMethods)
+end

data/lib/bson/binary.rb

@@ -0,0 +1,125 @@
+# encoding: utf-8
+module BSON
+
+  # Represents binary data.
+  #
+  # @see http://bsonspec.org/#/specification
+  #
+  # @since 2.0.0
+  class Binary
+    include JSON
+    include Encodable
+
+    # A binary is type 0x05 in the BSON spec.
+    #
+    # @since 2.0.0
+    BSON_TYPE = 5.chr.force_encoding(BINARY).freeze
+
+    # The mappings of subtypes to their single byte identifiers.
+    #
+    # @since 2.0.0
+    SUBTYPES = {
+      :generic => 0.chr,
+      :function => 1.chr,
+      :old =>  2.chr,
+      :uuid_old => 3.chr,
+      :uuid => 4.chr,
+      :md5 => 5.chr,
+      :user => 128.chr
+    }.freeze
+
+    # The mappings of single byte subtypes to their symbol counterparts.
+    #
+    # @since 2.0.0
+    TYPES = SUBTYPES.invert.freeze
+
+    # @!attribute data
+    #   @return [ Object ] The raw binary data.
+    #   @since 2.0.0
+    # @!attribute type
+    #   @return [ Symbol ] The binary type.
+    #   @since 2.0.0
+    attr_reader :data, :type
+
+    # Determine if this binary object is equal to another object.
+    #
+    # @example Check the binary equality.
+    #   binary == other
+    #
+    # @param [ Object ] other The object to compare against.
+    #
+    # @return [ true, false ] If the objects are equal.
+    #
+    # @since 2.0.0
+    def ==(other)
+      return false unless other.is_a?(Binary)
+      type == other.type && data == other.data
+    end
+
+    # Get the binary as JSON hash data.
+    #
+    # @example Get the binary as a JSON hash.
+    #   binary.as_json
+    #
+    # @return [ Hash ] The binary as a JSON hash.
+    #
+    # @since 2.0.0
+    def as_json(*args)
+      { "$binary" => data, "$type" => type }
+    end
+
+    # Instantiate the new binary object.
+    #
+    # @example Instantiate a binary.
+    #   BSON::Binary.new(data, :md5)
+    #
+    # @param [ Object ] data The raw binary data.
+    # @param [ Symbol ] type The binary type.
+    #
+    # @since 2.0.0
+    def initialize(data = "", type = :generic)
+      @data = data
+      @type = type
+    end
+
+    # Encode the binary type
+    #
+    # @example Encode the binary.
+    #   binary.to_bson
+    #
+    # @return [ String ] The encoded binary.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def to_bson(encoded = ''.force_encoding(BINARY))
+      encode_binary_data_with_placeholder(encoded) do |encoded|
+        encoded << SUBTYPES.fetch(type)
+        encoded << data.bytesize.to_bson if type == :old
+        encoded << data
+      end
+    end
+
+    # Deserialize the binary data from BSON.
+    #
+    # @param [ BSON ] bson The bson representing binary data.
+    #
+    # @return [ Binary ] The decoded binary data.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def self.from_bson(bson)
+      length = Int32.from_bson(bson)
+      type = TYPES[bson.read(1)]
+      length = Int32.from_bson(bson) if type == :old
+      data = bson.read(length)
+      new(data, type)
+    end
+
+    # Register this type when the module is loaded.
+    #
+    # @since 2.0.0
+    Registry.register(BSON_TYPE, self)
+  end
+end

data/lib/bson/boolean.rb

@@ -0,0 +1,35 @@
+# encoding: utf-8
+module BSON
+
+  # Represents a $maxKey type, which compares less than any other value in the
+  # specification.
+  #
+  # @see http://bsonspec.org/#/specification
+  #
+  # @since 2.0.0
+  class Boolean
+
+    # A boolean is type 0x08 in the BSON spec.
+    #
+    # @since 2.0.0
+    BSON_TYPE = 8.chr.force_encoding(BINARY).freeze
+
+    # Deserialize a boolean from BSON.
+    #
+    # @param [ BSON ] bson The encoded boolean.
+    #
+    # @return [ TrueClass, FalseClass ] The decoded boolean.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def self.from_bson(bson)
+      bson.readbyte == 1
+    end
+
+    # Register this type when the module is loaded.
+    #
+    # @since 2.0.0
+    Registry.register(BSON_TYPE, self)
+  end
+end

data/lib/bson/code.rb

@@ -0,0 +1,96 @@
+# encoding: utf-8
+module BSON
+
+  # Represents a code type, which is a wrapper around javascript code.
+  #
+  # @see http://bsonspec.org/#/specification
+  #
+  # @since 2.0.0
+  class Code
+    include JSON
+    include Encodable
+
+    # A code is type 0x0D in the BSON spec.
+    #
+    # @since 2.0.0
+    BSON_TYPE = 13.chr.force_encoding(BINARY).freeze
+
+    # @!attribute javascript
+    #   @return [ String ] The javascript code.
+    #   @since 2.0.0
+    attr_reader :javascript
+
+    # Determine if this code object is equal to another object.
+    #
+    # @example Check the code equality.
+    #   code == other
+    #
+    # @param [ Object ] other The object to compare against.
+    #
+    # @return [ true, false ] If the objects are equal.
+    #
+    # @since 2.0.0
+    def ==(other)
+      return false unless other.is_a?(Code)
+      javascript == other.javascript
+    end
+
+    # Get the code as JSON hash data.
+    #
+    # @example Get the code as a JSON hash.
+    #   code.as_json
+    #
+    # @return [ Hash ] The code as a JSON hash.
+    #
+    # @since 2.0.0
+    def as_json(*args)
+      { "$code" => javascript }
+    end
+
+    # Instantiate the new code.
+    #
+    # @example Instantiate the new code.
+    #   BSON::Code.new("this.value = 5")
+    #
+    # @param [ String ] javascript The javascript code.
+    #
+    # @since 2.0.0
+    def initialize(javascript = "")
+      @javascript = javascript
+    end
+
+    # Encode the javascript code.
+    #
+    # @example Encode the code.
+    #   code.to_bson
+    #
+    # @return [ String ] The encoded string.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def to_bson(encoded = ''.force_encoding(BINARY))
+      encode_with_placeholder_and_null(STRING_ADJUST, encoded) do |encoded|
+        javascript.to_bson_string(encoded)
+      end
+    end
+
+    # Deserialize code from BSON.
+    #
+    # @param [ BSON ] bson The encoded code.
+    #
+    # @return [ TrueClass, FalseClass ] The decoded code.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def self.from_bson(bson)
+      new(bson.read(Int32.from_bson(bson)).from_bson_string.chop!)
+    end
+
+    # Register this type when the module is loaded.
+    #
+    # @since 2.0.0
+    Registry.register(BSON_TYPE, self)
+  end
+end

data/lib/bson/code_with_scope.rb

@@ -0,0 +1,105 @@
+# encoding: utf-8
+module BSON
+
+  # Represents a code with scope, which is a wrapper around javascript code
+  # with variable scope provided.
+  #
+  # @see http://bsonspec.org/#/specification
+  #
+  # @since 2.0.0
+  class CodeWithScope
+    include Encodable
+    include JSON
+
+    # A code with scope is type 0x0F in the BSON spec.
+    #
+    # @since 2.0.0
+    BSON_TYPE = 15.chr.force_encoding(BINARY).freeze
+
+    # @!attribute javascript
+    #   @return [ String ] The javascript code.
+    #   @since 2.0.0
+    # @!attribute scope
+    #   @return [ Hash ] The variable scope.
+    #   @since 2.0.0
+    attr_reader :javascript, :scope
+
+    # Determine if this code with scope object is equal to another object.
+    #
+    # @example Check the code with scope equality.
+    #   code_with_scope == other
+    #
+    # @param [ Object ] other The object to compare against.
+    #
+    # @return [ true, false ] If the objects are equal.
+    #
+    # @since 2.0.0
+    def ==(other)
+      return false unless other.is_a?(CodeWithScope)
+      javascript == other.javascript && scope == other.scope
+    end
+
+    # Get the code with scope as JSON hash data.
+    #
+    # @example Get the code with scope as a JSON hash.
+    #   code_with_scope.as_json
+    #
+    # @return [ Hash ] The code with scope as a JSON hash.
+    #
+    # @since 2.0.0
+    def as_json(*args)
+      { "$code" => javascript, "$scope" => scope }
+    end
+
+    # Instantiate the new code with scope.
+    #
+    # @example Instantiate the code with scope.
+    #   BSON::CodeWithScope.new("this.value = name", name: "sid")
+    #
+    # @param [ String ] javascript The javascript code.
+    # @param [ Hash ] scope The variable scope.
+    #
+    # @since 2.0.0
+    def initialize(javascript = "", scope = {})
+      @javascript = javascript
+      @scope = scope
+    end
+
+    # Encode the javascript code with scope.
+    #
+    # @example Encode the code with scope.
+    #   code_with_scope.to_bson
+    #
+    # @return [ String ] The encoded string.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def to_bson(encoded = ''.force_encoding(BINARY))
+      encode_with_placeholder_and_null(BSON_ADJUST, encoded) do |encoded|
+        javascript.to_bson(encoded)
+        scope.to_bson(encoded)
+      end
+    end
+
+    # Deserialize a code with scope from BSON.
+    #
+    # @param [ BSON ] bson The encoded code with scope.
+    #
+    # @return [ TrueClass, FalseClass ] The decoded code with scope.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def self.from_bson(bson)
+      code_with_scope = StringIO.new(bson.read(Int32.from_bson(bson)))
+      length = code_with_scope.read(4).unpack(Int32::PACK).first
+      new(code_with_scope.read(length).from_bson_string.chop!)
+    end
+
+    # Register this type when the module is loaded.
+    #
+    # @since 2.0.0
+    Registry.register(BSON_TYPE, self)
+  end
+end

data/lib/bson/document.rb

@@ -0,0 +1,536 @@
+# encoding: utf-8
+require "yaml"
+
+# Since we have a custom bsondoc type for yaml serialization, we need
+# to ensure that it's properly deserialized when parsed.
+#
+# @since 2.0.0
+YAML.add_builtin_type("bsondoc") do |type, value|
+  BSON::Document[value.map{ |val| val.to_a.first }]
+end
+
+module BSON
+
+  # This module provides behaviour for serializing and deserializing entire
+  # BSON documents, according to the BSON specification.
+  #
+  # @note The specification is: document ::= int32 e_list "\x00"
+  #
+  # @see http://bsonspec.org/#/specification
+  #
+  # @since 2.0.0
+  class Document < ::Hash
+
+    # Get a value from the document for the provided key. Can use string or
+    # symbol access, but the fastest will be to always provide a key that is of
+    # the same type as the stored keys.
+    #
+    # @example Get an element for the key.
+    #   document["field"]
+    #
+    # @example Get an element for the key by symbol.
+    #   document[:field]
+    #
+    # @param [ String, Symbol ] key The key to lookup.
+    #
+    # @return [ Object ] The found value, or nil if none found.
+    #
+    # @since 2.0.0
+    def [](key)
+      super(key) || super(key.to_s)
+    end
+
+    # If we have ordered hashes, the a BSON::Document is simply a hash. If we do
+    # not, then we need to import our custom BSON::Document implementation.
+    #
+    # @since 2.0.0
+    unless ordered_hash_support?
+
+      # Message for argument error when providing bad arguments to [].
+      #
+      # @since 2.0.0
+      ARG_ERROR = "An even number of arguments must be passed to BSON::Document[]."
+
+      # Sets a value for the provided key.
+      #
+      # @example Set the value in the document.
+      #   document[:name] = "Sid"
+      #
+      # @param [ Object ] key The name of the key.
+      # @param [ Object ] value The value for the key.
+      #
+      # @return [ Object ] The passed in value.
+      #
+      # @since 2.0.0
+      def []=(key, value)
+        order.push(key) unless has_key?(key)
+        super
+      end
+
+      # Clear out all elements in the document.
+      #
+      # @example Clear out all elements.
+      #   document.clear
+      #
+      # @return [ BSON::Document ] The empty document.
+      #
+      # @since 2.0.0
+      def clear
+        super
+        order.clear
+        self
+      end
+
+      # Delete a value from the document for the provided key.
+      #
+      # @example Delete a value from the document.
+      #   document.delete(:name)
+      #
+      # @param [ Object ] key The key to delete for.
+      #
+      # @return [ Object ] The deleted value.
+      #
+      # @since 2.0.0
+      def delete(key)
+        if has_key?(key)
+          order.delete_at(order.index(key))
+        end
+        super
+      end
+
+      # Delete each key/value pair in the document for which the provided block
+      # returns true.
+      #
+      # @example Delete each for when the block is true.
+      #   document.delete_if do |key, value|
+      #     value == 1
+      #   end
+      #
+      # @return [ BSON::Document ] The document.
+      #
+      # @since 2.0.0
+      def delete_if
+        super
+        synchronize!
+        self
+      end
+      alias :reject! :delete_if
+
+      # Iterate over each element of the document in insertion order and yield
+      # the key and value.
+      #
+      # @example Iterate over the document.
+      #   document.each do |key, value|
+      #     #...
+      #   end
+      #
+      # @return [ BSON::Document ] The document if a block was given, otherwise
+      #   an enumerator.
+      #
+      # @since 2.0.0
+      def each
+        if block_given?
+          order.each{ |key| yield([ key, self[key]]) }
+          self
+        else
+          to_enum(:each)
+        end
+      end
+
+      # Iterate over each key in the document in insertion order and yield the
+      # key.
+      #
+      # @example Iterate over the keys.
+      #   document.each_key do |key|
+      #     #...
+      #   end
+      #
+      # @return [ BSON::Document ] The document if a block was given, otherwise
+      #   an enumerator.
+      #
+      # @since 2.0.0
+      def each_key
+        if block_given?
+          order.each{ |key| yield(key) }
+          self
+        else
+          to_enum(:each_key)
+        end
+      end
+
+      # Iterate over each value in the document in insertion order and yield the
+      # value.
+      #
+      # @example Iterate over the values.
+      #   document.each_value do |value|
+      #     #...
+      #   end
+      #
+      # @return [ BSON::Document ] The document if a block was given, otherwise
+      #   an enumerator.
+      #
+      # @since 2.0.0
+      def each_value
+        if block_given?
+          order.each{ |key| yield(self[key]) }
+          self
+        else
+          to_enum(:each_value)
+        end
+      end
+
+      # Iterate over each element of the document in insertion order and yield
+      # the key and value.
+      #
+      # @example Iterate over the document.
+      #   document.each_pair do |key, value|
+      #     #...
+      #   end
+      #
+      # @return [ BSON::Document ] The document if a block was given, otherwise
+      #   an enumerator.
+      #
+      # @since 2.0.0
+      def each_pair
+        if block_given?
+          order.each{ |key| yield([ key, self[key]]) }
+          self
+        else
+          to_enum(:each_pair)
+        end
+      end
+
+      # Encode the document with the provided coder.
+      #
+      # @example Encode the document with the coder.
+      #   document.encode_with(coder)
+      #
+      # @param [ Object ] coder The coder.
+      #
+      # @return [ String ] The encoded document.
+      #
+      # @since 2.0.0
+      def encode_with(coder)
+        coder.represent_seq("!bsondoc", map{ |key, value| { key => value }})
+      end
+
+      # Get all the keys in the document, in order.
+      #
+      # @example Get all the keys in the document.
+      #   document.keys
+      #
+      # @return [ Array<Object> ] The ordered keys.
+      #
+      # @since 2.0.0
+      def keys
+        order.dup
+      end
+
+      # Instantiate a new Document.
+      #
+      # @example Instantiate an empty new document.
+      #   BSON::Document.new
+      #
+      # @since 2.0.0
+      def initialize(*args, &block)
+        super
+        @order = []
+      end
+
+      # Inspect the contents of the document.
+      #
+      # @example Inspect the document.
+      #   document.inspect
+      #
+      # @return [ String ] The inspection string.
+      #
+      # @since 2.0.0
+      def inspect
+        "#<BSON::Document #{super}>"
+      end
+
+      # Invert the document - reverses the order of all key/value pairs and
+      # returns a new document.
+      #
+      # @example Invert the document.
+      #   document.invert
+      #
+      # @return [ BSON::Document ] The inverted document.
+      #
+      # @since 2.0.0
+      def invert
+        Document[to_a.map!{ |pair| pair.reverse }]
+      end
+
+      # Merge a document into this document. Will overwrite any existing keys and
+      # add potential new ones. This returns a new document instead of merging in
+      # place.
+      #
+      # @example Merge the document into this document.
+      #   document.merge(other_document)
+      #
+      # @param [ BSON::Document ] other The document to merge in.
+      #
+      # @return [ BSON::Document ] A newly merged document.
+      #
+      # @since 2.0.0
+      def merge(other, &block)
+        dup.merge!(other, &block)
+      end
+
+      # Merge a document into this document. Will overwrite any existing keys and
+      # add potential new ones.
+      #
+      # @example Merge the document into this document.
+      #   document.merge!(other_document)
+      #
+      # @param [ BSON::Document ] other The document to merge in.
+      #
+      # @return [ BSON::Document ] The document.
+      #
+      # @since 2.0.0
+      def merge!(other)
+        if block_given?
+          other.each do |key, value|
+            self[key] = key?(key) ? yield(key, self[key], value) : value
+          end
+        else
+          other.each{ |key, value| self[key] = value }
+        end
+        self
+      end
+      alias :update :merge!
+
+      # Delete each key/value pair in the document for which the provided block
+      # returns true. This returns a new document instead of modifying in place.
+      #
+      # @example Delete each for when the block is true.
+      #   document.reject do |key, value|
+      #     value == 1
+      #   end
+      #
+      # @return [ BSON::Document ] The new document.
+      #
+      # @since 2.0.0
+      def reject(&block)
+        dup.reject!(&block)
+      end
+
+      # Replace this document with the other document.
+      #
+      # @example Replace the contents of this document with the other.
+      #   document.replace(other_document)
+      #
+      # @param [ BSON::Document ] other The other document.
+      #
+      # @return [ BSON::Document ] The document replaced.
+      #
+      # @since 2.0.0
+      def replace(other)
+        super
+        @order = other.keys
+        self
+      end
+
+      # Shift the document by popping off the first key/value pair in the
+      # document.
+      #
+      # @example Shift the document.
+      #   document.shift
+      #
+      # @return [ Array<Object, Object> ] The first key/value pair.
+      #
+      # @since 2.0.0
+      def shift
+        key = order.first
+        value = delete(key)
+        [ key, value ]
+      end
+
+      alias :select :find_all
+
+      # Get the document as an array. This returns a multi-dimensional array
+      # where each element is a [ key, value ] pair in the insertion order.
+      #
+      # @example Get the document as an array.
+      #   document.to_a
+      #
+      # @return [ Array<Array<Object, Object>> ] The pairs in insertion order.
+      #
+      # @since 2.0.0
+      def to_a
+        order.map{ |key| [ key, self[key] ]}
+      end
+
+      # Convert this document to a hash. Since a document is simply an ordered
+      # hash we return self.
+      #
+      # @example Get the document as a hash.
+      #   document.to_hash
+      #
+      # @return [ BSON::Document ] The document.
+      #
+      # @since 2.0.0
+      def to_hash
+        self
+      end
+
+      # Convert the document to yaml.
+      #
+      # @example Convert the document to yaml.
+      #   document.to_yaml
+      #
+      # @param [ Hash ] options The yaml options.
+      #
+      # @return [ String ] The document as yaml.
+      #
+      # @since 2.0.0
+      def to_yaml(options = {})
+        if YAML.const_defined?(:ENGINE) && !YAML::ENGINE.syck?
+          return super
+        end
+        YAML.quick_emit(self, options) do |out|
+          out.seq(taguri) do |seq|
+            each{ |key, value| seq.add(key => value) }
+          end
+        end
+      end
+
+      # Get the custom yaml type for the document.
+      #
+      # @example Get the yaml type.
+      #   document.to_yaml_type
+      #
+      # @return [ String ] "!bsondoc".
+      #
+      # @since 2.0.0
+      def to_yaml_type
+        "!bsondoc"
+      end
+
+      # Get all the values in the document, by order of insertion.
+      #
+      # @example Get all the values in the document.
+      #   document.values
+      #
+      # @return [ Array<Object> ] The ordered values.
+      #
+      # @since 2.0.0
+      def values
+        order.map{ |key| self[key] }
+      end
+
+      class << self
+
+        # Create a new document given the provided arguments. The args can either
+        # be empty in order to instantiate an empty document, or an array of
+        # key/value pairs in the order that they should remain in.
+        #
+        # @example Create a new empty document.
+        #   BSON::Document[]
+        #
+        # @example Create a new document with the provided elements.
+        #   BSON::Document[1, 2, 3, 4]
+        #
+        # @example Create a new document with key/value array pairs.
+        #   BSON::Document[[ 1, 2 ], [ 3, 4 ]]
+        #
+        # @param [ Array<Object> ] args The key/value pairs.
+        #
+        # @return [ BSON::Document ] The new document.
+        #
+        # @since 2.0.0
+        def [](*args)
+          if (args.length == 1 && args.first.is_a?(Array))
+            return document_from_pairs(args)
+          end
+          raise ArgumentError.new(ARG_ERROR) unless (args.size % 2 == 0)
+          document_from_args(args)
+        end
+
+        private
+
+        # Returns a document that will be generated from an array of [ key, value ]
+        # array pairs.
+        #
+        # @api private
+        #
+        # @example Initialize a document from array pairs.
+        #   BSON::Document[[ 1, 2 ], [ 3, 4 ]]
+        #
+        # @param [ Array ] pairs The key/value pairs.
+        #
+        # @since 2.0.0
+        #
+        # @return [ BSON::Document ] The document.
+        def document_from_pairs(pairs)
+          document = new
+          pairs.first.each do |pair|
+            next unless (pair.is_a?(Array))
+            document[pair[0]] = pair[1]
+          end
+          return document
+        end
+
+        # Returns a document that will be generated from an even number of
+        # individual arguments.
+        #
+        # @api private
+        #
+        # @example Initialize a document from args.
+        #   BSON::Document[1, 2, 3, 4]
+        #
+        # @param [ Array ] args The arguments.
+        #
+        # @return [ BSON::Document ] The document.
+        #
+        # @since 2.0.0
+        def document_from_args(args)
+          document = new
+          args.each_with_index do |val, ind|
+            next if (ind % 2 != 0)
+            document[val] = args[ind + 1]
+          end
+          document
+        end
+      end
+
+      private
+
+      # @!attribute order
+      #   @api private
+      #   @return [ Array<String> ] The document keys in order.
+      #   @since 2.0.0
+      attr_reader :order
+
+      # Initialize a copy of the document for use with clone or dup.
+      #
+      # @api private
+      #
+      # @example Clone the document.
+      #   document.clone
+      #
+      # @param [ Object ] other The original copy.
+      #
+      # @since 2.0.0
+      def initialize_copy(other)
+        super
+        @order = other.keys
+      end
+
+      # Ensure that the ordered keys are the same entries as the internal keys.
+      #
+      # @api private
+      #
+      # @example Synchronize the keys.
+      #   document.synchronize!
+      #
+      # @return [ Array<Object> ] The keys.
+      #
+      # @since 2.0.0
+      def synchronize!
+        order.reject!{ |key| !has_key?(key) }
+      end
+    end
+  end
+end