ohm 0.0.32 → 0.0.33

data/README.markdown

@@ -3,7 +3,6 @@ Ohm ॐ
 
 Object-hash mapping library for Redis.
 
-
 Description
 -----------
 
@@ -47,7 +46,6 @@ Now, in an irb session you can test the Redis adapter directly:
     >> Ohm.redis.get "Foo"
     => "Bar"
 
-
 Models
 ------
 
@@ -59,8 +57,8 @@ the example below:
 
     class Event < Ohm::Model
       attribute :name
-      set :participants
-      list :comments
+      reference :venue, Venue
+      set :participants, Person
       counter :votes
 
       index :name
@@ -70,9 +68,18 @@ the example below:
       end
     end
 
+    class Venue < Ohm::Model
+      attribute :name
+      collection :events, Event
+    end
+
+    class Person < Ohm::Model
+      attribute :name
+    end
+
 All models have the `id` attribute built in, you don't need to declare it.
 
-This is how you interact with ids:
+This is how you interact with IDs:
 
     event = Event.create :name => "Ohm Worldwide Conference 2031"
     event.id
@@ -92,13 +99,16 @@ validations. Keep reading to find out what you can do with models.
 Attribute types
 ---------------
 
-Ohm::Model provides four attribute types: `attribute`, `set`, `list` and
-`counter`.
+Ohm::Model provides four attribute types: {Ohm::Model::attribute
+attribute}, {Ohm::Model::set set}, {Ohm::Model::list list}
+and {Ohm::Model::counter counter}; and two meta types:
+{Ohm::Model::reference reference} and {Ohm::Model::collection
+collection}.
 
 ### attribute
 
 An `attribute` is just any value that can be stored as a string. In the
-example above, we used this field to store the Event's `name`. You can
+example above, we used this field to store the event's `name`. You can
 use it to store numbers, but be aware that Redis will return a string
 when you retrieve the value.
 
@@ -122,6 +132,17 @@ 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.
 
+### reference
+
+It's a special kind of attribute that references another model.
+Internally, Ohm will keep a pointer to the model (its ID), but you get
+accessors that give you real instances. You can think of it as the model
+containing the foreign key to another model.
+
+### collection
+
+Provides an accessor to search for all models that `reference` the current model.
+
 Persistence strategy
 --------------------
 
@@ -150,54 +171,69 @@ If you are saving the object, this will suffice:
       event.comments << "Wonderful event!"
     end
 
+Working with Sets
+-----------------
 
-Associations
-------------
-
-Ohm lets you use collections (lists and sets) to represent associations.
-For this, you only need to provide a second parameter when declaring a
-list or a set:
-
-    set :attendees, Person
-
-After this, every time 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`.
+Given the following model declaration:
 
-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}.
+    class Event < Ohm::Model
+      attribute :name
+      set :attendees, Person
+    end
 
-Adding instances of `Person` to the attendees hash is done with the
-`add` method:
+You can add instances of `Person` to the set of attendees with the
+`<<` method:
 
-    @event.attendees.add(Person.create(name: "Albert"))
+    @event.attendees << Person.create(name: "Albert")
 
     # And now...
     @event.attendees.each do |person|
       # ...do what you want with this person.
     end
 
-Just to clarify: when you add items to a set with `<<`, Ohm inserts
-whatever you send without checking it. When you use `add`, it assumes
-it's an instance of some `Ohm::Model` and stores its id.
+Sorting
+-------
+
+Since `attendees` is a {Ohm::Model::Set Set}, it exposes two sorting
+methods: {Ohm::Model::Collection#sort sort} returns the elements
+ordered by `id`, and {Ohm::Model::Collection#sort_by 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::Model::Collection#sort sort}.
+
+Associations
+------------
+
+Ohm lets you declare `references` and `collections` to represent associations.
+
+    class Post < Ohm::Model
+      attribute :title
+      attribute :body
+      collection :comments, Comment
+    end
+
+    class Comment < Ohm::Model
+      attribute :body
+      reference :post, Post
+    end
 
+After this, every time you refer to `post.comments` you will be talking
+about instances of the model `Comment`. If you want to get a list of IDs
+you can use `post.comments.raw`.
 
 Indexes
 -------
 
 An index is a set that's handled automatically by Ohm. For any index declared,
-Ohm maintains different sets of objects ids for quick lookups.
+Ohm maintains different sets of objects IDs for quick lookups.
 
-For example, in the example above, the index on the name attribute will
-allow for searches like Event.find(name: "some value").
+In the `Event` example, the index on the name attribute will
+allow for searches like `Event.find(name: "some value")`.
 
 Note that the `assert_unique` validation and the methods `find` and `except` need a
 corresponding index in order to work.
 
-### Finding
+### Finding records
 
 You can find a collection of records with the `find` method:
 
@@ -230,7 +266,6 @@ are valid. Nesting assertions is a good practice, and you are also
 encouraged to create your own assertions. You can trigger validations at
 any point by calling `valid?` on a model instance.
 
-
 Assertions
 -----------
 

data/lib/ohm/collection.rb

@@ -0,0 +1,186 @@
+module Ohm
+  class Collection
+    include Enumerable
+
+    attr_accessor :key, :db
+
+    def initialize(key, db = Ohm.redis)
+      self.key = key
+      self.db = db
+    end
+
+    def each(&block)
+      all.each(&block)
+    end
+
+    # Return the values as model instances, ordered by the options supplied.
+    # Check redis documentation to see what values you can provide to each option.
+    #
+    # @param options [Hash] options to sort the collection.
+    # @option options [#to_s] :by Model attribute to sort the instances by.
+    # @option options [#to_s] :order (ASC) Sorting order, which can be ASC or DESC.
+    # @option options [Integer] :limit (all) Number of items to return.
+    # @option options [Integer] :start (0) An offset from where the limit will be applied.
+    #
+    # @example Get the first ten users sorted alphabetically by name:
+    #
+    #   @event.attendees.sort(:by => :name, :order => "ALPHA", :limit => 10)
+    #
+    # @example Get five posts sorted by number of votes and starting from the number 5 (zero based):
+    #
+    #   @blog.posts.sort(:by => :votes, :start => 5, :limit => 10")
+    def sort(options = {})
+      return [] if empty?
+      options[:start] ||= 0
+      options[:limit] = [options[:start], options[:limit]] if options[:limit]
+      db.sort(key, options)
+    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
+    # @return [Ohm::Model, nil] Returns the first instance found or nil.
+    def first(options = {})
+      options = options.merge(:limit => 1)
+      sort(options).first
+    end
+
+    def [](index)
+      first(:start => index)
+    end
+
+    def to_ary
+      all
+    end
+
+    def ==(other)
+      to_ary == other
+    end
+
+    # @return [true, false] Returns whether or not the collection is empty.
+    def empty?
+      size.zero?
+    end
+
+    # Clears the values in the collection.
+    def clear
+      db.del(key)
+      self
+    end
+
+    # Appends the given values to the collection.
+    def concat(values)
+      values.each { |value| self << value }
+      self
+    end
+
+    # Replaces the collection with the passed values.
+    def replace(values)
+      clear
+      concat(values)
+    end
+  end
+
+  # Represents a Redis list.
+  #
+  # @example Use a list attribute.
+  #
+  #   class Event < Ohm::Model
+  #     attribute :name
+  #     list :participants
+  #   end
+  #
+  #   event = Event.create :name => "Redis Meeting"
+  #   event.participants << "Albert"
+  #   event.participants << "Benoit"
+  #   event.participants.all
+  #   # => ["Albert", "Benoit"]
+  class List < Collection
+
+    # @param value [#to_s] Pushes value to the tail of the list.
+    def << value
+      db.rpush(key, value)
+    end
+
+    alias push <<
+
+    # @return [String] Return and remove the last element of the list.
+    def pop
+      db.rpop(key)
+    end
+
+    # @return [String] Return and remove the first element of the list.
+    def shift
+      db.lpop(key)
+    end
+
+    # @param value [#to_s] Pushes value to the head of the list.
+    def unshift(value)
+      db.lpush(key, value)
+    end
+
+    # @return [Array] Elements of the list.
+    def all
+      db.list(key)
+    end
+
+    # @return [Integer] Returns the number of elements in the list.
+    def size
+      db.llen(key)
+    end
+
+    def include?(value)
+      all.include?(value)
+    end
+
+    def inspect
+      "#<List: #{all.inspect}>"
+    end
+  end
+
+  # Represents a Redis set.
+  #
+  # @example Use a set attribute.
+  #
+  #   class Company < Ohm::Model
+  #     attribute :name
+  #     set :employees
+  #   end
+  #
+  #   company = Company.create :name => "Redis Co."
+  #   company.employees << "Albert"
+  #   company.employees << "Benoit"
+  #   company.employees.all       #=> ["Albert", "Benoit"]
+  #   company.employees.include?("Albert")  #=> true
+  class Set < Collection
+
+    # @param value [#to_s] Adds value to the list.
+    def << value
+      db.sadd(key, value)
+    end
+
+    def delete(value)
+      db.srem(key, value)
+    end
+
+    def include?(value)
+      db.sismember(key, value)
+    end
+
+    def all
+      db.smembers(key)
+    end
+
+    # @return [Integer] Returns the number of elements in the set.
+    def size
+      db.scard(key)
+    end
+
+    def inspect
+      "#<Set: #{all.inspect}>"
+    end
+  end
+end

data/lib/ohm/compat-1.8.6.rb

@@ -13,3 +13,12 @@ unless "".respond_to?(:lines)
     end
   end
 end
+
+unless Object.new.respond_to?(:tap)
+  class Object
+    def tap
+      yield(self)
+      self
+    end
+  end
+end

data/lib/ohm/key.rb

@@ -0,0 +1,46 @@
+module Ohm
+
+  # Represents a key in Redis.
+  class Key
+    attr :parts
+    attr :glue
+    attr :namespace
+
+    def self.[](*parts)
+      Key.new(parts)
+    end
+
+    def initialize(parts, glue = ":", namespace = [])
+      @parts = parts
+      @glue = glue
+      @namespace = namespace
+    end
+
+    def append(*parts)
+      @parts += parts
+      self
+    end
+
+    def eql?(other)
+      to_s == other.to_s
+    end
+
+    alias == eql?
+
+    def to_s
+      (namespace + [@parts.join(glue)]).join(":")
+    end
+
+    alias inspect to_s
+    alias to_str to_s
+
+    def volatile
+      @namespace = [:~]
+      self
+    end
+
+    def group(glue = self.glue)
+      Key.new([self], glue, namespace.slice!(0, namespace.size))
+    end
+  end
+end

data/lib/ohm/redis.rb

@@ -33,7 +33,6 @@ module Ohm
       :lpush => true,
       :lrem => true,
       :lset => true,
-      :rpoplpush => true,
       :rpush => true,
       :sadd => true,
       :set => true,