amico 1.1.0 → 1.2.0

data/.gitignore

@@ -4,3 +4,4 @@ Gemfile.lock
 pkg/*
 .yardoc
 doc
+*.rdb

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+# 1.2.0
+
+* Added pending to relationships
+
 # 1.1.0
 
 * Added blocking to relationships

data/README.md

@@ -27,6 +27,8 @@ Amico.configure do |configuration|
   configuration.followers_key = 'followers'
   configuration.blocked_key = 'blocked'
   configuration.reciprocated_key = 'reciprocated'
+  configuration.pending_key = 'pending'
+  configuration.pending_follow = false
   configuration.page_size = 25
 end
 ```
@@ -44,6 +46,8 @@ Amico.configure do |configuration|
   configuration.followers_key = 'followers'
   configuration.blocked_key = 'blocked'
   configuration.reciprocated_key = 'reciprocated'
+  configuration.pending_key = 'pending'
+  configuration.pending_follow = false
   configuration.page_size = 25
 end
 
@@ -111,10 +115,98 @@ Amico.reciprocated(1)
  => ["11"]
 ```
 
+Use amico (with pending relationships for follow):
+
+```ruby
+require 'amico'
+ => true 
+
+Amico.configure do |configuration|
+  configuration.redis = Redis.new
+  configuration.namespace = 'amico'
+  configuration.following_key = 'following'
+  configuration.followers_key = 'followers'
+  configuration.blocked_key = 'blocked'
+  configuration.reciprocated_key = 'reciprocated'
+  configuration.pending_key = 'pending'
+  configuration.pending_follow = true
+  configuration.page_size = 25
+end
+
+Amico.follow(1, 11)
+ => true 
+
+Amico.follow(11, 1)
+ => true 
+
+Amico.pending?(1, 11)
+ => true 
+
+Amico.pending?(11, 1)
+ => true 
+
+Amico.accept(1, 11)
+ => nil 
+
+Amico.pending?(1, 11)
+ => false 
+
+Amico.pending?(11, 1)
+ => true 
+
+Amico.following?(1, 11)
+ => true 
+
+Amico.following?(11, 1)
+ => false 
+
+Amico.follower?(11, 1)
+ => true 
+
+Amico.follower?(1, 11)
+ => false 
+
+Amico.accept(11, 1)
+ => [1, 1] 
+
+Amico.pending?(1, 11)
+ => false 
+
+Amico.pending?(11, 1)
+ => false 
+
+Amico.following?(1, 11)
+ => true 
+
+Amico.following?(11, 1)
+ => true 
+
+Amico.follower?(11, 1)
+ => true 
+
+Amico.follower?(1, 11)
+ => true 
+ 
+Amico.reciprocated?(1, 11)
+ => true 
+```
+
 ## Documentation 
 
 The source for the [relationships module](https://github.com/agoragames/amico/blob/master/lib/amico/relationships.rb) is well-documented. There are some 
-simple examples in the method documentation. You can also refer to the [online documentation](http://rubydoc.info/gems/amico/).
+simple examples in the method documentation. You can also refer to the [online documentation](http://rubydoc.info/github/agoragames/amico/master/frames).
+
+## FAQ?
+
+### Why use Redis sorted sets and not Redis sets?
+
+Based on the work I did in developing [leaderboard](https://github.com/agoragames/leaderboard), 
+leaderboards backed by Redis, I know I wanted to be able to page through the various relationships. 
+This does not seem to be possible given the current set of commands for Redis sets. 
+
+Also, by using the "score" in Redis sorted sets that is based on the time of when a relationship 
+is established, we can get our "recent friends". It is possible that the scoring function may be 
+user-defined in the future to allow for some specific ordering.
   
 ## Contributing to amico
  

data/lib/amico/configuration.rb

@@ -1,28 +1,34 @@
 module Amico
   # Configuration settings for Amico.
   module Configuration
-    # Public: Redis instance.
+    # Redis instance.
     attr_accessor :redis
 
-    # Public: Amico namespace for Redis.
-    attr_accessor :namespace
+    # Amico namespace for Redis.
+    attr_writer :namespace
 
-    # Public: Key used in Redis for tracking who an individual is following.
-    attr_accessor :following_key
+    # Key used in Redis for tracking who an individual is following.
+    attr_writer :following_key
 
-    # Public: Key used in Redis for tracking the followers of an individual.
-    attr_accessor :followers_key
+    # Key used in Redis for tracking the followers of an individual.
+    attr_writer :followers_key
 
-    # Public: Key used in Redis for tracking who an individual blocks.
-    attr_accessor :blocked_key
+    # Key used in Redis for tracking who an individual blocks.
+    attr_writer :blocked_key
 
-    # Public: Key used in Redis for tracking who has reciprocated a follow for an individual.
-    attr_accessor :reciprocated_key
+    # Key used in Redis for tracking who has reciprocated a follow for an individual.
+    attr_writer :reciprocated_key
 
-    # Public: Page size to be used when paging through the various types of relationships.
-    attr_accessor :page_size
+    # Key used in Redis for tracking pending follow relationships for an individual.
+    attr_writer :pending_key
 
-    # Public: Yield self to be able to configure Amico with block-style configuration.
+    # Key used to indicate whether or not a follow should be pending or not.
+    attr_writer :pending_follow
+
+    # Page size to be used when paging through the various types of relationships.
+    attr_writer :page_size
+
+    # Yield self to be able to configure Amico with block-style configuration.
     #
     # Example:
     #
@@ -33,50 +39,66 @@ module Amico
     #     configuration.followers_key = 'followers'
     #     configuration.blocked_key = 'blocked'
     #     configuration.reciprocated_key = 'reciprocated'
+    #     configuration.pending_key = 'pending'
+    #     configuration.pending_follow = false
     #     configuration.page_size = 25
     #   end
     def configure
       yield self
     end
 
-    # Public: Amico namespace for Redis.
+    # Amico namespace for Redis.
     #
-    # Returns the Amico namespace or the default of 'amico' if not set.
+    # @return the Amico namespace or the default of 'amico' if not set.
     def namespace
       @namespace ||= 'amico'
     end
 
-    # Public: Key used in Redis for tracking who an individual is following.
+    # Key used in Redis for tracking who an individual is following.
     #
-    # Returns the key used in Redis for tracking who an individual is following or the default of 'following' if not set.
+    # @return the key used in Redis for tracking who an individual is following or the default of 'following' if not set.
     def following_key
       @following_key ||= 'following'
     end
 
-    # Public: Key used in Redis for tracking the followers of an individual.
+    # Key used in Redis for tracking the followers of an individual.
     #
-    # Returns the key used in Redis for tracking the followers of an individual or the default of 'followers' if not set.
+    # @return the key used in Redis for tracking the followers of an individual or the default of 'followers' if not set.
     def followers_key
       @followers_key ||= 'followers'
     end
 
-    # Public: Key used in Redis for tracking who an individual blocks.
+    # Key used in Redis for tracking who an individual blocks.
     # 
-    # Returns the key used in Redis for tracking who an individual blocks or the default of 'blocked' if not set.
+    # @return the key used in Redis for tracking who an individual blocks or the default of 'blocked' if not set.
     def blocked_key
       @blocked_key ||= 'blocked'
     end
 
-    # Public: Key used in Redis for tracking who has reciprocated a follow for an individual.
+    # Key used in Redis for tracking who has reciprocated a follow for an individual.
     #
-    # Returns the key used in Redis for tracking who has reciprocated a follow for an individual or the default of 'reciprocated' if not set.
+    # @return the key used in Redis for tracking who has reciprocated a follow for an individual or the default of 'reciprocated' if not set.
     def reciprocated_key
       @reciprocated_key ||= 'reciprocated'
     end
 
-    # Public: Page size to be used when paging through the various types of relationships.
+    # Key used in Redis for tracking pending follow relationships for an individual.
+    #
+    # @return the key used in Redis for tracking pending follow relationships for an individual.
+    def pending_key
+      @pending_key ||= 'pending'
+    end
+
+    # Key used to indicate whether or not a follow should be pending or not.
+    #
+    # @return the key used to indicate whether or not a follow should be pending or not.
+    def pending_follow
+      @pending_follow ||= false
+    end
+
+    # Page size to be used when paging through the various types of relationships.
     #
-    # Returns the page size to be used when paging through the various types of relationships or the default of 25 if not set.
+    # @return the page size to be used when paging through the various types of relationships or the default of 25 if not set.
     def page_size
       @page_size ||= 25
     end

data/lib/amico/relationships.rb

@@ -1,11 +1,11 @@
 module Amico
   module Relationships
-    # Public: Establish a follow relationship between two IDs. After adding the follow 
-    #         relationship, it checks to see if the relationship is reciprocated and establishes that 
-    #         relationship if so.
+    # Establish a follow relationship between two IDs. After adding the follow 
+    # relationship, it checks to see if the relationship is reciprocated and establishes that 
+    # relationship if so.
     # 
-    # from_id - The ID of the individual establishing the follow relationship.
-    # to_id   - The ID of the individual to be followed. 
+    # @param from_id [String] The ID of the individual establishing the follow relationship.
+    # @param to_id [String] The ID of the individual to be followed. 
     #
     # Examples
     #
@@ -13,26 +13,21 @@ module Amico
     def follow(from_id, to_id)
       return if from_id == to_id
       return if blocked?(to_id, from_id)
+      return if Amico.pending_follow && pending?(from_id, to_id)
 
-      Amico.redis.multi do
-        Amico.redis.zadd("#{Amico.namespace}:#{Amico.following_key}:#{from_id}", Time.now.to_i, to_id)
-        Amico.redis.zadd("#{Amico.namespace}:#{Amico.followers_key}:#{to_id}", Time.now.to_i, from_id)
-      end
-
-      if reciprocated?(from_id, to_id)
-        Amico.redis.multi do
-          Amico.redis.zadd("#{Amico.namespace}:#{Amico.reciprocated_key}:#{from_id}", Time.now.to_i, to_id)
-          Amico.redis.zadd("#{Amico.namespace}:#{Amico.reciprocated_key}:#{to_id}", Time.now.to_i, from_id)
-        end
+      unless Amico.pending_follow
+        add_following_followers_reciprocated(from_id, to_id)
+      else
+        Amico.redis.zadd("#{Amico.namespace}:#{Amico.pending_key}:#{to_id}", Time.now.to_i, from_id)
       end
     end
 
-    # Public: Remove a follow relationship between two IDs. After removing the follow 
-    #         relationship, if a reciprocated relationship was established, it is 
-    #         also removed.
+    # Remove a follow relationship between two IDs. After removing the follow 
+    # relationship, if a reciprocated relationship was established, it is 
+    # also removed.
     #
-    # from_id - The ID of the individual removing the follow relationship.
-    # to_id   - The ID of the individual to be unfollowed.
+    # @param from_id [String] The ID of the individual removing the follow relationship.
+    # @param to_id [String] The ID of the individual to be unfollowed.
     # 
     # Examples
     #
@@ -46,14 +41,15 @@ module Amico
         Amico.redis.zrem("#{Amico.namespace}:#{Amico.followers_key}:#{to_id}", from_id)
         Amico.redis.zrem("#{Amico.namespace}:#{Amico.reciprocated_key}:#{from_id}", to_id)
         Amico.redis.zrem("#{Amico.namespace}:#{Amico.reciprocated_key}:#{to_id}", from_id)
+        Amico.redis.zrem("#{Amico.namespace}:#{Amico.pending_key}:#{to_id}", from_id)
       end
-    end
+    end  
 
-    # Public: Block a relationship between two IDs. This method also has the side effect 
-    #         of removing any follower or following relationship between the two IDs. 
+    # Block a relationship between two IDs. This method also has the side effect 
+    # of removing any follower or following relationship between the two IDs. 
     #
-    # from_id - The ID of the individual blocking the relationship.
-    # to_id   - The ID of the individual being blocked.
+    # @param from_id [String] The ID of the individual blocking the relationship.
+    # @param to_id [String] The ID of the individual being blocked.
     #
     # Examples
     #
@@ -68,14 +64,15 @@ module Amico
         Amico.redis.zrem("#{Amico.namespace}:#{Amico.followers_key}:#{from_id}", to_id)
         Amico.redis.zrem("#{Amico.namespace}:#{Amico.reciprocated_key}:#{from_id}", to_id)
         Amico.redis.zrem("#{Amico.namespace}:#{Amico.reciprocated_key}:#{to_id}", from_id)
+        Amico.redis.zrem("#{Amico.namespace}:#{Amico.pending_key}:#{from_id}", to_id)
         Amico.redis.zadd("#{Amico.namespace}:#{Amico.blocked_key}:#{from_id}", Time.now.to_i, to_id)
       end
     end
 
-    # Public: Unblock a relationship between two IDs.
+    # Unblock a relationship between two IDs.
     #
-    # from_id - The ID of the individual unblocking the relationship.
-    # to_id   - The ID of the blocked individual.
+    # @param from_id [String] The ID of the individual unblocking the relationship.
+    # @param to_id [String] The ID of the blocked individual.
     # 
     # Examples
     # 
@@ -87,51 +84,69 @@ module Amico
       Amico.redis.zrem("#{Amico.namespace}:#{Amico.blocked_key}:#{from_id}", to_id)
     end
 
-    # Public: Count the number of individuals that someone is following.
+    # Accept a relationship that is pending between two IDs.
+    #
+    # @param from_id [String] The ID of the individual accepting the relationship.
+    # @param to_id [String] The ID of the individual to be accepted.
+    #
+    # Example
+    #
+    #   Amico.follow(1, 11)
+    #   Amico.pending?(1, 11) # true
+    #   Amico.accept(1, 11)
+    #   Amico.pending?(1, 11) # false
+    #   Amico.following?(1, 11) #true
+    def accept(from_id, to_id)
+      return if from_id == to_id
+
+      add_following_followers_reciprocated(from_id, to_id)
+    end
+
+    # Count the number of individuals that someone is following.
     #
-    # id - ID of the individual to retrieve following count for.
+    # @param id [String] ID of the individual to retrieve following count for.
     # 
     # Examples
     # 
     #   Amico.follow(1, 11)
     #   Amico.following_count(1)
     #
-    # Returns the count of the number of individuals that someone is following.
+    # @return the count of the number of individuals that someone is following.
     def following_count(id)
       Amico.redis.zcard("#{Amico.namespace}:#{Amico.following_key}:#{id}")
     end
 
-    # Public: Count the number of individuals that are following someone.
+    # Count the number of individuals that are following someone.
     #
-    # id - ID of the individual to retrieve followers count for.
+    # @param id [String] ID of the individual to retrieve followers count for.
     #
     # Examples
     #
     #   Amico.follow(11, 1)
     #   Amico.followers_count(1)
     # 
-    # Returns the count of the number of individuals that are following someone.
+    # @return the count of the number of individuals that are following someone.
     def followers_count(id)
       Amico.redis.zcard("#{Amico.namespace}:#{Amico.followers_key}:#{id}")
     end
 
-    # Public: Count the number of individuals that someone has blocked.
+    # Count the number of individuals that someone has blocked.
     #
-    # id - ID of the individual to retrieve blocked count for.
+    # @param id [String] ID of the individual to retrieve blocked count for.
     # 
     # Examples
     #
     #   Amico.block(1, 11)
     #   Amico.blocked_count(1)
     #
-    # Returns the count of the number of individuals that someone has blocked.
+    # @return the count of the number of individuals that someone has blocked.
     def blocked_count(id)
       Amico.redis.zcard("#{Amico.namespace}:#{Amico.blocked_key}:#{id}")
     end
 
-    # Public: Count the number of individuals that have reciprocated a following relationship.
+    # Count the number of individuals that have reciprocated a following relationship.
     #
-    # id - ID of the individual to retrieve reciprocated following count for.
+    # @param id [String] ID of the individual to retrieve reciprocated following count for.
     # 
     # Examples
     # 
@@ -139,59 +154,75 @@ module Amico
     #   Amico.follow(11, 1)
     #   Amico.reciprocated_count(1)
     #
-    # Returns the count of the number of individuals that have reciprocated a following relationship.
+    # @return the count of the number of individuals that have reciprocated a following relationship.
     def reciprocated_count(id)
       Amico.redis.zcard("#{Amico.namespace}:#{Amico.reciprocated_key}:#{id}")
     end
 
-    # Public: Check to see if one individual is following another individual.
+    # Count the number of relationships pending for an individual.
     #
-    # id - ID of the individual checking the following status.
-    # following_id - ID of the individual to see if they are being followed by id.
+    # @param id [String] ID of the individual to retrieve pending count for.
+    # 
+    # Examples
+    #
+    #   Amico.follow(11, 1)
+    #   Amico.follow(12, 1)
+    #   Amico.pending_count(1) # 2
+    #
+    # @return the count of the number of relationships pending for an individual.
+    def pending_count(id)
+      Amico.redis.zcard("#{Amico.namespace}:#{Amico.pending_key}:#{id}")
+    end
+
+    # Check to see if one individual is following another individual.
+    #
+    # @param id [String] ID of the individual checking the following status.
+    # @param following_id [String] ID of the individual to see if they are being followed by id.
     #
     # Examples
     #
     #   Amico.follow(1, 11)
     #   Amico.following?(1, 11)
     #
-    # Returns true if id is following following_id, false otherwise
+    # @return true if id is following following_id, false otherwise
     def following?(id, following_id)
       !Amico.redis.zscore("#{Amico.namespace}:#{Amico.following_key}:#{id}", following_id).nil?
     end
 
-    # Public: Check to see if one individual is a follower of another individual.
+    # Check to see if one individual is a follower of another individual.
     #
-    # id - ID of the individual checking the follower status.
-    # following_id - ID of the individual to see if they are following id.
+    # @param id [String] ID of the individual checking the follower status.
+    # @param following_id [String] ID of the individual to see if they are following id.
     #
     # Examples
     #
     #   Amico.follow(11, 1)
     #   Amico.follower?(1, 11)
-    # Returns true if follower_id is following id, false otherwise
+    #
+    # @return true if follower_id is following id, false otherwise
     def follower?(id, follower_id)
       !Amico.redis.zscore("#{Amico.namespace}:#{Amico.followers_key}:#{id}", follower_id).nil?
     end
 
-    # Public: Check to see if one individual has blocked another individual.
+    # Check to see if one individual has blocked another individual.
     #
-    # id - ID of the individual checking the blocked status.
-    # blocked_id - ID of the individual to see if they are blocked by id.
+    # @param id [String] ID of the individual checking the blocked status.
+    # @param blocked_id [String] ID of the individual to see if they are blocked by id.
     #
     # Examples
     # 
     #   Amico.block(1, 11)
     #   Amico.blocked?(1, 11)
     #
-    # Returns true if id has blocked blocked_id, false otherwise
+    # @return true if id has blocked blocked_id, false otherwise
     def blocked?(id, blocked_id)
       !Amico.redis.zscore("#{Amico.namespace}:#{Amico.blocked_key}:#{id}", blocked_id).nil?
     end
 
-    # Public: Check to see if one individual has reciprocated in following another individual.
+    # Check to see if one individual has reciprocated in following another individual.
     #
-    # from_id - ID of the individual checking the reciprocated relationship.
-    # to_id - ID of the individual to see if they are following from_id.
+    # @param from_id [String] ID of the individual checking the reciprocated relationship.
+    # @param to_id [String] ID of the individual to see if they are following from_id.
     #
     # Examples
     #
@@ -199,16 +230,30 @@ module Amico
     #   Amico.follow(11, 1)
     #   Amico.reciprocated?(1, 11)
     #
-    # Returns true if both individuals are following each other, false otherwise
+    # @return true if both individuals are following each other, false otherwise
     def reciprocated?(from_id, to_id)
       following?(from_id, to_id) && following?(to_id, from_id)
     end
 
-    # Public: Retrieve a page of followed individuals for a given ID.
+    # Check to see if one individual has a pending relationship in following another individual.
     #
-    # id - ID of the individual.
-    # options - Options to be passed for retrieving a page of followed individuals.
-    #           default({:page_size => Amico.page_size, :page => 1})
+    # @param from_id [String] ID of the individual checking the pending relationships.
+    # @param to_id [String] ID of the individual to see if they are pending a follow from from_id.
+    #
+    # Examples
+    #
+    #   Amico.follow(1, 11)
+    #   Amico.pending?(1, 11) # true
+    #
+    # @return true if the relationship is pending, false otherwise
+    def pending?(from_id, to_id)
+      !Amico.redis.zscore("#{Amico.namespace}:#{Amico.pending_key}:#{to_id}", from_id).nil?
+    end
+
+    # Retrieve a page of followed individuals for a given ID.
+    #
+    # @param id [String] ID of the individual.
+    # @param options [Hash] Options to be passed for retrieving a page of followed individuals.
     #
     # Examples
     #
@@ -216,16 +261,15 @@ module Amico
     #   Amico.follow(1, 12)
     #   Amico.following(1, :page => 1)
     #
-    # Returns a page of followed individuals for a given ID.
+    # @return a page of followed individuals for a given ID.
     def following(id, options = default_options)
       members("#{Amico.namespace}:#{Amico.following_key}:#{id}", options)
     end
 
-    # Public: Retrieve a page of followers for a given ID.
+    # Retrieve a page of followers for a given ID.
     #
-    # id - ID of the individual.
-    # options - Options to be passed for retrieving a page of followers.
-    #           default({:page_size => Amico.page_size, :page => 1})
+    # @param id [String] ID of the individual.
+    # @param options [Hash] Options to be passed for retrieving a page of followers.
     #
     # Examples
     # 
@@ -233,16 +277,15 @@ module Amico
     #   Amico.follow(12, 1)
     #   Amico.followers(1, :page => 1)
     #
-    # Returns a page of followers for a given ID.
+    # @return a page of followers for a given ID.
     def followers(id, options = default_options)
       members("#{Amico.namespace}:#{Amico.followers_key}:#{id}", options)
     end
 
-    # Public: Retrieve a page of blocked individuals for a given ID.
+    # Retrieve a page of blocked individuals for a given ID.
     #
-    # id - ID of the individual.
-    # options - Options to be passed for retrieving a page of blocked individuals.
-    #           default({:page_size => Amico.page_size, :page => 1})
+    # @param id [String] ID of the individual.
+    # @param options [Hash] Options to be passed for retrieving a page of blocked individuals.
     #
     # Examples
     #
@@ -250,16 +293,15 @@ module Amico
     #   Amico.block(1, 12)
     #   Amico.blocked(1, :page => 1)
     #
-    # Returns a page of blocked individuals for a given ID.
+    # @return a page of blocked individuals for a given ID.
     def blocked(id, options = default_options)
       members("#{Amico.namespace}:#{Amico.blocked_key}:#{id}", options)
     end
 
-    # Public: Retrieve a page of individuals that have reciprocated a follow for a given ID.
+    # Retrieve a page of individuals that have reciprocated a follow for a given ID.
     #
-    # id - ID of the individual.
-    # options - Options to be passed for retrieving a page of individuals that have reciprocated a follow.
-    #           default({:page_size => Amico.page_size, :page => 1})
+    # @param id [String] ID of the individual.
+    # @param options [Hash] Options to be passed for retrieving a page of individuals that have reciprocated a follow.
     #
     # Examples
     #
@@ -269,15 +311,31 @@ module Amico
     #   Amico.follow(12, 1)
     #   Amico.reciprocated(1, :page => 1)
     #
-    # Returns a page of individuals that have reciprocated a follow for a given ID.
+    # @return a page of individuals that have reciprocated a follow for a given ID.
     def reciprocated(id, options = default_options)
       members("#{Amico.namespace}:#{Amico.reciprocated_key}:#{id}", options)
     end
 
-    # Public: Count the number of pages of following relationships for an individual.
+    # Retrieve a page of pending relationships for a given ID.
     #
-    # id - ID of the individual.
-    # page_size - Page size (default: Amico.page_size).
+    # @param id [String] ID of the individual.
+    # @param options [Hash] Options to be passed for retrieving a page of pending relationships.
+    #
+    # Examples
+    #
+    #   Amico.follow(1, 11)
+    #   Amico.follow(2, 11)
+    #   Amico.pending(1, :page => 1)
+    #
+    # @return a page of pending relationships for a given ID.
+    def pending(id, options = default_options)
+      members("#{Amico.namespace}:#{Amico.pending_key}:#{id}", options)
+    end
+
+    # Count the number of pages of following relationships for an individual.
+    #
+    # @param id [String] ID of the individual.
+    # @param page_size [int] Page size.
     #
     # Examples
     #
@@ -285,15 +343,15 @@ module Amico
     #   Amico.follow(1, 12)
     #   Amico.following_page_count(1)
     #
-    # Returns the number of pages of following relationships for an individual.
+    # @return the number of pages of following relationships for an individual.
     def following_page_count(id, page_size = Amico.page_size)
       total_pages("#{Amico.namespace}:#{Amico.following_key}:#{id}", page_size)
     end
 
-    # Public: Count the number of pages of follower relationships for an individual.
+    # Count the number of pages of follower relationships for an individual.
     #
-    # id - ID of the individual.
-    # page_size - Page size (default: Amico.page_size).
+    # @param id [String] ID of the individual.
+    # @param page_size [int] Page size (default: Amico.page_size).
     #
     # Examples
     #
@@ -301,15 +359,15 @@ module Amico
     #   Amico.follow(12, 1)
     #   Amico.followers_page_count(1)
     #
-    # Returns the number of pages of follower relationships for an individual.
+    # @return the number of pages of follower relationships for an individual.
     def followers_page_count(id, page_size = Amico.page_size)
       total_pages("#{Amico.namespace}:#{Amico.followers_key}:#{id}", page_size)
     end
 
-    # Public: Count the number of pages of blocked relationships for an individual.
+    # Count the number of pages of blocked relationships for an individual.
     #
-    # id - ID of the individual.
-    # page_size - Page size (default: Amico.page_size).
+    # @param id [String] ID of the individual.
+    # @param page_size [int] Page size (default: Amico.page_size).
     #
     # Examples
     #
@@ -317,15 +375,15 @@ module Amico
     #   Amico.block(1, 12)
     #   Amico.blocked_page_count(1)
     #    
-    # Returns the number of pages of blocked relationships for an individual.
+    # @return the number of pages of blocked relationships for an individual.
     def blocked_page_count(id, page_size = Amico.page_size)
       total_pages("#{Amico.namespace}:#{Amico.blocked_key}:#{id}", page_size)
     end
 
-    # Public: Count the number of pages of reciprocated relationships for an individual.
+    # Count the number of pages of reciprocated relationships for an individual.
     #
-    # id - ID of the individual.
-    # page_size - Page size (default: Amico.page_size).
+    # @param id [String] ID of the individual.
+    # @param page_size [int] Page size (default: Amico.page_size).
     #
     # Examples
     #
@@ -335,36 +393,72 @@ module Amico
     #   Amico.follow(12, 1)
     #   Amico.reciprocated_page_count(1)
     #    
-    # Returns the number of pages of reciprocated relationships for an individual.
+    # @return the number of pages of reciprocated relationships for an individual.
     def reciprocated_page_count(id, page_size = Amico.page_size)
       total_pages("#{Amico.namespace}:#{Amico.reciprocated_key}:#{id}", page_size)
     end
 
+    # Count the number of pages of pending relationships for an individual.
+    #
+    # @param id [String] ID of the individual.
+    # @param page_size [int] Page size (default: Amico.page_size).
+    #
+    # Examples
+    #
+    #   Amico.follow(11, 1)
+    #   Amico.follow(12, 1)
+    #   Amico.pending_page_count(1) # 1
+    #    
+    # @return the number of pages of pending relationships for an individual.
+    def pending_page_count(id, page_size = Amico.page_size)
+      total_pages("#{Amico.namespace}:#{Amico.pending_key}:#{id}", page_size)
+    end
+
     private
 
-    # Internal: Default options for doing, for example, paging.
+    # Add the following, followers and check for a reciprocated relationship. To be used from the 
+    # +follow++ and ++accept++ methods.
+    #
+    # @param from_id [String] The ID of the individual establishing the follow relationship.
+    # @param to_id [String] The ID of the individual to be followed. 
+    def add_following_followers_reciprocated(from_id, to_id)
+      Amico.redis.multi do
+        Amico.redis.zadd("#{Amico.namespace}:#{Amico.following_key}:#{from_id}", Time.now.to_i, to_id)
+        Amico.redis.zadd("#{Amico.namespace}:#{Amico.followers_key}:#{to_id}", Time.now.to_i, from_id)
+        Amico.redis.zrem("#{Amico.namespace}:#{Amico.pending_key}:#{to_id}", from_id)
+      end
+
+      if reciprocated?(from_id, to_id)
+        Amico.redis.multi do
+          Amico.redis.zadd("#{Amico.namespace}:#{Amico.reciprocated_key}:#{from_id}", Time.now.to_i, to_id)
+          Amico.redis.zadd("#{Amico.namespace}:#{Amico.reciprocated_key}:#{to_id}", Time.now.to_i, from_id)
+        end
+      end      
+    end
+
+    # Default options for doing, for example, paging.
     #
-    # Returns a hash of the default options.
+    # @return a hash of the default options.
     def default_options
       {:page_size => Amico.page_size, :page => 1}
     end
 
-    # Internal: Count the total number of pages for a given key in a Redis sorted set.
+    # Count the total number of pages for a given key in a Redis sorted set.
     #
-    # key - Redis key.
-    # page_size - Page size from which to calculate total pages.
+    # @param key [String] Redis key.
+    # @param page_size [int] Page size from which to calculate total pages.
     #
-    # Returns total number of pages for a given key in a Redis sorted set.
+    # @return total number of pages for a given key in a Redis sorted set.
     def total_pages(key, page_size)
       (Amico.redis.zcard(key) / page_size.to_f).ceil
     end
 
-    # Internal: Retrieve a page of items from a Redis sorted set without scores.
+    # Retrieve a page of items from a Redis sorted set without scores.
     #
-    # key - Redis key.
-    # options - Default options for paging (default: {:page_size => Amico.page_size, :page => 1})
+    # @param key [String] Redis key.
+    # @param options [Hash] Default options for paging.
     #
-    # Returns a page of items from a Redis sorted set without scores.
+    # @return a page of items from a Redis sorted set without scores.
     def members(key, options = default_options)
       options = default_options.dup.merge!(options)
       if options[:page] < 1

data/lib/amico/version.rb

@@ -1,3 +1,3 @@
 module Amico
-  VERSION = '1.1.0'
+  VERSION = '1.2.0'
 end

data/spec/amico/configuration_spec.rb

@@ -9,6 +9,8 @@ describe Amico::Configuration do
         configuration.followers_key.should eql('followers')
         configuration.blocked_key.should eql('blocked')
         configuration.reciprocated_key.should eql('reciprocated')
+        configuration.pending_key.should eql('pending')
+        configuration.pending_follow.should be_false
         configuration.page_size.should be(25)
       end
     end

data/spec/amico/relationships_spec.rb

@@ -269,6 +269,127 @@ describe Amico::Relationships do
     end
   end
 
+  describe 'pending_follow enabled' do
+    before(:each) do
+      Amico.pending_follow = true
+    end
+
+    after(:each) do
+      Amico.pending_follow = false
+    end
+
+    describe '#follow' do
+      it 'should allow you to follow but the relationship is initially pending' do
+        Amico.follow(1, 11)
+
+        Amico.redis.zcard("#{Amico.namespace}:#{Amico.following_key}:1").should be(0)
+        Amico.redis.zcard("#{Amico.namespace}:#{Amico.followers_key}:11").should be(0)
+        Amico.redis.zcard("#{Amico.namespace}:#{Amico.pending_key}:11").should be(1)
+      end
+
+      it 'should remove the pending relationship if you have a pending follow, but you unfollow' do
+        Amico.follow(1, 11)
+
+        Amico.redis.zcard("#{Amico.namespace}:#{Amico.following_key}:1").should be(0)
+        Amico.redis.zcard("#{Amico.namespace}:#{Amico.followers_key}:11").should be(0)
+        Amico.redis.zcard("#{Amico.namespace}:#{Amico.pending_key}:11").should be(1)
+
+        Amico.unfollow(1, 11)
+
+        Amico.redis.zcard("#{Amico.namespace}:#{Amico.following_key}:1").should be(0)
+        Amico.redis.zcard("#{Amico.namespace}:#{Amico.followers_key}:11").should be(0)
+        Amico.redis.zcard("#{Amico.namespace}:#{Amico.pending_key}:11").should be(0)
+      end
+
+      it 'should remove the pending relationship and add to following and followers if #accept is called' do
+        Amico.follow(1, 11)
+        Amico.pending?(1, 11).should be_true
+
+        Amico.accept(1, 11)
+
+        Amico.pending?(1, 11).should be_false
+        Amico.following?(1, 11).should be_true
+        Amico.following?(11, 1).should be_false
+        Amico.follower?(11, 1).should be_true
+        Amico.follower?(1, 11).should be_false
+      end
+
+      it 'should remove the pending relationship and add to following and followers if #accept is called and add to reciprocated relationship' do
+        Amico.follow(1, 11)
+        Amico.follow(11, 1)
+        Amico.pending?(1, 11).should be_true
+        Amico.pending?(11, 1).should be_true
+
+        Amico.accept(1, 11)
+
+        Amico.pending?(1, 11).should be_false
+        Amico.pending?(11, 1).should be_true
+        Amico.following?(1, 11).should be_true
+        Amico.following?(11, 1).should be_false
+        Amico.follower?(11, 1).should be_true
+        Amico.follower?(1, 11).should be_false
+
+        Amico.accept(11, 1)
+
+        Amico.pending?(1, 11).should be_false
+        Amico.pending?(11, 1).should be_false
+        Amico.following?(1, 11).should be_true
+        Amico.following?(11, 1).should be_true
+        Amico.follower?(11, 1).should be_true
+        Amico.follower?(1, 11).should be_true
+        Amico.reciprocated?(1, 11).should be_true
+      end
+    end
+
+    describe '#block' do
+      it 'should remove the pending relationship if you block someone' do
+        Amico.follow(11, 1)
+        Amico.pending?(11, 1).should be_true
+        Amico.block(1, 11)
+        Amico.pending?(11, 1).should be_false
+        Amico.blocked?(1, 11).should be_true
+      end
+    end
+
+    describe '#pending' do
+      it 'should return the correct list' do
+        Amico.follow(1, 11)
+        Amico.follow(11, 1)
+        Amico.pending(1).should eql(["11"])
+        Amico.pending(11).should eql(["1"])
+      end
+
+      it 'should page correctly' do
+        add_reciprocal_followers
+
+        Amico.pending(1, :page => 1, :page_size => 5).size.should be(5)
+        Amico.pending(1, :page => 1, :page_size => 10).size.should be(10)
+        Amico.pending(1, :page => 1, :page_size => 26).size.should be(25)
+      end
+    end
+
+    describe '#pending_count' do
+      it 'should return the correct count' do
+        Amico.follow(1, 11)
+        Amico.follow(11, 1)
+        Amico.follow(1, 12)
+        Amico.follow(12, 1)
+        Amico.follow(1, 13)
+        Amico.pending_count(1).should be(2)
+      end
+    end
+
+    describe '#pending_page_count' do
+      it 'should return the correct count' do
+        add_reciprocal_followers
+
+        Amico.pending_page_count(1).should be(1)
+        Amico.pending_page_count(1, 10).should be(3)
+        Amico.pending_page_count(1, 5).should be(5)
+      end
+    end
+  end
+
   private
 
   def add_reciprocal_followers(count = 26, block_relationship = false)

data/spec/spec_helper.rb

@@ -4,11 +4,19 @@ require 'amico'
 Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
 
 RSpec.configure do |config|
-  config.before(:each) do
+  config.before(:all) do
     Amico.configure do |configuration|
-      redis = Redis.new
-      redis.flushall
+      redis = Redis.new(:db => 15)
       configuration.redis = redis
     end
   end
+
+  config.before(:each) do
+    Amico.redis.flushdb
+  end
+
+  config.after(:all) do
+  	Amico.redis.flushdb
+    Amico.redis.quit
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: amico
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-01-13 00:00:00.000000000 Z
+date: 2012-02-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
-  requirement: &2164475940 !ruby/object:Gem::Requirement
+  requirement: &2157986940 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2164475940
+  version_requirements: *2157986940
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &2164475520 !ruby/object:Gem::Requirement
+  requirement: &2157986520 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2164475520
+  version_requirements: *2157986520
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2164475100 !ruby/object:Gem::Requirement
+  requirement: &2157986100 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,7 +43,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2164475100
+  version_requirements: *2157986100
 description: Relationships (e.g. friendships) backed by Redis
 email:
 - dczarnecki@agoragames.com
@@ -81,7 +81,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2967547926380313375
+      hash: 4319511261827775332
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -90,7 +90,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2967547926380313375
+      hash: 4319511261827775332
 requirements: []
 rubyforge_project: amico
 rubygems_version: 1.8.10