ohm 0.0.16 → 0.0.17

data/README.markdown

@@ -7,7 +7,7 @@ Object-hash mapping library for Redis.
 Description
 -----------
 
-Ohm is a library that allows to store an object in
+Ohm is a library for storing objects in
 [Redis](http://code.google.com/p/redis/), a persistent key-value
 database. It includes an extensible list of validations and has very
 good performance.
@@ -28,6 +28,8 @@ If you don't have Ohm, try this:
 
     $ sudo gem install ohm
 
+Or you can grab the code from [http://github.com/soveran/ohm](http://github.com/soveran/ohm).
+
 Now, in an irb session you can test the Redis adapter directly:
 
     >> require "ohm"
@@ -62,10 +64,25 @@ the example below:
       end
     end
 
+All models have the `id` attribute built in, you don't need to declare it.
+
+This is how you interact with ids:
+
+    event = Event.create :name => "Ohm Worldwide Conference 2031"
+    event.id
+    # => 1
+
+    # Find an event by id
+    event == Event[1]
+    # => true
+
+    # Trying to find a non existent event
+    Event[2]
+    # => nil
+
 This example shows some basic features, like attribute declarations and
 validations. Keep reading to find out what you can do with models.
 
-
 Attribute types
 ---------------
 
@@ -99,6 +116,24 @@ the value, but you can not assign it. In the example above, we used a
 counter attribute for tracking votes. As the incr and decr operations
 are atomic, you can rest assured a vote won't be counted twice.
 
+Associations
+------------
+
+Ohm lets you use collections (lists and sets) to represent associations.
+For this, you only need to provide a second paramenter when declaring a
+list or a set:
+
+    set :attendees, Person
+
+After this, everytime you refer to `event.attendees` you will be talking
+about instances of the model `Person`. If you want to get the raw values
+of the set, you can use `event.attendees.raw`.
+
+The `attendees` collection also exposes two sorting methods: `sort`
+returns the elements ordered by `id`, and `sort_by` receives a parameter
+with an attribute name, which will determine the sorting order. Both
+methods receive an options hash which is explained in the documentation
+for {Ohm::Attributes::Collection#sort}.
 
 Indexes
 -------
@@ -206,7 +241,8 @@ Given the following example:
 
 If all the assertions fail, the following errors will be present:
 
-    obj.errors #=> [[:foo, :not_present], [:bar, :not_numeric], [:baz, :format], [[:qux], :not_unique]]
+    obj.errors
+    # => [[:foo, :not_present], [:bar, :not_numeric], [:baz, :format], [[:qux], :not_unique]]
 
 Note that the error for assert_unique wraps the field in an array.
 The purpose for this is to standardize the format for both single and
@@ -229,7 +265,8 @@ is as follows:
       e.on [:account, :not_present], "You must supply an account"
     end
 
-    error_messages #=> ["Name must be present", "You must supply an account"]
+    error_messages
+    # => ["Name must be present", "You must supply an account"]
 
 Having the error message definitions in the views means you can use any
 sort of helpers. You can also use blocks instead of strings for the
@@ -241,4 +278,5 @@ values. The result of the block is used as the error message:
       end
     end
 
-    error_messages #=> ["The email foo@example.com is already registered."]
+    error_messages
+    # => ["The email foo@example.com is already registered."]

data/lib/ohm.rb

@@ -84,14 +84,32 @@ module Ohm
         instantiate(db.sort(key, options))
       end
 
-      # Sort the model instances by the given value.
+      # Sort the model instances by the given attribute.
+      #
+      # @example Sorting elements by name:
+      #
+      #   User.create :name => "B"
+      #   User.create :name => "A"
+      #
+      #   user = User.all.sort_by :name, :order => "ALPHA"
+      #   user.name == "A" #=> true
       def sort_by(att, options = {})
         sort(options.merge(:by => model.key("*", att)))
       end
 
+      # Sort the model instances by id and return the first instance
+      # found. If a :by option is provided with a valid attribute name, the
+      # method sort_by is used instead and the option provided is passed as the
+      # first parameter.
+      #
+      # @see #sort
+      # @see #sort_by
       # @return [Ohm::Model, nil] Returns the first instance found or nil.
-      def first
-        sort(:limit => 1).first
+      def first(options = {})
+        options = options.merge(:limit => 1)
+        options[:by] ?
+          sort_by(options.delete(:by), options).first :
+          sort(options).first
       end
 
       def to_ary
@@ -172,8 +190,8 @@ module Ohm
     #   company = Company.create :name => "Redis Co."
     #   company.employees << "Albert"
     #   company.employees << "Benoit"
-    #   company.employees.all #=> ["Albert", "Benoit"]
-    #   company.include?("Albert") #=> true
+    #   company.employees.all       #=> ["Albert", "Benoit"]
+    #   company.include?("Albert")  #=> true
     class Set < Collection
 
       # @param value [#to_s] Adds value to the list.
@@ -386,7 +404,7 @@ module Ohm
     end
 
     def save
-      create if new?
+      return create if new?
       return unless valid?
       update_indices
       save!

data/test/model_test.rb

@@ -186,6 +186,20 @@ class TestRedis < Test::Unit::TestCase
       Ohm.flush
       assert_equal [], Person.all.sort_by(:name)
     end
+
+    should "return the first element sorted by id when using first" do
+      Ohm.flush
+      Person.create :name => "A"
+      Person.create :name => "B"
+      assert_equal "A", Person.all.first.name
+    end
+
+    should "return the first element sorted by name if first receives a sorting option" do
+      Ohm.flush
+      Person.create :name => "B"
+      Person.create :name => "A"
+      assert_equal "A", Person.all.first(:by => :name, :order => "ALPHA").name
+    end
   end
 
   context "Loading attributes" do
@@ -399,7 +413,7 @@ class TestRedis < Test::Unit::TestCase
     end
 
     should "return instances of the passed model" do
-      assert_equal Post, @user.posts.all.first.class
+      assert_equal Post, @user.posts.first.class
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: ohm
 version: !ruby/object:Gem::Version 
-  version: 0.0.16
+  version: 0.0.17
 platform: ruby
 authors: 
 - Michel Martens
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-08-04 00:00:00 -03:00
+date: 2009-08-25 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -65,7 +65,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: ohm
-rubygems_version: 1.3.5
+rubygems_version: 1.3.4
 signing_key: 
 specification_version: 3
 summary: Object-hash mapping library for Redis.