lonely_coder 0.1.4 → 0.1.5

data/CHANGELOG

@@ -1,3 +1,5 @@
+0.1.5 (April 04, 2012)
+* Added ethnicity filter
 0.1.4 (March 27, 2012)
 * more consistent search results when paginating by using OKCupid server timestamps
 * Search#load_next_page returns boolean to deal with cases where pagination doesn't load new results

data/README.mdown

@@ -20,8 +20,7 @@ Lonely coder seeks nice boy
         :min_age => 25,
         :max_age => 35, # just someone around my age, yo
         :gentation => 'Guys who like guys', # don't hate
-        :order_by => 'Match %', # I want us to get along
-        :match_limit => 80, # let's make it last
+        :order_by => 'Match %', # I want us to get along, let's make it last
         :last_login => 'last month',
         :location => maybe_here
         :radius => 25, # acceptable values are 25, 50, 100, 250, 500, nil

data/lib/lonely_coder/search/options/age.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

data/lib/lonely_coder/search/options/ethnicity.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(values)
+      @filters << EthnicityFilter.new('ethnicity', values)
+    end
+  end
+end

data/lib/lonely_coder/search/options/filter.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

data/lib/lonely_coder/search/options/location.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

data/lib/lonely_coder/search/options/order_by.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

data/lib/lonely_coder/search/options/paginator.rb

@@ -0,0 +1,33 @@
+class OKCupid
+  # 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 Search
+    def add_pagination_option(value)
+      @parameters << @pagination = Paginator.new(value)
+    end
+  end
+end

data/lib/lonely_coder/search/options/radius.rb

@@ -0,0 +1,18 @@
+class OKCupid
+  class RadiusFilter < Filter
+    def lookup(value)
+      value.nil? ? '' : value
+    end
+    
+    def to_param(n)
+      return nil if @encoded_value === ''
+      super
+    end
+  end
+  
+  class Search
+    def add_radius_option(value)
+      @filters << RadiusFilter.new('radius', value)
+    end
+  end
+end

data/lib/lonely_coder/search/options/require_photo.rb

@@ -0,0 +1,13 @@
+class OKCupid
+  class RequirePhotoFilter < Filter
+    def lookup(value)
+      value ? 1 : 0
+    end
+  end
+  
+  class Search
+    def add_require_photo_option(value)
+      @filters << RequirePhotoFilter.new('require_photo', value)
+    end
+  end
+end

data/lib/lonely_coder/search.rb

@@ -1,15 +1,65 @@
 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 [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'.
+  #
+  # @option options [Integer] :radius (25) The search radius, in miles.
+  #                           Acceptable values are 25, 50, 100, 250, 500.
+  #                           You must also specific a :location option.
+  # @option options [Integer, String] :location ('near me'). A specific search location.
+  #                                   Acceptable values are 'near me', 'anywhere', a "City, State" pair
+  #                                   (e.g. 'Chicago, Illinois') or OKCupid location id which can be
+  #                                   obtained with Search#location_id_for("City, State").
+  #                                   If specifiying a location other than 'near me' or 'anywhere'
+  #                                   you may also provide a :radius option
+  # 
+  # @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 Search without results loaded. To trigger a query against OKCupid call `results`
   def search(options={})
     Search.new(options, @browser)
   end
   
+  # The OKCupid search object. Stores filters and query options and a results set.  Correct useage is to obtain
+  # and instance of this class by using OKCupid#search(options).
+  # @see OKCupid#search
   class Search
     class FilterError < StandardError; end
     
     attr_reader :filters
     
+    # @param [String] A string query for a city and state pair, e.g. 'Little Rock, Arkansas'
+    # @return [Integer] The OKCupid location id for the query
     def self.location_id_for(query)
       uri = URI("http://www.okcupid.com/locquery?func=query&query=#{URI.encode(query)}")
       JSON.parse(Net::HTTP.get(uri))['results'][0]['locid'].to_s
@@ -24,62 +74,29 @@ class OKCupid
     def parse(options)
       check_for_required_options(options)
       
+      # :age appears as two options when creating a search
+      # but is combined into one for paramterizing.
       options[:age] = combine_ages(options)
       
-      
+      # filters appear in the query string as filterN=code,value
+      # e.g. filter4=11,75
       @filters = []
+      
+      # parameters appear in the query string as named query parameters
+      # e.g. loc_id=1234567
       @parameters = []
       
+      
       options.each do |name,value|
         self.send("add_#{name}_option", value)
       end
       
       # OKC needs an initial time key of 1 to represent "waaaay in the past"
       # futures searches will use the OKC server value returned from the first
-      # results set
+      # results set.
       @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 add_match_limit_option(value)
-      # TODO.
-    end
-    
     def check_for_required_options(options)
       raise(FilterError, 'gentation is a required option') unless options.has_key?(:gentation)
     end
@@ -89,30 +106,19 @@ class OKCupid
       options[:age] = age
     end
     
-    # Default values for search:
-    # match_limit 80
-    # min_age 18
-    # max_age 99
-    # order_by 'match %'
-    # last_login 'last month'
-    # location 'Near me'
-    #    to search 'anywhere', use 'Near me' and omit a radius
-    # radius 25
-    # require_photo true
-    # relationship_status 'single'
+    #
     def defaults
       {
         :pagination => {
           :page => 1,
           :per_page => 10
         },
-        :match_limit => 80,
         :min_age => 18,
         :max_age => 99,
         :order_by => 'Match %',
         :last_login => 'last month',
         :location => 'Near me',
-        :radius => 25, # acceptable values are 25, 50, 100, 250, 500, nil
+        :radius => 25,
         :require_photo => true,
         :relationship_status => 'single'
       }
@@ -124,10 +130,13 @@ class OKCupid
       # the first results request has to receive a full HTML page.
       # subseqent calls can make json requests
       page = @browser.get(url)
+      
+      # Stores the OKCupid server timestamp. Without this, pagination returns
+      # inconsistent results.
       @timekey = page.search('script')[0].text.match(/CurrentGMT = new Date\(([\d]+)\*[\d]+\)/).captures[0]
       
-      # OKCupid will return previous profiles if there aren't enough
-      # profiles to fill a query, so we stop that with a set.
+      # OKCupid may return previously found profiles if there aren't enough
+      # to fill a query or pagination, so we stop that with a set.
       @results = Set.new
       @results += page.search('.match_row').collect do |node|
         OKCupid::Profile.from_search_result(node)
@@ -143,24 +152,25 @@ class OKCupid
     # update_prefs=1
     # using_saved_search=0
     # mygender=m
+    # 
     # no idea what the following parameters do, but without them, the search
     # behaves erratically
     # &custom_search=0
     # 
-    # OKCupid timestamps searches for pagniation. The first search gets a timestamp
+    # OKCupid timestamps searches for pagination. The first search gets a timestamp
     # of 1 (e.g. 1 second into the epoch) and future searches are stamped with
     # some server cache value. If that server value isn't submitted, the results
     # for pagniation don't quite match what you'd expect: you'll get duplicates, 
     # or lower numbers than expected.
     # &timekey=1
-    
     def magic_params_not_truly_understood
       "timekey=#{@timekey}&custom_search=0"
     end
     
-    # returns true if it worked, false if not.
-    # OKCupid searches will return duplicate results if you attempt to
-    # page beyond the availble results.
+    
+    # Loads the next page of possible results. Will return `true` if 
+    # additional results were available or `false` if not
+    # @return [true,false]
     def load_next_page
       @browser.pluggable_parser.html = SearchPaginationParser
       
@@ -194,121 +204,4 @@ class OKCupid
       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
-      # to do: 'anywhere' needs to remove the radius filter
-      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

data/lib/lonely_coder.rb

@@ -11,7 +11,7 @@ require 'mechanize'
 
 class OKCupid
   BaseUrl = 'http://www.okcupid.com'
-  VERSION = '0.1.4'
+  VERSION = '0.1.5'
   
   def initialize(username=nil, password=nil)
     @browser = Mechanize.new 
@@ -31,9 +31,7 @@ end
 
 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'

data/lonely_coder.gemspec

@@ -1,7 +1,7 @@
 # -*- encoding: utf-8 -*-
 Gem::Specification.new do |s|
   s.name        = "lonely_coder"
-  s.version     = '0.1.4'
+  s.version     = '0.1.5'
   s.platform    = Gem::Platform::RUBY
   s.authors     = ["Trek Glowacki"]
   s.email       = ["trek.glowacki@gmail.com"]

data/spec/ethnicity_filter_spec.rb

@@ -0,0 +1,21 @@
+require 'spec_helper'
+
+describe "EthnicityFilter" do
+  it "adds ethnicity as an numbered filter to the query url" do
+    @search = OKCupid::Search.new({
+      :gentation => 'guys who like guys',
+      :ethnicity => ['human']
+    })
+    @search.url.should match(/filter[\d]=9,512/)
+  end
+  
+  it "supports mulitple ethnicity values" do
+    @search = OKCupid::Search.new({
+      :gentation => 'guys who like guys',
+      :ethnicity => ['white', 'black']
+    })
+    # White + Black
+    # 256 + 8
+    @search.url.should match(/filter[\d]=9,264/)
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lonely_coder
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-27 00:00:00.000000000 Z
+date: 2012-04-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mechanize
@@ -55,11 +55,19 @@ files:
 - README.mdown
 - lib/lonely_coder.rb
 - lib/lonely_coder/authentication.rb
-- lib/lonely_coder/magic_constants.rb
 - lib/lonely_coder/mailbox.rb
 - lib/lonely_coder/profile.rb
 - lib/lonely_coder/search.rb
-- lib/lonely_coder/search_pagination_parser.rb
+- lib/lonely_coder/search/magic_constants.rb
+- lib/lonely_coder/search/options/age.rb
+- lib/lonely_coder/search/options/ethnicity.rb
+- lib/lonely_coder/search/options/filter.rb
+- lib/lonely_coder/search/options/location.rb
+- lib/lonely_coder/search/options/order_by.rb
+- lib/lonely_coder/search/options/paginator.rb
+- lib/lonely_coder/search/options/radius.rb
+- lib/lonely_coder/search/options/require_photo.rb
+- lib/lonely_coder/search/search_pagination_parser.rb
 - lonely_coder.gemspec
 - spec/authentication_spec.rb
 - spec/cassettes/failed_authentication.yml
@@ -75,6 +83,7 @@ files:
 - spec/cassettes/search_finding_no_results.yml
 - spec/cassettes/search_that_includes_a_location.yml
 - spec/cassettes/successful_authentication.yml
+- spec/ethnicity_filter_spec.rb
 - spec/helper_spec.rb
 - spec/location_id_spec.rb
 - spec/mailbox_spec.rb
@@ -123,6 +132,7 @@ test_files:
 - spec/cassettes/search_finding_no_results.yml
 - spec/cassettes/search_that_includes_a_location.yml
 - spec/cassettes/successful_authentication.yml
+- spec/ethnicity_filter_spec.rb
 - spec/helper_spec.rb
 - spec/location_id_spec.rb
 - spec/mailbox_spec.rb
@@ -131,3 +141,4 @@ test_files:
 - spec/profile_spec.rb
 - spec/search_spec.rb
 - spec/spec_helper.rb
+has_rdoc: