mongoid 7.1.0.rc0 → 7.1.5

data/lib/mongoid/criteria/modifiable.rb

@@ -74,7 +74,8 @@ module Mongoid
       # @since 5.1.0
       def create_with(attrs = {})
         tap do
-          (@create_attrs ||= {}).merge!(attrs)
+          @create_attrs ||= {}
+          @create_attrs.update(attrs)
         end
       end
 

data/lib/mongoid/criteria/queryable/extensions/numeric.rb

@@ -60,7 +60,7 @@ module Mongoid
             #
             # @since 1.0.0
             def __numeric__(object)
-              object.to_s =~ /(^[-+]?[0-9]+$)|(\.0+$)|(\.$)/ ? object.to_i : Float(object)
+              object.to_s =~ /(\A[-+]?[0-9]+\z)|(\.0+\z)|(\.\z)/ ? object.to_i : Float(object)
             end
 
             # Evolve the object to an integer.

data/lib/mongoid/criteria/queryable/extensions/regexp.rb

@@ -12,7 +12,7 @@ module Mongoid
           # Is the object a regexp?
           #
           # @example Is the object a regex?
-          #   /^[123]/.regexp?
+          #   /\A[123]/.regexp?
           #
           # @return [ true ] Always true.
           #
@@ -24,7 +24,7 @@ module Mongoid
             # Evolve the object into a regex.
             #
             # @example Evolve the object to a regex.
-            #   Regexp.evolve("^[123]")
+            #   Regexp.evolve("\A[123]")
             #
             # @param [ Regexp, String ] object The object to evolve.
             #
@@ -38,7 +38,7 @@ module Mongoid
             end
           end
 
-          module Raw
+          module Raw_
 
             # Is the object a regexp?
             #
@@ -55,7 +55,7 @@ module Mongoid
               # Evolve the object into a raw bson regex.
               #
               # @example Evolve the object to a regex.
-              #   BSON::Regexp::Raw.evolve("^[123]")
+              #   BSON::Regexp::Raw.evolve("\\A[123]")
               #
               # @param [ BSON::Regexp::Raw, String ] object The object to evolve.
               #
@@ -77,5 +77,5 @@ end
 
 ::Regexp.__send__(:include,Mongoid::Criteria::Queryable::Extensions::Regexp)
 ::Regexp.__send__(:extend, Mongoid::Criteria::Queryable::Extensions::Regexp::ClassMethods)
-BSON::Regexp::Raw.__send__(:include,Mongoid::Criteria::Queryable::Extensions::Regexp::Raw)
-BSON::Regexp::Raw.__send__(:extend, Mongoid::Criteria::Queryable::Extensions::Regexp::Raw::ClassMethods)
+BSON::Regexp::Raw.__send__(:include,Mongoid::Criteria::Queryable::Extensions::Regexp::Raw_)
+BSON::Regexp::Raw.__send__(:extend, Mongoid::Criteria::Queryable::Extensions::Regexp::Raw_::ClassMethods)

data/lib/mongoid/criteria/queryable/extensions/time_with_zone.rb

@@ -9,6 +9,18 @@ module Mongoid
         # This module contains additional time with zone behavior.
         module TimeWithZone
 
+          # Evolve the time as a date, UTC midnight.
+          #
+          # @example Evolve the time to a date query format.
+          #   time.__evolve_date__
+          #
+          # @return [ Time ] The date at midnight UTC.
+          #
+          # @since 1.0.0
+          def __evolve_date__
+            ::Time.utc(year, month, day, 0, 0, 0, 0)
+          end
+
           # Evolve the time into a utc time.
           #
           # @example Evolve the time.

data/lib/mongoid/criteria/queryable/mergeable.rb

@@ -163,7 +163,7 @@ module Mongoid
               if expr.is_a?(Selectable)
                 expr = expr.selector
               end
-              normalized = _mongoid_normalize_expr(expr)
+              normalized = _mongoid_expand_keys(expr)
               sel.store(operator, result_criteria.push(normalized))
             end
           end
@@ -190,9 +190,9 @@ module Mongoid
             sel = query.selector
             _mongoid_flatten_arrays(criteria).each do |criterion|
               if criterion.is_a?(Selectable)
-                expr = _mongoid_normalize_expr(criterion.selector)
+                expr = _mongoid_expand_keys(criterion.selector)
               else
-                expr = criterion
+                expr = _mongoid_expand_keys(criterion)
               end
               if sel.empty?
                 sel.store(operator, [expr])
@@ -212,7 +212,7 @@ module Mongoid
         # explicitly only expands Array objects and Array subclasses.
         private def _mongoid_flatten_arrays(array)
           out = []
-          pending = array
+          pending = array.dup
           until pending.empty?
             item = pending.shift
             if item.nil?
@@ -226,11 +226,78 @@ module Mongoid
           out
         end
 
-        # @api private
-        private def _mongoid_normalize_expr(expr)
-          expr.inject({}) do |hash, (field, value)|
-            hash.merge!(field.__expr_part__(value.__expand_complex__))
+        # Takes a criteria hash and expands Key objects into hashes containing
+        # MQL corresponding to said key objects.
+        #
+        # Ruby does not permit multiple symbol operators. For example,
+        # {:foo.gt => 1, :foo.gt => 2} is collapsed to {:foo.gt => 2} by the
+        # language. Therefore this method never has to deal with multiple
+        # identical operators.
+        #
+        # Similarly, this method should never need to expand a literal value
+        # and an operator at the same time.
+        #
+        # @param [ Hash ] Criteria including Key instances.
+        #
+        # @return [ Hash ] Expanded criteria.
+        private def _mongoid_expand_keys(expr)
+          unless expr.is_a?(Hash)
+            raise ArgumentError, 'Argument must be a Hash'
+          end
+
+          result = {}
+          expr.each do |field, value|
+            field.__expr_part__(value.__expand_complex__).each do |k, v|
+              if result[k]
+                if result[k].is_a?(Hash)
+                  # Existing value is an operator.
+                  # If new value is also an operator, ensure there are no
+                  # conflicts and add
+                  if v.is_a?(Hash)
+                    # The new value is also an operator.
+                    # If there are no conflicts, combine the hashes, otherwise
+                    # add new conditions to top level with $and.
+                    if (v.keys & result[k].keys).empty?
+                      result[k].update(v)
+                    else
+                      raise NotImplementedError, 'Ruby does not allow same symbol operator with different values'
+                      result['$and'] ||= []
+                      result['$and'] << {k => v}
+                    end
+                  else
+                    # The new value is a simple value.
+                    # If there isn't an $eq operator already in the query,
+                    # transform the new value into an $eq operator and add it
+                    # to the existing hash. Otherwise add the new condition
+                    # with $and to the top level.
+                    if result[k].key?('$eq')
+                      raise NotImplementedError, 'Ruby does not allow same symbol operator with different values'
+                      result['$and'] ||= []
+                      result['$and'] << {k => v}
+                    else
+                      result[k].update('$eq' => v)
+                    end
+                  end
+                else
+                  # Existing value is a simple value.
+                  # If we are adding an operator, and the operator is not $eq,
+                  # convert existing value into $eq and add the new operator
+                  # to the same hash. Otherwise add the new condition with $and
+                  # to the top level.
+                  if v.is_a?(Hash) && !v.key?('$eq')
+                    result[k] = {'$eq' => result[k]}.update(v)
+                  else
+                    raise NotImplementedError, 'Ruby does not allow same symbol operator with different values'
+                    result['$and'] ||= []
+                    result['$and'] << {k => v}
+                  end
+                end
+              else
+                result[k] = v
+              end
+            end
           end
+          result
         end
 
         # Adds the criterion to the existing selection.

data/lib/mongoid/criteria/queryable/pipeline.rb

@@ -33,7 +33,7 @@ module Mongoid
         # Add a group operation to the aggregation pipeline.
         #
         # @example Add a group operation.
-        #   pipeline.group(:count.sum => 1, :max.max => "likes")
+        #   pipeline.group(:_id => "foo", :count.sum => 1, :max.max => "likes")
         #
         # @param [ Hash ] entry The group entry.
         #
@@ -76,7 +76,8 @@ module Mongoid
         #   pipeline.unwind(:field)
         #   pipeline.unwind(document)
         #
-        # @param [ String, Symbol, Hash ] field_or_doc The name of the field or a document.
+        # @param [ String, Symbol, Hash ] field_or_doc A field name or a
+        #   document.
         #
         # @return [ Pipeline ] The pipeline.
         #

data/lib/mongoid/criteria/queryable/selectable.rb

@@ -89,11 +89,27 @@ module Mongoid
             if new_s.is_a?(Selectable)
               new_s = new_s.selector
             end
-            normalized = _mongoid_normalize_expr(new_s)
+            normalized = _mongoid_expand_keys(new_s)
             normalized.each do |k, v|
               k = k.to_s
-              if c.selector[k] || k[0] == ?$
-                c = c.send(:__multi__, [{k => v}], '$and')
+              if c.selector[k]
+                # There is already a condition on k.
+                # If v is an operator, and all existing conditions are
+                # also operators, and v isn't present in existing conditions,
+                # we can add to existing conditions.
+                # Otherwise use $and.
+                if v.is_a?(Hash) &&
+                  v.length == 1 &&
+                  (new_k = v.keys.first).start_with?('$') &&
+                  (existing_kv = c.selector[k]).is_a?(Hash) &&
+                  !existing_kv.key?(new_k) &&
+                  existing_kv.keys.all? { |sub_k| sub_k.start_with?('$') }
+                then
+                  merged_v = c.selector[k].merge(v)
+                  c.selector.store(k, merged_v)
+                else
+                  c = c.send(:__multi__, [k => v], '$and')
+                end
               else
                 c.selector.store(k, v)
               end
@@ -567,17 +583,21 @@ module Mongoid
               if new_s.is_a?(Selectable)
                 new_s = new_s.selector
               end
-              new_s.each do |k, v|
+              _mongoid_expand_keys(new_s).each do |k, v|
                 k = k.to_s
                 if c.selector[k] || k[0] == ?$
                   c = c.send(:__multi__, [{'$nor' => [{k => v}]}], '$and')
                 else
-                  if v.is_a?(Regexp)
-                    negated_operator = '$not'
+                  if v.is_a?(Hash)
+                    c = c.send(:__multi__, [{'$nor' => [{k => v}]}], '$and')
                   else
-                    negated_operator = '$ne'
+                    if v.is_a?(Regexp)
+                      negated_operator = '$not'
+                    else
+                      negated_operator = '$ne'
+                    end
+                    c = c.send(:__override__, {k => v}, negated_operator)
                   end
-                  c = c.send(:__override__, {k => v}, negated_operator)
                 end
               end
               c
@@ -586,13 +606,34 @@ module Mongoid
         end
         key :not, :override, "$not"
 
-        # Adds $or selection to the selectable.
+        # Creates a disjunction using $or from the existing criteria in the
+        # receiver and the provided arguments.
+        #
+        # This behavior (receiver becoming one of the disjunction operands)
+        # matches ActiveRecord's +or+ behavior.
+        #
+        # Use +any_of+ to add a disjunction of the arguments as an additional
+        # constraint to the criteria already existing in the receiver.
+        #
+        # Each argument can be a Hash, a Criteria object, an array of
+        # Hash or Criteria objects, or a nested array. Nested arrays will be
+        # flattened and can be of any depth. Passing arrays is deprecated.
         #
-        # @example Add the $or selection.
+        # @example Add the $or selection where both fields must have the specified values.
         #   selectable.or(field: 1, field: 2)
         #
-        # @param [ Array<Hash | Criteria> ] criteria Multiple key/value pair
-        #   matches or Criteria objects.
+        # @example Add the $or selection where either value match is sufficient.
+        #   selectable.or({field: 1}, {field: 2})
+        #
+        # @example Same as previous example but using the deprecated array wrap.
+        #   selectable.or([{field: 1}, {field: 2}])
+        #
+        # @example Same as previous example, also deprecated.
+        #   selectable.or([{field: 1}], [{field: 2}])
+        #
+        # @param [ Hash | Criteria | Array<Hash | Criteria>, ... ] criteria
+        #   Multiple key/value pair matches or Criteria objects, or arrays
+        #   thereof. Passing arrays is deprecated.
         #
         # @return [ Selectable ] The new selectable.
         #
@@ -600,7 +641,73 @@ module Mongoid
         def or(*criteria)
           _mongoid_add_top_level_operation('$or', criteria)
         end
-        alias :any_of :or
+
+        # Adds a disjunction of the arguments as an additional constraint
+        # to the criteria already existing in the receiver.
+        #
+        # Use +or+ to make the receiver one of the disjunction operands.
+        #
+        # Each argument can be a Hash, a Criteria object, an array of
+        # Hash or Criteria objects, or a nested array. Nested arrays will be
+        # flattened and can be of any depth. Passing arrays is deprecated.
+        #
+        # @example Add the $or selection where both fields must have the specified values.
+        #   selectable.any_of(field: 1, field: 2)
+        #
+        # @example Add the $or selection where either value match is sufficient.
+        #   selectable.any_of({field: 1}, {field: 2})
+        #
+        # @example Same as previous example but using the deprecated array wrap.
+        #   selectable.any_of([{field: 1}, {field: 2}])
+        #
+        # @example Same as previous example, also deprecated.
+        #   selectable.any_of([{field: 1}], [{field: 2}])
+        #
+        # @param [ Hash | Criteria | Array<Hash | Criteria>, ... ] criteria
+        #   Multiple key/value pair matches or Criteria objects, or arrays
+        #   thereof. Passing arrays is deprecated.
+        #
+        # @return [ Selectable ] The new selectable.
+        #
+        # @since 1.0.0
+        def any_of(*criteria)
+          criteria = _mongoid_flatten_arrays(criteria)
+          case criteria.length
+          when 0
+            clone
+          when 1
+            # When we have a single criteria, any_of behaves like and.
+            # Note: criteria can be a Query object, which #where method does
+            # not support.
+            self.and(*criteria)
+          else
+            # When we have multiple criteria, combine them all with $or
+            # and add the result to self.
+            exprs = criteria.map do |criterion|
+              if criterion.is_a?(Selectable)
+                _mongoid_expand_keys(criterion.selector)
+              else
+                Hash[criterion.map do |k, v|
+                  if k.is_a?(Symbol)
+                    [k.to_s, v]
+                  else
+                    [k, v]
+                  end
+                end]
+              end
+            end
+            # Should be able to do:
+            #where('$or' => exprs)
+            # But since that is broken do instead:
+            clone.tap do |query|
+              if query.selector['$or']
+                query.selector.store('$or', query.selector['$or'] + exprs)
+              else
+                query.selector.store('$or', exprs)
+              end
+            end
+          end
+        end
 
         # Add a $size selection for array fields.
         #

data/lib/mongoid/criteria/queryable/storable.rb

@@ -17,67 +17,49 @@ module Mongoid
       # @api private
       module Storable
 
-        # Adds an operator expression to the selector.
-        #
-        # This method takes the operator and the operator value expression
-        # separately for callers' convenience. It can be considered to
-        # handle storing the hash `{operator => op_expr}`.
-        #
-        # If the selector already has the specified operator in it (on the
-        # top level), the new condition given in op_expr is added to the
-        # existing conditions for the specified operator. This is
-        # straightforward for $and; for other logical operators, the behavior
-        # of this method is to add the new conditions to the existing operator.
-        # For example, if the selector is currently:
-        #
-        #     {'foo' => 'bar', '$or' => [{'hello' => 'world'}]}
-        #
-        # ... and operator is '$or' and op_expr is `{'test' => 123'}`,
-        # the resulting selector will be:
-        #
-        #     {'foo' => 'bar', '$or' => [{'hello' => 'world'}, {'test' => 123}]}
+        # Adds a field expression to the query.
         #
-        # This does not implement an OR between the existing selector and the
-        # new operator expression - handling this is the job of upstream
-        # methods. This method simply stores op_expr into the selector on the
-        # assumption that the existing selector is the correct left hand side
-        # of the operation already.
+        # +field+ must be a field name, and it must be a string. The upstream
+        # code must have converted other field/key types to the simple string
+        # form by the time this method is invoked.
         #
-        # For non-logical query-level operators like $where and $text, if
-        # there already is a top-level operator with the same name, the
-        # op_expr is added to the selector via a top-level $and operator,
-        # thus producing a selector having both operator values.
+        # +value+ can be of any type, it is written into the selector unchanged.
         #
-        # This method does not simplify values (i.e. if the selector is
-        # currently empty and operator is $and, op_expr is written to the
-        # selector with $and even if the $and can in principle be elided).
+        # This method performs no processing on the provided field value.
         #
-        # This method mutates the receiver.
+        # Mutates the receiver.
         #
-        # @param [ String ] operator The operator to add.
-        # @param [ Hash ] op_expr Operator value to add.
+        # @param [ String ] field The field name.
+        # @param [ Object ] value The field value.
         #
         # @return [ Storable ] self.
-        def add_operator_expression(operator, op_expr)
-          unless operator.is_a?(String)
-            raise ArgumentError, "Operator must be a string: #{operator}"
-          end
-
-          unless operator[0] == ?$
-            raise ArgumentError, "Operator must begin with $: #{operator}"
+        def add_field_expression(field, value)
+          unless field.is_a?(String)
+            raise ArgumentError, "Field must be a string: #{field}"
           end
 
-          if %w($and $nor $or).include?(operator)
-            return add_logical_operator_expression(operator, op_expr)
+          if field[0] == ?$
+            raise ArgumentError, "Field cannot be an operator (i.e. begin with $): #{field}"
           end
 
-          # For other operators, if the operator already exists in the
-          # query, add the new condition with $and, otherwise add the
-          # new condition to the top level.
-          if selector[operator]
-            add_logical_operator_expression('$and', [{operator => op_expr}])
+          if selector[field]
+            # We already have a restriction by the field we are trying
+            # to restrict, combine the restrictions.
+            if value.is_a?(Hash) && selector[field].is_a?(Hash) &&
+              value.keys.all? { |key|
+                key_s = key.to_s
+                key_s[0] == ?$ && !selector[field].key?(key_s)
+              }
+            then
+              # Multiple operators can be combined on the same field by
+              # adding them to the existing hash.
+              new_value = selector[field].merge(value)
+              selector.store(field, new_value)
+            else
+              add_operator_expression('$and', [{field => value}])
+            end
           else
-            selector.store(operator, op_expr)
+            selector.store(field, value)
           end
 
           self
@@ -87,41 +69,40 @@ module Mongoid
         #
         # This method only handles logical operators ($and, $nor and $or).
         # It raises ArgumentError if called with another operator. Note that
-        # in MongoDB, $not is a field-level operator and not a query-level one
-        # $not is not handled by this method as a result.
+        # in MQL, $not is a field-level operator and not a query-level one,
+        # and therefore $not is not handled by this method.
         #
         # This method takes the operator and the operator value expression
         # separately for callers' convenience. It can be considered to
         # handle storing the hash `{operator => op_expr}`.
         #
-        # If the selector already has the specified operator in it (on the
-        # top level), the new condition given in op_expr is added to the
-        # existing conditions for the specified operator. This is
-        # straightforward for $and; for other logical operators, the behavior
-        # of this method is to add the new conditions to the existing operator.
+        # If the selector consists of a single condition which is the specified
+        # operator (on the top level), the new condition given in op_expr is
+        # added to the existing conditions for the specified operator.
         # For example, if the selector is currently:
         #
-        #     {'foo' => 'bar', '$or' => [{'hello' => 'world'}]}
+        #     {'$or' => [{'hello' => 'world'}]}
         #
-        # ... and operator is '$or' and op_expr is `{'test' => 123'}`,
+        # ... and operator is '$or' and op_expr is `[{'test' => 123'}]`,
         # the resulting selector will be:
         #
-        #     {'foo' => 'bar', '$or' => [{'hello' => 'world'}, {'test' => 123}]}
+        #     {'$or' => [{'hello' => 'world'}, {'test' => 123}]}
         #
-        # This does not implement an OR between the existing selector and the
-        # new operator expression - handling this is the job of upstream
-        # methods. This method simply stores op_expr into the selector on the
-        # assumption that the existing selector is the correct left hand side
-        # of the operation already.
+        # This method always adds the new conditions as additional requirements;
+        # in other words, it does not implement the ActiveRecord or/nor behavior
+        # where the receiver becomes one of the operands. It is expected that
+        # code upstream of this method implements such behavior.
         #
         # This method does not simplify values (i.e. if the selector is
         # currently empty and operator is $and, op_expr is written to the
         # selector with $and even if the $and can in principle be elided).
+        # Such simplification is also expected to have already been performed
+        # by the upstream code.
         #
         # This method mutates the receiver.
         #
         # @param [ String ] operator The operator to add.
-        # @param [ Hash ] op_expr Operator value to add.
+        # @param [ Array<Hash> ] op_expr Operator value to add.
         #
         # @return [ Storable ] self.
         def add_logical_operator_expression(operator, op_expr)
@@ -145,56 +126,80 @@ module Mongoid
             # with whatever other conditions exist.
             selector.store(operator, op_expr)
           else
-            # Other operators need to operate explicitly on the previous
-            # conditions and the new condition.
-            new_value = [selector.to_hash.dup] + op_expr
-            selector.replace(operator => new_value)
+            # Other operators need to be added separately
+            if selector[operator]
+              add_logical_operator_expression('$and', [operator => op_expr])
+            else
+              selector.store(operator, op_expr)
+            end
           end
 
           self
         end
 
-        # Adds a field expression to the query.
+        # Adds an operator expression to the selector.
         #
-        # field must be a field name, and it must be a string. The upstream
-        # code must have converted other field/key types to the simple string
-        # form by the time this method is invoked.
+        # This method takes the operator and the operator value expression
+        # separately for callers' convenience. It can be considered to
+        # handle storing the hash `{operator => op_expr}`.
         #
-        # This method performs no processing on the provided field value.
+        # The operator value can be of any type.
         #
-        # Mutates the receiver.
+        # If the selector already has the specified operator in it (on the
+        # top level), the new condition given in op_expr is added to the
+        # existing conditions for the specified operator. This is
+        # straightforward for $and; for other logical operators, the behavior
+        # of this method is to add the new conditions to the existing operator.
+        # For example, if the selector is currently:
         #
-        # @param [ String ] field The field name.
-        # @param [ Object ] value The field value.
+        #     {'foo' => 'bar', '$or' => [{'hello' => 'world'}]}
+        #
+        # ... and operator is '$or' and op_expr is `{'test' => 123'}`,
+        # the resulting selector will be:
+        #
+        #     {'foo' => 'bar', '$or' => [{'hello' => 'world'}, {'test' => 123}]}
+        #
+        # This does not implement an OR between the existing selector and the
+        # new operator expression - handling this is the job of upstream
+        # methods. This method simply stores op_expr into the selector on the
+        # assumption that the existing selector is the correct left hand side
+        # of the operation already.
+        #
+        # For non-logical query-level operators like $where and $text, if
+        # there already is a top-level operator with the same name, the
+        # op_expr is added to the selector via a top-level $and operator,
+        # thus producing a selector having both operator values.
+        #
+        # This method does not simplify values (i.e. if the selector is
+        # currently empty and operator is $and, op_expr is written to the
+        # selector with $and even if the $and can in principle be elided).
+        #
+        # This method mutates the receiver.
+        #
+        # @param [ String ] operator The operator to add.
+        # @param [ Object ] op_expr Operator value to add.
         #
         # @return [ Storable ] self.
-        def add_field_expression(field, value)
-          unless field.is_a?(String)
-            raise ArgumentError, "Field must be a string: #{field}"
+        def add_operator_expression(operator, op_expr)
+          unless operator.is_a?(String)
+            raise ArgumentError, "Operator must be a string: #{operator}"
           end
 
-          if field[0] == ?$
-            raise ArgumentError, "Field cannot be an operator (i.e. begin with $): #{field}"
+          unless operator[0] == ?$
+            raise ArgumentError, "Operator must begin with $: #{operator}"
           end
 
-          if selector[field]
-            # We already have a restriction by the field we are trying
-            # to restrict, combine the restrictions.
-            if value.is_a?(Hash) && selector[field].is_a?(Hash) &&
-              value.keys.all? { |key|
-                key_s = key.to_s
-                key_s[0] == ?$ && !selector[field].key?(key_s)
-              }
-            then
-              # Multiple operators can be combined on the same field by
-              # adding them to the existing hash.
-              new_value = selector[field].merge(value)
-              selector.store(field, new_value)
-            else
-              add_operator_expression('$and', [{field => value}])
-            end
+          if %w($and $nor $or).include?(operator)
+            return add_logical_operator_expression(operator, op_expr)
+          end
+
+          # For other operators, if the operator already exists in the
+          # query, add the new condition with $and, otherwise add the
+          # new condition to the top level.
+          if selector[operator]
+            add_logical_operator_expression('$and', [{operator => op_expr}])
           else
-            selector.store(field, value)
+            selector.store(operator, op_expr)
           end
 
           self