light_mongo 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+coverage
+rdoc
+pkg
+

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Elliot Crosby-McCullough
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,134 @@
+LightMongo
+==========
+LightMongo is a lightweight Mongo object persistence layer for Ruby which makes use of Mongo's features rather than trying to emulate ActiveRecord.
+
+Status
+-----------------
+LightMongo is only a few days old, so while most of the features demo'd below work, there's no strong integration testing yet, so I wouldn't use it for data you particularly care about until I release a gem.
+
+Check out the development roadmap for an idea of my current priorities.
+
+The problem
+-----------
+Developers occasionally encounter a domain which defies simple modelling in an ActiveRecord relational style, and look to some of the nosql databases for a solution.  They find Mongo, a document database, and feel it might provide the flexibility they need.  After a bit of research they pick out a persistence library which seems popular and well maintained.  It even emulates most of ActiveRecord's behaviour, style and relational philosophy.  Great!
+
+Hang on a minute, wasn't it ActiveRecord's behaviour, style and relational philosophy they moved to Mongo to get away from?
+
+The solution
+------------
++ Ruby instances store their state in instance variables.  Why do we need to hide this in the persistence layer?
++ Ruby has quite the heap of array management operators.  Why do we need explicit relationships and relationship proxies?
++ Objects of the same class can perform a number of different roles or be related to other classes in lots of ways.  Why do we need to jump through complicated and restrictive hoops to do something we do in pure Ruby domains all the time?
+
+Mongo is a flexible database.  We can make use of that flexibility to allow our persistence layer to make decisions on how to best serialise and deserialise our objects.  It's our responsibility to make sure our domain is correct.  It's the library's responsibility to store those domain objects.
+
+We're Ruby developers.  Let's act like it.
+
+An example
+----------
+    class Article
+      include LightMongo::Document
+    end
+    
+    geology_article = Article.new(:title => 'Fluid Physics in Geology', :abstract => 'Lorem ipsum dolor..')
+    geology_article.save
+    
+    Article.find.first
+    => #<Article:0x101647448 @_id="4b93c1e97bc7697187000001" @title="Fluid Physics in Geology" @abstract="Lorem upsum dolor...">
+
+No tables.  No database.  Save your migrations for when you actually have some data to shift around.
+    
+Slightly more complex
+---------------------
+Plain Ruby objects stored in your Documents will be serialised along with the Document and embedded in the Mongo document.
+
+    class Article
+      include LightMongo::Document
+      
+      attr_accessor :title, :comments
+      
+      def initialize(*args)
+        @comments = []
+        super
+      end
+    end
+    
+    class Comment
+      attr_accessor :author_name, :text
+    end
+    
+    geology_article = Article.create(:title => 'Fluid Physics in Geology')
+    comment = Comment.new
+    comment.author_name = 'Dave'
+    comment.text = "Cool article!"
+    
+    geology_article.comments << comment
+    geology_article.save
+    
+    first_article = Article.find.first
+    
+    first_article.title
+    => "Fluid Physics in Geology"
+    
+    first_article.comments
+    => [#<Comment:0x101664138 @author_name="Dave" @text="Cool article!">]
+
+Dynamic finders
+---------------
+It's not generally a good idea to do much searching on keys that haven't been indexed (as in most databases), so LightMongo will only set up dynamic finders for attributes you've asked to have indexed.  If you really want an unindexed finder, they're not difficult to write.
+
+    class Article
+      include LightMongo::Document
+      attr_reader :page_length
+      index :title
+      index :abstract, :as => :precis
+    end
+
+    geology_article = Article.create(:title => 'Fluid Physics in Geology',
+                                     :abstract => 'A study in geological fluid physics',
+                                     :page_length => 367)
+    
+    Article.find_by_title('Fluid Physics in Geology').first == geology_article
+    => true
+    
+    Article.find_by_precis('A study in geological fluid physics').first == geology_article
+    => true
+    
+The aliasing option is not required, but is recommended if you want dynamic finders for indexed keys that can't be represented in a standard Ruby method name (for example, a finder will not be created for a complex multi-level Mongo key index.  See the Mongo manual for more information).
+
+Cross-collection relationships
+------------------------------
+LightMongo uses its Document mixin to signify a collection, so if you embed a LightMongo::Document inside another LightMongo::Document, the serialisation engine will consider this a cross-collection relationship and behave accordingly.
+
+    class Article
+      include LightMongo::Document
+      attr_reader :author
+    end
+
+    class Person
+      include LightMongo::Document
+    end
+    
+    dave = Person.new(:name => 'Dave')
+    fluid_physics = Article.create(:title => 'Fluid Physics in Geology', :author => dave)
+    
+    Person.find.first
+    => #<Person:0x101664138 @_id="4b93cf9397bc7697187000001" @name="Dave">
+    
+    Article.find.first.author == Person.find.first
+    => true
+
+Roadmap
+-------
+1. Improved testbed to allow stronger integration testing.
+2. More intelligent and efficient object serialisation.
+3. Proper deserialisation of cross-collection objects (currently they go in, don't come back out).
+4. Nested hash serialisation.
+4. Migrations (e.g. when you rename classes or modify their collection style).
+5. Some kind of validations, perhaps.
+
+
+
+
+
+

data/Rakefile

@@ -0,0 +1,45 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "light_mongo"
+    gem.summary = %Q{A lightweight Ruby object persistence library for Mongo DB}
+    gem.description = %Q{LightMongo is a lightweight Mongo object persistence layer for Ruby which makes use of Mongo's features rather than trying to emulate ActiveRecord.}
+    gem.email = "elliot.cm@gmail.com"
+    gem.homepage = "http://github.com/elliotcm/light_mongo"
+    gem.authors = ["Elliot Crosby-McCullough"]
+    gem.add_development_dependency "rspec", ">= 1.3.0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+
+  # check_dependencies is defined by jeweler
+  task :spec => :check_dependencies
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+  spec.spec_opts = ['--color']
+end
+
+Spec::Rake::SpecTask.new(:integration) do |spec|
+  spec.libs << 'lib' << 'integration'
+  spec.spec_files = FileList['integration/**/*_spec.rb']
+  spec.spec_opts = ['--color']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+  spec.spec_opts = ['--color']
+end
+
+
+task :default => [:spec, :integration]

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/integration/basic_storage_cycle_spec.rb

@@ -0,0 +1,21 @@
+require File.expand_path(File.dirname(__FILE__) + '/support/integration_helper')
+
+class Article
+  include LightMongo::Document
+end
+
+describe 'The basic storage cycle' do
+  before(:each) do
+    @geology_article = Article.new(:title => (@title = 'Fluid Physics in Geology'),
+                                   :abstract => (@abstract = 'Lorem ipsum dolor..'))
+  end
+  
+  it "allows the storage and retrieval of documents." do
+    @geology_article.save
+    stored_article = Article.find.first
+    stored_article.instance_variable_get('@title').should == @title
+    stored_article.instance_variable_get('@abstract').should == @abstract
+  end
+  
+  db_teardown
+end

data/integration/cross_collection_relationships_spec.rb

@@ -0,0 +1,29 @@
+require File.expand_path(File.dirname(__FILE__) + '/support/integration_helper')
+
+LightMongo.slow_serialization = true
+
+class Article
+  include LightMongo::Document
+  attr_reader :author
+end
+
+class Person
+  include LightMongo::Document
+end
+
+describe 'Embedding a LightMongo::Document within another LightMongo::Document' do
+  before(:each) do
+    @dave = Person.new(:name => 'Dave')
+    @geology_article = Article.create(:title => 'Fluid Physics in Geology', :author => @dave)
+  end
+  
+  it "allows independent access to the embedded document via its collection." do
+    Person.find.first.should == @dave
+  end
+  
+  it "retains a reference to the embedded document in its container document." do
+    Article.find.first.author.should == @dave
+  end
+  
+  db_teardown
+end

data/integration/dynamic_finders_spec.rb

@@ -0,0 +1,33 @@
+require File.expand_path(File.dirname(__FILE__) + '/support/integration_helper')
+
+LightMongo.slow_serialization = true
+
+class Article
+  include LightMongo::Document
+
+  attr_reader :page_length
+  index :title
+  index :abstract, :as => :precis
+end
+
+describe 'Indexing an attribute' do
+  before(:each) do
+    @geology_article = Article.create(:title => 'Fluid Physics in Geology',
+                                      :abstract => 'A study in geological fluid physics',
+                                      :page_length => 367)
+  end
+  
+  context "where an alias is not given" do
+    it "creates a finder using the key name" do
+      Article.find_by_title('Fluid Physics in Geology').first.should == @geology_article
+    end
+  end
+  
+  context "where an alias has been given" do
+    it "creates a finder using the alias name" do
+      Article.find_by_precis('A study in geological fluid physics').first.should == @geology_article
+    end
+  end
+  
+  db_teardown
+end

data/integration/meta_spec.rb

@@ -0,0 +1,20 @@
+require File.expand_path(File.dirname(__FILE__) + '/support/integration_helper')
+
+describe 'Integration tests' do
+  db_teardown
+  
+  before(:each) do
+    class Integration
+      include LightMongo::Document
+    end
+  end
+
+  after(:all) do
+    Integration.find.should be_empty
+  end
+
+  it "tears down the database after each run" do
+    Integration.create :name => 'Database teardown example'
+    Integration.find.first.should be_a(Integration)
+  end
+end

data/integration/object_embedding_spec.rb

@@ -0,0 +1,42 @@
+require File.expand_path(File.dirname(__FILE__) + '/support/integration_helper')
+
+LightMongo.slow_serialization = true
+
+class Article
+  include LightMongo::Document
+
+  attr_accessor :title, :comments
+
+  def initialize(*args)
+    @comments = []
+    super
+  end
+end
+
+class Comment
+  attr_accessor :author_name, :text
+end
+
+describe 'Embedding a Ruby object within your LightMongo::Document' do
+  before(:each) do
+    @geology_article = Article.create(:title => (@title = 'Fluid Physics in Geology'))
+
+    @comment = Comment.new
+    @comment.author_name = 'Dave'
+    @comment.text = "Cool article!"
+    
+    @geology_article.comments << @comment
+    @geology_article.save
+  end
+  
+  it "is represented as embedded MongoDB documents and eager restored." do
+    stored_article = Article.find.first
+    stored_article.title.should == @title
+    
+    stored_comment = stored_article.comments.first
+    stored_comment.author_name.should == @comment.author_name
+    stored_comment.text.should == @comment.text
+  end
+  
+  db_teardown
+end

data/integration/support/integration_helper.rb

@@ -0,0 +1,9 @@
+require File.dirname(__FILE__) + '/../../lib/light_mongo'
+
+LightMongo.database = 'light_mongo_test'
+
+def db_teardown
+  after(:each) do
+    LightMongo.connection.drop_database(LightMongo.database.name)
+  end
+end

data/lib/document/persistence.rb

@@ -0,0 +1,84 @@
+module LightMongo
+  # Connection and database getters/setters hoofed from jnunemaker's MongoMapper
+  def self.connection
+    @@connection ||= Mongo::Connection.new
+  end
+
+  def self.connection=(new_connection)
+    @@connection = new_connection
+  end
+  
+  def self.database=(name)
+    @@database = nil
+    @@database_name = name
+  end
+ 
+  def self.database
+    unless defined?(@@database_name) and !Util.blank?(@@database_name)
+      raise 'You forgot to set the default database name: LightMongo.database = "foobar"'
+    end
+ 
+    @@database ||= LightMongo.connection.db(@@database_name)
+  end
+  
+  module Document
+    module Persistence
+      def self.included(document_class)
+        document_class.extend ClassMethods
+        document_class.collection = Mongo::Collection.new(LightMongo.database, document_class.name)
+      end
+      
+      def collection
+        self.class.collection
+      end
+      
+      def save
+        @_id = collection.save(self.to_hash)
+      end
+      
+      def id
+        @_id
+      end
+      
+      def ==(other)
+        self.id == other.id
+      end
+
+      
+      module ClassMethods
+        attr_accessor :collection
+
+        def create(params)
+          new_object = new(params)
+          new_object.save
+          return new_object
+        end
+        
+        def index(key_name, options={})
+          return if Util.blank?(key_name)
+          
+          method_name = 'find_by_'+(options[:as] or key_name).to_s
+          if viable_method_name(method_name)
+            (class << self; self; end).class_eval do
+              define_method method_name.to_sym do |value|
+                collection.find(key_name.to_sym => value).map{|bson_hash| new(bson_hash)}
+              end
+            end
+          end
+          
+          collection.create_index(key_name)
+        end
+        
+        def find(query=nil)
+          query = {'_id' => query} unless query.nil? or query.is_a?(Hash)
+          collection.find(query).map{|bson_hash| new(bson_hash)}
+        end
+        
+        def viable_method_name(method_name)
+          method_name =~ /^\w+[!?]?$/
+        end
+      end
+      
+    end
+  end
+end

data/lib/document/serialization/hash_serializer.rb

@@ -0,0 +1,74 @@
+require 'mongo'
+
+module LightMongo
+  module Document
+    module Serialization
+      
+      class HashSerializer
+        class <<self
+          def dump(object_to_serialize, current_depth=0)
+            case object_to_serialize
+            when Array
+              return serialize_array(object_to_serialize, current_depth)
+            when Hash
+              return serialize_hash(object_to_serialize, current_depth)
+            else
+              return serialize_object(object_to_serialize, current_depth)
+            end
+          end
+        
+          def serialize_array(object_to_serialize, current_depth)
+            object_to_serialize.map do |entry|
+              Serializer.serialize(entry, current_depth + 1)
+            end
+          end
+
+          def serialize_hash(object_to_serialize, current_depth)
+            outbound_hash = {}
+            object_to_serialize.each_pair do |key, entry|
+              outbound_hash[key] = Serializer.serialize(entry, current_depth + 1)
+            end
+            outbound_hash
+          end
+          
+          def serialize_object(object_to_serialize, current_depth)
+            return object_to_serialize if natively_embeddable?(object_to_serialize)
+
+            return object_to_serialize.export if object_to_serialize.is_a? LightMongo::Document and current_depth > 0
+
+            return hashify(object_to_serialize, current_depth)
+          end
+          
+          def hashify(object_to_serialize, current_depth)
+            hashed_object = {}
+            hashed_object['_class_name'] = object_to_serialize.class.name if current_depth > 0
+            
+            object_to_serialize.instance_variables.each do |attribute_name|
+              new_hash_key = attribute_name.sub(/^@/, '')
+              nested_object = object_to_serialize.instance_variable_get(attribute_name)
+              hashed_object[new_hash_key] = Serializer.serialize(nested_object, current_depth + 1)
+            end
+
+            return hashed_object
+          end
+          
+          def natively_embeddable?(object)
+            begin
+              raise_unless_natively_embeddable(object)
+            rescue Mongo::InvalidDocument => e
+              return false
+            end
+            
+            return true
+          end
+          
+          def raise_unless_natively_embeddable(object)
+            BSON_RUBY.new.bson_type(object)
+          end
+
+        end
+      end
+      
+    end
+  end
+end

data/lib/document/serialization/serializer.rb

@@ -0,0 +1,76 @@
+require File.dirname(__FILE__) + '/hash_serializer'
+
+module LightMongo
+  module Document
+    module Serialization
+      class Serializer
+        attr_accessor :depth
+        
+        class <<self
+          def deserialize(object_to_deserialize)
+            return array_deserialize(object_to_deserialize) if object_to_deserialize.is_a?(Array)
+            if object_to_deserialize.is_a?(Hash)
+              if object_to_deserialize.has_key?('_data')
+                return Marshal.load(object_to_deserialize['_data'])
+              end
+
+              if object_to_deserialize.has_key?('_class_name')
+                class_name = object_to_deserialize.delete('_class_name')
+
+                if !object_to_deserialize.has_key?('_id')
+                  object = Object.const_get(class_name).new
+                  object_to_deserialize.each_pair do |attr_name, attr_value|
+                    object.instance_variable_set '@'+attr_name, attr_value
+                  end
+                  
+                  return object
+                end
+
+                if object_to_deserialize.has_key?('_embed') and object_to_deserialize['_embed'] == true
+                  return Object.const_get(class_name).find(object_to_deserialize['_id']).first
+                end
+              end
+              
+              return hash_deserialize(object_to_deserialize)
+            end
+            
+            return object_to_deserialize
+          end
+        
+          def serialize(object_to_serialize, depth=0)
+            serializer = Serializer.new(object_to_serialize, depth)
+            return serializer.hash_serialize if LightMongo.slow_serialization or depth < LightMongo.marshal_depth
+            serializer.marshal
+          end
+          
+          def array_deserialize(array)
+            array.map do |entry|
+              deserialize(entry)
+            end
+          end
+          
+          def hash_deserialize(hash)
+            deserialized_hash = {}
+            hash.each_pair do |key, value|
+              deserialized_hash[key] = deserialize(value)
+            end
+            return deserialized_hash
+          end
+        end
+        
+        def initialize(object_to_serialize, depth=0)
+          @object_to_serialize = object_to_serialize
+          @depth = depth
+        end
+        
+        def marshal
+          {'_data' => Marshal.dump(@object_to_serialize)}
+        end
+
+        def hash_serialize
+          HashSerializer.dump(@object_to_serialize, @depth)
+        end
+      end
+    end
+  end
+end

data/lib/document/serialization.rb

@@ -0,0 +1,45 @@
+require File.dirname(__FILE__) + '/serialization/serializer'
+
+module LightMongo
+  def self.slow_serialization=(boolean)
+    @@slow_serialization = boolean
+  end
+  
+  def self.slow_serialization
+    @@slow_serialization = nil unless defined?(@@slow_serialization)
+    @@slow_serialization ||= false
+  end
+
+  def self.marshal_depth=(depth)
+    @@marshal_depth = depth
+  end
+  
+  def self.marshal_depth
+    @@marshal_depth = nil unless defined?(@@marshal_depth)
+    @@marshal_depth ||= 3
+  end
+  
+  module Document
+    module Serialization
+      def initialize(params={})
+        self.from_hash(params)
+      end
+
+      def to_hash(current_depth=0)
+        Serializer.serialize(self, current_depth)
+      end
+
+      def from_hash(hash)
+        Serializer.deserialize(hash).each_pair do |attr_name, attr_value|
+          self.instance_variable_set '@'+attr_name.to_s, attr_value
+        end
+      end
+      
+      def export
+        return self unless self.class.include?(LightMongo::Document::Persistence)
+        self.save
+        {'_class_name' => self.class.name, '_id' => self.id, '_embed' => true}
+      end
+    end
+  end
+end

data/lib/document.rb

@@ -0,0 +1,20 @@
+require 'rubygems'
+require 'mongo'
+
+def require_document(lib)
+  require File.dirname(__FILE__) + "/document/" + lib
+end
+
+require_document 'serialization'
+require_document 'persistence'
+
+module LightMongo
+  module Document
+    def self.included(document_class)
+      document_class.class_eval %{
+        include Serialization
+        include Persistence
+      }
+    end
+  end
+end

data/lib/light_mongo.rb

@@ -0,0 +1,3 @@
+root = File.dirname(__FILE__)
+require root+'/util'
+require root+'/document'