pablobm-bossman 0.1.2.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Jay Pignata
+
+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

@@ -0,0 +1,176 @@
+= BOSSMan -- Gem for interaction with the Yahoo BOSS web service
+
+== Description
+
+BOSSMan can be used to perform image, web and news searches against Yahoo's index. For more information about BOSS (Build your Own Search Service) please refer to http://developer.yahoo.com/search/boss/. 
+
+== Bugs, Features, Feedback
+
+Feedback would be really appreciated. You can send it to me at john.pignata@gmail.com -- tickets can
+be submitted by using Lighthouse: http://pignata.lighthouseapp.com/projects/15761-bossman
+
+== Example Usage
+
+=== Web
+
+	require 'rubygems'
+	require 'bossman'
+	include BOSSMan
+
+	BOSSMan.application_id = <Your Application ID>
+
+	boss = BOSSMan::Search.web("prospect park", { :count => 5, :filter => "-hate" })
+
+	puts "Number of results: #{boss.totalhits}"
+	puts
+
+	boss.results.each do |result|
+	  puts "#{result.title}"
+	  puts "-" * 80
+	  puts "#{result.abstract}"
+	  puts
+	end
+
+=== News
+
+	require 'rubygems'
+	require 'bossman'
+	include BOSSMan
+
+	BOSSMan.application_id = <Your Application ID>
+
+	boss = BOSSMan::Search.news("brooklyn new york", { :age => "7d" })
+
+	boss.results.each do |result|
+	  puts "#{result.title} [from #{result.source}]"
+	  puts "-" * 80
+	  puts "#{result.abstract}"
+	  puts
+		
+=== Images
+
+	require 'rubygems'
+	require 'bossman'
+	include BOSSMan
+
+	BOSSMan.application_id = <Your Application ID>
+
+	boss = BOSSMan::Search.images("brooklyn dumbo", { :dimensions => "large" })
+
+	boss.results.each do |result|
+	  puts "#{result.url}: #{result.abstract}"
+	end
+	
+=== Spelling
+
+	require 'rubygems'
+	require 'bossman'
+	include BOSSMan
+	
+	BOSSMan.application_id = <Your Application ID>
+	
+	boss = BOSSMan::Search.spelling("Diabretes")
+	
+	puts boss.suggestion
+	
+== Output Objects
+
+Assuming an object bossed called search:
+
+search = BOSSMan::Search.web("staten island", 0, 20)
+
+=== Common
+
+search.responsecode				: HTTP response code
+search.nextpage					: REST URL to next page of search results
+search.count					: Number of search results contained in response
+search.start					: Search result from which output starts
+search.totalhits				: De-duplicated total number of results search yielded
+search.deephits					: Total number of results search yielded
+search.results[].clickurl		: Tracking URL of result; must be used in user-facing
+										anchor tags by BOSS TOU
+search.results[].url			: URL of result
+
+=== Web
+
+search.results[].abstract		: Description of result with keywords emboldened
+search.results[].title			: Document title with keywords emboldened
+search.results[].dispurl		: Display URL of result
+search.results[].size			: Size of result in bytes
+search.results[].date			: Date result was indexed
+
+=== News
+
+search.results[].abstract		: Description of news story
+search.results[].title			: Title of news story
+search.results[].language		: Language of news story
+search.results[].date			: Last publication date of news story
+search.results[].time			: Last publication time of news story
+search.results[].source			: Source of news story
+search.results[].sourceurl		: URL of source publication
+
+=== Images
+
+search.results[].abstract			: Description of image
+search.results[].filename			: Filename of image
+search.results[].size				: Size of image
+search.results[].format				: Format of image
+search.results[].height				: Height of full-size image
+search.results[].date				: Last modification date of image (YYYY/MM/DD)
+search.results[].mimetype			: MIME type of image
+search.results[].refererclickurl	: Link to page where image was found
+search.results[].refererurl 		: Link to page where image was found
+search.results[].title				: Title of image (usually the filename)
+search.results[].width				: Width of full-size image
+search.results[].thumbnailurl		: URL of thumbnail image
+search.results[].thumbnail_height	: Height of thumbnail image
+search.results[].thumbnail_width    : Width of thumbnail image
+
+=== Spelling
+
+search.suggestion					: Returns spelling suggestion from BOSS
+
+=== Raw dump formats
+
+Resultsets are returnable in JSON, XML and YAML by use of to_json, to_xml (or to_s), to_yaml respectively.
+
+search			 			: dumps XML of entire resultset
+search.to_json	 			: dumps JSON of entire resultset
+search.to_yaml				: dumps YAML of entire resultset
+search.results[3]			: dumps XML of one search result
+search.results[3].to_json	: dumps JSON of one search result
+search.results[3].to_yaml	: dumps YAML of one search result
+
+== Installation
+
+   jp@populuxe:~/code/ruby$ gem sources -a http://gems.github.com
+   jp@populuxe:~/code/ruby$ gem install jpignata-bossman
+
+== Requirements
+
+* Active Support >= 2.1
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Jay Pignata
+
+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/bossman.gemspec

@@ -0,0 +1,14 @@
+Gem::Specification.new do |s|
+  s.name = "bossman"
+  s.version = "0.1.2.1"
+  s.date = "2008-08-28"
+  s.summary = "Class for interaction with the Yahoo BOSS web service."
+  s.email = "jpignata@waterfrontmedia.com"
+  s.homepage = "http://github.com/jpignata/bossman-gem"
+  s.authors = ["Jay Pignata"]
+  s.files = ['bossman.gemspec', 'lib/bossman.rb', 'lib/bossman/basevalueobject.rb', 
+    'lib/bossman/rest.rb', 'lib/bossman/result.rb', 'lib/bossman/resultset.rb', 
+    'lib/bossman/search.rb', 'README', 'LICENSE']
+  s.add_dependency("activesupport", [">= 2.1.0"])
+  s.has_rdoc = false
+end

data/lib/bossman.rb

@@ -0,0 +1,18 @@
+require 'rubygems'
+require 'active_support'
+
+Dir["#{File.dirname(__FILE__)}/bossman/*.rb"].sort.each { |bossman_lib| require bossman_lib }
+
+module BOSSMan
+  API_VERSION = :v1
+  API_BASEURI = "http://boss.yahooapis.com/ysearch"
+  
+  %w( application_id proxy_host proxy_port proxy_user proxy_pass ).each do |att|
+    attr_accessor att.to_sym
+    module_function att.to_sym, "#{att}=".to_sym
+  end
+
+  class MissingConfiguration < StandardError; end
+  class InvalidParameter < StandardError; end
+  class BOSSError < StandardError; end
+end

data/lib/bossman/basevalueobject.rb

@@ -0,0 +1,19 @@
+module BOSSMan
+  class BaseValueObject
+
+      def set_parameter(key, value)
+        value = value.gsub(/\\u(\d+)/, '&#x\1;') if value.kind_of? String
+        instance_variable_set("@#{key}", value) 
+        instance_eval("def #{key}; @#{key}; end")
+      end
+      
+      def to_yaml
+        @response.to_yaml
+      end
+
+      def to_json
+        ActiveSupport::JSON.encode(@response)
+      end
+      
+  end 
+end

data/lib/bossman/rest.rb

@@ -0,0 +1,41 @@
+require 'net/http'
+require 'uri'
+
+module BOSSMan
+  class REST
+        
+    def self.get(method, query, options)
+      validate_parameters(options)
+      uri = URI.parse(URI.encode("#{API_BASEURI}/#{method}/#{API_VERSION}/#{query}"))
+      uri.query = options.to_query
+      request = Net::HTTP::Get.new(uri.request_uri)
+      response = Net::HTTP.new(uri.host).request(request)
+
+      case response
+        when Net::HTTPSuccess
+          return ResultSet.new(ActiveSupport::JSON.decode(response.body))
+        else
+          raise BOSSError, parse_error(response.body)
+      end 
+    end  
+    
+    def self.parse_error(response_string)
+      response_document = REXML::Document.new(response_string)
+      error_code = REXML::XPath.first(response_document, '//yahoo:code').text
+      error_description = REXML::XPath.first(response_document, '//yahoo:description').text
+      error_detail = REXML::XPath.first(response_document, '//yahoo:detail').text
+      return "#{error_code} #{error_description}: #{error_detail}"
+    end        
+    
+    def self.validate_parameters(options) 
+      unless BOSSMan.application_id
+        raise MissingConfiguration, "Application ID must be set prior to making a service call."
+      end
+
+      unless options[:count] > 0
+        raise InvalidParameter, "Invalid count. Count must be > 0." 
+      end
+    end
+  
+  end
+end

data/lib/bossman/result.rb

@@ -0,0 +1,15 @@
+module BOSSMan
+  class Result < BaseValueObject
+
+    def initialize(response)
+      @response = response
+      response.each { |key, value| set_parameter(key, value) }
+    end
+
+    def to_xml
+      @response.to_xml(:root => 'result')
+    end
+
+    alias to_s to_xml
+  end
+end

data/lib/bossman/resultset.rb

@@ -0,0 +1,42 @@
+module BOSSMan
+  class ResultSet < BaseValueObject
+    
+    def initialize(response)
+      @response = response
+
+      @response["ysearchresponse"].each do |key, value|
+        if key.include? "resultset_spell"
+          set_parameter("suggestion", @response["ysearchresponse"]["resultset_spell"][0]["suggestion"])
+        elsif key.include? "resultset"
+          results = Array.new
+          response["ysearchresponse"][key].each { |result| 
+            begin
+              result = Result.new(result) 
+            rescue
+              next
+            else
+              results << result
+            end
+          }
+          set_parameter("results", results)
+        else
+          set_parameter(key, value)
+        end        
+      end
+    end
+              
+    def to_xml
+      @response['ysearchresponse'].to_xml(:root => 'resultset')
+    end
+    
+    def _dump(level)
+      @response.to_json
+    end
+    
+    def self._load(string)
+      ResultSet.new(ActiveSupport::JSON.decode(string))
+    end
+    
+    alias to_s to_xml
+  end  
+end

data/lib/bossman/search.rb

@@ -0,0 +1,40 @@
+module BOSSMan
+  class Search 
+    class << self
+      DEFAULT_COUNT = 10
+      DEFAULT_START = 0
+      
+      def web(query, options = {})    
+        method = "web"
+        options.merge!(return_options(options))
+        return REST.get(method, query, options)
+      end
+
+      def images(query, options = {})
+        method = "images"
+        options.merge!(return_options(options))        
+        return REST.get(method, query, options)
+      end
+
+      def news(query, options = {})
+        method = "news"
+        options.merge!(return_options(options))
+        return REST.get(method, query, options)
+      end
+
+      def spelling(query, options = {})
+        method = "spelling"
+        options.merge!(return_options(options))
+        return REST.get(method, query, options)
+      end
+      
+      private
+      def return_options(options)
+        count = options[:count] ? options[:count] : DEFAULT_COUNT
+        start = options[:start] ? options[:start] : DEFAULT_START
+        return {:appid => BOSSMan.application_id, :count => count, :start => start }
+      end
+
+    end
+  end
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification 
+name: pablobm-bossman
+version: !ruby/object:Gem::Version 
+  version: 0.1.2.1
+platform: ruby
+authors: 
+- Jay Pignata
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-08-28 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.1.0
+    version: 
+description: 
+email: jpignata@waterfrontmedia.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- bossman.gemspec
+- lib/bossman.rb
+- lib/bossman/basevalueobject.rb
+- lib/bossman/rest.rb
+- lib/bossman/result.rb
+- lib/bossman/resultset.rb
+- lib/bossman/search.rb
+- README
+- LICENSE
+has_rdoc: false
+homepage: http://github.com/jpignata/bossman-gem
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Class for interaction with the Yahoo BOSS web service.
+test_files: []
+