Reorganized filter/parameter classes and added documentation.

Author: trek

lib/lonely_coder.rb

@@ -31,9 +31,7 @@ def love(n=20)
 
 require 'active_support/core_ext/string/inflections'
 
-require 'lonely_coder/magic_constants'
 require 'lonely_coder/profile'
 require 'lonely_coder/search'
-require 'lonely_coder/search_pagination_parser'
 require 'lonely_coder/authentication'
 require 'lonely_coder/mailbox'

lib/lonely_coder/search.rb

@@ -1,13 +1,34 @@
 require 'uri'
 require 'set'
 
+require 'lonely_coder/search/magic_constants'
+require 'lonely_coder/search/search_pagination_parser'
+require 'lonely_coder/search/options/filter'
+
+# these are the included filters. See Filter class documentation for adding your own.
+require 'lonely_coder/search/options/age'
+require 'lonely_coder/search/options/ethnicity'
+require 'lonely_coder/search/options/order_by'
+require 'lonely_coder/search/options/location'
+require 'lonely_coder/search/options/paginator'
+require 'lonely_coder/search/options/radius'
+require 'lonely_coder/search/options/require_photo'
+
 class OKCupid
   # Creates a new Search with the passed options to act as query parameters.
   # A search will not trigger a query to OKCupid until `results` is called.
   #
   # @param [Hash] options a list of options for the search
-  # @option options [Integer] :min_age (18) Minimum age to search for
-  # @option options [Integer] :max_age (99) Maximum age to search for
+  # @option options [Integer] :min_age (18) Minimum age to search for.
+  # @option options [Integer] :max_age (99) Maximum age to search for.
+  # @option options [String]  :gentation Gentation is OKCupid's portmanteau for 'gender and orientation'.
+  #                           Acceptable values are:
+  #                           "girls who like guys", "guys who like girls", "girls who like girls", 
+  #                           "guys who like guys", "both who like bi guys", "both who like bi girls",
+  #                           "straight girls only", "straight guys only", "gay girls only", 
+  #                           "gay guys only", "bi girls only", "bi guys only", "everybody"
+  #                           this option is required.
+  # 
   # @option options [String]  :order_by ('match %') The sort order of the search results.
   #                           Acceptable values are 'match %','friend %', 'enemy %', 
   #                           'special blend', 'join', and 'last login'.
@@ -24,7 +45,7 @@ class OKCupid
   # 
   # @option options [true, false] :require_photo (true). Search for profiles that have photos
   # @option options [String] :relationship_status ('single'). Acceptable values are 'single', 'not single', 'any'
-  # @return [Search] A Searhc without results loaded. To trigger a query against OKCupid call `results`
+  # @return [Search] A Search without results loaded. To trigger a query against OKCupid call `results`
   def search(options={})
     Search.new(options, @browser)
   end
@@ -76,42 +97,6 @@ def parse(options)
       @timekey = 1
     end
 
-    def add_order_by_option(value)
-      @parameters << OrderByParameter.new(value)
-    end
-    
-    def add_last_login_option(value)
-      @filters << Filter.new('last_login', value)
-    end
-    
-    def add_location_option(value)
-      @parameters << LocationParameter.new(value)
-    end
-    
-    def add_radius_option(value)
-      @filters << RadiusFilter.new('radius', value)
-    end
-    
-    def add_require_photo_option(value)
-      @filters << RequirePhotoFilter.new('require_photo', value)
-    end
-    
-    def add_relationship_status_option(value)
-      @filters << Filter.new('relationship_status', value)
-    end
-    
-    def add_gentation_option(value)
-      @filters << Filter.new('gentation', value)
-    end
-    
-    def add_age_option(value)
-      @filters << AgeFilter.new('age', value)
-    end
-    
-    def add_pagination_option(value)
-      @parameters << @pagination = Paginator.new(value)
-    end
-    
     def check_for_required_options(options)
       raise(FilterError, 'gentation is a required option') unless options.has_key?(:gentation)
     end
@@ -219,120 +204,4 @@ def filters_as_query
       filters.compact.to_enum(:each_with_index).map {|filter,index| filter.to_param(index+1)}.join('&')
     end
   end
-  
-  # used to create the pagination part of a search url:
-  # low=1&count=10&ajax_load=1
-  # where low is the start value
-  # count is the number of items per page
-  class Paginator
-    attr_reader :page, :per_page
-    
-    def initialize(options)
-      @per_page = options[:per_page]
-      @page = options[:page]
-    end
-    
-    def low
-      @low = ((@page - 1) * @per_page) + 1
-    end
-    
-    def next
-      @page +=1
-      self
-    end
-    
-    def to_param
-      "low=#{low}&count=#{@per_page}"
-    end
-  end
-  
-  class Filter
-    class NoSuchFilter < StandardError; end
-    class BadValue     < StandardError; end
-    
-    attr_reader :name, :value, :code
-    
-    def initialize(name, value)
-      @code = MagicNumbers::Filters[name.to_s]
-      raise(NoSuchFilter, name) unless @code
-      
-      @name = name.to_s
-      @value = value
-      @encoded_value = lookup(@value)
-      unless @encoded_value
-        raise(BadValue, "#{@value.inspect} is not a possible value for #{@name}. Try one of #{allowed_values.map(&:inspect).join(', ')}")
-      end
-    end
-    
-    def allowed_values
-      MagicNumbers.const_get(@name.camelize).keys
-    end
-    
-    def lookup(value)
-      MagicNumbers.const_get(@name.camelize)[value.downcase]
-    end
-    
-    def to_param(n)
-      "filter#{n}=#{@code},#{@encoded_value}"
-    end
-  end
-  
-  class EthnicityFilter < Filter
-    def lookup(values)
-      # lookup the race values and sum them. I think OKC is doing some kind of base2 math on them
-      values.collect {|v| MagicNumbers::Ethnicity[v.downcase]}.inject(0, :+)
-    end
-  end
-  
-  class LocationParameter
-    def initialize(value)
-      @value = value
-    end
-    
-    def to_param
-      if @value.is_a?(String)
-        if @value.downcase == 'near me'
-          "locid=0"
-        else
-          "locid=#{Search.location_id_for(@value)}&lquery=#{URI.escape(@value)}"
-        end
-      else
-        "locid=#{@value}"
-      end
-    end
-  end
-
-  class OrderByParameter
-    def initialize(value)
-      @value = value
-      @encoded_value = MagicNumbers::OrderBy[value.downcase]
-    end
-    
-    def to_param
-      "matchOrderBy=#{@encoded_value}"
-    end
-  end
-
-  class RequirePhotoFilter < Filter
-    def lookup(value)
-      value ? 1 : 0
-    end
-  end
-    
-  class RadiusFilter < Filter
-    def lookup(value)
-      value.nil? ? '' : value
-    end
-    
-    def to_param(n)
-      return nil if @encoded_value === ''
-      super
-    end
-  end
-  
-  class AgeFilter < Filter
-    def lookup(value)
-      "#{value[0]},#{value[1]}"
-    end
-  end
 end

lib/lonely_coder/magic_constants.rb renamed to lib/lonely_coder/search/magic_constants.rb

@@ -0,0 +1,13 @@
+class OKCupid
+  class AgeFilter < Filter
+    def lookup(value)
+      "#{value[0]},#{value[1]}"
+    end
+  end
+  
+  class Search
+    def add_age_option(value)
+      @filters << AgeFilter.new('age', value)
+    end
+  end
+end

lib/lonely_coder/search/options/age.rb

@@ -0,0 +1,14 @@
+class OKCupid
+  class EthnicityFilter < Filter
+    def lookup(values)
+      # lookup the race values and sum them. I think OKC is doing some kind of base2 math on them
+      values.collect {|v| MagicNumbers::Ethnicity[v.downcase]}.inject(0, :+)
+    end
+  end
+  
+  class Search
+    def add_ethnicity_option(value)
+      # implement
+    end
+  end
+end

lib/lonely_coder/search/options/ethnicity.rb

@@ -0,0 +1,74 @@
+class OKCupid
+ # Filter instances are used to build the query parameters for a search on OKCupid.
+ # OKCupid has specific coded values for many search values, you should check the magic_constants file
+ # for a list. Not all of them have been implemented yet.
+ # 
+ # Adding a Filter takes one of three forms:
+ #    1) implementing a add_<filter_name>_option method on Search
+ #       that pushes a new named Filter to the @filters array for unmamed query parts
+ #    
+ #    2) Subclassing Filter for filters that have atypical parameterization behavior.
+ #       where you'll implement a add_<filter_name>_option method on Search
+ #       and provide a custom class overriding `lookup` or `to_param` to create
+ #       a correct url query part.
+ # 
+ #    3) Creating a new class to handle query parameters that are specifically named
+ #       These are refered to as "Parameters" to contrast them with "Filters" which
+ #       are parameterized in the "filterN=code,value" pattern (e.g. filter4=22,7).
+ #       Parameters are not numbered and have specific names, e.g. "loc_id=1234567"
+ #       You'll also implement a add_<filter_name>_option that adds an instance of this 
+ #       class to the @parameters array (not the @filters array).
+ # 
+ #  See the included Filter and Parameter classes for ideas on how to structure these objects.
+ # 
+ #  OKCupid's query system is a bit obtuse and the details aren't published anywhere. 
+ #  If you're implementing a new filter, you may need to spend some time figuring out
+ #  what data they expect to receive and the kinds of results it will return.
+ class Filter
+    class NoSuchFilter < StandardError; end
+    class BadValue     < StandardError; end
+
+    attr_reader :name, :value, :code
+
+    def initialize(name, value)
+      @code = MagicNumbers::Filters[name.to_s]
+      raise(NoSuchFilter, name) unless @code
+  
+      @name = name.to_s
+      @value = value
+      @encoded_value = lookup(@value)
+      unless @encoded_value
+        raise(BadValue, "#{@value.inspect} is not a possible value for #{@name}. Try one of #{allowed_values.map(&:inspect).join(', ')}")
+      end
+    end
+
+    def allowed_values
+      MagicNumbers.const_get(@name.camelize).keys
+    end
+
+    def lookup(value)
+      MagicNumbers.const_get(@name.camelize)[value.downcase]
+    end
+
+    def to_param(n)
+      "filter#{n}=#{@code},#{@encoded_value}"
+    end
+  end
+  
+  # All filters that follow the base Filter pattern are exposed here through a
+  # add_<filter_name>_option method. Custom filters and parameters are defined
+  # in their own files and include the appropriate add_<option_name>_option method.
+  class Search
+    def add_relationship_status_option(value)
+      @filters << Filter.new('relationship_status', value)
+    end
+    
+    def add_gentation_option(value)
+      @filters << Filter.new('gentation', value)
+    end
+    
+    def add_last_login_option(value)
+      @filters << Filter.new('last_login', value)
+    end
+  end
+end

lib/lonely_coder/search/options/filter.rb

@@ -0,0 +1,25 @@
+class OKCupid
+  class LocationParameter
+    def initialize(value)
+      @value = value
+    end
+    
+    def to_param
+      if @value.is_a?(String)
+        if @value.downcase == 'near me'
+          "locid=0"
+        else
+          "locid=#{Search.location_id_for(@value)}&lquery=#{URI.escape(@value)}"
+        end
+      else
+        "locid=#{@value}"
+      end
+    end
+  end
+  
+  class Search
+    def add_location_option(value)
+      @parameters << LocationParameter.new(value)
+    end
+  end
+end

lib/lonely_coder/search/options/location.rb

@@ -0,0 +1,19 @@
+class OKCupid
+  class OrderByParameter
+    def initialize(value)
+      @value = value
+      @encoded_value = MagicNumbers::OrderBy[value.downcase]
+    end
+    
+    def to_param
+      "matchOrderBy=#{@encoded_value}"
+    end
+  end
+  
+  # Reopen Search to accept order_by filters
+  class Search
+    def add_order_by_option(value)
+      @parameters << OrderByParameter.new(value)
+    end
+  end
+end