yanapi 0.4.0 → 0.4.1

data/CHANGELOG

@@ -1,4 +1,8 @@
 == COMPLETED
+=== 0.4.1
+Switched to CGI for encoding URLs, a bug with parsing non english characters.
+
+Enhanced the overall documentation.
 === 0.4.0
 Implemented multivalued parameters as Arrays. You can now search in many regions
 and categories simultaneously.

data/README

@@ -11,19 +11,28 @@
 YANAPI is an API for Yahoo! Answers web services. It has been developed
 in {Ruby}[http://www.ruby-lang.org].
 
-YANAPI provides a flexible interface to the {Yahoo! Answers}[http://answers.yahoo.com/] search services.
+YANAPI provides a flexible interface to the
+{Yahoo! Answers}[http://answers.yahoo.com/] search services. As for this writing
+it is the <b>most complete library</b> for accessing
+{Yahoo! Answers}[http://answers.yahoo.com/] compared to other libraries on
+{RubyGems}[http://rubygems.org/].
 
 It supports four search types:
-* key word search;
-* search based on the category name or the category ID;
-* search for a precise question ID;
-* search for a questions posted by a user with an ID.
+* {key word search}[http://developer.yahoo.com/answers/V1/questionSearch.html];
+* {search based on the category name or the category ID
+  }[http://developer.yahoo.com/answers/V1/getByCategory.html];
+* {search for a precise question ID
+  }[http://developer.yahoo.com/answers/V1/getQuestion.html];
+* {search for a questions posted by a user with an ID
+  }[http://developer.yahoo.com/answers/V1/getByUser.html].
+
+See CHANGELOG for features which are planned for future releases.
 
 It is possible to restrict key word based search through a category.
 
 Question Search and User Search cannot be extended by key words or category IDs.
 
-YANAPI tries to as flexible as possible. It restricts unallowed parameter
+YANAPI tries to be as flexible as possible. It restricts unallowed parameter
 combinations and forces using mandatory ones. But it doesn't care about defaults.
 For example, as for this writing the default output value is an xml based format.
 If it changes in the future, the user will be responsible to choose the format.
@@ -35,7 +44,8 @@ YANAPI provides the minimal acceptable query.
 To install YANAPI ussue the following command:
   $ gem install yanapi
 
-You might want to install versions prior to +0.3.1+:
+You might want to install versions prior to +0.3.1+, if you are bound on
+the old one dimensional parameter hash:
   $ gem install yanapi -v 0.1.1
 
 If you want to do a system wide installation, do this as root
@@ -72,14 +82,27 @@ A small example shall demostrate the usage:
   api.get # => String
 
 
-For details on particular keys and defaults see {the official description}[http://developer.yahoo.com/answers/] and the RDoc documentation in this library.
+For details on particular keys and defaults see
+{the official description}[http://developer.yahoo.com/answers/]
+and the RDoc documentation in this library.
 
-== EXCEPTION HIERARCHY
+=== Exception Hierarchy
 While using YANAPI you can face three kinds of errors:
 * <tt>YANAPI::UserError</tt>;
 * <tt>YANAPI::ExternalError</tt>;
 * <tt>YANAPI::ContentError</tt>.
 
+The errors here are presented in the order they may occur
+during YANAPI's work.
+
+First YANAPI checks the user input and throws a <tt>YANAPI::UserError</tt>.
+
+Then it fetches a response from a remote server, it can result
+in a <tt>YANAPI::ExternalError</tt>.
+
+If the response contains no <b>200 OK</b> code or the response body
+cannot be parsed, the library throws a <tt>YANAPI::ContentError</tt>.
+
 See the RDoc documentation on semantics of these errors.
 
 All of them are subcalsses of <tt>YANAPI::Error</tt> which is in turn a subclass
@@ -88,9 +111,37 @@ of the standard +RuntimeError+.
 If you want to intercept any and every exception thrown by YANAPI simply rescue
 <tt>YANAPI::Error</tt>.
 
+=== Parameter Semantics
+YANAPI accepts following keys and values (given default values if appropriate):
+  {
+    :query_params => {
+      :appid => 'YahooDemo', # It is required, register your own ID.
+      :callback => 'str', # Only in combination with <:output => 'json'>.
+      :category_id => '123456', # See below.
+      :category_name => 'Wohnen', # See below.
+      :date_range => 'all', # '7'|'7-30'|'30-60'|'60-90'|'more90'
+      :filter => 'question', # 'best_answer'
+      :output => 'xml', # 'json'|'php'|'rss'
+      :query => 'Haus AND Grund',
+      :question_id => '123456',
+      :region => 'us',	# 'de'|'uk'|'ca'|'au'|'in'|'es'|'br'|
+      	      	 	# 'ar'|'mx'|'e1'|'it'|'fr'|'sg'
+      :results => 10, # 0..50 (0 returns the default value)
+      :search_in => "all", # "question" | "best_answer"
+      :sort => 'relevance', # 'date_desc'| 'date_asc'
+      :start => 0, # Now <= 1000, otherwise you'll get an empty response.
+      :type => 'all', # 'resolved'|'open'|'undecided'
+      :user_id => '123456'
+    },
+    :method => 'questionSearch', # 'getByUser'|'getByCategory'|'getQuestion'
+  }
+
 == SEARCH STRATEGIES
 This section will describe possible applications of YANAPI.
 
+=== Boolean Search
+
+
 == CHANGELOG
 See CHANGELOG.
 

data/lib/yanapi/api.rb

@@ -7,7 +7,9 @@ require 'yanapi/category_query'
 require 'yanapi/user_query'
 require 'yanapi/question_query'
 
+# The top namespace for the library.
 module YANAPI
+  
   class API
     REQUIRED_PARAMS = [:method, :query_params]
     ACCEPTED_METHODS = ['questionSearch',

data/lib/yanapi/common.rb

@@ -1,4 +1,6 @@
 module YANAPI
+  # This module is ment to be mixed into *Query classes to avoid duplication.
+  # It implements common parts for semantic checks.
   module Common
     private
     def basic_check(params)
@@ -8,7 +10,7 @@ module YANAPI
     def check_semantics(allowed, actual)
       actual.each_key do |param|
         unless allowed.include?(param.to_s)
-          raise Error, "The parameter #{param} is not allowed!"
+          raise UserError, "The parameter #{param} is not allowed!"
         end
       end
     end

data/lib/yanapi/error.rb

@@ -1,24 +1,17 @@
 module YANAPI
+  # YANAPI::Error is not used anywhere in the code.
+  # If you want to intercept all error from YANAPI, simply rescue this one.
   class Error < RuntimeError; end
 
-  # The result is illformed (as xml|json|php|rss) and cannot be parsed
-  # or contains an error message.
-  # Human beings should pay attention to it!
-  class ContentError < Error
-    # it takes a kind of Exception or String as the argument
-    def initialize(arg)
-      if arg.kind_of? String
-        msg = arg
-      else
-        msg = "You got illformed content:\n" +
-              "#{arg.message} (#{arg.class})"
-      end
-      super(msg)
-    end
+  # It is raised if the user has provided unvalid options.
+  # YANAPI intentionally does not handle any defaults,
+  # the user must correct the input hash.
+  class UserError < Error
   end
   
   # A technical error accessing the server,
-  # may be caught and handled with a new attempt.
+  # this error may be caught and handled with a new attempt.
+  # The services by Yahoo! are rather unstable and often unavailable.
   class ExternalError < Error
     def initialize(arg)
       msg = "Some external error occured:\n"
@@ -29,16 +22,24 @@ module YANAPI
       end
       super(msg)
     end
-  end
+  end  
 
-  # This kind of error is used, if there is no answer to our request.
-  # The status code is 200 OK and the xml structure is valid, but
-  # there is no useful information in the response.
-  # We can check this way if we have just placed a too strict request or
-  # we are out of the response range (but we are under the :start limitations).
-  class EmptyResponse < Error
+  # The result is illformed (as xml|json|php|rss) and cannot be parsed
+  # or contains an error message (humans should read it carefully).
+  # Yahoo! APIs are irregular concerning errors,
+  # not every input incorrectness results in a HTTP Error Code,
+  # but often in a normal response with an error message in the response body.
+  class ContentError < Error
+    # it takes a kind of Exception or String as the argument
+    def initialize(arg)
+      if arg.kind_of? String
+        msg = arg
+      else
+        msg = "You got illformed content:\n" +
+              "#{arg.message} (#{arg.class})"
+      end
+      super(msg)
+    end
   end
 
-  class UserError < Error
-  end
 end # YANAPI

data/lib/yanapi/query.rb

@@ -1,7 +1,9 @@
+# -*- coding: utf-8 -*-
 # This code is based on ideas from "rc_rest" and "yahoo" gems.
 require 'nokogiri'
 require 'net/http'
 require 'uri'
+require 'cgi'
 
 require 'yanapi/error'
 
@@ -89,17 +91,13 @@ module YANAPI
     end # check_params
     
     # It returns an URI::HTTP object containing the complete url for the request.
+    # Use <CGI>, not <URI>, the latter is somehow buggy.
     def build_url(params)
-      # URI does not know if our string contains special characters or not.
-      # That's why it treats them as special, we need a stricter form and
-      # provide a list of characters which should be escaped.
-      reserved_chars = Regexp.new(/[ !*'();:@&=+$,\/?#\]\[]/)
-
-
       expanded_params = expand_params(params) # It is an array now! 
       escaped_params = expanded_params.map do |k, v|
-        k = URI.escape(k.to_s, unsafe = reserved_chars)
-        v = URI.escape(v.to_s, unsafe = reserved_chars)
+        k = CGI.escape(k.to_s)
+        v = CGI.escape(v.to_s)
+        
         "#{k}=#{v}"
       end
       

data/lib/yanapi/term_query.rb

@@ -29,7 +29,7 @@ module YANAPI
     # validates uniqueness of query
     def check_params(params)
       unless params[:query]
-        raise Error, "Query is missing!"
+        raise UserError, "Query is missing!"
       end
 
       allowed = %w{query search_in category_id

data/lib/yanapi/version.rb

@@ -1,3 +1,3 @@
 module YANAPI
-  VERSION = '0.4.0'
+  VERSION = '0.4.1'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: yanapi
 version: !ruby/object:Gem::Version 
-  hash: 15
+  hash: 13
   prerelease: 
   segments: 
   - 0
   - 4
-  - 0
-  version: 0.4.0
+  - 1
+  version: 0.4.1
 platform: ruby
 authors: 
 - Andrei Beliankou
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-08-11 00:00:00 Z
+date: 2011-08-14 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: nokogiri