factual-api 0.2 → 0.5

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## v0.3
+* return hash instead of objects
+* removing facets
+* a little refactoring
+
 ## v0.2
 * refactoring
 

data/README.md

@@ -5,8 +5,8 @@ This is the Factual supported Ruby driver for [Factual's public API](http://deve
 # Installation
 
     gem 'factual-api'
-    require 'factual_api'
-    factual = Factual::Api.new(YOUR_KEY, YOUR_SECRET)
+    require 'factual'
+    factual = Factual.new(YOUR_KEY, YOUR_SECRET)
   
 # Examples
 
@@ -37,7 +37,7 @@ This is the Factual supported Ruby driver for [Factual's public API](http://deve
     # 6. Page it
     query = query.page(2, :per => 10)
 
-    # 7. Finally, get response in Factual::Row objects
+    # 7. Finally, get response in a hash or array of hashes
     query.first    # return one row
     query.rows     # return many rows
 
@@ -56,7 +56,7 @@ This is the Factual supported Ruby driver for [Factual's public API](http://deve
 
 ## Resolve
 
-    # Returns resolved entities as Factual::Row objects
+    # Returns resolved entities as an array of hashes
     query = factual.resolve("name" => "McDonalds",
                     "address" => "10451 Santa Monica Blvd",
                     "region" => "CA",
@@ -67,11 +67,5 @@ This is the Factual supported Ruby driver for [Factual's public API](http://deve
 
 ## Schema
 
-    # Returns a Factual::Table object whose fields are an array of Factual::Field objects
-    factual.table("global").schema()
-
-## Facets
-
-    # Returns number of starbucks in regions thoughout the world
-    factual.table("global").select("country", "region").search("starbucks").min_count(2).facets()
-
+    # Returns a hash of table metadata, including an array of fields
+    factual.table("global").schema

data/lib/factual.rb

@@ -0,0 +1,27 @@
+require 'oauth'
+require 'factual/api'
+require 'factual/query'
+
+class Factual
+  def initialize(key, secret)
+    @api = Factual::API.new(generate_token(key, secret))
+  end
+
+  def crosswalk(factual_id)
+    Query.new(@api, :crosswalk, "places/crosswalk", :factual_id => factual_id)
+  end
+
+  def resolve(values)
+    Query.new(@api, :resolve, "places/resolve", :values => values)
+  end
+
+  def table(table_id_or_alias)
+    Query.new(@api, :read, "t/#{table_id_or_alias}")
+  end
+
+  private
+
+  def generate_token(key, secret)
+    OAuth::AccessToken.new(OAuth::Consumer.new(key, secret))
+  end
+end

data/lib/factual/api.rb

@@ -0,0 +1,52 @@
+require 'json'
+require 'uri'
+
+class Factual
+  class API
+    API_V3_HOST        = "http://api.v3.factual.com"
+    DRIVER_VERSION_TAG = "factual-ruby-driver-1.0"
+    PARAM_ALIASES      = { :search => :q }
+
+    def initialize(access_token)
+      @access_token = access_token
+    end
+
+    def execute(query)
+      params_with_count = query.params.merge(:include_count => true)
+      handle_request(query.action || :read, query.path, params_with_count)
+    end
+
+    def schema(query)
+      handle_request(:schema, query.path + "/schema", query.params)["view"]
+    end
+
+    private
+
+    def handle_request(action, path, params)
+      response = make_request(path, params)
+      json    = response.body
+      payload = JSON.parse(json)
+
+      raise StandardError.new(payload["message"]) unless payload["status"] == "ok"
+
+      payload["response"]
+    end
+
+    def make_request(path, params)
+      url     = "#{API_V3_HOST}/#{path}?#{query_string(params)}"
+      headers = { "X-Factual-Lib" => DRIVER_VERSION_TAG }
+
+      @access_token.get(url, headers)
+    end
+
+    def query_string(params)
+      query_array = params.keys.inject([]) do |array, key|
+        param_alias = PARAM_ALIASES[key.to_sym] || key.to_sym
+        value = params[key].class == Hash ? params[key].to_json : params[key].to_s
+        array << "#{param_alias}=#{URI.escape(value)}"
+      end
+
+      query_array.join("&")
+    end
+  end
+end

data/lib/factual/query.rb

@@ -0,0 +1,105 @@
+class Factual
+  class Query
+    include Enumerable
+
+    DEFAULT_LIMIT = 20
+    VALID_PARAMS = {
+      :read      => [ :filters, :search, :geo, :sort, :select, :limit, :offset ],
+      :resolve   => [ :values ],
+      :crosswalk => [ :factual_id ],
+      :schema    => [ ],
+      :any       => [ :include_count ]
+    }
+
+    def initialize(api, action, path, params = {})
+      @api = api
+      @action = action
+      @path = path
+      @params = params
+      @response = nil
+      @schema = nil
+      validate_params
+    end
+
+    # Attribute Readers
+    attr_reader :action
+
+    [:path, :params].each do |attribute|
+      define_method(attribute) do
+        instance_variable_get("@#{attribute}").clone
+      end
+    end
+
+    # Response Methods
+    def each(&block)
+      rows.each { |row| block.call(row) }
+    end
+
+    def last
+      rows.last
+    end
+
+    def [](index)
+      rows[index]
+    end
+
+    def rows
+      (@response ||= @api.execute(self))["data"].clone
+    end
+
+    def total_rows
+      (@response ||= @api.execute(self))["total_row_count"]
+    end
+
+    def schema
+      (@schema ||= @api.schema(self)).clone
+    end
+
+    # Query Modifiers
+    VALID_PARAMS.values.flatten.uniq.each do |param|
+      define_method(param) do |*args|
+        args  = args.collect{|arg| arg.is_a?(String) ? arg.strip : arg }
+        value = (args.length == 1) ? args.first : args.join(',')
+
+        new_params = @params.clone
+        new_params[param] = value
+
+        Query.new(@api, @action, @path, new_params)
+      end
+    end
+
+    def sort_desc(*args)
+      columns = args.map { |column| "#{column}:desc" }
+
+      new_params = @params.clone
+      new_params[:sort] = columns.join(',')
+
+      Query.new(@api, @action, @path, new_params)
+    end
+
+    def page(page_number, paging_options = {})
+      limit = (paging_options[:per] || paging_options["per"] || DEFAULT_LIMIT).to_i
+      limit = DEFAULT_LIMIT if limit < 1
+
+      page_number = page_number.to_i
+      page_number = 1 if page_number < 1
+
+      new_params = @params.clone
+      new_params[:limit] = limit
+      new_params[:offset] = (page_number - 1) * limit
+
+      Query.new(@api, @action, @path, new_params)
+    end
+
+    private
+
+    # Validations
+    def validate_params
+      @params.each do |param, val|
+        unless (VALID_PARAMS[@action] + VALID_PARAMS[:any]).include?(param)
+          raise StandardError.new("InvalidArgument #{param} for #{@action}")
+        end
+      end
+    end
+  end
+end

metadata

@@ -2,16 +2,17 @@
 name: factual-api
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: "0.2"
+  version: "0.5"
 platform: ruby
 authors: 
+- Rudiger Lippert
 - Forrest Cao
 - Aaron Crow
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2012-01-12 00:00:00 +08:00
+date: 2012-01-19 00:00:00 +08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -35,7 +36,9 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
-- lib/factual_api.rb
+- lib/factual/api.rb
+- lib/factual/query.rb
+- lib/factual.rb
 - README.md
 - CHANGELOG.md
 has_rdoc: true

data/lib/factual_api.rb

@@ -1,239 +0,0 @@
-require 'oauth'
-require 'json'
-require 'uri'
-require 'ostruct'
-
-module Factual
-  class Api
-    API_V3_HOST        = "http://api.v3.factual.com"
-    DRIVER_VERSION_TAG = "factual-ruby-driver-1.0"
-    PARAM_ALIASES      = { :search => :q }
-
-    # initializers
-    # ----------------
-    def initialize(key, secret)
-      @access_token = OAuth::AccessToken.new(
-        OAuth::Consumer.new(key, secret))
-    end
-
-    # actions
-    # ----------------
-    def crosswalk(factual_id, format = :object)
-      query = Query.new(self, :crosswalk, "places/crosswalk", { :factual_id => factual_id }, format)
-
-      return query
-    end
-
-    def resolve(values, format = :object)
-      query = Query.new(self, :resolve, "places/resolve", { :values => values }, format)
-
-      return query
-    end
-
-    def table(table_id_or_alias, format = :object)
-      query = Query.new(self, :read, "t/#{table_id_or_alias}", Hash.new, format)
-
-      return query
-    end
-
-    # requesting
-    # ----------------
-    def request(path, params)
-      url     = "#{API_V3_HOST}/#{path}?#{query_string(params)}"
-      headers = {"X-Factual-Lib" => DRIVER_VERSION_TAG}
-
-      return @access_token.get(url, headers)
-    end
-
-    private
-
-    def query_string(params)
-      arr = []
-      params.each do |param, v|
-        param_alias = PARAM_ALIASES[param.to_sym] || param.to_sym
-
-        v = v.to_json if v.class == Hash
-        arr << "#{param_alias}=#{URI.escape(v.to_s)}"
-      end
-      return arr.join("&")
-    end
-
-  end
-
-  class Query
-
-    # helper functions
-    DEFAULT_LIMIT = 20
-
-    VALID_PARAMS = {
-      :read      => [ :filters, :search, :geo, :sort, :select, :limit, :offset ],
-      :resolve   => [ :values ],
-      :crosswalk => [ :factual_id ],
-      :facets    => [ :filters, :search, :geo, :limit, :select, :min_count ],
-      :schema    => [ ],
-      :any       => [ :include_count ]
-    }
-
-    attr_accessor :params
-
-    # initializers
-    # ----------------
-    def initialize(api, action, path, params = nil, format = :object)
-      @api    = api
-      @action = action
-      @path   = path
-      @params = params || Hash.new
-      @format = format
-    end
-    
-    # helper functions
-    # ----------------
-    def clone
-      new_query = self.class.new(@api, @action, @path, @params.clone, @format)
-
-      return new_query
-    end
-
-    def set_param(key, value)
-      @params[key] = value
-    end
-
-    # attributes, after 'get'
-    # ----------------
-    def first
-      row_data = read_response["data"].first
-
-      if (@format == :json) # or :object
-        return row_data
-      else
-        return Row.new(row_data)
-      end
-    end
-
-    def rows
-      return read_response["data"] if (@format == :json)
-
-      return read_response["data"].collect do |row_data|
-        Row.new(row_data)
-      end
-    end
-
-    def total_count
-      read_response["total_row_count"]
-    end
-
-
-    def schema
-      unless @schema_response
-        @path  += "/schema"
-        @schema_response = response(:schema)
-      end
-
-      view   = @schema_response["view"]
-      fields = view["fields"]
-
-      schema = Table.new(view)
-      if schema && fields
-        schema.fields = fields.collect do |f|
-          Field.new(f)
-        end
-      end
-
-      return schema
-    end
-
-    def facets
-      unless @facets_response
-        @path  += "/facets"
-        @facets_response = response(:facets)
-      end
-      columns = @facets_response["data"]
-
-      return Facet.new(columns)
-    end
-
-    # query builder, returns immutable ojbects
-    # ----------------
-    VALID_PARAMS.values.flatten.uniq.each do |param|
-      define_method(param) do |*args|
-        api = self.clone()
-        val = (args.length == 1) ? args.first : args.join(',')
-
-        api.set_param(param, val)
-
-        return api
-      end
-    end
-    
-    # sugers
-    # ----------------
-    def sort_desc(*args)
-      api = self.clone
-      columns = args.collect{ |col|"#{col}:desc" }
-      api.set_param(:sort, columns.join(','))
-
-      return api
-    end
-
-    def page(page_num, paging_opts = {})
-      limit = (paging_opts[:per] || paging_opts["per"]).to_i
-      limit = DEFAULT_LIMIT if limit < 1
-
-      page_num = page_num.to_i
-      page_num = 1 if page_num < 1
-      offset   = (page_num - 1) * limit
-
-      api = self.clone
-      api.set_param(:limit, limit)
-      api.set_param(:offset, offset)
-
-      return api
-    end
-
-    # requesting
-    # ----------------
-    private
-
-    def read_response
-      unless @read_response
-        # always include count for reads
-        @params[:include_count] = true
-        @read_response = response(@action || :read)
-      end
-
-      return @read_response
-    end
-
-    def check_params!(action)
-      @params.each do |param, val|
-        unless (VALID_PARAMS[action] + VALID_PARAMS[:any]).include?(param)
-          raise StandardError.new("InvalidArgument #{param} for #{action}")
-        end
-      end
-    end
-
-    def response(action)
-      check_params!(action)
-
-      res = @api.request(@path, @params)
-
-      code    = res.code
-      json    = res.body
-      payload = JSON.parse(json)
-
-      if payload["status"] == "ok"
-        return payload["response"]
-      else
-        raise StandardError.new(payload["message"])
-      end
-    end
-
-  end
-
-  # response classes
-  # ----------------
-  class Row < OpenStruct; end
-  class Facet < OpenStruct; end
-  class Table < OpenStruct; end
-  class Field < OpenStruct; end
-end