duck-duck-go 1.0.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Andrew Jones, http://andrew-jones.com
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,44 @@
+This is a Ruby library to access the DuckDuckGo Zero Click Info API.
+
+= How to install
+
+  gem install duck-duck-go
+
+= Synopsis
+  
+  require "duck_duck_go"
+  
+  ddg = DuckDuckGo.new
+  zci = ddg.zeroclickinfo("Stephen Fry") # ZeroClickInfo object
+  
+  zci.heading # Stephen Fry
+  zci.abstract_text # Stephen John Fry is an English actor, screenwriter, author, playwright, ...
+  zci.related_topics["_"][0].text # Stephen Fry (cricketer) ...
+  
+= Description
+
+This library accesses the DuckDuckGo Zero Click Info API[http://duckduckgo.com/api.html], and returns an DuckDuckGo::ZeroClickInfo object containing the result.
+
+Depending on the result type, the +related_topics+ hash will contain slightly different results.
+
+For most queries, <code>related_topics["_"]</code> contains an array of the related topics.
+
+For a disambiguation query, <code>related_topics["_"]</code> contains the related topics, where as <code>related_topics["Topic"]</code> contains the disambiguation results. For example, searching for _apple_, you will find a <code>related_topics["Compaines"]</code> entry containing <i>Apple Inc</i> and <i>Apple Corp</i>, amongst others.
+
+= Issues
+
+http://github.com/andrewrjones/ruby-duck-duck-go/issues
+
+= Source code
+
+http://github.com/andrewrjones/ruby-duck-duck-go
+
+= Credits
+
+API and design heavily influenced by WWW::DuckDuckGo[http://search.cpan.org/~getty/WWW-DuckDuckGo-0.006/lib/WWW/DuckDuckGo/ZeroClickInfo.pm], the equivalent Perl module.
+
+= Copyright and License
+
+Copyright (c) 2011 Andrew Jones (http://andrew-jones.com)
+
+This code is available under the MIT License. See the LICENSE file for more details.

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rake'
+
+task :default => [:test]
+
+require 'rake/testtask'
+desc "Run unit tests"
+Rake::TestTask.new("test") { |t|
+  t.pattern = 'test/tc_*.rb'
+  t.verbose = true
+}
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "duck-duck-go"
+    gem.summary = %Q{Access the DuckDuckGo Zero Click Info API}
+    gem.description = %Q{A Ruby library to access the DuckDuckGo Zero Click Info API.}
+    gem.email = "andrwe@arjones.co.uk"
+    gem.homepage = "https://github.com/andrewrjones/ruby-duck-duck-go"
+    gem.authors = ["andrewrjones"]
+    gem.add_dependency('httpclient')
+    gem.add_dependency('json')
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |rcov|
+    rcov.libs << 'test'
+    rcov.pattern = 'test/tc_*.rb'
+    rcov.verbose = true
+    rcov.rcov_opts << '--exclude gems'
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install rcov"
+  end
+end
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "duck-duck-go #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('LICENSE')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/lib/duck_duck_go.rb

@@ -0,0 +1,50 @@
+# Author: Andrew Jones <http://andrew-jones.com>
+# The license of this source is MIT Licence
+
+module DuckDuckGo
+  
+  require 'rubygems'
+  require 'uri'
+  require 'httpclient'
+  require 'json'
+  require 'duck_duck_go/zero_click_info'
+
+  # see DuckDuckGo::Main.new
+  def self.new(*params)
+    DuckDuckGo::Main.new(*params)
+  end
+  
+  class Main
+    
+    API_URL = 'http://api.duckduckgo.com/'
+    API_URL_SECURE = 'https://api.duckduckgo.com/'
+    
+    # Create a new instance.
+    # It is recommended to pass in a meaningful user agent.
+    # Defaults to using the secure api (https)
+    def initialize(http_agent_name = 'DuckDuckGo.rb', secure = true)
+      if secure
+        @url = API_URL_SECURE
+      else
+        @url = API_URL
+      end
+      @http = HTTPClient.new(:agent_name => http_agent_name)
+    end
+    
+    # Run a query against Duck Duck Go
+    # Returns an instance of DuckDuckGo::ZeroClickInfo
+    def zeroclickinfo(query)
+      data = @http.get_content(@url, { 'q' => query, 'o' => 'json' })
+  
+      # parse the JSON and return an instance
+      # of the ZeroClickInfo class
+      DuckDuckGo::ZeroClickInfo.by(JSON.parse(data))
+    end
+  
+    # Alias for DuckDuckGo::Main.zeroclickinfo
+    def zci(*params)
+      self.zeroclickinfo(*params)
+    end
+  end
+  
+end

data/lib/duck_duck_go/icon.rb

@@ -0,0 +1,26 @@
+module DuckDuckGo
+  
+  require 'uri'
+  
+  class DuckDuckGo::Icon
+    
+    attr_reader :url, :width, :height
+    
+    # Representes a DDG icon
+    def initialize(url = nil, width = nil, height = nil)
+      @url = url
+      @width = width
+      @height = height
+    end
+    
+    # Populate an DuckDuckGo::Icon from a result
+    def self.by(icon_result)
+      url = URI.parse(icon_result['URL']) unless icon_result['URL'].empty?
+      width = icon_result['Width'] if icon_result['Width']
+      height = icon_result['Height'] if icon_result['Height']
+      
+      self.new(url, width, height)
+    end
+  end
+  
+end

data/lib/duck_duck_go/link.rb

@@ -0,0 +1,29 @@
+module DuckDuckGo
+  
+  require 'uri'
+  require 'duck_duck_go/icon'
+  
+  class DuckDuckGo::Link
+    
+    attr_reader :result, :first_url, :icon, :text
+    
+    # Representes a DDG link
+    def initialize(result = nil, first_url = nil, icon = nil, text = nil)
+      @result = result
+      @first_url = first_url
+      @icon = icon
+      @text = text
+    end
+    
+    # Populate a DuckDuckGo::Link from a result
+    def self.by(link_result)
+      result = link_result['Result'] unless link_result['Result'].empty?
+      first_url = URI.parse(link_result['FirstURL']) unless link_result['FirstURL'].empty?
+      icon = DuckDuckGo::Icon.by(link_result['Icon']) unless link_result['Icon'].empty?
+      text = link_result['Text'] unless link_result['Text'].empty?
+      
+      self.new(result, first_url, icon, text)
+    end
+  end
+  
+end

data/lib/duck_duck_go/zero_click_info.rb

@@ -0,0 +1,82 @@
+module DuckDuckGo
+  
+  require 'uri'
+  require 'duck_duck_go/link'
+  require 'duck_duck_go/icon'
+  
+  class DuckDuckGo::ZeroClickInfo
+    
+    # Definitions for the result type
+    TYPE_DEFINITIONS = {
+      'A' => 'article',
+      'D' => 'disambiguation',
+      'C' => 'category',
+      'N' => 'name',
+      'E' => 'exclusive',
+    }
+    
+    attr_reader :abstract, :abstract_text, :abstract_source, :abstract_url, :image, :heading, :answer, :answer_type, :definition, :definition_source, :definition_url, :type, :type_long, :results, :related_topics
+    
+    # Representes a DDG Zero Click Info result
+    def initialize(abstract = nil, abstract_text = nil, abstract_source = nil, abstract_url = nil, image = nil, heading = nil, answer = nil, answer_type = nil, definition = nil, definition_source = nil, definition_url = nil, type = nil, results = nil, related_topics = nil)
+      @abstract = abstract
+      @abstract_text = abstract_text
+      @abstract_source = abstract_source
+      @abstract_url = abstract_url
+      @image = image
+      @heading = heading
+      @answer = answer
+      @answer_type = answer_type
+      @definition = definition
+      @definition_source = definition_source
+      @definition_url = definition_url
+      @type = type unless type.nil?
+      @type_long = TYPE_DEFINITIONS[type]
+      @results = results
+      @related_topics = related_topics
+    end
+    
+    # Populate the DuckDuckGo::ZeroClickInfo from a result
+    def self.by(result)
+      
+      abstract = result['Abstract'] unless result['Abstract'].empty?
+      abstract_text = result['AbstractText'] unless result['AbstractText'].empty?
+      abstract_source = result['AbstractSource'] unless result['AbstractSource'].empty?
+      abstract_url = URI.parse(result['AbstractURL']) unless result['AbstractURL'].empty?
+      image = URI.parse(result['Image']) unless result['Image'].empty?
+      heading = result['Heading'] unless result['Heading'].empty?
+      answer = result['Answer'] unless result['Answer'].empty?
+      answer_type = result['AnswerType'] unless result['AnswerType'].empty?
+      definition = result['Definition'] unless result['Definition'].empty?
+      definition_source = result['DefinitionSource'] unless result['DefinitionSource'].empty?
+      definition_url = URI.parse(result['DefinitionURL']) unless result['DefinitionURL'].empty?
+      type = result['Type'] unless result['Type'].empty?
+      
+      if result['Results']
+        results = Array.new
+        result['Results'].each do |link_result|
+          results << DuckDuckGo::Link.by(link_result)
+        end
+      end
+      
+      if result['RelatedTopics']
+        related_topics = Hash.new
+        result['RelatedTopics'].each do |t|
+          if t['Topics']
+            topics = Array.new
+            t['Topics'].each do |link_result|
+              topics << DuckDuckGo::Link.by(link_result)
+            end
+            related_topics[t['Name']] = topics
+          else
+            related_topics['_'] = Array.new if related_topics['_'].nil?
+            related_topics['_'] << DuckDuckGo::Link.by(t)
+          end
+        end
+      end
+      
+      self.new(abstract, abstract_text, abstract_source, abstract_url, image, heading, answer, answer_type, definition, definition_source, definition_url, type, results, related_topics)
+    end
+  end
+  
+end

data/scripts/search_dump.rb

@@ -0,0 +1,23 @@
+# dumps out the result of the query, in JSON and Ruby
+# used during development
+#
+# usage: ruby scripts/search_dump.rb foo
+
+require 'rubygems'
+require 'httpclient'
+require 'json'
+require 'pp'
+
+http = HTTPClient.new
+query = { 'q' => ARGV[0], 'o' => 'json' }
+
+json = http.get_content('http://api.duckduckgo.com/', query)
+ruby = JSON.parse(json)
+
+puts 'JSON'
+puts '----'
+puts json
+puts
+puts 'Ruby'
+puts '----'
+pp ruby

data/test/tc_icon.rb

@@ -0,0 +1,23 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'test/unit'
+require 'duck_duck_go/icon'
+require 'uri'
+
+class TestIcon < Test::Unit::TestCase
+  
+  def test_icon
+    data = {
+      "URL" => "https://i.duckduckgo.com/i/foo.com.ico",
+      "Height" => 16,
+      "Width" => 16
+    }
+    
+    icon = DuckDuckGo::Icon.by(data)
+    assert_instance_of(DuckDuckGo::Icon, icon)
+    assert_instance_of(URI::HTTPS, icon.url)
+    assert_equal("i.duckduckgo.com", icon.url.host)
+    assert_equal(16, icon.width)
+    assert_equal(16, icon.height)
+  end
+end

data/test/tc_link.rb

@@ -0,0 +1,46 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'test/unit'
+require 'duck_duck_go/link'
+require 'duck_duck_go/icon'
+require 'uri'
+
+class TestLink < Test::Unit::TestCase
+  
+  def test_link
+    data = {
+      "Result" => "<a href=\"http://www.foo.com\"><b>Official site</b></a><a href=\"http://www.foo.com\"></a>",
+      "Icon" => {
+        "URL" => "https://i.duckduckgo.com/i/foo.com.ico",
+        "Height" => 16,
+        "Width" => 16
+      },
+      "FirstURL" => "http://www.foo.com",
+      "Text" => "Official site"
+    }
+    
+    link = DuckDuckGo::Link.by(data)
+    assert_instance_of(DuckDuckGo::Link, link)
+    assert_instance_of(DuckDuckGo::Icon, link.icon)
+    assert_instance_of(URI::HTTP, link.first_url)
+    assert_equal('www.foo.com', link.first_url.host)
+    assert_equal('Official site', link.text)
+  end
+  
+  def test_link_missing_icon
+    data = {
+      "Result" => "<a href=\"http://www.foo.com\"><b>Official site</b></a><a href=\"http://www.foo.com\"></a>",
+      "Icon" => {
+      },
+      "FirstURL" => "http://www.foo.com",
+      "Text" => "Official site"
+    }
+    
+    link = DuckDuckGo::Link.by(data)
+    assert_instance_of(DuckDuckGo::Link, link)
+    assert_nil(link.icon)
+    assert_instance_of(URI::HTTP, link.first_url)
+    assert_equal('www.foo.com', link.first_url.host)
+    assert_equal('Official site', link.text)
+  end
+end

data/test/tc_live.rb

@@ -0,0 +1,45 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require 'test/unit'
+require 'duck_duck_go'
+require 'duck_duck_go/zero_click_info'
+
+class TestLive < Test::Unit::TestCase
+  
+  # test a live search for 'stephen fry'
+  def test_live
+    
+    ddg = DuckDuckGo.new(nil, false)
+    zci = ddg.zci('stephen fry')
+    
+    assert_instance_of(DuckDuckGo::ZeroClickInfo, zci)
+    assert_equal("Stephen Fry", zci.heading)
+    assert_equal("Wikipedia", zci.abstract_source)
+    assert_equal("A", zci.type)
+  end
+  
+  # test using http
+  def test_live_http
+    
+    ddg = DuckDuckGo.new(nil, true)
+    zci = ddg.zci('stephen fry')
+    
+    assert_instance_of(DuckDuckGo::ZeroClickInfo, zci)
+    assert_equal("Stephen Fry", zci.heading)
+    assert_equal("Wikipedia", zci.abstract_source)
+    assert_equal("A", zci.type)
+  end
+  
+  # questions do not currently get a response on the api
+  def test_answer
+    ddg = DuckDuckGo.new
+    zci = ddg.zci('age of obama')
+    
+    assert_nil(zci.abstract)
+    assert_nil(zci.answer)
+    assert_nil(zci.definition)
+    assert_nil(zci.heading)
+    assert_equal(0, zci.related_topics.size)
+    assert_equal(0, zci.results.size)
+  end
+end