bson 1.12.5 → 2.0.0.alpha

data/lib/bson/encodable.rb

@@ -0,0 +1,73 @@
+# encoding: utf-8
+module BSON
+
+  # Defines behaviour around objects that can be encoded.
+  #
+  # @since 2.0.0
+  module Encodable
+
+    # A 4 byte placeholder that would be replaced by a length at a later point.
+    #
+    # @since 2.0.0
+    PLACEHOLDER = 0.to_bson.freeze
+
+    # Adjustment value for total number of document bytes.
+    #
+    # @since 2.0.0
+    BSON_ADJUST = 0.freeze
+
+    # Adjustment value for total number of string bytes.
+    #
+    # @since 2.0.0
+    STRING_ADJUST = -4.freeze
+
+    # Encodes BSON to raw bytes, for types that require the length of the
+    # entire bytes to be present as the first word of the encoded string. This
+    # includes Hash, CodeWithScope.
+    #
+    # @example Encode the BSON with placeholder bytes.
+    #   hash.encode_with_placeholder_and_null(BSON_ADJUST, encoded) do |encoded|
+    #     each do |field, value|
+    #       value.to_bson(encoded)
+    #     end
+    #   end
+    #
+    # @param [ Integer ] adjust The number of bytes to adjust with.
+    # @param [ String ] encoded The string to encode.
+    #
+    # @return [ String ] The encoded string.
+    #
+    # @since 2.0.0
+    def encode_with_placeholder_and_null(adjust, encoded = ''.force_encoding(BINARY))
+      pos = encoded.bytesize
+      encoded << PLACEHOLDER
+      yield(encoded)
+      encoded << NULL_BYTE
+      encoded.set_int32(pos, encoded.bytesize - pos + adjust)
+      encoded
+    end
+
+    # Encodes binary data with a generic placeholder value to be written later
+    # once all bytes have been written.
+    #
+    # @example Encode the BSON with placeholder bytes.
+    #   string.encode_binary_data_with_placeholder(encoded) do |encoded|
+    #     each do |field, value|
+    #       value.to_bson(encoded)
+    #     end
+    #   end
+    #
+    # @param [ String ] encoded The string to encode.
+    #
+    # @return [ String ] The encoded string.
+    #
+    # @since 2.0.0
+    def encode_binary_data_with_placeholder(encoded = ''.force_encoding(BINARY))
+      pos = encoded.bytesize
+      encoded << PLACEHOLDER
+      yield(encoded)
+      encoded.set_int32(pos, encoded.bytesize - pos - 5)
+      encoded
+    end
+  end
+end

data/lib/bson/false_class.rb

@@ -0,0 +1,48 @@
+# encoding: utf-8
+module BSON
+
+  # Injects behaviour for encoding and decoding false values to and from
+  # raw bytes as specified by the BSON spec.
+  #
+  # @see http://bsonspec.org/#/specification
+  #
+  # @since 2.0.0
+  module FalseClass
+
+    # A false value in the BSON spec is 0x00.
+    #
+    # @since 2.0.0
+    FALSE_BYTE = 0.chr.force_encoding(BINARY).freeze
+
+    # The BSON type for false values is the general boolean type of 0x08.
+    #
+    # @example Get the bson type.
+    #   false.bson_type
+    #
+    # @return [ String ] The character 0x08.
+    #
+    # @since 2.0.0
+    def bson_type
+      Boolean::BSON_TYPE
+    end
+
+    # Get the false boolean as encoded BSON.
+    #
+    # @example Get the false boolean as encoded BSON.
+    #   false.to_bson
+    #
+    # @return [ String ] The encoded string.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def to_bson(encoded = ''.force_encoding(BINARY))
+      encoded << FALSE_BYTE
+    end
+  end
+
+  # Enrich the core FalseClass class with this module.
+  #
+  # @since 2.0.0
+  ::FalseClass.send(:include, FalseClass)
+end

data/lib/bson/float.rb

@@ -0,0 +1,69 @@
+# encoding: utf-8
+module BSON
+
+  # Injects behaviour for encoding and decoding floating point values
+  # to and from # raw bytes as specified by the BSON spec.
+  #
+  # @see http://bsonspec.org/#/specification
+  #
+  # @since 2.0.0
+  module Float
+
+    # A floating point is type 0x01 in the BSON spec.
+    #
+    # @since 2.0.0
+    BSON_TYPE = 1.chr.force_encoding(BINARY).freeze
+
+    # The pack directive is for 8 byte floating points.
+    #
+    # @since 2.0.0
+    PACK = "E".freeze
+
+    # Get the floating point as encoded BSON.
+    #
+    # @example Get the floating point as encoded BSON.
+    #   1.221311.to_bson
+    #
+    # @return [ String ] The encoded string.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def to_bson(encoded = ''.force_encoding(BINARY))
+      encoded << [ self ].pack(PACK)
+    end
+
+    module ClassMethods
+
+      # Deserialize an instance of a Float from a BSON double.
+      #
+      # @param [ BSON ] bson The encoded double.
+      #
+      # @return [ Float ] The decoded Float.
+      #
+      # @see http://bsonspec.org/#/specification
+      #
+      # @since 2.0.0
+      def from_bson(bson)
+        from_bson_double(bson.read(8))
+      end
+
+      private
+
+      def from_bson_double(double)
+        double.unpack(PACK).first
+      end
+    end
+
+    # Register this type when the module is loaded.
+    #
+    # @since 2.0.0
+    Registry.register(BSON_TYPE, ::Float)
+  end
+
+  # Enrich the core Float class with this module.
+  #
+  # @since 2.0.0
+  ::Float.send(:include, Float)
+  ::Float.send(:extend, Float::ClassMethods)
+end

data/lib/bson/hash.rb

@@ -0,0 +1,71 @@
+# encoding: utf-8
+module BSON
+
+  # Injects behaviour for encoding and decoding hashes to
+  # and from raw bytes as specified by the BSON spec.
+  #
+  # @see http://bsonspec.org/#/specification
+  #
+  # @since 2.0.0
+  module Hash
+    include Encodable
+
+    # An hash (embedded document) is type 0x03 in the BSON spec.
+    #
+    # @since 2.0.0
+    BSON_TYPE = 3.chr.force_encoding(BINARY).freeze
+
+    # Get the hash as encoded BSON.
+    #
+    # @example Get the hash as encoded BSON.
+    #   { field: "value" }.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|
+        each do |field, value|
+          encoded << value.bson_type
+          field.to_bson_key(encoded)
+          value.to_bson(encoded)
+        end
+      end
+    end
+
+    module ClassMethods
+
+      # Deserialize the hash from BSON.
+      #
+      # @param [ String ] bson The bson representing a hash.
+      #
+      # @return [ Array ] The decoded hash.
+      #
+      # @see http://bsonspec.org/#/specification
+      #
+      # @since 2.0.0
+      def from_bson(bson)
+        hash = new
+        bson.read(4) # Swallow the first four bytes.
+        while (type = bson.readbyte.chr) != NULL_BYTE
+          field = bson.gets(NULL_BYTE).from_bson_string.chop!
+          hash[field] = BSON::Registry.get(type).from_bson(bson)
+        end
+        hash
+      end
+    end
+
+    # Register this type when the module is loaded.
+    #
+    # @since 2.0.0
+    Registry.register(BSON_TYPE, ::Hash)
+  end
+
+  # Enrich the core Hash class with this module.
+  #
+  # @since 2.0.0
+  ::Hash.send(:include, Hash)
+  ::Hash.send(:extend, Hash::ClassMethods)
+end

data/lib/bson/int32.rb

@@ -0,0 +1,46 @@
+# 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 Int32
+
+    # A boolean is type 0x08 in the BSON spec.
+    #
+    # @since 2.0.0
+    BSON_TYPE = 16.chr.force_encoding(BINARY).freeze
+
+    # Constant for the int 32 pack directive.
+    #
+    # @since 2.0.0
+    PACK = ruby_18? ? "l".freeze : "l<".freeze
+
+    # Deserialize an Integer from BSON.
+    #
+    # @param [ BSON ] bson The encoded int32.
+    #
+    # @return [ Integer ] The decoded Integer.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def self.from_bson(bson)
+      from_bson_int32(bson.read(4))
+    end
+
+    private
+
+    def self.from_bson_int32(bytes)
+      bytes.unpack(PACK).first
+    end
+
+    # Register this type when the module is loaded.
+    #
+    # @since 2.0.0
+    Registry.register(BSON_TYPE, self)
+  end
+end

data/lib/bson/int64.rb

@@ -0,0 +1,46 @@
+# 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 Int64
+
+    # A boolean is type 0x08 in the BSON spec.
+    #
+    # @since 2.0.0
+    BSON_TYPE = 18.chr.force_encoding(BINARY).freeze
+
+    # Constant for the int 64 pack directive.
+    #
+    # @since 2.0.0
+    PACK = ruby_18? ? "q".freeze : "q<".freeze
+
+    # Deserialize an Integer from BSON.
+    #
+    # @param [ BSON ] bson The encoded int64.
+    #
+    # @return [ Integer ] The decoded Integer.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def self.from_bson(bson)
+      from_bson_int64(bson.read(8))
+    end
+
+    private
+
+    def self.from_bson_int64(bytes)
+      bytes.unpack(PACK).first
+    end
+
+    # Register this type when the module is loaded.
+    #
+    # @since 2.0.0
+    Registry.register(BSON_TYPE, self)
+  end
+end

data/lib/bson/integer.rb

@@ -0,0 +1,172 @@
+# encoding: utf-8
+module BSON
+
+  # Injects behaviour for encoding and decoding integer values to and from
+  # raw bytes as specified by the BSON spec.
+  #
+  # @see http://bsonspec.org/#/specification
+  #
+  # @since 2.0.0
+  module Integer
+
+    # A 32bit integer is type 0x10 in the BSON spec.
+    #
+    # @since 2.0.0
+    INT32_TYPE = 16.chr.force_encoding(BINARY).freeze
+
+    # A 64bit integer is type 0x12 in the BSON spec.
+    #
+    # @since 2.0.0
+    INT64_TYPE = 18.chr.force_encoding(BINARY).freeze
+
+    # The maximum 32 bit integer value.
+    #
+    # @since 2.0.0
+    MAX_32BIT = (1 << 31) - 1
+
+    # The maximum 64 bit integer value.
+    #
+    # @since 2.0.0
+    MAX_64BIT = (1 << 63) - 1
+
+    # The minimum 32 bit integer value.
+    #
+    # @since 2.0.0
+    MIN_32BIT = -(1 << 31)
+
+    # The minimum 64 bit integer value.
+    #
+    # @since 2.0.0
+    MIN_64BIT = -(1 << 63)
+
+    # The BSON index size.
+    #
+    # @since 2.0.0
+    BSON_INDEX_SIZE = 1024.freeze
+
+    # A hash of index values for array optimization.
+    #
+    # @since 2.0.0
+    BSON_ARRAY_INDEXES = ::Array.new(BSON_INDEX_SIZE) do |i|
+      (i.to_s.force_encoding(BINARY) << NULL_BYTE).freeze
+    end.freeze
+
+    # Is this integer a valid BSON 32 bit value?
+    #
+    # @example Is the integer a valid 32 bit value?
+    #   1024.bson_int32?
+    #
+    # @return [ true, false ] If the integer is 32 bit.
+    #
+    # @since 2.0.0
+    def bson_int32?
+      (MIN_32BIT <= self) && (self <= MAX_32BIT)
+    end
+
+    # Is this integer a valid BSON 64 bit value?
+    #
+    # @example Is the integer a valid 64 bit value?
+    #   1024.bson_int64?
+    #
+    # @return [ true, false ] If the integer is 64 bit.
+    #
+    # @since 2.0.0
+    def bson_int64?
+      (MIN_64BIT <= self) && (self <= MAX_64BIT)
+    end
+
+    # Get the BSON type for this integer. Will depend on whether the integer
+    # is 32 bit or 64 bit.
+    #
+    # @example Get the BSON type for the integer.
+    #   1024.bson_type
+    #
+    # @return [ String ] The single byte BSON type.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def bson_type
+      bson_int32? ? INT32_TYPE : (bson_int64? ? INT64_TYPE : out_of_range!)
+    end
+
+    # Get the integer as encoded BSON.
+    #
+    # @example Get the integer as encoded BSON.
+    #   1024.to_bson
+    #
+    # @return [ String ] The encoded string.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def to_bson(encoded = ''.force_encoding(BINARY))
+      if bson_int32?
+        to_bson_int32(encoded)
+      elsif bson_int64?
+        to_bson_int64(encoded)
+      else
+        out_of_range!
+      end
+    end
+
+    # Convert the integer to a 32 bit (4 bytes) raw bytes string.
+    #
+    # @example Convert the integer to it's 32 bit bytes.
+    #   1024.to_bson_int32
+    #
+    # @param [ String ] encoded The string to encode to.
+    #
+    # @return [ String ] The encoded string.
+    #
+    # @since 2.0.0
+    def to_bson_int32(encoded)
+      append_bson_int32(encoded)
+    end
+
+    # Convert the integer to a 64 bit (8 bytes) raw bytes string.
+    #
+    # @example Convert the integer to it's 64 bit bytes.
+    #   1024.to_bson_int64
+    #
+    # @param [ String ] encoded The string to encode to.
+    #
+    # @return [ String ] The encoded string.
+    #
+    # @since 2.0.0
+    def to_bson_int64(encoded)
+      append_bson_int32(encoded)
+      encoded << ((self >> 32) & 255)
+      encoded << ((self >> 40) & 255)
+      encoded << ((self >> 48) & 255)
+      encoded << ((self >> 56) & 255)
+    end
+
+    def to_bson_key(encoded = ''.force_encoding(BINARY))
+      if self < BSON_INDEX_SIZE
+        encoded << BSON_ARRAY_INDEXES[self]
+      else
+        self.to_s.to_bson_cstring(encoded)
+      end
+    end
+
+    private
+
+    def append_bson_int32(encoded)
+      encoded << (self & 255)
+      encoded << ((self >> 8) & 255)
+      encoded << ((self >> 16) & 255)
+      encoded << ((self >> 24) & 255)
+    end
+
+    def out_of_range!
+      raise RangeError.new("#{self} is not a valid 8 byte integer value.")
+    end
+
+  end
+
+  # Enrich the core Integer class with this module.
+  #
+  # @since 2.0.0
+  ::Integer.send(:include, Integer)
+end