wolfram-alpha 0.1 → 0.2

data/library/wolfram-alpha.rb

@@ -1,5 +1,6 @@
 # encoding: utf-8
 
+require 'cgi'
 require 'open-uri'
 require 'nokogiri'
 
@@ -8,10 +9,15 @@ require 'wolfram-alpha/client'
 require 'wolfram-alpha/subpod'
 require 'wolfram-alpha/response'
 
+# Wolfram|Alpha introduces a fundamentally new way to get knowledge and answers—
+# not by searching the web, but by doing dynamic computations based on a vast collection of
+# built-in data, algorithms, and methods.
+#
+# @author Mikkel Kroman
 module WolframAlpha
-  RequestURI = "http://api.wolframalpha.com/v2/query?input=%s&appid=%s"
+  # The current version of the WolframAlpha library.
+  Version = "0.2"
 
-  class << Version = [1,0]
-    def to_s; join '.' end
-  end
+  # The API request-uri.
+  RequestURI = "http://api.wolframalpha.com/v2/query?input=%s&appid=%s"
 end

data/library/wolfram-alpha/client.rb

@@ -1,15 +1,36 @@
 # encoding: utf-8
 
 module WolframAlpha
+  # Front object for communicating with the Wolfram|Alpha API.
   class Client
-    attr_accessor :app_id
+    # The Wolfram|Alpha API developer key, which is set upon initialization.
+    attr_accessor :application_key
 
-    def initialize app_id = nil
-      @app_id = app_id
+    # The default options for a new client, it is merged with the options
+    # set upon initialization.
+    DefaultOptions = {
+      timeout: 1
+    }
+
+    # Initialize a new client to communicate with the Wolfram|Alpha API.
+    #
+    # @param [String] application_key The developers API-key that can be easily
+    #   obtained from http://products.wolframalpha.com/api/
+    # @param [Hash] options A set of options that may be put in the request.
+    #
+    # @see DefaultOptions
+    def initialize application_key = nil, options = {}
+      @options = DefaultOptions.merge options
+      @application_key = application_key
     end
 
+    # Compute the value of user input, and return a new response.
+    #
+    # @param [String] query The users input query.
+    #
+    # @return [Response] The parsed response object.
     def compute query
-      document = Nokogiri::XML open WolframAlpha::RequestURI % [URI.escape(query), @app_id]#File.open("/home/mk/Documents/response.xml")
+      document = Nokogiri::XML open request_url(query)
 
       if document.root.name == "queryresult"
         Response.new document
@@ -17,5 +38,24 @@ module WolframAlpha
         raise "Invalid response"
       end
     end
+
+  private
+
+    # Mash together the request url, this is where the request-uri is modified
+    # according to the client options.
+    #
+    # @param [String] query The users input query.
+    #
+    # @return [String] The complete, formatted uri.
+    def request_url query = nil
+      escaped_query = CGI.escape query
+      formatted_url = WolframAlpha::RequestURI % [escaped_query, @application_key]
+
+      if @options[:timeout]
+        formatted_url << "&timeout=#{@options[:timeout]}"
+      end
+
+      return formatted_url
+    end
   end
 end

data/library/wolfram-alpha/pod.rb

@@ -1,9 +1,17 @@
 # encoding: utf-8
 
 module WolframAlpha
+  # A wrapper for the pod element.
   class Pod
+    # @return [Array] an array of sub-pods in this pod.
     attr_reader :subpods
 
+    # Access an attribute on the pod element.
+    def [] attribute
+      @element[attribute]
+    end
+
+    # Construct a new pod with an assigned element, then extract all subpods from it.
     def initialize element
       @element = element
 

data/library/wolfram-alpha/response.rb

@@ -1,13 +1,48 @@
 # encoding: utf-8
 
 module WolframAlpha
+  # This is a response object that wraps the response data in a
+  # easily managable object.
+  #
+  # @see #input_as_text
+  # @see #result_as_text
   class Response
     attr_reader :pods
 
+    # Construct a new response for a +document+.
     def initialize document = nil
       @document = document
 
-      @pods = @document.xpath("//pod").map { |element| Pod.new element }
+      @pods = @document.xpath("//pod").map {|element| Pod.new element }
+    end
+
+    # Return the pod containing the subpods which is of type +input+.
+    def input
+      find_pod_with_id "Input"
+    end
+
+    # Map and join the input interpreted pod's subpods as a printable string.
+    def input_as_text
+      input.subpods.map(&:text).join ', '
+    end
+
+    # Return the pod containing the subpods which is of type +result+.
+    def result
+      find_pod_with_id "Result"
+    end
+
+    # Map and join the result pod's subpods as a printable string.
+    def result_as_text
+      result.subpods.map(&:text).join ', '
+    end
+
+  private
+
+    # Find a pod of which id is +id+.
+    def find_pod_with_id id
+      @pods.find do |pod|
+        pod["id"] == id
+      end
     end
   end
 end

data/library/wolfram-alpha/subpod.rb

@@ -1,11 +1,23 @@
 # encoding: utf-8
 
 module WolframAlpha
+  # A subpod is a container for a type of output, such as plain text,
+  # numbers, images, etc.
   class Subpod
+    # This is the pod that this subpod belongs to.
+    attr_accessor :pod
+
+    # Construct a new subpod.
     def initialize pod, element
       @pod, @element = pod, element
     end
 
+    # Access an attribute on the subpod element.
+    def [] key
+      return @element[key]
+    end
+
+    # Get the contents of plaintext as plain text.
     def text
       @element.xpath("plaintext").text
     end

metadata

@@ -1,69 +1,63 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: wolfram-alpha
-version: !ruby/object:Gem::Version 
-  prerelease: false
-  segments: 
-  - 0
-  - 1
-  version: "0.1"
+version: !ruby/object:Gem::Version
+  version: '0.2'
+  prerelease: 
 platform: ruby
-authors: 
+authors:
 - Mikkel Kroman
 autorequire: 
-bindir: executables
+bindir: bin
 cert_chain: []
-
-date: 2011-01-27 00:00:00 +01:00
-default_executable: 
-dependencies: []
-
+date: 2012-03-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: &22778340 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *22778340
 description: 
 email: mk@maero.dk
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
+- library/wolfram-alpha.rb
 - library/wolfram-alpha/client.rb
-- library/wolfram-alpha/response.rb
 - library/wolfram-alpha/pod.rb
+- library/wolfram-alpha/response.rb
 - library/wolfram-alpha/subpod.rb
-- library/wolfram-alpha.rb
-has_rdoc: true
 homepage: 
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - library
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 1
-      - 9
-      - 1
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
       version: 1.9.1
-required_rubygems_version: !ruby/object:Gem::Requirement 
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.3.7
+rubygems_version: 1.8.11
 signing_key: 
 specification_version: 3
-summary: Wolfram|Alpha API implementation.
+summary: Wolfram|Alpha introduces a fundamentally new way to get knowledge and answers
+  — not by searching the web, but by doing dynamic computations based on a vast collection
+  of built-in data, algorithms, and methods.
 test_files: []
-
+has_rdoc: