bson 4.5.0 → 4.6.0

data/lib/bson/document.rb

@@ -88,7 +88,49 @@ module BSON
       super(convert_key(key))
     end
 
-    # Set a value on the document. Will normalize symbol keys into strings.
+    # Stores a key-value pair in the current document.
+    #
+    # Since BSON documents provide deep indifferent access (both strings and
+    # symbols are accepted as keys, recursively), the value may be converted
+    # to facilitate indifferent access. This conversion is performed for
+    # built-in Array and Hash classes, and other classes can override
+    # +to_bson_normalized_value+ method to provide custom conversion logic.
+    # For example:
+    #
+    #     doc = BSON::Document.new
+    #     doc[:a] = {b: {c: 'd'}}
+    #     doc['a']['b']['c']
+    #     # => "d"
+    #
+    # Note that due to this conversion, the object that is stored in the
+    # receiver Document may be different from the object supplied as the
+    # right hand side of the assignment. In Ruby, the result of assignment
+    # is the right hand side, not the return value of []= method.
+    # Because of this, modifying the result of assignment generally does not
+    # work as intended:
+    #
+    #     doc = BSON::Document.new
+    #     foo = (doc[:a] = {b: {c: 'd'}})
+    #     # foo is original Hash with symbol keys
+    #     foo['test'] = 'test'
+    #     # doc is not modified
+    #     doc
+    #     # => {"a"=>{"b"=>{"c"=>"d"}}}
+    #
+    # This behavior can be encountered when defaulting document contents with
+    # []= in a method, such as:
+    #
+    #     def foo
+    #       # @doc is a BSON::Document
+    #       @doc[:foo] ||= calculation
+    #     end
+    #
+    # The above method should be written as follows to allow chaining:
+    #
+    #     def foo
+    #       # @doc is a BSON::Document
+    #       @doc[:foo] ||= calculation and @doc[:foo]
+    #     end
     #
     # @example Set a value on the document.
     #   document[:test] = "value"

data/lib/bson/hash.rb

@@ -22,7 +22,7 @@ module BSON
   # @since 2.0.0
   module Hash
 
-    # An hash (embedded document) is type 0x03 in the BSON spec.
+    # A hash, also called an embedded document, is type 0x03 in the BSON spec.
     #
     # @since 2.0.0
     BSON_TYPE = 3.chr.force_encoding(BINARY).freeze
@@ -45,7 +45,16 @@ module BSON
         buffer.put_int32(0)
         each do |field, value|
           buffer.put_byte(value.bson_type)
-          buffer.put_cstring(field.to_bson_key(validating_keys))
+          key = field.to_bson_key(validating_keys)
+          begin
+            buffer.put_cstring(key)
+          rescue ArgumentError => e
+            raise ArgumentError, "Error serializing key #{key}: #{e.class}: #{e}"
+          rescue EncodingError => e
+            # Note this may convert exception class from a subclass of
+            # EncodingError to EncodingError itself
+            raise EncodingError, "Error serializing key #{key}: #{e.class}: #{e}"
+          end
           value.to_bson(buffer, validating_keys)
         end
         buffer.put_byte(NULL_BYTE)

data/lib/bson/int32.rb

@@ -51,16 +51,28 @@ module BSON
 
     # Instantiate a BSON Int32.
     #
-    # @param [ Integer ] integer The 32-bit integer.
+    # @param [ Integer ] value The 32-bit integer.
     #
     # @see http://bsonspec.org/#/specification
     #
     # @since 4.2.0
-    def initialize(integer)
-      out_of_range! unless integer.bson_int32?
-      @integer = integer.freeze
+    def initialize(value)
+      if value.is_a?(self.class)
+        @value = value.value
+        return
+      end
+
+      unless value.bson_int32?
+        raise RangeError.new("#{value} cannot be stored in 32 bits")
+      end
+      @value = value.freeze
     end
 
+    # Returns the value of this Int32.
+    #
+    # @return [ Integer ] The integer value.
+    attr_reader :value
+
     # Append the integer as encoded BSON to a ByteBuffer.
     #
     # @example Encoded the integer and append to a ByteBuffer.
@@ -72,7 +84,7 @@ module BSON
     #
     # @since 4.2.0
     def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
-      buffer.put_int32(@integer)
+      buffer.put_int32(value)
     end
 
     # Convert the integer to a BSON string key.
@@ -86,7 +98,7 @@ module BSON
     #
     # @since 4.2.0
     def to_bson_key(validating_keys = Config.validating_keys?)
-      @integer
+      value
     end
 
     # Check equality of the int32 with another object.
@@ -98,17 +110,11 @@ module BSON
     # @since 4.4.0
     def ==(other)
       return false unless other.is_a?(Int32)
-      @integer == other.instance_variable_get('@integer')
+      value == other.value
     end
     alias :eql? :==
     alias :=== :==
 
-    private
-
-    def out_of_range!
-      raise RangeError.new("#{self} is not a valid 4 byte integer value.")
-    end
-
     # Register this type when the module is loaded.
     #
     # @since 2.0.0

data/lib/bson/int64.rb

@@ -46,16 +46,28 @@ module BSON
 
     # Instantiate a BSON Int64.
     #
-    # @param [ Integer ] integer The 64-bit integer.
+    # @param [ Integer ] value The 64-bit integer.
     #
     # @see http://bsonspec.org/#/specification
     #
     # @since 4.2.0
-    def initialize(integer)
-      out_of_range! unless integer.bson_int64?
-      @integer = integer.freeze
+    def initialize(value)
+      if value.is_a?(self.class)
+        @value = value.value
+        return
+      end
+
+      unless value.bson_int64?
+        raise RangeError.new("#{value} cannot be stored in 64 bits")
+      end
+      @value = value.freeze
     end
 
+    # Returns the value of this Int64.
+    #
+    # @return [ Integer ] The integer value.
+    attr_reader :value
+
     # Append the integer as encoded BSON to a ByteBuffer.
     #
     # @example Encoded the integer and append to a ByteBuffer.
@@ -67,7 +79,7 @@ module BSON
     #
     # @since 4.2.0
     def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
-      buffer.put_int64(@integer)
+      buffer.put_int64(value)
     end
 
     # Convert the integer to a BSON string key.
@@ -81,7 +93,7 @@ module BSON
     #
     # @since 4.2.0
     def to_bson_key(validating_keys = Config.validating_keys?)
-      @integer
+      value
     end
 
     # Check equality of the int64 with another object.
@@ -93,17 +105,11 @@ module BSON
     # @since 4.4.0
     def ==(other)
       return false unless other.is_a?(Int64)
-      @integer == other.instance_variable_get('@integer')
+      value == other.value
     end
     alias :eql? :==
     alias :=== :==
 
-    private
-
-    def out_of_range!
-      raise RangeError.new("#{self} is not a valid 8 byte integer value.")
-    end
-
     # Register this type when the module is loaded.
     #
     # @since 2.0.0

data/lib/bson/version.rb

@@ -13,5 +13,5 @@
 # limitations under the License.
 
 module BSON
-  VERSION = "4.5.0".freeze
+  VERSION = "4.6.0".freeze
 end

data/spec/bson/byte_buffer_read_spec.rb

@@ -0,0 +1,141 @@
+require 'spec_helper'
+
+describe BSON::ByteBuffer do
+
+  describe '#get_byte' do
+
+    let(:buffer) do
+      described_class.new(BSON::Int32::BSON_TYPE)
+    end
+
+    let!(:byte) do
+      buffer.get_byte
+    end
+
+    it 'gets the byte from the buffer' do
+      expect(byte).to eq(BSON::Int32::BSON_TYPE)
+    end
+
+    it 'increments the read position by 1' do
+      expect(buffer.read_position).to eq(1)
+    end
+  end
+
+  describe '#get_bytes' do
+
+    let(:string) do
+      "#{BSON::Int32::BSON_TYPE}#{BSON::Int32::BSON_TYPE}"
+    end
+
+    let(:buffer) do
+      described_class.new(string)
+    end
+
+    let!(:bytes) do
+      buffer.get_bytes(2)
+    end
+
+    it 'gets the bytes from the buffer' do
+      expect(bytes).to eq(string)
+    end
+
+    it 'increments the position by the length' do
+      expect(buffer.read_position).to eq(string.bytesize)
+    end
+  end
+
+  describe '#get_cstring' do
+
+    let(:buffer) do
+      described_class.new("testing#{BSON::NULL_BYTE}")
+    end
+
+    let!(:string) do
+      buffer.get_cstring
+    end
+
+    it 'gets the cstring from the buffer' do
+      expect(string).to eq("testing")
+    end
+
+    it 'increments the position by string length + 1' do
+      expect(buffer.read_position).to eq(8)
+    end
+  end
+
+  describe '#get_double' do
+
+    let(:buffer) do
+      described_class.new("#{12.5.to_bson.to_s}")
+    end
+
+    let!(:double) do
+      buffer.get_double
+    end
+
+    it 'gets the double from the buffer' do
+      expect(double).to eq(12.5)
+    end
+
+    it 'increments the read position by 8' do
+      expect(buffer.read_position).to eq(8)
+    end
+  end
+
+  describe '#get_int32' do
+
+    let(:buffer) do
+      described_class.new("#{12.to_bson.to_s}")
+    end
+
+    let!(:int32) do
+      buffer.get_int32
+    end
+
+    it 'gets the int32 from the buffer' do
+      expect(int32).to eq(12)
+    end
+
+    it 'increments the position by 4' do
+      expect(buffer.read_position).to eq(4)
+    end
+  end
+
+  describe '#get_int64' do
+
+    let(:buffer) do
+      described_class.new("#{(Integer::MAX_64BIT - 1).to_bson.to_s}")
+    end
+
+    let!(:int64) do
+      buffer.get_int64
+    end
+
+    it 'gets the int64 from the buffer' do
+      expect(int64).to eq(Integer::MAX_64BIT - 1)
+    end
+
+    it 'increments the position by 8' do
+      expect(buffer.read_position).to eq(8)
+    end
+  end
+
+  describe '#get_string' do
+
+    let(:buffer) do
+      described_class.new("#{8.to_bson.to_s}testing#{BSON::NULL_BYTE}")
+    end
+
+    let!(:string) do
+      buffer.get_string
+    end
+
+    it 'gets the string from the buffer' do
+      expect(string).to eq("testing")
+    end
+
+    it 'increments the position by string length + 5' do
+      expect(buffer.read_position).to eq(12)
+    end
+  end
+end

data/spec/bson/byte_buffer_spec.rb

@@ -13,144 +13,17 @@ describe BSON::ByteBuffer do
     end
   end
 
-  describe '#get_byte' do
-
-    let(:buffer) do
-      described_class.new(BSON::Int32::BSON_TYPE)
-    end
-
-    let!(:byte) do
-      buffer.get_byte
-    end
-
-    it 'gets the byte from the buffer' do
-      expect(byte).to eq(BSON::Int32::BSON_TYPE)
-    end
-
-    it 'increments the read position by 1' do
-      expect(buffer.read_position).to eq(1)
-    end
-  end
-
-  describe '#get_bytes' do
-
-    let(:string) do
-      "#{BSON::Int32::BSON_TYPE}#{BSON::Int32::BSON_TYPE}"
-    end
-
-    let(:buffer) do
-      described_class.new(string)
-    end
-
-    let!(:bytes) do
-      buffer.get_bytes(2)
-    end
-
-    it 'gets the bytes from the buffer' do
-      expect(bytes).to eq(string)
-    end
-
-    it 'increments the position by the length' do
-      expect(buffer.read_position).to eq(string.bytesize)
-    end
-  end
-
-  describe '#get_cstring' do
-
-    let(:buffer) do
-      described_class.new("testing#{BSON::NULL_BYTE}")
-    end
-
-    let!(:string) do
-      buffer.get_cstring
-    end
-
-    it 'gets the cstring from the buffer' do
-      expect(string).to eq("testing")
-    end
-
-    it 'increments the position by string length + 1' do
-      expect(buffer.read_position).to eq(8)
-    end
-  end
-
-  describe '#get_double' do
-
-    let(:buffer) do
-      described_class.new("#{12.5.to_bson.to_s}")
-    end
-
-    let!(:double) do
-      buffer.get_double
-    end
-
-    it 'gets the double from the buffer' do
-      expect(double).to eq(12.5)
-    end
-
-    it 'increments the read position by 8' do
-      expect(buffer.read_position).to eq(8)
-    end
-  end
-
-  describe '#get_int32' do
-
-    let(:buffer) do
-      described_class.new("#{12.to_bson.to_s}")
-    end
-
-    let!(:int32) do
-      buffer.get_int32
-    end
-
-    it 'gets the int32 from the buffer' do
-      expect(int32).to eq(12)
-    end
-
-    it 'increments the position by 4' do
-      expect(buffer.read_position).to eq(4)
-    end
-  end
-
-  describe '#get_int64' do
-
-    let(:buffer) do
-      described_class.new("#{(Integer::MAX_64BIT - 1).to_bson.to_s}")
-    end
-
-    let!(:int64) do
-      buffer.get_int64
-    end
-
-    it 'gets the int64 from the buffer' do
-      expect(int64).to eq(Integer::MAX_64BIT - 1)
-    end
-
-    it 'increments the position by 8' do
-      expect(buffer.read_position).to eq(8)
-    end
-  end
-
-  describe '#get_string' do
-
-    let(:buffer) do
-      described_class.new("#{8.to_bson.to_s}testing#{BSON::NULL_BYTE}")
-    end
-
-    let!(:string) do
-      buffer.get_string
-    end
+  describe '#length' do
+    context 'empty buffer' do
 
-    it 'gets the string from the buffer' do
-      expect(string).to eq("testing")
-    end
+      let(:buffer) do
+        described_class.new
+      end
 
-    it 'increments the position by string length + 5' do
-      expect(buffer.read_position).to eq(12)
+      it 'is zero' do
+        expect(buffer.length).to eq(0)
+      end
     end
-  end
-
-  describe '#length' do
 
     context 'when the byte buffer is initialized with no bytes' do
 
@@ -179,296 +52,6 @@ describe BSON::ByteBuffer do
     end
   end
 
-  describe '#put_byte' do
-
-    let(:buffer) do
-      described_class.new
-    end
-
-    let!(:modified) do
-      buffer.put_byte(BSON::Int32::BSON_TYPE)
-    end
-
-    it 'appends the byte to the byte buffer' do
-      expect(modified.to_s).to eq(BSON::Int32::BSON_TYPE.chr)
-    end
-
-    it 'increments the write position by 1' do
-      expect(modified.write_position).to eq(1)
-    end
-
-    context 'when it receives a numeric value' do
-      it 'raises the ArgumentError exception' do
-        expect{buffer.put_byte(1)}.to raise_error(ArgumentError)
-      end
-    end
-
-    context 'when it receives a nil value' do
-      it 'raises the ArgumentError exception' do
-        expect{buffer.put_byte(nil)}.to raise_error(ArgumentError)
-      end
-    end
-  end
-
-  describe '#put_cstring' do
-
-    let(:buffer) do
-      described_class.new
-    end
-
-    context 'when the string is valid' do
-
-      let!(:modified) do
-        buffer.put_cstring('testing')
-      end
-
-      it 'appends the string plus null byte to the byte buffer' do
-        expect(modified.to_s).to eq("testing#{BSON::NULL_BYTE}")
-      end
-
-      it 'increments the write position by the length + 1' do
-        expect(modified.write_position).to eq(8)
-      end
-    end
-
-    context "when the string contains a null byte" do
-
-      let(:string) do
-        "test#{BSON::NULL_BYTE}ing"
-      end
-
-      it "raises an error" do
-        expect {
-          buffer.put_cstring(string)
-        }.to raise_error(ArgumentError)
-      end
-    end
-  end
-
-  describe '#put_double' do
-
-    let(:buffer) do
-      described_class.new
-    end
-
-    let!(:modified) do
-      buffer.put_double(1.2332)
-    end
-
-    it 'appends the double to the buffer' do
-      expect(modified.to_s).to eq([ 1.2332 ].pack(Float::PACK))
-    end
-
-    it 'increments the write position by 8' do
-      expect(modified.write_position).to eq(8)
-    end
-  end
-
-  describe '#put_int32' do
-
-    let(:buffer) do
-      described_class.new
-    end
-
-    context 'when the integer is 32 bit' do
-
-      context 'when the integer is positive' do
-
-        let!(:modified) do
-          buffer.put_int32(Integer::MAX_32BIT - 1)
-        end
-
-        let(:expected) do
-          [ Integer::MAX_32BIT - 1 ].pack(BSON::Int32::PACK)
-        end
-
-        it 'appends the int32 to the byte buffer' do
-          expect(modified.to_s).to eq(expected)
-        end
-
-        it 'increments the write position by 4' do
-          expect(modified.write_position).to eq(4)
-        end
-      end
-
-      context 'when the integer is negative' do
-
-        let!(:modified) do
-          buffer.put_int32(Integer::MIN_32BIT + 1)
-        end
-
-        let(:expected) do
-          [ Integer::MIN_32BIT + 1 ].pack(BSON::Int32::PACK)
-        end
-
-        it 'appends the int32 to the byte buffer' do
-          expect(modified.to_s).to eq(expected)
-        end
-
-        it 'increments the write position by 4' do
-          expect(modified.write_position).to eq(4)
-        end
-      end
-
-      context 'when the integer is not 32 bit' do
-
-        it 'raises an exception' do
-          expect {
-            buffer.put_int32(Integer::MAX_64BIT - 1)
-          }.to raise_error(RangeError)
-        end
-      end
-    end
-  end
-
-  describe '#put_int64' do
-
-    let(:buffer) do
-      described_class.new
-    end
-
-    context 'when the integer is 64 bit' do
-
-      context 'when the integer is positive' do
-
-        let!(:modified) do
-          buffer.put_int64(Integer::MAX_64BIT - 1)
-        end
-
-        let(:expected) do
-          [ Integer::MAX_64BIT - 1 ].pack(BSON::Int64::PACK)
-        end
-
-        it 'appends the int64 to the byte buffer' do
-          expect(modified.to_s).to eq(expected)
-        end
-
-        it 'increments the write position by 8' do
-          expect(modified.write_position).to eq(8)
-        end
-      end
-
-      context 'when the integer is negative' do
-
-        let!(:modified) do
-          buffer.put_int64(Integer::MIN_64BIT + 1)
-        end
-
-        let(:expected) do
-          [ Integer::MIN_64BIT + 1 ].pack(BSON::Int64::PACK)
-        end
-
-        it 'appends the int64 to the byte buffer' do
-          expect(modified.to_s).to eq(expected)
-        end
-
-        it 'increments the write position by 8' do
-          expect(modified.write_position).to eq(8)
-        end
-      end
-
-      context 'when the integer is larger than 64 bit' do
-
-        it 'raises an exception' do
-          expect {
-            buffer.put_int64(Integer::MAX_64BIT + 1)
-          }.to raise_error(RangeError)
-        end
-      end
-    end
-  end
-
-  describe '#put_string' do
-
-    context 'when the buffer does not need to be expanded' do
-
-      let(:buffer) do
-        described_class.new
-      end
-
-      context 'when the string is UTF-8' do
-
-        let!(:modified) do
-          buffer.put_string('testing')
-        end
-
-        it 'appends the string to the byte buffer' do
-          expect(modified.to_s).to eq("#{8.to_bson.to_s}testing#{BSON::NULL_BYTE}")
-        end
-
-        it 'increments the write position by length + 5' do
-          expect(modified.write_position).to eq(12)
-        end
-      end
-    end
-
-    context 'when the buffer needs to be expanded' do
-
-      let(:buffer) do
-        described_class.new
-      end
-
-      let(:string) do
-        300.times.inject(""){ |s, i| s << "#{i}" }
-      end
-
-      context 'when no bytes exist in the buffer' do
-
-        let!(:modified) do
-          buffer.put_string(string)
-        end
-
-        it 'appends the string to the byte buffer' do
-          expect(modified.to_s).to eq("#{(string.bytesize + 1).to_bson.to_s}#{string}#{BSON::NULL_BYTE}")
-        end
-
-        it 'increments the write position by length + 5' do
-          expect(modified.write_position).to eq(string.bytesize + 5)
-        end
-      end
-
-      context 'when bytes exist in the buffer' do
-
-        let!(:modified) do
-          buffer.put_int32(4).put_string(string)
-        end
-
-        it 'appends the string to the byte buffer' do
-          expect(modified.to_s).to eq(
-            "#{[ 4 ].pack(BSON::Int32::PACK)}#{(string.bytesize + 1).to_bson.to_s}#{string}#{BSON::NULL_BYTE}"
-          )
-        end
-
-        it 'increments the write position by length + 5' do
-          expect(modified.write_position).to eq(string.bytesize + 9)
-        end
-      end
-    end
-  end
-
-  describe '#replace_int32' do
-
-    let(:buffer) do
-      described_class.new
-    end
-
-    let(:exp_first) do
-      [ 5 ].pack(BSON::Int32::PACK)
-    end
-
-    let(:exp_second) do
-      [ 4 ].pack(BSON::Int32::PACK)
-    end
-
-    let(:modified) do
-      buffer.put_int32(0).put_int32(4).replace_int32(0, 5)
-    end
-
-    it 'replaces the int32 at the location' do
-      expect(modified.to_s).to eq("#{exp_first}#{exp_second}")
-    end
-  end
-
   describe '#rewind!' do
 
     shared_examples_for 'a rewindable buffer' do
@@ -512,33 +95,13 @@ describe BSON::ByteBuffer do
 
       it_behaves_like 'a rewindable buffer'
     end
-  end
-
-  describe '#put_bytes' do
-
-    let(:buffer) do
-      described_class.new
-    end
-
-    let!(:modified) do
-      buffer.put_bytes(BSON::Int32::BSON_TYPE)
-      buffer
-    end
-
-    it 'increments the write position by 1' do
-      expect(modified.write_position).to eq(1)
-    end
 
-    context 'when it receives a numeric value' do
-      it 'raises the ArgumentError exception' do
-        expect{buffer.put_bytes(1)}.to raise_error(ArgumentError)
-      end
-    end
-    
-    context 'when it receives a nil value' do
-      it 'raises the ArgumentError exception' do
-        expect{buffer.put_bytes(nil)}.to raise_error(ArgumentError)
-      end
+    it 'does not change write position' do
+      buffer = described_class.new
+      buffer.put_byte(BSON::Int32::BSON_TYPE)
+      expect(buffer.write_position).to eq(1)
+      buffer.rewind!
+      expect(buffer.write_position).to eq(1)
     end
   end
 end