bson 1.12.5 → 2.0.0.alpha

data/lib/bson/regexp.rb

@@ -0,0 +1,111 @@
+# encoding: utf-8
+module BSON
+
+  # Injects behaviour for encoding and decoding regular expression values to
+  # and from raw bytes as specified by the BSON spec.
+  #
+  # @see http://bsonspec.org/#/specification
+  #
+  # @since 2.0.0
+  module Regexp
+    include JSON
+
+    # A regular expression is type 0x0B in the BSON spec.
+    #
+    # @since 2.0.0
+    BSON_TYPE = 11.chr.force_encoding(BINARY).freeze
+
+    # Get the regexp as JSON hash data.
+    #
+    # @example Get the regexp as a JSON hash.
+    #   regexp.as_json
+    #
+    # @return [ Hash ] The regexp as a JSON hash.
+    #
+    # @since 2.0.0
+    def as_json(*args)
+      { "$regex" => source, "$options" => bson_options }
+    end
+
+    # Get the regular expression as encoded BSON.
+    #
+    # @example Get the regular expression as encoded BSON.
+    #   %r{\d+}.to_bson
+    #
+    # @note From the BSON spec: The first cstring is the regex pattern,
+    #   the second is the regex options string. Options are identified
+    #   by characters, which must be stored in alphabetical order.
+    #   Valid options are 'i' for case insensitive matching,
+    #   'm' for multiline matching, 'x' for verbose mode,
+    #   'l' to make \w, \W, etc. locale dependent,
+    #   's' for dotall mode ('.' matches everything),
+    #   and 'u' to make \w, \W, etc. match unicode.
+    #
+    # @return [ String ] The encoded string.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def to_bson(encoded = ''.force_encoding(BINARY))
+      source.to_bson_cstring(encoded)
+      bson_options.to_bson_cstring(encoded)
+    end
+
+    private
+
+    def bson_options
+      bson_ignorecase + bson_multiline + bson_extended
+    end
+
+    def bson_extended
+      (options & ::Regexp::EXTENDED != 0) ? "x" : NO_VALUE
+    end
+
+    def bson_ignorecase
+      (options & ::Regexp::IGNORECASE != 0) ? "i" : NO_VALUE
+    end
+
+    def bson_multiline
+      (options & ::Regexp::MULTILINE != 0) ? "ms" : NO_VALUE
+    end
+
+    module ClassMethods
+      # Deserialize the regular expression from BSON.
+      #
+      # @param [ BSON ] bson The bson representing a regular expression.
+      #
+      # @return [ Regexp ] The decoded regular expression.
+      #
+      # @see http://bsonspec.org/#/specification
+      #
+      # @since 2.0.0
+      def from_bson(bson)
+        pattern = bson.gets(NULL_BYTE).from_bson_string.chop!
+        options = 0
+        while (option = bson.readbyte) != 0
+          case option
+          when 105 # 'i'
+            options |= ::Regexp::IGNORECASE
+          when 109, 115 # 'm', 's'
+            options |= ::Regexp::MULTILINE
+          when 120 # 'x'
+            options |= ::Regexp::EXTENDED
+          end
+        end
+
+        new(pattern, options)
+      end
+    end
+
+    # Register this type when the module is loaded.
+    #
+    # @since 2.0.0
+    Registry.register(BSON_TYPE, ::Regexp)
+  end
+
+  # Enrich the core Regexp class with this module.
+  #
+  # @since 2.0.0
+  ::Regexp.send(:include, Regexp)
+  ::Regexp.send(:extend, Regexp::ClassMethods)
+end

data/lib/bson/registry.rb

@@ -0,0 +1,57 @@
+# encoding: utf-8
+module BSON
+
+  # Provides constant values for each to the BSON types and mappings from raw
+  # bytes back to these types.
+  #
+  # @see http://bsonspec.org/#/specification
+  #
+  # @since 2.0.0
+  module Registry
+    extend self
+
+    # A Mapping of all the BSON types to their corresponding Ruby classes.
+    #
+    # @since 2.0.0
+    MAPPINGS = {}
+
+    # Get the class for the single byte identifier for the type in the BSON
+    # specification.
+    #
+    # @example Get the type for the byte.
+    #   BSON::Registry.get("\x01")
+    #
+    # @return [ Class ] The corresponding Ruby class for the type.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def get(byte)
+      MAPPINGS.fetch(byte)
+    end
+
+    # Register the Ruby type for the corresponding single byte.
+    #
+    # @example Register the type.
+    #   BSON::Registry.register("\x01", Float)
+    #
+    # @param [ String ] byte The single byte.
+    # @param [ Class ] The class the byte maps to.
+    #
+    # @return [ Class ] The class.
+    #
+    # @since 2.0.0
+    def register(byte, type)
+      MAPPINGS.store(byte, type)
+      define_type_reader(type)
+    end
+
+    private
+
+    def define_type_reader(type)
+      type.module_eval <<-MOD
+        def bson_type; BSON_TYPE; end
+      MOD
+    end
+  end
+end

data/lib/bson/specialized.rb

@@ -0,0 +1,61 @@
+# encoding: utf-8
+module BSON
+
+  # Provides behaviour to special values that exist in the BSON spec that don't
+  # have a native type, like $minKey and $maxKey.
+  #
+  # @see http://bsonspec.org/#/specification
+  #
+  # @since 2.0.0
+  module Specialized
+
+    # Determine if the min key is equal to another object.
+    #
+    # @example Check min key equality.
+    #   BSON::MinKey.new == object
+    #
+    # @param [ Object ] other The object to check against.
+    #
+    # @return [ true, false ] If the objects are equal.
+    #
+    # @since 2.0.0
+    def ==(other)
+      self.class == other.class
+    end
+
+    # Encode the min key - has no value since it only needs the type and field
+    # name when being encoded.
+    #
+    # @example Encode the min key value.
+    #   min_key.to_bson
+    #
+    # @return [ String ] An empty string.
+    #
+    # @since 2.0.0
+    def to_bson(encoded = ''.force_encoding(BINARY))
+      encoded
+    end
+
+    private
+
+    def self.included(klass)
+      klass.extend(ClassMethods)
+    end
+
+    module ClassMethods
+
+      # Deserialize MinKey from BSON.
+      #
+      # @param [ BSON ] bson The encoded MinKey.
+      #
+      # @return [ MinKey ] The decoded MinKey.
+      #
+      # @see http://bsonspec.org/#/specification
+      #
+      # @since 2.0.0
+      def from_bson(bson)
+        new
+      end
+    end
+  end
+end

data/lib/bson/string.rb

@@ -0,0 +1,173 @@
+# encoding: utf-8
+module BSON
+
+  # Injects behaviour for encoding and decoding string values to and from
+  # raw bytes as specified by the BSON spec.
+  #
+  # @see http://bsonspec.org/#/specification
+  #
+  # @since 2.0.0
+  module String
+    include Encodable
+
+    # A string is type 0x02 in the BSON spec.
+    #
+    # @since 2.0.0
+    BSON_TYPE = 2.chr.force_encoding(BINARY).freeze
+
+    # Get the string as encoded BSON.
+    #
+    # @example Get the string as encoded BSON.
+    #   "test".to_bson
+    #
+    # @raise [ EncodingError ] If the string is not UTF-8.
+    #
+    # @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|
+        to_bson_string(encoded)
+      end
+    end
+
+    # Get the string as a BSON key name encoded C string with checking for special characters.
+    #
+    # @example Get the string as key name.
+    #   "test".to_bson_key
+    #
+    # @raise [ EncodingError ] If the string is not UTF-8.
+    #
+    # @return [ String ] The encoded string.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def to_bson_key(encoded = ''.force_encoding(BINARY))
+      check_for_illegal_characters!
+      to_bson_cstring(encoded)
+    end
+
+    # Get the string as an encoded C string.
+    #
+    # @example Get the string as an encoded C string.
+    #   "test".to_bson_cstring
+    #
+    # @raise [ EncodingError ] If the string is not UTF-8.
+    #
+    # @return [ String ] The encoded string.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def to_bson_cstring(encoded = ''.force_encoding(BINARY))
+      check_for_illegal_characters!
+      to_bson_string(encoded) << NULL_BYTE
+    end
+
+    # Convert the string to a UTF-8 string then force to binary. This is so
+    # we get errors for strings that are not UTF-8 encoded.
+    #
+    # @example Convert to valid BSON string.
+    #   "Straße".to_bson_string
+    #
+    # @raise [ EncodingError ] If the string is not UTF-8.
+    #
+    # @return [ String ] The binary string.
+    #
+    # @since 2.0.0
+    def to_bson_string(encoded = ''.force_encoding(BINARY))
+      begin
+        to_utf8_binary(encoded)
+      rescue EncodingError
+        data = dup.force_encoding(UTF8)
+        raise unless data.valid_encoding?
+        encoded << data.force_encoding(BINARY)
+      end
+    end
+
+    # Convert the string to a hexidecimal representation.
+    #
+    # @example Convert the string to hex.
+    #   "\x01".to_hex_string
+    #
+    # @return [ String ] The string as hex.
+    #
+    # @since 2.0.0
+    def to_hex_string
+      unpack("H*")[0]
+    end
+
+    # Take the binary string and return a UTF-8 encoded string.
+    #
+    # @example Convert from a BSON string.
+    #   "\x00".from_bson_string
+    #
+    # @raise [ EncodingError ] If the string is not UTF-8.
+    #
+    # @return [ String ] The UTF-8 string.
+    #
+    # @since 2.0.0
+    def from_bson_string
+      force_encoding(UTF8)
+    end
+
+    # Set four bytes for int32 in a binary string and return it.
+    #
+    # @example Set int32 in a BSON string.
+    #   "".set_int32(pos, int32)
+    #
+    # @param [ Fixnum ] The position to set.
+    # @param [ Fixnum ] The int32 value.
+    #
+    # @return [ String ] The binary string.
+    #
+    # @since 2.0.0
+    def set_int32(pos, int32)
+      self[pos, 4] = [ int32 ].pack(Int32::PACK)
+    end
+
+    private
+
+    def to_utf8_binary(encoded)
+      encoded << encode(UTF8).force_encoding(BINARY)
+    end
+
+    module ClassMethods
+
+      # Deserialize a string from BSON.
+      #
+      # @param [ BSON ] bson The bson representing a string.
+      #
+      # @return [ Regexp ] The decoded string.
+      #
+      # @see http://bsonspec.org/#/specification
+      #
+      # @since 2.0.0
+      def from_bson(bson)
+        bson.read(Int32.from_bson(bson)).from_bson_string.chop!
+      end
+    end
+
+    private
+
+    def check_for_illegal_characters!
+      if include?(NULL_BYTE)
+        raise RuntimeError.new("Illegal C-String '#{self}' contains a null byte.")
+      end
+    end
+
+    # Register this type when the module is loaded.
+    #
+    # @since 2.0.0
+    Registry.register(BSON_TYPE, ::String)
+  end
+
+  # Enrich the core String class with this module.
+  #
+  # @since 2.0.0
+  ::String.send(:include, String)
+  ::String.send(:extend, String::ClassMethods)
+end

data/lib/bson/symbol.rb

@@ -0,0 +1,74 @@
+# encoding: utf-8
+module BSON
+
+  # Injects behaviour for encoding and decoding symbol values to and from
+  # raw bytes as specified by the BSON spec.
+  #
+  # @note Symbols are deprecated in the BSON spec, but they are still
+  #   currently supported here for backwards compatibility.
+  #
+  # @see http://bsonspec.org/#/specification
+  #
+  # @since 2.0.0
+  module Symbol
+
+    # A symbol is type 0x0E in the BSON spec.
+    #
+    # @since 2.0.0
+    BSON_TYPE = 14.chr.force_encoding(BINARY).freeze
+
+    # Get the symbol as encoded BSON.
+    #
+    # @example Get the symbol as encoded BSON.
+    #   :test.to_bson
+    #
+    # @return [ Symbol ] The encoded symbol.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def to_bson(encoded = ''.force_encoding(BINARY))
+      to_s.to_bson(encoded)
+    end
+
+    # Get the symbol as a BSON key name encoded C symbol.
+    #
+    # @example Get the symbol as a key name.
+    #   :test.to_bson_key
+    #
+    # @return [ String ] The encoded symbol as a BSON key.
+    #
+    # @see http://bsonspec.org/#/specification
+    #
+    # @since 2.0.0
+    def to_bson_key(encoded = ''.force_encoding(BINARY))
+      to_s.to_bson_cstring(encoded)
+    end
+
+    module ClassMethods
+      # Deserialize a symbol from BSON.
+      #
+      # @param [ BSON ] bson The bson representing a symbol.
+      #
+      # @return [ Regexp ] The decoded symbol.
+      #
+      # @see http://bsonspec.org/#/specification
+      #
+      # @since 2.0.0
+      def from_bson(bson)
+        bson.read(Int32.from_bson(bson)).from_bson_string.chop!.intern
+      end
+    end
+
+    # Register this type when the module is loaded.
+    #
+    # @since 2.0.0
+    Registry.register(BSON_TYPE, ::Symbol)
+  end
+
+  # Enrich the core Symbol class with this module.
+  #
+  # @since 2.0.0
+  ::Symbol.send(:include, Symbol)
+  ::Symbol.send(:extend, Symbol::ClassMethods)
+end