bson 4.1.1 → 5.2.0

data/lib/bson/regexp.rb

@@ -1,4 +1,6 @@
-# Copyright (C) 2009-2015 MongoDB Inc.
+# frozen_string_literal: true
+
+# Copyright (C) 2009-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -12,8 +14,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+# The top-level BSON module.
 module BSON
-
   # Injects behaviour for encoding and decoding regular expression values to
   # and from raw bytes as specified by the BSON spec.
   #
@@ -26,32 +28,34 @@ module BSON
     # A regular expression is type 0x0B in the BSON spec.
     #
     # @since 2.0.0
-    BSON_TYPE = 11.chr.force_encoding(BINARY).freeze
+    BSON_TYPE = ::String.new(11.chr, encoding: BINARY).freeze
 
     # Extended value constant.
     #
     # @since 3.2.6
-    EXTENDED_VALUE = 'x'.freeze
+    EXTENDED_VALUE = 'x'
 
     # Ignore case constant.
     #
     # @since 3.2.6
-    IGNORECASE_VALUE = 'i'.freeze
+    IGNORECASE_VALUE = 'i'
 
     # Multiline constant.
     #
     # @since 3.2.6
-    MULTILINE_VALUE = 'm'.freeze
+    MULTILINE_VALUE = 'm'
 
     # Newline constant.
     #
     # @since 3.2.6
-    NEWLINE_VALUE = 's'.freeze
+    NEWLINE_VALUE = 's'
 
     # Ruby multiline constant.
     #
     # @since 3.2.6
-    RUBY_MULTILINE_VALUE = 'ms'.freeze
+    #
+    # @deprecated Will be removed in 5.0
+    RUBY_MULTILINE_VALUE = 'ms'
 
     # Get the regexp as JSON hash data.
     #
@@ -59,10 +63,8 @@ module BSON
     #   regexp.as_json
     #
     # @return [ Hash ] The regexp as a JSON hash.
-    #
-    # @since 2.0.0
-    def as_json(*args)
-      { "$regex" => source, "$options" => bson_options }
+    def as_json(*)
+      { '$regex' => source, '$options' => bson_options }
     end
 
     # Get the regular expression as encoded BSON.
@@ -79,12 +81,12 @@ module BSON
     #   's' for dotall mode ('.' matches everything),
     #   and 'u' to make \w, \W, etc. match unicode.
     #
-    # @return [ String ] The encoded string.
+    # @param [ BSON::ByteBuffer ] buffer The byte buffer to append to.
     #
-    # @see http://bsonspec.org/#/specification
+    # @return [ BSON::ByteBuffer ] The buffer with the encoded object.
     #
-    # @since 2.0.0
-    def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
+    # @see http://bsonspec.org/#/specification
+    def to_bson(buffer = ByteBuffer.new)
       buffer.put_cstring(source)
       buffer.put_cstring(bson_options)
     end
@@ -92,32 +94,33 @@ module BSON
     private
 
     def bson_options
-      bson_ignorecase + bson_multiline + bson_extended
+      # Ruby's Regexp always has BSON's equivalent of 'm' on, so always add it
+      bson_ignorecase + MULTILINE_VALUE + bson_dotall + bson_extended
     end
 
     def bson_extended
-      (options & ::Regexp::EXTENDED != 0) ? EXTENDED_VALUE : NO_VALUE
+      options.nobits?(::Regexp::EXTENDED) ? NO_VALUE : EXTENDED_VALUE
     end
 
     def bson_ignorecase
-      (options & ::Regexp::IGNORECASE != 0) ? IGNORECASE_VALUE : NO_VALUE
+      options.nobits?(::Regexp::IGNORECASE) ? NO_VALUE : IGNORECASE_VALUE
     end
 
-    def bson_multiline
-      (options & ::Regexp::MULTILINE != 0) ? RUBY_MULTILINE_VALUE : NO_VALUE
+    def bson_dotall
+      # Ruby Regexp's MULTILINE is equivalent to BSON's dotall value
+      options.nobits?(::Regexp::MULTILINE) ? NO_VALUE : NEWLINE_VALUE
     end
 
     # Represents the raw values for the regular expression.
     #
     # @see https://jira.mongodb.org/browse/RUBY-698
-    #
-    # @since 3.0.0
     class Raw
+      include JSON
 
       # @return [ String ] pattern The regex pattern.
       attr_reader :pattern
 
-      # @return [ Integer ] options The options.
+      # @return [ String ] options The options.
       attr_reader :options
 
       # Compile the Regular expression into the native type.
@@ -126,10 +129,8 @@ module BSON
       #   raw.compile
       #
       # @return [ ::Regexp ] The compiled regular expression.
-      #
-      # @since 3.0.0
       def compile
-        @compiled ||= ::Regexp.new(pattern, options)
+        @compile ||= ::Regexp.new(pattern, options_to_int)
       end
 
       # Initialize the new raw regular expression.
@@ -138,69 +139,141 @@ module BSON
       #   Raw.new(pattern, options)
       #
       # @param [ String ] pattern The regular expression pattern.
-      # @param [ Integer ] options The options.
-      #
-      # @since 3.0.0
-      def initialize(pattern, options)
+      # @param [ String | Symbol ] options The options.
+      def initialize(pattern, options = '')
+        if pattern.include?(NULL_BYTE)
+          raise Error::InvalidRegexpPattern, "Regexp pattern cannot contain a null byte: #{pattern}"
+        elsif options.is_a?(String) || options.is_a?(Symbol)
+          if options.to_s.include?(NULL_BYTE)
+            raise Error::InvalidRegexpPattern, "Regexp options cannot contain a null byte: #{options}"
+          end
+        else
+          raise ArgumentError, 'Regexp options must be a String or Symbol'
+        end
+
         @pattern = pattern
-        @options = options
+        @options = options.to_s
       end
 
       # Allow automatic delegation of methods to the Regexp object
       # returned by +compile+.
       #
       # @param [ String] method The name of a method.
+      def respond_to_missing?(method, include_private = false)
+        # YAML calls #respond_to? during deserialization, before the object
+        # is initialized.
+        defined?(@pattern) && compile.respond_to?(method, include_private)
+      end
+
+      # Encode the Raw Regexp object to BSON.
+      #
+      # @example Get the raw regular expression as encoded BSON.
+      #   raw_regexp.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.
+      #
+      # @param [ BSON::ByteBuffer ] buffer The byte buffer to append to.
+      #
+      # @return [ BSON::ByteBuffer ] The buffer with the encoded object.
+      #
+      # @see http://bsonspec.org/#/specification
+      def to_bson(buffer = ByteBuffer.new)
+        buffer.put_cstring(source)
+        buffer.put_cstring(options.chars.sort.join)
+      end
+
+      # Get the raw BSON regexp as JSON hash data.
+      #
+      # @example Get the raw regexp as a JSON hash.
+      #   raw_regexp.as_json
       #
-      # @since 3.1.0
-      def respond_to?(method, include_private = false)
-        compile.respond_to?(method, include_private = false) || super
+      # @return [ Hash ] The raw regexp as a JSON hash.
+      def as_json(*)
+        as_extended_json(mode: :legacy)
       end
 
+      # Converts this object to a representation directly serializable to
+      # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json/extended-json.md).
+      #
+      # @option opts [ nil | :relaxed | :legacy ] :mode Serialization mode
+      #   (default is canonical extended JSON)
+      #
+      # @return [ Hash ] The extended json representation.
+      def as_extended_json(**opts)
+        if opts[:mode] == :legacy
+          { '$regex' => source, '$options' => options }
+        else
+          { '$regularExpression' => { 'pattern' => source, 'options' => options } }
+        end
+      end
+
+      # Check equality of the raw bson regexp against another.
+      #
+      # @example Check if the raw bson regexp is equal to the other.
+      #   raw_regexp == other
+      #
+      # @param [ Object ] other The object to check against.
+      #
+      # @return [ true, false ] If the objects are equal.
+      def ==(other)
+        return false unless other.is_a?(::Regexp::Raw)
+
+        pattern == other.pattern && options == other.options
+      end
+      alias eql? ==
+
       private
 
       def method_missing(method, *arguments)
         return super unless respond_to?(method)
+
         compile.send(method, *arguments)
       end
+
+      def options_to_int
+        opts = 0
+        opts |= ::Regexp::IGNORECASE if options.include?(IGNORECASE_VALUE)
+        opts |= ::Regexp::MULTILINE if options.include?(NEWLINE_VALUE)
+        opts |= ::Regexp::EXTENDED if options.include?(EXTENDED_VALUE)
+        opts
+      end
     end
 
+    # Class-level methods to be added to the Regexp class.
     module ClassMethods
-
       # Deserialize the regular expression from BSON.
       #
+      # @note If the argument cannot be parsed, an exception will be raised
+      #   and the argument will be left in an undefined state. The caller
+      #   must explicitly call `rewind` on the buffer before trying to parse
+      #   it again.
+      #
       # @param [ ByteBuffer ] buffer The byte buffer.
       #
+      # @option opts [ nil | :bson ] :mode Decoding mode to use.
+      #
       # @return [ Regexp ] The decoded regular expression.
       #
       # @see http://bsonspec.org/#/specification
-      #
-      # @since 2.0.0
-      def from_bson(buffer)
+      def from_bson(buffer, **_)
         pattern = buffer.get_cstring
-        options = 0
-        while (option = buffer.get_byte) != NULL_BYTE
-          case option
-          when IGNORECASE_VALUE
-            options |= ::Regexp::IGNORECASE
-          when MULTILINE_VALUE, NEWLINE_VALUE
-            options |= ::Regexp::MULTILINE
-          when EXTENDED_VALUE
-            options |= ::Regexp::EXTENDED
-          end
-        end
+        options = buffer.get_cstring
         Raw.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)
+  ::Regexp.include Regexp
+  ::Regexp.extend Regexp::ClassMethods
 end

data/lib/bson/registry.rb

@@ -1,4 +1,6 @@
-# Copyright (C) 2009-2014 MongoDB Inc.
+# frozen_string_literal: true
+# rubocop:todo all
+# Copyright (C) 2009-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -40,7 +42,7 @@ module BSON
     #
     # @since 2.0.0
     def get(byte, field = nil)
-      if type = MAPPINGS[byte]
+      if type = MAPPINGS[byte] || (byte.is_a?(String) && type = MAPPINGS[byte.ord])
         type
       else
         handle_unsupported_type!(byte, field)
@@ -53,21 +55,16 @@ module BSON
     #   BSON::Registry.register("\x01", Float)
     #
     # @param [ String ] byte The single byte.
-    # @param [ Class ] The class the byte maps to.
+    # @param [ Class ] type The class the byte maps to.
     #
     # @return [ Class ] The class.
     #
     # @since 2.0.0
     def register(byte, type)
-      MAPPINGS.store(byte, type)
+      MAPPINGS[byte.ord] = type
       define_type_reader(type)
     end
 
-    # Raised when trying to get a type from the registry that doesn't exist.
-    #
-    # @since 4.1.0
-    class UnsupportedType < RuntimeError; end
-
     private
 
     def define_type_reader(type)
@@ -80,7 +77,7 @@ module BSON
       message = "Detected unknown BSON type #{byte.inspect} "
       message += (field ? "for fieldname \"#{field}\". " : "in array. ")
       message +="Are you using the latest BSON version?"
-      raise UnsupportedType.new(message)
+      raise Error::UnsupportedType.new(message)
     end
   end
 end

data/lib/bson/specialized.rb

@@ -1,4 +1,6 @@
-# Copyright (C) 2009-2014 MongoDB Inc.
+# frozen_string_literal: true
+# rubocop:todo all
+# Copyright (C) 2009-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -42,10 +44,10 @@ module BSON
     # @example Encode the min key value.
     #   min_key.to_bson
     #
-    # @return [ String ] An empty string.
+    # @return [ BSON::ByteBuffer ] The buffer with the encoded object.
     #
     # @since 2.0.0
-    def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
+    def to_bson(buffer = ByteBuffer.new)
       buffer
     end
 
@@ -61,12 +63,14 @@ module BSON
       #
       # @param [ ByteBuffer ] buffer The byte buffer.
       #
+      # @option options [ nil | :bson ] :mode Decoding mode to use.
+      #
       # @return [ Specialized ] The decoded specialized class.
       #
       # @see http://bsonspec.org/#/specification
       #
       # @since 2.0.0
-      def from_bson(buffer)
+      def from_bson(buffer, **options)
         new
       end
     end

data/lib/bson/string.rb

@@ -1,5 +1,7 @@
+# rubocop:todo all
 # -*- coding: utf-8 -*-
-# Copyright (C) 2009-2014 MongoDB Inc.
+# frozen_string_literal: true
+# Copyright (C) 2009-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -26,12 +28,12 @@ module BSON
     # A string is type 0x02 in the BSON spec.
     #
     # @since 2.0.0
-    BSON_TYPE = 2.chr.force_encoding(BINARY).freeze
+    BSON_TYPE = ::String.new(2.chr, encoding: BINARY).freeze
 
     # Regex for matching illegal BSON keys.
     #
     # @since 4.1.0
-    ILLEGAL_KEY = /(\A[$])|(\.)/.freeze
+    ILLEGAL_KEY = /(\A[$])|(\.)/
 
     # Get the string as encoded BSON.
     #
@@ -40,12 +42,12 @@ module BSON
     #
     # @raise [ EncodingError ] If the string is not UTF-8.
     #
-    # @return [ String ] The encoded string.
+    # @return [ BSON::ByteBuffer ] The buffer with the encoded object.
     #
     # @see http://bsonspec.org/#/specification
     #
     # @since 2.0.0
-    def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
+    def to_bson(buffer = ByteBuffer.new)
       buffer.put_string(self)
     end
 
@@ -56,18 +58,12 @@ module BSON
     #
     # @raise [ EncodingError ] If the string is not UTF-8.
     #
-    # @raise [ IllegalKey ] If validating keys and it contains a '.' or starts
-    #   with '$'.
-    #
     # @return [ String ] The encoded string.
     #
     # @see http://bsonspec.org/#/specification
     #
     # @since 2.0.0
-    def to_bson_key(validating_keys = Config.validating_keys?)
-      if validating_keys
-        raise IllegalKey.new(self) if ILLEGAL_KEY =~ self
-      end
+    def to_bson_key
       self
     end
 
@@ -79,7 +75,7 @@ module BSON
     #
     # @note This is used for repairing legacy bson data.
     #
-    # @raise [ InvalidObjectId ] If the string is not 12 elements.
+    # @raise [ BSON::Error::InvalidObjectId ] If the string is not 12 elements.
     #
     # @return [ String ] The raw object id bytes.
     #
@@ -100,36 +96,20 @@ module BSON
       unpack("H*")[0]
     end
 
-    # Raised when validating keys and a key is illegal in MongoDB
-    #
-    # @since 4.1.0
-    class IllegalKey < RuntimeError
-
-      # Instantiate the exception.
-      #
-      # @example Instantiate the exception.
-      #   BSON::Object::IllegalKey.new(string)
-      #
-      # @param [ String ] string The illegal string.
-      #
-      # @since 4.1.0
-      def initialize(string)
-        super("'#{string}' is an illegal key in MongoDB. Keys may not start with '$' or contain a '.'.")
-      end
-    end
-
     module ClassMethods
 
       # Deserialize a string from BSON.
       #
       # @param [ ByteBuffer ] buffer The byte buffer.
       #
+      # @option options [ nil | :bson ] :mode Decoding mode to use.
+      #
       # @return [ Regexp ] The decoded string.
       #
       # @see http://bsonspec.org/#/specification
       #
       # @since 2.0.0
-      def from_bson(buffer)
+      def from_bson(buffer, **options)
         buffer.get_string
       end
     end

data/lib/bson/symbol.rb

@@ -1,4 +1,6 @@
-# Copyright (C) 2009-2014 MongoDB Inc.
+# frozen_string_literal: true
+# rubocop:todo all
+# Copyright (C) 2009-2020 MongoDB Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -28,7 +30,7 @@ module BSON
     # A symbol is type 0x0E in the BSON spec.
     #
     # @since 2.0.0
-    BSON_TYPE = 14.chr.force_encoding(BINARY).freeze
+    BSON_TYPE = ::String.new(14.chr, encoding: BINARY).freeze
 
     # Symbols are serialized as strings as symbols are now removed from the
     # BSON specification. Therefore the bson_type when serializing must be a
@@ -51,13 +53,13 @@ module BSON
     # @example Get the symbol as encoded BSON.
     #   :test.to_bson
     #
-    # @return [ Symbol ] The encoded symbol.
+    # @return [ BSON::ByteBuffer ] The buffer with the encoded object.
     #
     # @see http://bsonspec.org/#/specification
     #
     # @since 2.0.0
-    def to_bson(buffer = ByteBuffer.new, validating_keys = Config.validating_keys?)
-      to_s.to_bson(buffer)
+    def to_bson(buffer = ByteBuffer.new)
+      buffer.put_symbol(self)
     end
 
     # Get the symbol as a BSON key name encoded C symbol.
@@ -70,8 +72,8 @@ module BSON
     # @see http://bsonspec.org/#/specification
     #
     # @since 2.0.0
-    def to_bson_key(validating_keys = Config.validating_keys?)
-      to_s.to_bson_key(validating_keys)
+    def to_bson_key
+      self
     end
 
     # Converts the symbol to a normalized key in a BSON document.
@@ -86,26 +88,120 @@ module BSON
       to_s
     end
 
+    # Converts this object to a representation directly serializable to
+    # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json/extended-json.md).
+    #
+    # @return [ Hash ] The extended json representation.
+    def as_extended_json(**_options)
+      { "$symbol" => to_s }
+    end
+
+    class Raw
+      include JSON
+
+      # Create a BSON Symbol
+      #
+      # @param [ String | Symbol ] str_or_sym The symbol represented by this
+      #   object. Can be specified as a Symbol or a String.
+      #
+      # @see http://bsonspec.org/#/specification
+      def initialize(str_or_sym)
+        unless str_or_sym.is_a?(String) || str_or_sym.is_a?(Symbol)
+          raise ArgumentError, "BSON::Symbol::Raw must be given a symbol or a string, not #{str_or_sym}"
+        end
+
+        @symbol = str_or_sym.to_sym
+      end
+
+      # Get the underlying symbol as a Ruby symbol.
+      #
+      # @return [ Symbol ] The symbol represented by this BSON object.
+      def to_sym
+        @symbol
+      end
+
+      # Get the underlying symbol as a Ruby string.
+      #
+      # @return [ String ] The symbol as a string.
+      def to_s
+        @symbol.to_s
+      end
+
+      # Check equality of the raw bson symbol against another.
+      #
+      # @param [ Object ] other The object to check against.
+      #
+      # @return [ true, false ] If the objects are equal.
+      def ==(other)
+        return false unless other.is_a?(Raw)
+        to_sym == other.to_sym
+      end
+      alias :eql? :==
+
+      # Get the symbol as encoded BSON.
+      #
+      # @raise [ EncodingError ] If the symbol is not UTF-8.
+      #
+      # @return [ BSON::ByteBuffer ] The buffer with the encoded object.
+      #
+      # @see http://bsonspec.org/#/specification
+      def to_bson(buffer = ByteBuffer.new)
+        buffer.put_string(to_s)
+      end
+
+      def bson_type
+        Symbol::BSON_TYPE
+      end
+
+      # Return a string representation of the raw symbol for use in
+      # application-level JSON serialization. This method is intentionally
+      # different from #as_extended_json.
+      #
+      # @example Get the raw symbol as a JSON-serializable object.
+      #   raw_symbol.as_json
+      #
+      # @return [ String ] The raw symbol as a String.
+      def as_json(*args)
+        to_s
+      end
+
+      # Converts this object to a representation directly serializable to
+      # Extended JSON (https://github.com/mongodb/specifications/blob/master/source/extended-json/extended-json.md).
+      #
+      # @return [ Hash ] The extended json representation.
+      def as_extended_json(**_options)
+        { '$symbol' => to_s }
+      end
+    end
+
     module ClassMethods
 
       # Deserialize a symbol from BSON.
       #
       # @param [ ByteBuffer ] buffer The byte buffer.
       #
-      # @return [ Regexp ] The decoded symbol.
+      # @option options [ nil | :bson ] :mode Decoding mode to use.
+      #
+      # @return [ Symbol | BSON::Symbol::Raw ] The decoded symbol.
       #
       # @see http://bsonspec.org/#/specification
       #
       # @since 2.0.0
-      def from_bson(buffer)
-        buffer.get_string.intern
+      def from_bson(buffer, **options)
+        sym = buffer.get_string.intern
+
+        if options[:mode] == :bson
+          Raw.new(sym)
+        else
+          sym
+        end
       end
     end
 
     # Register this type when the module is loaded.
     #
     # @since 2.0.0
-    Registry::MAPPINGS.store(BSON_TYPE, ::Symbol)
+    Registry::MAPPINGS[BSON_TYPE.ord] = ::Symbol
   end
 
   # Enrich the core Symbol class with this module.