mongo 0.15 → 0.15.1

data/README.rdoc

@@ -311,6 +311,7 @@ Jon Crosby, jon@joncrosby.me
 John Nunemaker, http://railstips.org
 * Collection#create_index takes symbols as well as strings
 * Fix for Collection#save
+* Add logger convenience methods to connection and database
 
 David James, djames@sunlightfoundation.com
 * Fix dates to return as UTC
@@ -319,8 +320,9 @@ Paul Dlug, paul.dlug@gmail.com
 * Generate _id on the client side if not provided
 * Collection#insert and Collection#save return _id
 
-Durran Jordan and Les Hill, durran@gmail.com
+Durran Jordan, durran@gmail.com
 * DB#collections
+* Support for specifying sort order as array of [key, direction] pairs
 
 Cyril Mougel, cyril.mougel@gmail.com
 * Initial logging support

data/lib/mongo.rb

@@ -15,5 +15,5 @@ module Mongo
   ASCENDING = 1
   DESCENDING = -1
 
-  VERSION = "0.15"
+  VERSION = "0.15.1"
 end

data/lib/mongo/collection.rb

@@ -91,9 +91,9 @@ module Mongo
     # :skip :: Number of documents to omit (from the start of the result set)
     #          when returning the results
     # :limit :: Maximum number of records to return
-    # :sort :: Either hash of field names as keys and 1/-1 as values; 1 ==
-    #          ascending, -1 == descending, or array of field names (all
-    #          assumed to be sorted in ascending order).
+    # :sort :: An array of [key, direction] pairs to sort by. Direction should
+    #          be specified as Mongo::ASCENDING (or :ascending / :asc) or
+    #          Mongo::DESCENDING (or :descending / :desc)
     # :hint :: See #hint. This option overrides the collection-wide value.
     # :snapshot :: If true, snapshot mode will be used for this query.
     #              Snapshot mode assures no duplicates are returned, or

data/lib/mongo/connection.rb

@@ -94,6 +94,10 @@ module Mongo
     def db(db_name, options={})
       DB.new(db_name, @pair, @options.merge(options))
     end
+    
+    def logger
+      @options[:logger]
+    end
 
     # Returns a hash containing database names as keys and disk space for
     # each as values.

data/lib/mongo/cursor.rb

@@ -75,16 +75,24 @@ module Mongo
 
     # Sort this cursor's result
     #
-    # Takes either a hash of field names as keys and 1/-1 as values; 1 ==
-    # ascending, -1 == descending, or array of field names (all assumed to be
-    # sorted in ascending order).
+    # Takes either a single key and a direction, or an array of [key,
+    # direction] pairs. Directions should be specified as Mongo::ASCENDING
+    # or Mongo::DESCENDING (or :ascending or :descending) (or :asc or :desc).
     #
-    # Raises InvalidOperation if this cursor has already been used.
+    # Raises InvalidOperation if this cursor has already been used. Raises
+    # InvalidSortValueError if specified order is invalid.
     #
     # This method overrides any sort order specified in the Collection#find
     # method, and only the last sort applied has an effect
-    def sort(order)
+    def sort(key_or_list, direction=nil)
       check_modifiable
+
+      if !direction.nil?
+        order = [[key_or_list, direction]]
+      else
+        order = key_or_list
+      end
+
       @query.order_by = order
       self
     end

data/lib/mongo/db.rb

@@ -58,6 +58,9 @@ module Mongo
 
     # The database's socket. For internal (and Cursor) use only.
     attr_reader :socket
+    
+    # The logger instance if :logger is passed to initialize
+    attr_reader :logger
 
     def slave_ok?; @slave_ok; end
     def auto_reconnect?; @auto_reconnect; end

data/lib/mongo/errors.rb

@@ -23,4 +23,7 @@ module Mongo
 
   # Raised when an invalid name is used.
   class InvalidName < RuntimeError; end
+
+  # Raised when the client supplies an invalid value to sort by.
+  class InvalidSortValueError < RuntimeError; end
 end

data/lib/mongo/message/query_message.rb

@@ -16,11 +16,12 @@
 
 require 'mongo/message/message'
 require 'mongo/message/opcodes'
+require 'mongo/util/conversions'
 require 'mongo/util/ordered_hash'
 
 module Mongo
-
   class QueryMessage < Message
+    include Mongo::Conversions
 
     attr_reader :query
 
@@ -36,27 +37,17 @@ module Mongo
       if query.contains_special_fields
         sel = OrderedHash.new
         sel['query'] = query.selector
-        if query.order_by && query.order_by.length > 0
-          sel['orderby'] = case query.order_by
-                           when String
-                             {query.order_by => 1}
-                           when Array
-                             h = OrderedHash.new
-                             query.order_by.each { |ob|
-                               case ob
-                               when String
-                                 h[ob] = 1
-                               when Hash # should have one entry; will handle all
-                                 ob.each { |k,v| h[k] = v }
-                               else
-                                 raise "illegal query order_by value #{query.order_by.inspect}"
-                               end
-                             }
-                             h
+        if query.order_by
+          order_by = query.order_by
+          sel['orderby'] = case order_by
+                           when String then string_as_sort_parameters(order_by)
+                           when Symbol then symbol_as_sort_parameters(order_by)
+                           when Array then array_as_sort_parameters(order_by)
                            when Hash # Should be an ordered hash, but this message doesn't care
-                             query.order_by
+                             warn_if_deprecated(order_by)
+                             order_by
                            else
-                             raise "illegal order_by: is a #{query.order_by.class.name}, must be String, Array, Hash, or OrderedHash"
+                             raise InvalidSortValueError.new("illegal order_by: is a #{query.order_by.class.name}, must be String, Array, Hash, or OrderedHash")
                            end
         end
         sel['$hint'] = query.hint if query.hint && query.hint.length > 0

data/lib/mongo/query.rb

@@ -108,7 +108,7 @@ module Mongo
     end
 
     def contains_special_fields
-      (@order_by != nil && @order_by.length > 0) || @explain || @hint || @snapshot
+      @order_by || @explain || @hint || @snapshot
     end
 
     def to_s

data/lib/mongo/util/conversions.rb

@@ -0,0 +1,110 @@
+# --
+# Copyright (C) 2008-2009 10gen Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ++
+module Mongo #:nodoc:
+
+  # Utility module to include when needing to convert certain types of
+  # objects to mongo-friendly parameters.
+  module Conversions
+
+    ASCENDING = ["ascending", "asc", "1"]
+    DESCENDING = ["descending", "desc", "-1"]
+
+    # Converts the supplied +Array+ to a +Hash+ to pass to mongo as
+    # sorting parameters. The returned +Hash+ will vary depending 
+    # on whether the passed +Array+ is one or two dimensional.
+    #
+    # Example:
+    #
+    # *DEPRECATED
+    #
+    # <tt>array_as_sort_parameters(["field1", "field2"])</tt> =>
+    # <tt>{ "field1" => "1", "field2" => "1" }</tt>
+    #
+    # *New Syntax:
+    #
+    # <tt>array_as_sort_parameters([["field1", :asc], ["field2", :desc]])</tt> =>
+    # <tt>{ "field1" => 1, "field2" => -1}</tt>
+    def array_as_sort_parameters(value)
+      warn_if_deprecated(value)
+      order_by = OrderedHash.new
+      value.each do |param|
+        if (param.class.name == "String")
+          order_by[param] = 1
+        else
+          order_by[param[0]] = sort_value(param[1]) unless param[1].nil?
+        end
+      end
+      order_by
+    end
+
+    # Converts the supplied +String+ to a +Hash+ to pass to mongo as
+    # a sorting parameter with ascending order. If the +String+
+    # is empty then an empty +Hash+ will be returned.
+    #
+    # Example:
+    #
+    # *DEPRECATED
+    #
+    # <tt>string_as_sort_parameters("field")</tt> => <tt>{ "field" => 1 }</tt>
+    # <tt>string_as_sort_parameters("")</tt> => <tt>{}</tt>
+    def string_as_sort_parameters(value)
+      warn_if_deprecated(value)
+      return {} if value.empty?
+      { value => 1 }
+    end
+
+    # Converts the supplied +Symbol+ to a +Hash+ to pass to mongo as
+    # a sorting parameter with ascending order.
+    #
+    # Example:
+    #
+    # *DEPRECATED
+    #
+    # <tt>symbol_as_sort_parameters(:field)</tt> => <tt>{ "field" => 1 }</tt>
+    def symbol_as_sort_parameters(value)
+      warn_if_deprecated(value)
+      { value.to_s => 1 }
+    end
+
+    # Converts the +String+, +Symbol+, or +Integer+ to the 
+    # corresponding sort value in MongoDB.
+    #
+    # Valid conversions (case-insensitive):
+    #
+    # <tt>ascending, asc, :ascending, :asc, 1</tt> => <tt>1</tt>
+    # <tt>descending, desc, :descending, :desc, -1</tt> => <tt>-1</tt>
+    #
+    # If the value is invalid then an error will be raised.
+    def sort_value(value)
+      val = value.to_s.downcase
+      return 1 if ASCENDING.include?(val)
+      return -1 if DESCENDING.include?(val)
+      raise InvalidSortValueError.new(
+        "#{self} was supplied as a sort direction when acceptable values are: " +
+        "Mongo::ASCENDING, 'ascending', 'asc', :ascending, :asc, 1, Mongo::DESCENDING, 'descending', 'desc', :descending, :desc, -1.")
+    end
+
+    # This is the method to call when the client needs to be warned of
+    # deprecation in the way sorting parameters are supplied.
+    def warn_if_deprecated(value)
+      unless value.is_a?(Array) && value.first.is_a?(Array)
+        warn("Specifying sort order as #{value.inspect} has been deprecated in favor of a new syntax: \n" +
+          "  :sort => [['field1', '(ascending|descending)'], ['field2', '(ascending|descending)']]")
+      end
+    end
+
+  end
+end

data/mongo-ruby-driver.gemspec

@@ -45,6 +45,7 @@ PACKAGE_FILES = ['README.rdoc', 'Rakefile', 'mongo-ruby-driver.gemspec',
                  'lib/mongo/types/regexp_of_holding.rb',
                  'lib/mongo/util/bson.rb',
                  'lib/mongo/util/byte_buffer.rb',
+                 'lib/mongo/util/conversions.rb',
                  'lib/mongo/util/ordered_hash.rb',
                  'lib/mongo/util/xml_to_ruby.rb',
                  'lib/mongo.rb']
@@ -68,6 +69,7 @@ TEST_FILES = ['test/mongo-qa/_common.rb',
               'test/test_chunk.rb',
               'test/test_collection.rb',
               'test/test_connection.rb',
+              'test/test_conversions.rb',
               'test/test_cursor.rb',
               'test/test_db.rb',
               'test/test_db_api.rb',
@@ -83,7 +85,7 @@ Gem::Specification.new do |s|
   s.name = 'mongo'
 
   # be sure to change this constant in lib/mongo.rb as well
-  s.version = '0.15'
+  s.version = '0.15.1'
 
   s.platform = Gem::Platform::RUBY
   s.summary = 'Ruby driver for the MongoDB'

data/test/test_connection.rb

@@ -66,6 +66,17 @@ class TestConnection < Test::Unit::TestCase
     assert output.string.include?("db.test.find")
     assert !output.string.include?("db.test.remove")
   end
+  
+  def test_connection_logger
+    output = StringIO.new
+    logger = Logger.new(output)
+    logger.level = Logger::DEBUG
+    connection = Connection.new(@host, @port, :logger => logger)
+    assert_equal logger, connection.logger
+    
+    connection.logger.debug 'testing'
+    assert output.string.include?('testing')
+  end
 
   def test_drop_database
     db = @mongo.db('ruby-mongo-will-be-deleted')

data/test/test_conversions.rb

@@ -0,0 +1,121 @@
+$LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
+require 'mongo/errors'
+require 'mongo/util/conversions'
+require 'mongo/util/ordered_hash'
+require 'test/unit'
+
+class ConversionsTest < Test::Unit::TestCase
+  include Mongo::Conversions
+
+  def test_array_as_sort_parameters_with_array_of_strings
+    params = array_as_sort_parameters(["field1", "field2"])
+    assert_equal({ "field1" => 1, "field2" => 1 }, params)
+  end
+
+  def test_array_as_sort_parameters_with_array_of_string_and_values
+    params = array_as_sort_parameters([["field1", :asc], ["field2", :desc]])
+    assert_equal({ "field1" => 1, "field2" => -1 }, params)
+  end
+
+  def test_string_as_sort_parameters_with_string
+    params = string_as_sort_parameters("field")
+    assert_equal({ "field" => 1 }, params)
+  end
+
+  def test_string_as_sort_parameters_with_empty_string
+    params = string_as_sort_parameters("")
+    assert_equal({}, params)
+  end
+
+  def test_symbol_as_sort_parameters
+    params = symbol_as_sort_parameters(:field)
+    assert_equal({ "field" => 1 }, params)
+  end
+
+  def test_sort_value_when_value_is_one
+    assert_equal 1, sort_value(1)
+  end
+
+  def test_sort_value_when_value_is_one_as_a_string
+    assert_equal 1, sort_value("1")
+  end
+
+  def test_sort_value_when_value_is_negative_one
+    assert_equal -1, sort_value(-1)
+  end
+
+  def test_sort_value_when_value_is_negative_one_as_a_string
+    assert_equal -1, sort_value("-1")
+  end
+
+  def test_sort_value_when_value_is_ascending
+    assert_equal 1, sort_value("ascending")
+  end
+
+  def test_sort_value_when_value_is_asc
+    assert_equal 1, sort_value("asc")
+  end
+
+  def test_sort_value_when_value_is_uppercase_ascending
+    assert_equal 1, sort_value("ASCENDING")
+  end
+
+  def test_sort_value_when_value_is_uppercase_asc
+    assert_equal 1, sort_value("ASC")
+  end
+
+  def test_sort_value_when_value_is_symbol_ascending
+    assert_equal 1, sort_value(:ascending)
+  end
+
+  def test_sort_value_when_value_is_symbol_asc
+    assert_equal 1, sort_value(:asc)
+  end
+
+  def test_sort_value_when_value_is_symbol_uppercase_ascending
+    assert_equal 1, sort_value(:ASCENDING)
+  end
+
+  def test_sort_value_when_value_is_symbol_uppercase_asc
+    assert_equal 1, sort_value(:ASC)
+  end
+
+  def test_sort_value_when_value_is_descending
+    assert_equal -1, sort_value("descending")
+  end
+
+  def test_sort_value_when_value_is_desc
+    assert_equal -1, sort_value("desc")
+  end
+
+  def test_sort_value_when_value_is_uppercase_descending
+    assert_equal -1, sort_value("DESCENDING")
+  end
+
+  def test_sort_value_when_value_is_uppercase_desc
+    assert_equal -1, sort_value("DESC")
+  end
+
+  def test_sort_value_when_value_is_symbol_descending
+    assert_equal -1, sort_value(:descending)
+  end
+
+  def test_sort_value_when_value_is_symbol_desc
+    assert_equal -1, sort_value(:desc)
+  end
+
+  def test_sort_value_when_value_is_uppercase_symbol_descending
+    assert_equal -1, sort_value(:DESCENDING)
+  end
+
+  def test_sort_value_when_value_is_uppercase_symbol_desc
+    assert_equal -1, sort_value(:DESC)
+  end
+
+  def test_sort_value_when_value_is_invalid
+    assert_raise Mongo::InvalidSortValueError do
+      sort_value(2)
+    end
+  end
+
+end

data/test/test_cursor.rb

@@ -62,22 +62,30 @@ class CursorTest < Test::Unit::TestCase
     @@coll.clear
     5.times{|x| @@coll.insert({"a" => x}) }
 
-    assert_kind_of Cursor, @@coll.find().sort({:a => 1})
+    assert_kind_of Cursor, @@coll.find().sort(:a, 1)
 
-    assert_equal 0, @@coll.find().sort({:a => 1}).next_object["a"]
-    assert_equal 4, @@coll.find().sort({:a => -1}).next_object["a"]
-    assert_equal 0, @@coll.find().sort(["a"]).next_object["a"]
+    assert_equal 0, @@coll.find().sort(:a, 1).next_object["a"]
+    assert_equal 4, @@coll.find().sort(:a, -1).next_object["a"]
+    assert_equal 0, @@coll.find().sort([["a", :asc]]).next_object["a"]
 
-    assert_kind_of Cursor, @@coll.find().sort({:a => -1, :b => 1})
+    assert_kind_of Cursor, @@coll.find().sort([[:a, -1], [:b, 1]])
 
-    assert_equal 4, @@coll.find().sort({:a => 1}).sort({:a => -1}).next_object["a"]
-    assert_equal 0, @@coll.find().sort({:a => -1}).sort({:a => 1}).next_object["a"]
+    assert_equal 4, @@coll.find().sort(:a, 1).sort(:a, -1).next_object["a"]
+    assert_equal 0, @@coll.find().sort(:a, -1).sort(:a, 1).next_object["a"]
 
     cursor = @@coll.find()
     cursor.next_object()
     assert_raise InvalidOperation do
       cursor.sort(["a"])
     end
+
+    assert_raise InvalidSortValueError do
+      @@coll.find().sort(:a, 25).next_object
+    end
+
+    assert_raise InvalidSortValueError do
+      @@coll.find().sort(25).next_object
+    end
   end
 
   def test_limit

data/test/test_db.rb

@@ -2,6 +2,8 @@ $LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
 require 'digest/md5'
 require 'mongo'
 require 'test/unit'
+require 'stringio'
+require 'logger'
 
 class TestPKFactory
   def create_pk(row)
@@ -45,6 +47,17 @@ class DBTest < Test::Unit::TestCase
       @@users = @@db.collection('system.users')
     end
   end
+  
+  def test_logger
+    output = StringIO.new
+    logger = Logger.new(output)
+    logger.level = Logger::DEBUG
+    db = Connection.new(@host, @port, :logger => logger).db('ruby-mongo-test')
+    assert_equal logger, db.logger
+    
+    db.logger.debug 'testing'
+    assert output.string.include?('testing')
+  end
 
   def test_full_coll_name
     coll = @@db.collection('test')

data/test/test_db_api.rb

@@ -149,7 +149,7 @@ class DBAPITest < Test::Unit::TestCase
     @@coll.insert('a' => 4, 'b' => 1)
 
     # Sorting (ascending)
-    docs = @@coll.find({'a' => { '$lt' => 10 }}, :sort => {'a' => 1}).to_a
+    docs = @@coll.find({'a' => { '$lt' => 10 }}, :sort => [['a', 1]]).to_a
     assert_equal 4, docs.size
     assert_equal 1, docs[0]['a']
     assert_equal 2, docs[1]['a']
@@ -157,7 +157,7 @@ class DBAPITest < Test::Unit::TestCase
     assert_equal 4, docs[3]['a']
 
     # Sorting (descending)
-    docs = @@coll.find({'a' => { '$lt' => 10 }}, :sort => {'a' => -1}).to_a
+    docs = @@coll.find({'a' => { '$lt' => 10 }}, :sort => [['a', -1]]).to_a
     assert_equal 4, docs.size
     assert_equal 4, docs[0]['a']
     assert_equal 3, docs[1]['a']
@@ -187,16 +187,10 @@ class DBAPITest < Test::Unit::TestCase
     assert_equal 1, docs[2]['a']
     assert_equal 3, docs[3]['a']
 
-    # Sorting using empty array; no order guarantee (Mongo bug #898) but
-    # should not blow up.
+    # Sorting using empty array; no order guarantee should not blow up.
     docs = @@coll.find({'a' => { '$lt' => 10 }}, :sort => []).to_a
     assert_equal 4, docs.size
 
-    # Sorting using array of hashes; no order guarantee (Mongo bug #898) but
-    # should not blow up.
-    docs = @@coll.find({'a' => { '$lt' => 10 }}, :sort => [{'b' => 1}, {'a' => -1}]).to_a
-    assert_equal 4, docs.size
-
     # Sorting using ordered hash. You can use an unordered one, but then the
     # order of the keys won't be guaranteed thus your sort won't make sense.
     oh = OrderedHash.new
@@ -208,16 +202,15 @@ class DBAPITest < Test::Unit::TestCase
     assert_equal 2, docs[2]['a']
     assert_equal 1, docs[3]['a']
 
-    # TODO this will not pass due to known Mongo bug #898
-#     oh = OrderedHash.new
-#     oh['b'] = -1
-#     oh['a'] = 1
-#     docs = @@coll.find({'a' => { '$lt' => 10 }}, :sort => oh).to_a
-#     assert_equal 4, docs.size
-#     assert_equal 1, docs[0]['a']
-#     assert_equal 3, docs[1]['a']
-#     assert_equal 2, docs[2]['a']
-#     assert_equal 4, docs[3]['a']
+    oh = OrderedHash.new
+    oh['b'] = -1
+    oh['a'] = 1
+    docs = @@coll.find({'a' => { '$lt' => 10 }}, :sort => oh).to_a
+    assert_equal 4, docs.size
+    assert_equal 1, docs[0]['a']
+    assert_equal 3, docs[1]['a']
+    assert_equal 2, docs[2]['a']
+    assert_equal 4, docs[3]['a']
   end
 
   def test_find_limits

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: mongo
 version: !ruby/object:Gem::Version 
-  version: "0.15"
+  version: 0.15.1
 platform: ruby
 authors: 
 - Jim Menard
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-10-05 00:00:00 -04:00
+date: 2009-10-08 00:00:00 -04:00
 default_executable: 
 dependencies: []
 
@@ -70,6 +70,7 @@ files:
 - lib/mongo/types/regexp_of_holding.rb
 - lib/mongo/util/bson.rb
 - lib/mongo/util/byte_buffer.rb
+- lib/mongo/util/conversions.rb
 - lib/mongo/util/ordered_hash.rb
 - lib/mongo/util/xml_to_ruby.rb
 - lib/mongo.rb
@@ -124,6 +125,7 @@ test_files:
 - test/test_chunk.rb
 - test/test_collection.rb
 - test/test_connection.rb
+- test/test_conversions.rb
 - test/test_cursor.rb
 - test/test_db.rb
 - test/test_db_api.rb