mongomatic 0.2.0 → 0.3.0

data/README.rdoc

@@ -98,7 +98,52 @@ You can add validations to your model by creating a validate method. If your val
   p["address"] = { "zip" => 94107 }
   p.valid?
   => true
-
+  
+=== The Validation Helper (Expectations)
+
+To make writing your validate method a little simpler you can use Mongomatic::Expectations. You must include Mongomatic::Expectations::Helper on any class you wish to use them. You can use expectations like this:
+
+   class Person < Mongomatic::Base
+     include Mongomatic::Expectations::Helper
+     
+     def validate
+       expectations do
+         be_present self['name'], "Name cannot be blank"
+         not_be_match self['nickname'], "Nickname cannot contain an uppercase letter", :with => /[A-Z]/
+       end
+     end
+  end
+  
+  p = Person.new
+  p.valid?
+  => false
+  p.errors.full_messages
+  => ["Name cannot be blank"]
+  p['name'] = 'Jordan'
+  p.valid?
+  => true
+  p['nickname'] = 'Jordan'
+  p.valid?
+  p.errors.full_messages
+  => ["Name cannot be blank", "Nickname cannot contain an uppercase letter"]=> false 
+
+You can use any of these expectations inside of the expectations block:
+
+  * be_expected value, error_message - validates that value is true
+  * not_be_expected value, error_message - validates that value is false
+  * [not]_be_present value, error_message - validates presence of value
+  * [not]_be_a_number value, error_message, options - validates that value is/is not a number 
+                                                      Can be a string containing only a number).
+                                                      Only takes :allow_nil option
+                                                      
+  * [not]_be_match value, error_message, options -  validates that value matches/does not match 
+                                                      regular expression specified by option :with.
+                                                      Also, takes option :allow_nil
+  * be_of_length value, error_message, options - validates that value is any of: less than the number
+                                                 specified in the :minimum option, greater than the number
+                                                 specified in option :maximum, or in range specified by 
+                                                 option :range                    
+  
 == Relationships
 
 Mongomatic doesn't have any kind of special support for relationship management but it's easy to add this to your models where you need it. Here's an example that models Twitter-like followers on a User model:

data/lib/mongomatic.rb

@@ -15,10 +15,13 @@ end
 
 module Mongomatic
   class << self
+    # Returns an instance of Mongo::DB
     def db
       @db
     end
     
+    # Set to an instance of Mongo::DB to be used for all models:
+    #  Mongomatic.db = Mongo::Connection.new().db('mydb')
     def db=(obj)
       unless obj.is_a?(Mongo::DB)
         raise(ArgumentError, "Must supply a Mongo::DB object")
@@ -30,4 +33,5 @@ end
 require "#{File.dirname(__FILE__)}/mongomatic/cursor"
 require "#{File.dirname(__FILE__)}/mongomatic/modifiers"
 require "#{File.dirname(__FILE__)}/mongomatic/errors"
+require "#{File.dirname(__FILE__)}/mongomatic/expectations"
 require "#{File.dirname(__FILE__)}/mongomatic/base"

data/lib/mongomatic/base.rb

@@ -3,45 +3,56 @@ module Mongomatic
     include Mongomatic::Modifiers
     
     class << self
+      # Returns this models own db attribute if set, otherwise will return Mongomatic.db
       def db
         @db || Mongomatic.db || raise(ArgumentError, "No db supplied")
       end
       
+      # Override Mongomatic.db with a Mongo::DB instance for this model specifically
+      #  MyModel.db = Mongo::Connection.new().db('mydb_mymodel')
       def db=(obj)
         unless obj.is_a?(Mongo::DB)
           raise(ArgumentError, "Must supply a Mongo::DB object")
         end; @db = obj
       end
 
+      # Override this method on your model if you want to use a different collection name
       def collection_name
         self.to_s
       end
 
+      # Return the raw MongoDB collection for this model
       def collection
         @collection ||= self.db.collection(self.collection_name)
       end
 
+      # Query MongoDB for documents. Same arguments as http://api.mongodb.org/ruby/current/Mongo/Collection.html#find-instance_method
       def find(query={}, opts={})
         Mongomatic::Cursor.new(self, collection.find(query, opts))
       end
       
+      # Query MongoDB and return one document only. Same arguments as http://api.mongodb.org/ruby/current/Mongo/Collection.html#find_one-instance_method
       def find_one(query={}, opts={})
         return nil unless doc = self.collection.find_one(query, opts)
         self.new(doc, false)
       end
       
+      # Return a Mongomatic::Cursor instance of all documents in the collection.
       def all
         find
       end
       
+      # Iterate over all documents in the collection (uses a Mongomatic::Cursor)
       def each
         find.each { |found| yield(found) }
       end
       
+      # Return the first document in the collection
       def first
         find.limit(1).next_document
       end
       
+      # Return the number of documents in the collection
       def count
         find.count
       end
@@ -56,6 +67,12 @@ module Mongomatic
       self.errors  = Mongomatic::Errors.new
     end
     
+    # Override this with your own validate() method for validations.
+    # Simply push your errors into the self.errors property and
+    # if self.errors remains empty your document will be valid.
+    #  def validate
+    #    self.errors << ["name", "cannot be blank"]
+    #  end
     def validate
       true
     end
@@ -76,32 +93,48 @@ module Mongomatic
       self.is_new == true
     end
     
+    # Set a field on this document:
+    #  mydoc["name"] = "Ben"
+    #  mydoc["address"] = { "city" => "San Francisco" }
     def []=(k,v)
       @doc[k.to_s] = v
     end
     
+    # Fetch a field (just like a hash):
+    #  mydoc["name"]
+    #   => "Ben"
     def [](k)
       @doc[k.to_s]
     end
     
+    # Merge this document with the supplied hash. Useful for updates:
+    #  mydoc.merge(params[:user])
     def merge(hash)
       hash.each { |k,v| self[k] = v }; @doc
     end
     
+    # Will return true if the document has been removed.
     def removed?
       self.removed == true
     end
     
+    # Check equality with another Mongomatic document
     def ==(obj)
       obj.is_a?(self.class) && obj.doc["_id"] == @doc["_id"]
     end
 
+    # Reload the document from the database
     def reload
       if obj = self.class.find({"_id" => @doc["_id"]}).next_document
         @doc = obj.doc; true
       end
     end
 
+    # Insert the document into the database. Will return false if the document has
+    # already been inserted or is invalid. Returns the generated BSON::ObjectID
+    # for the new document. Will silently fail if MongoDB is unable to insert the
+    # document, use insert! if you want an error raised instead. Note that this will
+    # require an additional call to the db.
     def insert(opts={})
       return false unless new? && valid?
       self.send(:before_insert) if self.respond_to?(:before_insert)
@@ -115,10 +148,16 @@ module Mongomatic
       ret
     end
     
+    # Calls insert(...) with {:safe => true} passed in as an option. Will check MongoDB
+    # after insert to make sure that the insert was successful, and raise a Mongo::OperationError
+    # if there were any problems.
     def insert!(opts={})
       insert(opts.merge(:safe => true))
     end
     
+    # Will persist any changes you have made to the document. Will silently fail if
+    # MongoDB is unable to update the document, use update! instead if you want an
+    # error raised. Note that this will require an additional call to the db.
     def update(opts={},update_doc=@doc)
       return false if new? || removed? || !valid?
       self.send(:before_update) if self.respond_to?(:before_update)
@@ -129,10 +168,13 @@ module Mongomatic
       ret
     end
     
+    # Same as update(...) but will raise a Mongo::OperationError in case of any issues.
     def update!(opts={},update_doc=@doc)
       update(opts.merge(:safe => true),update_doc)
     end
     
+    # Remove this document from the collection. Silently fails on error, use remove!
+    # if you want an exception raised.
     def remove(opts={})
       return false if new?
       self.send(:before_remove) if self.respond_to?(:before_remove)
@@ -143,10 +185,13 @@ module Mongomatic
       ret
     end
     
+    # Like remove(...) but raises Mongo::OperationError if MongoDB is unable to
+    # remove the document.
     def remove!(opts={})
       remove(opts.merge(:safe => true))
     end
     
+    # Return this document as a hash.
     def to_hash
       @doc || {}
     end

data/lib/mongomatic/cursor.rb

@@ -1,4 +1,11 @@
 module Mongomatic
+  # Wraps a Mongo::Cursor for managing result sets from MongoDB:
+  #  cursor = User.find({"zip" => 94107})
+  #  user1 = cursor.next
+  #
+  #  User.find({"zip" => 94107}).each { |u| puts u["name"] }
+  #
+  #  User.find({"zip" => 94107}).count
   class Cursor
     include Enumerable
     

data/lib/mongomatic/expectations.rb

@@ -0,0 +1,89 @@
+module Mongomatic
+  module Expectations
+    module Helper
+      
+      private
+      
+      def define_expectations
+        Expectation.subclasses.each do |klass|
+          if Expectation.define_to_be?(klass)
+            instance_eval %Q{
+              def be_#{klass.name.downcase}(value, message, opts = {})
+                #{klass}.new(self, value, message, opts).to_be
+              end
+            }
+          end
+          if Expectation.define_to_not_be?(klass)
+            instance_eval %Q{
+              def not_be_#{klass.name.downcase}(value, message, opts = {})
+                #{klass}.new(self, value, message, opts).to_not_be
+              end
+            }
+          end
+        end
+      end
+      
+      def undefine_expectations
+        Expectation.subclasses.each do |klass|
+          instance_eval %Q{
+            if respond_to? "be_#{klass.name.downcase}"
+              class << self
+                remove_method "be_#{klass.name.downcase}" 
+              end
+            end
+            if respond_to? "not_be_#{klass.name.downcase}"
+              class << self
+                remove_method "not_be_#{klass.name.downcase}" 
+              end
+            end
+          }
+        end
+      end
+      
+      def expectations(&block)
+        define_expectations
+        block.call
+        undefine_expectations
+      end 
+    end
+    
+    class Expectation
+      
+      attr_accessor :instance, :value, :message, :opts
+      
+      class << self
+        attr_accessor :subclasses
+        
+        def subclasses
+          @subclasses ||= []
+          @subclasses
+        end
+        
+        def inherited(klass)
+          subclasses << klass
+        end
+        
+        def define_to_be?(klass)
+          klass.new(nil, nil, nil).respond_to? :to_be
+        end
+        
+        def define_to_not_be?(klass)
+          klass.new(nil, nil, nil).respond_to? :to_not_be
+        end
+      end
+      
+      def initialize(instance, value, message, opts = {})
+        @value = value
+        @instance = instance
+        @message = message
+        @opts = opts
+      end
+      
+      def add_error_msg
+        instance.errors << [message]
+      end
+    end
+  end
+end
+
+Dir["#{File.dirname(__FILE__)}/expectations/*.rb"].each { |f| require f }

data/lib/mongomatic/expectations/expected.rb

@@ -0,0 +1,9 @@
+class Expected < Mongomatic::Expectations::Expectation
+  def to_be
+    add_error_msg unless value
+  end
+
+  def to_not_be
+    add_error_msg if value
+  end
+end

data/lib/mongomatic/expectations/is_number.rb

@@ -0,0 +1,15 @@
+class IsNumber < Mongomatic::Expectations::Expectation
+  def self.name
+    "a_number"
+  end
+  
+  def to_be
+    return true if opts[:allow_nil] && value.nil?
+    
+    add_error_msg if (value.to_s =~ /^\d*\.{0,1}\d+$/).nil?
+  end
+  
+  def to_not_be
+    add_error_msg unless (value.to_s =~ /^\d*\.{0,1}\d+$/).nil?
+  end
+end

data/lib/mongomatic/expectations/match.rb

@@ -0,0 +1,15 @@
+class Match < Mongomatic::Expectations::Expectation
+  def self.name
+    "match"
+  end
+  
+  def to_be
+    return true if opts[:allow_nil] && value.nil?
+    
+    add_error_msg unless opts[:with].match(value.to_s)
+  end
+  
+  def to_not_be
+    add_error_msg if opts[:with].match(value.to_s)
+  end
+end

data/lib/mongomatic/expectations/of_length.rb

@@ -0,0 +1,16 @@
+class OfLength < Mongomatic::Expectations::Expectation
+  def self.name
+    "of_length"
+  end
+  
+  def to_be
+    return true if opts[:allow_nil] && value.nil?
+    
+    length = (value) ? value.size : value.to_s.size
+    add_error_msg if opts[:minimum] && length < opts[:minimum]
+    add_error_msg if opts[:maximum] && length > opts[:maximum]
+    if opts[:range]
+      add_error_msg unless opts[:range].include?(length)
+    end  
+  end
+end 

data/lib/mongomatic/expectations/present.rb

@@ -0,0 +1,9 @@
+class Present < Mongomatic::Expectations::Expectation
+  def to_be
+    add_error_msg if value.blank?
+  end
+  
+  def to_not_be
+    add_error_msg unless value.blank?
+  end
+end

data/lib/mongomatic/modifiers.rb

@@ -1,9 +1,11 @@
 module Mongomatic
+  # Provides convenience methods for atomic MongoDB operations.
   module Modifiers
 
-    # { $push : { field : value } }
-    # appends value to field, if field is an existing array, otherwise sets field to the array [value] 
+    # MongoDB equivalent: { $push : { field : value } }<br/>
+    # Appends value to field, if field is an existing array, otherwise sets field to the array [value] 
     # if field is not present. If field is present but is not an array, an error condition is raised.
+    #  user.push("interests", "skydiving")
     def push(field, val, do_reload=true)
       field = field.to_s
       if update({}, { "$push" => { field => val } })
@@ -11,10 +13,11 @@ module Mongomatic
       end
     end
     
-    # { $pushAll : { field : value_array } }
-    # appends each value in value_array to field, if field is an existing array, otherwise sets field to 
+    # MongoDB equivalent: { $pushAll : { field : value_array } }<br/>
+    # Appends each value in value_array to field, if field is an existing array, otherwise sets field to 
     # the array value_array if field is not present. If field is present but is not an array, an error 
     # condition is raised.
+    #  user.push("interests", ["skydiving", "coding"])
     def push_all(field, val, do_reload=true)
       field = field.to_s
       val = Array(val)
@@ -23,9 +26,10 @@ module Mongomatic
       end
     end
     
-    # { $pull : { field : _value } }
-    # removes all occurrences of value from field, if field is an array. If field is present but is not 
+    # MongoDB equivalent: { $pull : { field : _value } }<br/>
+    # Removes all occurrences of value from field, if field is an array. If field is present but is not 
     # an array, an error condition is raised.
+    #  user.pull("interests", "watching paint dry")
     def pull(field, val, do_reload=true)
       field = field.to_s
       if update({}, { "$pull" => { field => val } })
@@ -33,18 +37,20 @@ module Mongomatic
       end
     end
     
-    # { $pullAll : { field : value_array } }
-    # removes all occurrences of each value in value_array from field, if field is an array. If field is 
+    # MongoDB equivalent: { $pullAll : { field : value_array } }<br/>
+    # Removes all occurrences of each value in value_array from field, if field is an array. If field is 
     # present but is not an array, an error condition is raised.
-    def pullAll(field, val, do_reload=true)
+    #  user.pull_all("interests", ["watching paint dry", "sitting on my ass"])
+    def pull_all(field, val, do_reload=true)
       field = field.to_s
       if update({}, { "$pullAll" => { field => val } })
         reload if do_reload; true
       end
     end
     
-    # { $inc : { field : value } }
-    # increments field by the number value if field is present in the object, otherwise sets field to the number value.
+    # MongoDB equivalent: { $inc : { field : value } }<br/>
+    # Increments field by the number value if field is present in the object, otherwise sets field to the number value.
+    #  user.inc("cents_in_wallet", 1000)
     def inc(field, val, do_reload=true)
       field = field.to_s
       if update({}, { "$inc" => { field => val } })
@@ -52,8 +58,9 @@ module Mongomatic
       end
     end
     
-    # { $set : { field : value } }
-    # sets field to value. All datatypes are supported with $set.
+    # MongoDB equivalent: { $set : { field : value } }<br/>
+    # Sets field to value. All datatypes are supported with $set.
+    #  user.set("name", "Ben")
     def set(field, val, do_reload=true)
       field = field.to_s
       if update({}, { "$set" => { field => val } })
@@ -61,8 +68,9 @@ module Mongomatic
       end
     end
 
-    # { $unset : { field : 1} }
+    # MongoDB equivalent: { $unset : { field : 1} }<br/>
     # Deletes a given field. v1.3+
+    #  user.unset("name")
     def unset(field, do_reload=true)
       field = field.to_s
       if update({}, { "$unset" => { field => 1 } })
@@ -70,12 +78,11 @@ module Mongomatic
       end
     end
     
-    # { $addToSet : { field : value } }
-    # Adds value to the array only if its not in the array already.
-    # 
-    # To add many valuest.update
-    # 
+    # MongoDB equivalent: { $addToSet : { field : value } }<br/>
+    # Adds value to the array only if its not in the array already.<br/>
+    # Or to add many values:<br/>
     # { $addToSet : { a : { $each : [ 3 , 5 , 6 ] } } }
+    #  user.add_to_set("friend_ids", BSON::ObjectID('...'))
     def add_to_set(field, val, do_reload=true)
       field = field.to_s
       if update({}, { "$addToSet" => { field => val } })
@@ -83,8 +90,9 @@ module Mongomatic
       end
     end
     
-    # { $pop : { field : 1  } }
-    # removes the last element in an array (ADDED in 1.1)
+    # MongoDB equivalent: { $pop : { field : 1  } }<br/>
+    # Removes the last element in an array (ADDED in 1.1)
+    #  user.pop_last("friend_ids")
     def pop_last(field, do_reload=true)
       field = field.to_s
       if update({}, { "$pop" => { field => 1 } })
@@ -92,8 +100,9 @@ module Mongomatic
       end
     end
     
-    # { $pop : { field : -1  } }
-    # removes the first element in an array (ADDED in 1.1)
+    # MongoDB equivalent: { $pop : { field : -1  } }<br/>
+    # Removes the first element in an array (ADDED in 1.1)
+    #  user.pop_first("friend_ids")
     def pop_first(field, do_reload=true)
       field = field.to_s
       if update({}, { "$pop" => { field => -1 } })

data/test/helper.rb

@@ -10,6 +10,7 @@ require 'mongomatic'
 Mongomatic.db = Mongo::Connection.new.db("mongomatic_test")
 
 class Person < Mongomatic::Base
+  include Mongomatic::Expectations::Helper
   attr_accessor :callback_tests
   
   def self.create_indexes

data/test/test_mongomatic.rb

@@ -212,4 +212,169 @@ class TestMongomatic < Test::Unit::TestCase
     assert_equal found["_id"], "mycustomid"
     assert_equal 26, found["age"]
   end
+ 
+  should "be able to use the be_expect expectation" do
+    p = Person.new
+    class << p
+      def validate
+        expectations do
+          be_expected self['alive'], "Alive must be true"
+          not_be_expected self['dead'], "Dead must be false"
+        end
+      end
+    end
+    
+    assert !p.valid?
+    assert_equal ['Alive must be true'], p.errors.full_messages
+    
+    p['alive'] = true
+    assert p.valid?
+    
+    p['dead'] = true
+    assert !p.valid?
+    assert_equal ['Dead must be false'], p.errors.full_messages
+  end
+  
+  should "be able to use the be_present expectation" do
+    p = Person.new
+    class << p
+      def validate
+        expectations do 
+          be_present self['name'], 'name cannot be blank' 
+          not_be_present self['age'],  'age must be blank'
+        end
+      end
+    end
+    
+    assert !p.valid?
+    assert_equal ['name cannot be blank'], p.errors.full_messages
+    
+    p['name'] = "Jordan"
+    p['age'] = 21
+    
+    
+    assert !p.valid?
+    assert_equal ['age must be blank'], p.errors.full_messages
+    
+    p['age'] = nil
+    
+    assert p.valid?
+    
+  end
+  
+  should "be able to use be_a_number expectation" do
+    p = Person.new
+    class << p
+      def validate
+        expectations do
+          be_a_number self['age'], 'Age is not a number'
+          not_be_a_number self['name'], 'Name cannot be a number'
+          be_a_number self['birth_year'], 'Birth year is not a number', :allow_nil => true
+        end
+      end
+    end
+    
+    assert !p.valid?
+    assert_equal ["Age is not a number"], p.errors.full_messages
+    
+    p['age'] = 21
+    p['name'] = 65
+    
+    assert !p.valid?
+    assert_equal ["Name cannot be a number"], p.errors.full_messages
+    
+    p['name'] = 'Jordan'
+    
+    assert p.valid?
+  end
+  
+  should "be able to use be_match expectation" do
+    p = Person.new
+    class << p
+      def validate
+        expectations do 
+          be_match self['name'], "Name must start with uppercase letter", :with => /[A-Z][a-z]*/
+          not_be_match self['nickname'], "Nickname cannot start with uppercase letter", :with => /[A-Z][a-z]*/
+          be_match self['age'], "Age must only contain digits", :with => /\d+/, :allow_nil => true
+        end
+      end
+    end
+    
+    assert !p.valid?
+    assert_equal ["Name must start with uppercase letter"], p.errors.full_messages
+    
+    p['name'] = 'Jordan'
+    p['nickname'] = 'Jordan'
+    
+    assert !p.valid?
+    assert_equal ["Nickname cannot start with uppercase letter"], p.errors.full_messages
+    
+    p['nickname'] = 'jordan'
+    
+    assert p.valid?
+    
+    p['age'] = 'asd'
+    
+    assert !p.valid?
+    assert_equal ["Age must only contain digits"], p.errors.full_messages
+    
+    p['age'] = '21'
+    
+    assert p.valid?
+    
+  end
+  
+  should "be able to use be_of_length expectation" do
+    p = Person.new
+    class << p
+      def validate
+        expectations do
+          be_of_length self['name'], "Name must be 3 characters long", :minimum => 3
+          be_of_length self['nickname'], "Nickname must not be longer than 5 characters", :maximum => 5
+          be_of_length self['computers'], "Can only specify between 1 and 3 computers", :range => 1..3
+          be_of_length self['status'], "Status must be a minimum of 1 character", :minumum => 1, :allow_nil => true
+        end
+      end
+    end
+    
+    assert !p.valid?
+    assert_equal ["Name must be 3 characters long",  
+                  "Can only specify between 1 and 3 computers"], p.errors.full_messages
+            
+    p['name'] = 'Jordan'
+    p['nickname'] = 'Jordan'
+    
+    assert !p.valid?
+    assert_equal ["Nickname must not be longer than 5 characters", 
+                  "Can only specify between 1 and 3 computers"], p.errors.full_messages
+                  
+    p['nickname'] = 'abc'
+    p['computers'] = ['comp_a']
+    
+    assert p.valid?
+  end
+  
+  should "raise an error if expectations are called outside of helper block" do
+    p = Person.new
+    class << p
+      def validate
+        be_present self['name'], ''
+      end
+    end
+    
+    assert_raise NoMethodError do
+      p.valid?
+    end
+    
+    class << p
+      def validate
+        expectations {  }
+        be_present
+      end
+    end
+    
+    assert_raise NameError do 
+      p.valid?
+    end
+  end
 end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 2
+  - 3
   - 0
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Ben Myles
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-08-12 00:00:00 -07:00
+date: 2010-08-14 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -106,13 +106,19 @@ files:
 - lib/mongomatic/base.rb
 - lib/mongomatic/cursor.rb
 - lib/mongomatic/errors.rb
+- lib/mongomatic/expectations.rb
+- lib/mongomatic/expectations/expected.rb
+- lib/mongomatic/expectations/is_number.rb
+- lib/mongomatic/expectations/match.rb
+- lib/mongomatic/expectations/of_length.rb
+- lib/mongomatic/expectations/present.rb
 - lib/mongomatic/modifiers.rb
 - LICENSE
 - README.rdoc
 - test/helper.rb
 - test/test_mongomatic.rb
 has_rdoc: true
-homepage: http://github.com/benmyles/mongomatic
+homepage: http://mongomatic.com/
 licenses: []
 
 post_install_message: