lib/ohm.rb in ohm-2.3.0 vs lib/ohm.rb in ohm-3.0.0

@@ -1,8 +1,8 @@
 # encoding: UTF-8
 
-require "msgpack"
+require "json"
 require "nido"
 require "redic"
 require "stal"
 
 module Ohm
@@ -475,21 +475,33 @@
     #
     def sort_by(att, options = {})
       sort(options.merge(:by => to_key(att)))
     end
 
-    # Syntactic sugar for `sort_by` or `sort` when you only need the
-    # first element.
+    # Returns the first record of the set. Internally uses `sort` or
+    # `sort_by` if a `:by` option is given. Accepts all options supported
+    # by `sort`.
     #
-    # Example:
+    #   class User < Ohm::Model
+    #     attribute :name
+    #   end
     #
-    #   User.all.first ==
-    #     User.all.sort(:limit => [0, 1]).first
+    #   User.create(name: "alice")
+    #   User.create(name: "bob")
+    #   User.create(name: "eve")
     #
-    #   User.all.first(:by => :name, "ALPHA") ==
-    #     User.all.sort_by(:name, :order => "ALPHA", :limit => [0, 1]).first
+    #   User.all.first.name # => "alice"
+    #   User.all.first(by: :name).name # => "alice"
     #
+    #   User.all.first(order: "ASC")  # => "alice"
+    #   User.all.first(order: "DESC") # => "eve"
+    #
+    # You can use the `:order` option to bring the last record:
+    #
+    #   User.all.first(order: "DESC").name             # => "eve"
+    #   User.all.first(by: :name, order: "ALPHA DESC") # => "eve"
+    #
     def first(options = {})
       opts = options.dup
       opts.merge!(:limit => [0, 1])
 
       if opts[:by]
@@ -533,13 +545,14 @@
     #
     # Example:
     #
     #   set = User.find(:status => "active")
     #   set.combine(:name => ["John", "Jane"])
-    #   
+    #
     #   # The result will include all users with active status
     #   # and with names "John" or "Jane".
+    #
     def combine(dict)
       Ohm::Set.new(
         model, namespace, [:SINTER, key, [:SUNION, *model.filters(dict)]]
       )
     end
@@ -650,11 +663,11 @@
   #
   #     set :posts, :Post
   #   end
   #
   #   u = User.create(:name => "John", :email => "[e-mail]")
-  #   u.incr :points
+  #   u.increment :points
   #   u.posts.add(Post.create)
   #
   # When you execute `User.create(...)`, you run the following Redis
   # commands:
   #
@@ -1039,22 +1052,22 @@
       end
     end
 
     # Declare a counter. All the counters are internally stored in
     # a different Redis hash, independent from the one that stores
-    # the model attributes. Counters are updated with the `incr` and
-    # `decr` methods, which interact directly with Redis. Their value
-    # can't be assigned as with regular attributes.
+    # the model attributes. Counters are updated with the `increment`
+    # and `decrement` methods, which interact directly with Redis. Their
+    # value can't be assigned as with regular attributes.
     #
     # Example:
     #
     #   class User < Ohm::Model
     #     counter :points
     #   end
     #
     #   u = User.create
-    #   u.incr :points
+    #   u.increment :points
     #
     #   u.points
     #   # => 1
     #
     # Note: You can't use counters until you save the model. If you
@@ -1086,10 +1099,11 @@
     end
 
     # Returns the namespace for the keys generated using this model.
     # Check `Ohm::Model.key` documentation for more details.
     def key
+      raise MissingID if not defined?(@id)
       model.key[id]
     end
 
     # Initialize a model using a dictionary of attributes.
     #
@@ -1116,11 +1130,10 @@
     #
     #   u.key
     #   # => User:1
     #
     def id
-      raise MissingID if not defined?(@id)
       @id
     end
 
     # Check for equality by doing the following assertions:
     #
@@ -1189,24 +1202,54 @@
     #   # => true
     #
     #   u.save
     #   u.new?
     #   # => false
+    #
     def new?
       !defined?(@id)
     end
 
-    # Increment a counter atomically. Internally uses HINCRBY.
-    def incr(att, count = 1)
+    # Increments a counter atomically. Internally uses `HINCRBY`.
+    #
+    #   class Ad
+    #     counter :hits
+    #   end
+    #
+    #   ad = Ad.create
+    #
+    #   ad.increment(:hits)
+    #   ad.hits # => 1
+    #
+    #   ad.increment(:hits, 2)
+    #   ad.hits # => 3
+    #
+    def increment(att, count = 1)
       redis.call("HINCRBY", key[:counters], att, count)
     end
 
-    # Decrement a counter atomically. Internally uses HINCRBY.
-    def decr(att, count = 1)
-      incr(att, -count)
+    # Decrements a counter atomically. Internally uses `HINCRBY`.
+    #
+    #   class Post
+    #     counter :score
+    #   end
+    #
+    #   post = Post.create
+    #
+    #   post.decrement(:score)
+    #   post.score # => -1
+    #
+    #   post.decrement(:hits, 2)
+    #   post.score # => -3
+    #
+    def decrement(att, count = 1)
+      increment(att, -count)
     end
 
+    alias_method(:incr, :increment)
+    alias_method(:decr, :decrement)
+
     # Return a value that allows the use of models as hash keys.
     #
     # Example:
     #
     #   h = {}
@@ -1303,14 +1346,14 @@
       if defined?(@id)
         features["id"] = @id
       end
 
       @id = script(LUA_SAVE, 0,
-        features.to_msgpack,
-        _sanitized_attributes.to_msgpack,
-        indices.to_msgpack,
-        uniques.to_msgpack
+        features.to_json,
+        _sanitized_attributes.to_json,
+        indices.to_json,
+        uniques.to_json
       )
 
       return self
     end
 
@@ -1328,12 +1371,12 @@
 
       script(LUA_DELETE, 0,
         { "name" => model.name,
           "id" => id,
           "key" => key
-        }.to_msgpack,
-        uniques.to_msgpack,
-        model.tracked.to_msgpack
+        }.to_json,
+        uniques.to_json,
+        model.tracked.to_json
       )
 
       return self
     end