mongo 0.0.1

data/README.rdoc

@@ -0,0 +1,134 @@
+= Introduction
+
+This is a Ruby driver for the 10gen Mongo DB. For more information about
+Mongo, see http://www.mongodb.org.
+
+Note: this driver is still alpha quality. The API will change, as *may* the
+data saved to the database (especially primary key values). Do *_not_* use
+this for any production data yet.
+
+Start by reading the XGen::Mongo::Driver::Mongo and XGen::Mongo::Driver::DB
+documentation, then move on to XGen::Mongo::Driver::Collection and
+XGen::Mongo::Driver::Cursor.
+
+A quick code sample:
+
+  require 'mongo'
+
+  include XGen::Mongo::Driver
+
+  db = Mongo.new('localhost').db('sample-db')
+  coll = db.collection('test')
+
+  coll.clear
+  3.times { |i| coll.insert({'a' => i+1}) }
+  puts "There are #{coll.count()} records. Here they are:"
+  coll.find().each { |doc| puts doc.inspect }
+
+= Installation
+
+Install the "mongo" gem by typing
+
+  $ sudo gem install mongo
+
+The source code is available at http://github.com/jimm/mongo-ruby-driver. You
+can either clone the git repository or download a tarball or zip file. Once
+you have the source, you can use it from wherever you downloaded it or you can
+install it as a gem from the source by typing
+
+  $ rake gem:install
+
+
+= Demo
+
+You can see and run the examples if you've downloaded the source. Mongo must
+be running, of course.
+
+  $ ruby examples/simple.rb
+
+See also the test code, especially tests/test_db_api.rb.
+
+
+= Testing
+
+If you have the source code, you can run the tests.
+
+  $ rake test
+
+The tests assume that the Mongo database is running on the default port.
+
+
+= Documentation
+
+This documentation is available online at http://mongo.rubyforge.org. You can
+generate the documentation if you have the source by typing
+
+  $ rake rdoc
+
+Then open the file html/index.html.
+
+
+= Release Notes
+
+See the git log comments.
+
+
+= To Do
+
+* Add group_by. Need to figure out how we are going to send functions. The
+  current thinking is that Mongo will allow a subset of JavaScript (which we
+  would have to send as a string), but this is still under discussion.
+
+* Add explain and hint support.
+
+* Only update message sizes once, not after every write of a value. This will
+  require an explicit call to update_message_length in each message subclass.
+
+* Tests for update and repsert.
+
+* Add a way to specify a collection of databases on startup (a simple array of
+  IP address/port numbers, perhaps, or a hash or something). The driver would
+  then find the master and, on each subsequent command, ask that machine if it
+  is the master before proceeding.
+
+* Tests that prove that this driver's ObjectID and Geir's Java version do the
+  same thing. (I've done so manually.)
+
+* Support more types: REF, SYMBOL, CODE_W_SCOPE, etc.
+
+* Introduce optional per-database and per-collection PKInjector.
+
+* More tests.
+
+* Study src/main/ed/db/{dbcollection,dbcursor,db}.js and ByteEncoder.java in
+  the Babble code. That's what I should be writing to.
+
+
+= Credits
+
+Adrian Madrid, aemadrid@gmail.com
+* bin/mongo_console
+* examples/benchmarks.rb
+* examples/irb.rb
+* Modifications to examples/simple.rb
+* Found plenty of bugs and missing features.
+* Ruby 1.9 support.
+* Gem support.
+* Many other code suggestions and improvements.
+
+
+= License
+
+Copyright (C) 2008-2009 10gen Inc.
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU Affero General Public License, version 3, as published by
+the Free Software Foundation.
+
+This program is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+details.
+
+See http://www.gnu.org/licenses for a copy of the GNU Affero General Public
+License.

data/Rakefile

@@ -0,0 +1,86 @@
+require 'rubygems'
+require 'rubygems/specification'
+require 'fileutils'
+require 'rake'
+require 'rake/testtask'
+require 'rake/gempackagetask'
+require 'rake/contrib/rubyforgepublisher'
+
+GEM = "mongo"
+GEM_VERSION = '0.0.1'
+SUMMARY = 'Simple pure-Ruby driver for the 10gen Mongo DB'
+DESCRIPTION = 'This is a simple pure-Ruby driver for the 10gen Mongo DB. For more information about Mongo, see http://www.mongodb.org.'
+AUTHOR = 'Jim Menard'
+EMAIL = 'jimm@io.com'
+HOMEPAGE = 'http://www.mongodb.org'
+RUBYFORGE_USER = 'jimm'
+ 
+spec = Gem::Specification.new do |s|
+  s.name = GEM
+  s.version = GEM_VERSION
+  s.platform = Gem::Platform::RUBY
+  s.summary = SUMMARY
+  s.description = DESCRIPTION
+  
+  s.require_paths = ['lib']
+  
+  s.files = FileList['bin/*', 'lib/**/*.rb', 'tests/**/*.rb', '[A-Z]*'].to_a
+  
+  s.bindir = 'bin'
+  s.executables  = %w( mongo_console )
+  s.has_rdoc = true
+
+  s.author = AUTHOR
+  s.email = EMAIL
+  s.homepage = HOMEPAGE
+
+  s.rubyforge_project = GEM # GitHub bug, gem isn't being build when this miss
+end
+
+# NOTE: some of the tests assume Mongo is running
+Rake::TestTask.new do |t|
+  t.test_files = FileList['tests/test*.rb']
+end
+
+desc "Generate documentation"
+task :rdoc do
+  FileUtils.rm_rf('html')
+  system "rdoc --main README.rdoc --op html --inline-source --quiet README.rdoc `find lib -name '*.rb'`"
+end
+
+desc "Publish documentation to mongo.rubyforge.org"
+task :publish => [:rdoc] do
+  # Assumes docs are in ./html
+  Rake::RubyForgePublisher.new(GEM, RUBYFORGE_USER).upload
+end
+
+namespace :gem do 
+
+  Rake::GemPackageTask.new(spec) do |pkg|
+    pkg.gem_spec = spec
+  end
+
+  desc "Install the gem locally"
+  task :install => [:package] do
+    sh %{sudo gem install pkg/#{GEM}-#{GEM_VERSION}}
+  end
+  
+  desc "Install the gem locally with ruby 1.9"
+  task :'install19' => [:package] do
+    sh %{sudo gem19 install pkg/#{GEM}-#{GEM_VERSION}}
+  end
+ 
+  desc "Create a gemspec file"
+  task :make_spec do
+    File.open("#{GEM}.gemspec", "w") do |file|
+      file.puts spec.to_ruby
+    end
+  end
+
+end
+
+task :default => :list
+
+task :list do
+  system 'rake -T'
+end

data/bin/mongo_console

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+org_argv = ARGV.dup
+ARGV.clear
+
+require 'irb'
+
+$LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
+require 'mongo'
+
+include XGen::Mongo::Driver
+
+host = org_argv[0] || ENV['MONGO_RUBY_DRIVER_HOST'] || 'localhost'
+port = org_argv[1] || ENV['MONGO_RUBY_DRIVER_PORT'] || XGen::Mongo::Driver::Mongo::DEFAULT_PORT
+dbnm = org_argv[2] || ENV['MONGO_RUBY_DRIVER_DB']   || 'ruby-mongo-console'
+
+puts "Connecting to #{host}:#{port} (CONN) on with database #{dbnm} (DB)"
+CONN = Mongo.new(host, port)
+DB = CONN.db(dbnm)
+
+puts "Starting IRB session..."
+IRB.start(__FILE__)

data/lib/mongo.rb

@@ -0,0 +1,7 @@
+require 'mongo/mongo'
+require 'mongo/objectid'
+require 'mongo/message'
+require 'mongo/db'
+require 'mongo/cursor'
+require 'mongo/collection'
+require 'mongo/admin'

data/lib/mongo/admin.rb

@@ -0,0 +1,86 @@
+# --
+# Copyright (C) 2008-2009 10gen Inc.
+#
+# This program is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Affero General Public License, version 3, as
+# published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License
+# for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+# ++
+
+require 'mongo/util/ordered_hash'
+
+module XGen
+  module Mongo
+    module Driver
+
+      # Provide administrative database methods: those having to do with
+      # profiling and validation.
+      class Admin
+
+        def initialize(db)
+          @db = db
+        end
+
+        # Return the current database profiling level.
+        def profiling_level
+          oh = OrderedHash.new
+          oh[:profile] = -1
+          doc = @db.db_command(oh)
+          raise "Error with profile command: #{doc.inspect}" unless @db.ok?(doc) && doc['was'].kind_of?(Numeric)
+          case doc['was'].to_i
+          when 0
+            :off
+          when 1
+            :slow_only
+          when 2
+            :all
+          else
+            raise "Error: illegal profiling level value #{doc['was']}"
+          end
+        end
+
+        # Set database profiling level to :off, :slow_only, or :all.
+        def profiling_level=(level)
+          oh = OrderedHash.new
+          oh[:profile] = case level
+                         when :off
+                           0
+                         when :slow_only
+                           1
+                         when :all
+                           2
+                         else
+                           raise "Error: illegal profiling level value #{level}"
+                         end
+          doc = @db.db_command(oh)
+          raise "Error with profile command: #{doc.inspect}" unless @db.ok?(doc)
+        end
+
+        # Return an array contining current profiling information from the
+        # database.
+        def profiling_info
+          @db.query(DB::SYSTEM_PROFILE_COLLECTION, Query.new({})).to_a
+        end
+
+        # Validate a named collection by raising an exception if there is a
+        # problem or returning +true+ if all is well.
+        def validate_collection(name)
+          doc = @db.db_command(:validate => name)
+          raise "Error with validate command: #{doc.inspect}" unless @db.ok?(doc)
+          result = doc['result']
+          raise "Error with validation data: #{doc.inspect}" unless result.kind_of?(String)
+          raise "Error: invalid collection #{name}: #{doc.inspect}" if result =~ /\b(exception|corrupt)\b/i
+          true
+        end
+
+      end
+    end
+  end
+end

data/lib/mongo/collection.rb

@@ -0,0 +1,136 @@
+# --
+# Copyright (C) 2008-2009 10gen Inc.
+#
+# This program is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Affero General Public License, version 3, as
+# published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License
+# for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+# ++
+
+require 'mongo/query'
+
+module XGen
+  module Mongo
+    module Driver
+
+      # A named collection of records in a database.
+      class Collection
+
+        attr_reader :db, :name
+
+        def initialize(db, name)
+          @db = db
+          @name = name
+        end
+
+        # Return records that match a +selector+ hash. See Mongo docs for
+        # details.
+        #
+        # Options:
+        # :fields :: Array of collection field names; only those will be returned (plus _id if defined)
+        # :offset :: Start at this record when returning records
+        # :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).
+        def find(selector={}, options={})
+          fields = options.delete(:fields)
+          fields = nil if fields && fields.empty?
+          offset = options.delete(:offset) || 0
+          limit = options.delete(:limit) || 0
+          sort = options.delete(:sort)
+          raise RuntimeError, "Unknown options [#{options.inspect}]" unless options.empty?
+          @db.query(@name, Query.new(selector, fields, offset, limit, sort))
+        end
+
+        # Insert +objects+, which are hashes. "<<" is aliased to this method.
+        def insert(*objects)
+          objects = objects.first if objects.size == 1 && objects.first.is_a?(Array)
+          res = @db.insert_into_db(@name, objects)
+          res.size > 1 ? res : res.first
+        end
+        alias_method :<<, :insert
+
+        # Remove the records that match +selector+.
+        def remove(selector={})
+          @db.remove_from_db(@name, selector)
+        end
+
+        # Remove all records.
+        def clear
+          remove({})
+        end
+
+        # Update records that match +selector+ by applying +obj+ as an update.
+        # If no match, inserts (???).
+        def repsert(selector, obj)
+          @db.repsert_in_db(@name, selector, obj)
+        end
+
+        # Update records that match +selector+ by applying +obj+ as an update.
+        def replace(selector, obj)
+          @db.replace_in_db(@name, selector, obj)
+        end
+
+        # Update records that match +selector+ by applying +obj+ as an update.
+        # Both +selector+ and +modifier_obj+ are required.
+        def modify(selector, modifier_obj)
+          raise "no object" unless modifier_obj
+          raise "no selector" unless selector
+          @db.modify_in_db(@name, selector, modifier_obj)
+        end
+
+        # Create a new index named +index_name+. +fields+ should be an array
+        # of field names.
+        def create_index(name, *fields)
+          @db.create_index(@name, name, fields)
+        end
+
+        # Drop index +name+.
+        def drop_index(name)
+          @db.drop_index(@name, name)
+        end
+
+        # Drop all indexes.
+        def drop_indexes
+          # just need to call drop indexes with no args; will drop them all
+          @db.drop_index(@name, '*')
+        end
+
+        # Return an array of hashes, one for each index. Each hash contains:
+        #
+        # :name :: Index name
+        #
+        # :keys :: Hash whose keys are the names of the fields that make up
+        #          the key and values are integers.
+        #
+        # :ns :: Namespace; same as this collection's name.
+        def index_information
+          @db.index_information(@name)
+        end
+
+        # Return a hash containing options that apply to this collection.
+        # 'create' will be the collection name. For the other possible keys
+        # and values, see DB#create_collection.
+        def options
+          @db.collections_info(@name).next_object()['options']
+        end
+
+        # Return the number of records that match +selector+. If +selector+ is
+        # +nil+ or an empty hash, returns the count of all records.
+        def count(selector={})
+          @db.count(@name, selector || {})
+        end
+
+      end
+    end
+  end
+end
+