ruby-factual 0.0.5 → 0.0.6

data/lib/factual.rb

@@ -1,26 +1,55 @@
-require 'curl'
+# A Ruby Lib for using Facutal API 
+#
+# For more information, visit http://github.com/factual/ruby-lib (TODO), 
+# and {Factual Developer Tools}[http://www.factual.com/devtools]
+#
+# Author:: Forrest Cao (mailto:forrest@factual.com)
+# Copyright:: Copyright (c) 2010 {Factual Inc}[http://www.factual.com].
+# License:: GPL
+
+require 'net/http'
 require 'json'
 require 'uri'
 
 module Factual
+  # The start point of using Factual API
   class Api
+
+    # To initialize a Factual::Api, you will have to get an api_key from {Factual Developer Tools}[http://www.factual.com/developers/api_key]
+    #
+    # Params: opts as a hash
+    # * <tt>opts[:api_key]</tt> required
+    # * <tt>opts[:debug]</tt>   optional, default is false. If you set it as true, it will print the Factual Api Call URLs on the screen
+    # * <tt>opts[:version]</tt> optional, default value is 2, just do not change it
+    # * <tt>opts[:domain]</tt>  optional, default value is www.factual.com (only configurable by Factual employees) 
+    # 
+    # Sample: 
+    #   api = Factual::Api.new(:api_key => MY_API_KEY, :debug => true)
     def initialize(opts)
       @api_key = opts[:api_key]
-      @version = opts[:version]
+      @version = opts[:version] || 2
       @domain  = opts[:domain] || 'www.factual.com'
-      @adapter = Adapter.new(@api_key, @version, @domain)
+      @debug   = opts[:debug]
+
+      @adapter = Adapter.new(@api_key, @version, @domain, @debug)
     end
 
+    # Get a Factual::Table object by inputting the table_key
+    #
+    # Sample: 
+    #   api.get_table('g9R1u2')
     def get_table(table_key)
       Table.new(table_key, @adapter)
     end
   end
 
+  # This class holds the metadata of a Factual table. The filter and sort methods are to filter and/or sort
+  # the table data before calling a find_one or each_row.
   class Table
-    attr_accessor :name, :description, :rating, :source, :creator, :total_row_count, :created_at, :updated_at, :fields, :geo_enabled, :downloadable
-    attr_accessor :key, :adapter
+    attr_accessor :name, :key, :description, :rating, :source, :creator, :total_row_count, :created_at, :updated_at, :fields, :geo_enabled, :downloadable
+    attr_reader   :adapter # :nodoc:
 
-    def initialize(table_key, adapter)
+    def initialize(table_key, adapter) # :nodoc:
       @table_key = table_key
       @adapter   = adapter
       @schema    = adapter.schema(@table_key)
@@ -37,54 +66,92 @@ module Factual
      end
     end
 
+    # Define table filters, it can be chained before +find_one+ or +each_row+.
+    # 
+    # The params can be:
+    # * simple hash for equal filter
+    # * nested hash with filter operators
+    #
+    # Samples:
+    #   table.filter(:state => 'CA').find_one # hash
+    #   table.filter(:state => 'CA', :city => 'LA').find_one # multi-key hash
+    #   table.filter(:state => {"$has" => 'A'}).find_one  # nested hash
+    #   table.filter(:state => {"$has" => 'A'}, :city => {"$ew" => 'A'}).find_one # multi-key nested hashes
+    #   
+    # For more detail inforamtion about filter syntax, please look up at {Server API Doc for Filter}[http://wiki.developer.factual.com/Filter]
     def filter(filters)
       @filters = filters
       return self
     end
 
-    def sort(sorts)
+    # Define table sorts, it can be chained before +find_one+ or +each_row+.
+    # 
+    # The params can be:
+    # * a hash with single key
+    # * single-key hashes, only the first 2 sorts will work. (secondary sort will be supported in next release of Factual API)
+    #
+    # Samples:
+    #   table.sort(:state => 1).find_one  # hash with single key
+    #   table.sort({:state => 1}, {:abbr => -1}).find_one # single-key hashes
+    # For more detail inforamtion about sort syntax, please look up at {Server API Doc for Sort (TODO)}[http://wiki.developer.factual.com/Sort]
+    def sort(*sorts)
       @sorts = sorts
       return self
     end
 
-    def each_row
-      filters_query = "&filters=" + @filters.to_json if @filters
-      if @sorts
-        sorts_by = "sort_by=" + @sorts.keys.collect{|k| get_field_id(k).to_s}.join(",") 
-        sorts_dir = "sort_dir=" + @sorts.values.collect{|v| (v==1) ? 'asc' : 'desc' }.join(",")
-        sorts_query = "&" + sorts_by + "&" + sorts_dir
+    # Find the first row (a Factual::Row object) of the table with filters and/or sorts.
+    #
+    # Samples:
+    # * <tt>table.filter(:state => 'CA').find_one</tt>
+    # * <tt>table.filter(:state => 'CA').sort(:city => 1).find_one</tt>
+    def find_one
+      resp = @adapter.read_table(@table_key, @filters, @sorts, 1)
+      row_data = resp["data"].first
+
+      if row_data
+        return Row.new(self, row_data)
+      else
+        return nil
       end
+    end
 
-      resp = @adapter.api_call("/tables/#{@table_key}/read.jsaml?limit=999" + filters_query.to_s + sorts_query.to_s)
+    # An iterator on each row (a Factual::Row object) of the filtered and/or sorted table data
+    #
+    # Samples:
+    #   table.filter(:state => 'CA').sort(:city => 1).each do |row|
+    #     puts row.inspect
+    #   end
+    def each_row
+      resp = @adapter.read_table(@table_key, @filters, @sorts)
 
-      @total_rows = resp["response"]["total_rows"]
-      rows = resp["response"]["data"]
+      @total_rows = resp["total_rows"]
+      rows = resp["data"]
 
-      # TODO iterator
       rows.each do |row_data|
         row = Row.new(self, row_data) 
         yield(row) if block_given?
       end
     end
 
-    private
-
-    def get_field_id(field_ref)
-      @fields.each do |f|
-        return f['id'] if f['field_ref'] == field_ref.to_s
-      end
+    # TODO
+    def add_row(values)
     end
 
+    private
+
     def camelize(str)
       s = str.to_s.split("_").collect{ |w| w.capitalize }.join
       s[0].chr.downcase + s[1..-1]
     end
   end
 
+  # This class holds the subject_key, subject (in array) and facts (Factual::Fact objects) of a Factual Subject. 
+  #
+  # The subject_key and subject array can be accessable directly from attributes, and you can get a fact by <tt>row[field_ref]</tt>.
   class Row
-    attr_accessor :subject_key, :subject
+    attr_reader :subject_key, :subject
 
-    def initialize(table, row_data)
+    def initialize(table, row_data) # :nodoc:
       @subject_key = row_data[0]
 
       @table       = table
@@ -105,6 +172,11 @@ module Factual
       end
     end
 
+    # Get a Factual::Fact object by field_ref
+    #
+    # Sample: 
+    #   city_info = table.filter(:state => 'CA').find_one
+    #   city_info['city_name']
     def [](field_ref)
       @facts_hash[field_ref]
     end
@@ -115,10 +187,11 @@ module Factual
     end
   end
 
+  # This class holds the subject_key, value, field_ref field (field metadata in hash). The input method is for suggesting a new value for the fact.  
   class Fact
-    attr_accessor :value, :subject_key, :field, :adapter
+    attr_reader :value, :subject_key, :field_ref, :field 
 
-    def initialize(table, subject_key, field, value)
+    def initialize(table, subject_key, field, value) # :nodoc:
       @value = value 
       @field = field
       @subject_key = subject_key
@@ -127,64 +200,104 @@ module Factual
       @adapter   = table.adapter
     end
 
-    def field_ref
+    def field_ref # :nodoc:
       @field["field_ref"]
     end
 
+    # To input a new value to the fact
+    #
+    # Parameters:
+    #  * +value+ 
+    #  * <tt>opts[:source]</tt> the source of an input, can be a URL or something else
+    #  * <tt>opts[:comment]</tt> the comment of an input
+    #
+    # Sample:
+    #   fact.input('new value', :source => 'http://website.com', :comment => 'because it is new value.'
     def input(value, opts={})
       return false if value.nil?
 
       hash = opts.merge({
         :subjectKey => @subject_key,
-        :fieldId => @field['id'],
-        :value => value
+        :fieldId    => @field['id'],
+        :value      => value
       })
-      query_string = hash.to_a.collect{ |k,v| URI.escape(k.to_s) + '=' + URI.escape(v.to_s) }.join('&')
 
-      @adapter.api_call("/tables/#{@table_key}/input.js?" + query_string)
+      @adapter.input(@table_key, hash)
       return true
     end
 
+    # Just return the value
     def to_s
       @value
     end
 
+    # Just return the value
     def inspect
       @value
     end
   end
 
 
-  class Adapter
+  class Adapter # :nodoc:
     CONNECT_TIMEOUT = 30
 
-    def initialize(api_key, version, domain)
-      @base = "http://#{domain}/api/v#{version}/#{api_key}"
+    def initialize(api_key, version, domain, debug=false)
+      @domain = domain
+      @base   = "/api/v#{version}/#{api_key}"
+      @debug  = debug
     end
 
     def api_call(url)
       api_url = @base + url
+      puts "[Factual API Call] http://#{@domain}#{api_url}" if @debug
 
+      json = "{}"
       begin
-        curl = Curl::Easy.new(api_url) do |c|
-          c.connect_timeout = CONNECT_TIMEOUT
+        Net::HTTP.start(@domain, 80) do |http|
+          response = http.get(api_url)
+          json     = response.body
         end
-        curl.http_get
       rescue Exception => e
         raise ApiError.new(e.to_s + " when getting " + api_url)
       end
 
-      resp = JSON.parse(curl.body_str)
+      resp = JSON.parse(json)
       raise ApiError.new(resp["error"]) if resp["status"] == "error"
       return resp
     end
 
     def schema(table_key)
-      resp = api_call("/tables/#{table_key}/schema.json")
+      url  = "/tables/#{table_key}/schema.json"
+      resp = api_call(url)
+
       return resp["schema"]
     end
+
+    def read_table(table_key, filters=nil, sorts=nil, limit=999)
+      filters_query = "&filters=" + filters.to_json if filters
+
+      if sorts
+        sorts = sorts[0] if sorts.length == 1
+        sorts_query = "&sort=" + sorts.to_json
+      end
+
+      url  = "/tables/#{table_key}/read.jsaml?limit=#{limit}" + filters_query.to_s + sorts_query.to_s
+      resp = api_call(url)
+
+      return resp["response"]
+    end
+
+    def input(table_key, params)
+      query_string = params.to_a.collect{ |k,v| URI.escape(k.to_s) + '=' + URI.escape(v.to_s) }.join('&')
+
+      url  = "/tables/#{table_key}/input.js?" + query_string
+      resp = api_call(url)
+
+      return resp['response']
+    end
   end
 
+  # Exception class for Factual Api Errors  
   class ApiError < Exception
   end
 end

data/test/unit/adapter.rb

@@ -0,0 +1,53 @@
+require 'test/unit/helper'
+require 'lib/factual'
+
+class AdapterTest < Factual::TestCase
+  def setup
+    @adapter = Factual::Adapter.new(API_KEY, API_VERSION, API_DOMAIN, DEBUG_MODE)
+  end
+
+  def test_corret_request
+    url = "/tables/#{TABLE_KEY}/schema.json"
+
+    assert_nothing_raised do
+      resp = @adapter.api_call(url)
+    end
+  end
+
+  def test_wrong_request
+    url = "/tables/#{WRONG_KEY}/schema.json"
+
+    assert_raise Factual::ApiError do
+      resp = @adapter.api_call(url)
+    end
+  end
+
+  def test_getting_schema
+    schema = @adapter.schema(TABLE_KEY)
+
+    assert_not_nil schema
+    assert_equal schema['name'], TABLE_NAME
+  end
+
+  def test_reading_table
+    resp = @adapter.read_table(TABLE_KEY)
+    assert_equal resp['total_rows'], TOTAL_ROWS
+  end
+
+  def test_reading_table_with_filter
+    resp = @adapter.read_table(TABLE_KEY, {:two_letter_abbrev => 'CA'})
+    assert_equal resp['total_rows'], 1
+  end
+
+  def test_inputting
+    params = {
+      :subjectKey => SUBJECT_KEY,
+      :value      => 'sample text',
+      :fieldId    => STATE_FIELD_ID
+    }
+
+    assert_raise Factual::ApiError do
+      @adapter.input(TABLE_KEY, params)
+    end
+  end
+end

data/test/unit/table.rb

@@ -0,0 +1,51 @@
+require 'lib/factual'
+require 'test/unit/helper'
+
+class TableTest < Factual::TestCase
+  def setup
+    api = Factual::Api.new(:api_key => API_KEY, :debug => DEBUG_MODE)
+
+    @table = api.get_table(TABLE_KEY)
+  end
+
+  def test_metadata
+    assert_equal @table.name, TABLE_NAME
+    assert_equal @table.creator, TABLE_OWNER
+  end
+
+  def test_each_row
+    states = []
+    @table.each_row do |state_info|
+      fact = state_info['state']
+      states << fact.value
+    end
+
+    assert_equal states.length, TOTAL_ROWS
+  end
+
+  def test_filtering
+    row = @table.filter(:two_letter_abbrev => 'WA').find_one
+    assert_equal row["state"].value, "Washington"
+
+    row = @table.filter(:two_letter_abbrev => { '$has' => 'a' }).sort(:state => 1).find_one
+    assert_equal row["state"].value, "California"
+  end
+
+  def test_sorting
+    row = @table.sort(:state => 1).find_one
+    assert_equal row["state"].value, "California"
+
+    assert_raise Factual::ApiError do 
+      # secondary sort will be supported in next release
+      row = @table.sort({:state => 1}, {:test_field1 => 1}).find_one
+      row["state"].value
+    end
+  end
+
+  def test_row
+    row = @table.find_one
+  end
+
+  def test_fact
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: ruby-factual
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 19
   prerelease: false
   segments: 
   - 0
   - 0
-  - 5
-  version: 0.0.5
+  - 6
+  version: 0.0.6
 platform: ruby
 authors: 
 - Forrest Cao
@@ -15,29 +15,13 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-09-14 00:00:00 +08:00
+date: 2010-10-20 00:00:00 +08:00
 default_executable: 
 dependencies: 
-- !ruby/object:Gem::Dependency 
-  name: curb
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 27
-        segments: 
-        - 0
-        - 3
-        - 4
-        version: 0.3.4
-  type: :runtime
-  version_requirements: *id001
 - !ruby/object:Gem::Dependency 
   name: json
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -49,7 +33,7 @@ dependencies:
         - 0
         version: 1.2.0
   type: :runtime
-  version_requirements: *id002
+  version_requirements: *id001
 description: ""
 email: forrest@factual.com
 executables: []
@@ -61,6 +45,8 @@ extra_rdoc_files:
 files: 
 - README.md
 - lib/factual.rb
+- test/unit/adapter.rb
+- test/unit/table.rb
 has_rdoc: true
 homepage: http://github.com/forrestc/ruby-factual
 licenses: []
@@ -101,5 +87,6 @@ rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: ""
-test_files: []
-
+test_files: 
+- test/unit/adapter.rb
+- test/unit/table.rb