howcast 0.4.3 → 0.4.10

data/{History.txt → CHANGELOG}

@@ -1,3 +1,15 @@
+== 0.4.9 2009-08-19
+
+* require hpricot, update readme
+
+== 0.4.8 2009-08-19
+
+* Move gem to github, use echoe to clean up configuration, remove dependency on hpricot
+
+== 0.4.5 2009-07-27
+
+* Removed guide wrappers, Howcast API just has how-to's which merges old video and guides
+
 == 0.4.3 2009-03-02
 
 * Compatibility with ruby 1.9 - replacing dependency on hpricot with why-hpricot as github as the ruby 1.9 hpricot gem

data/Manifest

@@ -0,0 +1,19 @@
+CHANGELOG
+lib/howcast/client/base.rb
+lib/howcast/client/category.rb
+lib/howcast/client/search.rb
+lib/howcast/client/video.rb
+lib/howcast/client.rb
+lib/howcast/errors.rb
+lib/howcast.rb
+License.txt
+Manifest
+Rakefile
+README.markdown
+spec/howcast/client/base_spec.rb
+spec/howcast/client/category_spec.rb
+spec/howcast/client/search_spec.rb
+spec/howcast/client/video_spec.rb
+spec/spec.opts
+spec/spec_helper.rb
+tasks/github.rake

data/README.markdown

@@ -2,11 +2,11 @@
 
 Copyright (c) 2008 Howcast Media Inc.
 
-Author: Michael Murray <michael@howcast.com>
+Author: Jingshen Jimmy Zhang <jimmy@howcast.com>
 
 ## Installing
 	
-    sudo gem install howcast
+    sudo gem install howcast-howcast
   
 ## Example
 
@@ -20,14 +20,14 @@ Author: Michael Murray <michael@howcast.com>
       puts v.title
     end
 
-    puts "2nd Page of Recent Featured Videos"
-    # Will print out the video titles of the 2nd page of recent featured videos
-    hc.videos(:page => 2, :sort => "most_recent", :filter => "featured").each do |v|
+    puts "2nd Page of Top Rated Videos"
+    # Will print out the video titles of the 2nd page of top rated videos
+    hc.videos(:page => 2, :sort => "top_rated", :filter => "all").each do |v|
       puts v.title
     end
 
     puts "Videos matching 'origami'"
-    hc.video_search("origami").each do |v|
+    hc.search("origami").each do |v|
       puts v.title
     end
 

data/Rakefile

@@ -1,4 +1,32 @@
-require 'config/requirements'
-require 'config/hoe' # setup Hoe + all gem configuration
+require 'rubygems'
+require 'rake'
 
-Dir['tasks/**/*.rake'].each { |rake| load rake }
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "howcast"
+    gemspec.summary = "Howcast API Ruby Wrapper"
+    gemspec.description = <<-EOS
+    Howcast offers an Application Programming Interface (API) which allows
+    developers to build applications that interface with Howcast. The Howcast
+    API is RESTful (REpresentational State Transfer) and users of this API will
+    be able: 1) Retreive detailed information about a single video, including
+    metadata such as title, description, video views, rating etc; 2) Retrieve a
+    list of videos restricted by a set of filters offered by Howcast and sorted
+    using several metrics that you can specify (most recent, most views, etc);
+    3) Search for video; 4) And much more. Note: Before you can use our APIs,
+    you must register an API key, that is submitted with each request.
+    EOS
+    gemspec.email = "support@howcast.com"
+    gemspec.homepage = "http://github.com/howcast/howcast-gem"
+    gemspec.authors = ["Jingshen Jimmy Zhang", "Ian Smith-Heisters"]
+    gemspec.add_dependency "hpricot"
+    gemspec.add_development_dependency "rspec"
+    gemspec.files = FileList['**/*'].exclude('tmp/*', 'script/*', 'tags', 'pkg')
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
+end
+
+
+Dir["#{File.dirname(__FILE__)}/tasks/*.rake"].sort.each { |ext| load ext }

data/VERSION

@@ -0,0 +1 @@
+0.4.10

data/howcast.gemspec

@@ -0,0 +1,79 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{howcast}
+  s.version = "0.4.10"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Jingshen Jimmy Zhang", "Ian Smith-Heisters"]
+  s.date = %q{2010-01-04}
+  s.description = %q{    Howcast offers an Application Programming Interface (API) which allows
+    developers to build applications that interface with Howcast. The Howcast
+    API is RESTful (REpresentational State Transfer) and users of this API will
+    be able: 1) Retreive detailed information about a single video, including
+    metadata such as title, description, video views, rating etc; 2) Retrieve a
+    list of videos restricted by a set of filters offered by Howcast and sorted
+    using several metrics that you can specify (most recent, most views, etc);
+    3) Search for video; 4) And much more. Note: Before you can use our APIs,
+    you must register an API key, that is submitted with each request.
+}
+  s.email = %q{support@howcast.com}
+  s.extra_rdoc_files = [
+    "README.markdown"
+  ]
+  s.files = [
+    "CHANGELOG",
+     "License.txt",
+     "Manifest",
+     "README.markdown",
+     "Rakefile",
+     "VERSION",
+     "howcast.gemspec",
+     "lib/howcast.rb",
+     "lib/howcast/client.rb",
+     "lib/howcast/client/base.rb",
+     "lib/howcast/client/category.rb",
+     "lib/howcast/client/search.rb",
+     "lib/howcast/client/video.rb",
+     "lib/howcast/errors.rb",
+     "spec/howcast/client/base_spec.rb",
+     "spec/howcast/client/category_spec.rb",
+     "spec/howcast/client/search_spec.rb",
+     "spec/howcast/client/video_spec.rb",
+     "spec/spec.opts",
+     "spec/spec_helper.rb",
+     "tasks/github.rake"
+  ]
+  s.homepage = %q{http://github.com/howcast/howcast-gem}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Howcast API Ruby Wrapper}
+  s.test_files = [
+    "spec/howcast/client/base_spec.rb",
+     "spec/howcast/client/category_spec.rb",
+     "spec/howcast/client/search_spec.rb",
+     "spec/howcast/client/video_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<hpricot>, [">= 0"])
+      s.add_development_dependency(%q<rspec>, [">= 0"])
+    else
+      s.add_dependency(%q<hpricot>, [">= 0"])
+      s.add_dependency(%q<rspec>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<hpricot>, [">= 0"])
+    s.add_dependency(%q<rspec>, [">= 0"])
+  end
+end
+

data/lib/howcast.rb

@@ -4,6 +4,5 @@ def require_local(suffix)
   require(File.expand_path(File.join(File.dirname(__FILE__), suffix)))
 end
 
-require_local('howcast/version')
 require_local('howcast/client')
 require_local('howcast/errors')

data/lib/howcast/client.rb

@@ -4,6 +4,5 @@ end
 
 require_local('howcast/client/base.rb')
 require_local('howcast/client/video.rb')
-require_local('howcast/client/guide.rb')
 require_local('howcast/client/search.rb')
 require_local('howcast/client/category.rb')

data/lib/howcast/client/base.rb

@@ -24,6 +24,7 @@
 require 'rubygems'
 require 'hpricot'
 require 'open-uri'
+require 'uri'
 
 class Howcast::Client
   attr_accessor :key
@@ -43,7 +44,21 @@ class Howcast::Client
     raise Howcast::ApiKeyNotFound if options[:key].nil?
     @key = options[:key]
   end
-  
+
+  class << self
+    def base_uri= new_base_uri
+      @base_uri = case new_base_uri
+      when URI      then new_base_uri
+      when String   then URI.parse new_base_uri
+      when Hash     then URI::HTTP.build new_base_uri
+      else;         raise ArgumentError, "can't convert URI: #{new_base_uri.inspect}"
+      end
+    end
+
+    def base_uri
+      @base_uri ||= URI.parse("http://www.howcast.com")
+    end
+  end
   protected
     # Establishes a connection with the Howcast API. Will auto append the api key, that was used
     # to instantiate the Client object, to the URL
@@ -65,8 +80,11 @@ class Howcast::Client
     #
     # Get the Hpricot data for most recent howcast studios videos
     #   establish_connection("videos/most_recent/howcast_studios.xml") 
-    def establish_connection(relative_path)
-      h = Hpricot.XML(open(url = attach_api_key("http://www.howcast.com/#{relative_path}")))
+    def establish_connection(relative_path_and_query)
+      uri = self.class.base_uri.dup
+      relative_path_and_query = '/' + relative_path_and_query unless relative_path_and_query[0] == '/'
+      uri.path, uri.query = *relative_path_and_query.split('?')
+      h = Hpricot.XML(open(url = attach_api_key(uri)))
       puts "Established connection with: '#{url}'"
       raise Howcast::ApiKeyNotFound if h.at(:error) && h.at(:error).inner_html.match(/Invalid API Key/)
       return h
@@ -79,10 +97,10 @@ class Howcast::Client
     # === Inputs
     #
     # * <tt>xml</tt> -- See below for a sample xml input
-    # * <tt>klass</tt> -- Class to create - Guide | Video | Category supported
+    # * <tt>klass</tt> -- Class to create - Video | Category supported
     #
     # Sample input xml
-    #   <guide>
+    #   <video>
     #      <id>1086</id>
     #      <rating>96</rating>
     #      <title>How To Choose a Paintbrush</title>
@@ -94,7 +112,7 @@ class Howcast::Client
     #      <permalink>http://www.howcast.com/guides/1086-How-To-Choose-a-Paintbrush</permalink>
     #      <username>michaelrsanchez</username>
     #      <created-at>Thu, 20 Dec 2007 14:14:58 -0800</created-at>
-    #    </guide>
+    #    </video>
     #
     # === Outputs 
     # 
@@ -130,25 +148,55 @@ class Howcast::Client
       opts && opts[:page] ? "#{opts[:use_ampersand] ? '&' : '?'}page=#{opts[:page]}" : ""
     end
     
-    # Appends the api key to a url and returns the appended url
+    # Appends the api key to a uri and returns the appended uri
     # 
     # === Inputs
     # 
-    # * <tt>url</tt> -- the url to append the api_key to
+    # * <tt>uri</tt> -- the URI object to append the api_key to
     #
     # === Outputs
     #
-    # The url with the api_key appended
+    # The uri with the api_key appended to the query string
     #
     # === Examples
     #
-    #   attach_api_key("http://www.howcast.com")
+    #   attach_api_key(URI.parse("http://www.howcast.com")).to_s
     #   => "http://www.howcast.com?api_key=APIKEYHERE"
     #   
-    #   attach_api_key("http://www.howcast.com/videos/most_recent/all?page=2")
+    #   attach_api_key(URI.parse("http://www.howcast.com/videos/most_recent/all?page=2")).to_s
     #   => "http://www.howcast.com/videos/most_recent/all?page=2&api_key=APIKEYHERE"
-    def attach_api_key(url)
-      url.match(/\?/) ? "#{url}&api_key=#{self.key}" : "#{url}?api_key=#{self.key}"
+    def attach_api_key(uri)
+      uri = uri.dup
+      key = "api_key=#{self.key}"
+      uri.query = uri.query.to_s.strip != "" ? uri.query+"&"+key : key
+      uri
+    end
+
+    # From merb/core_ext/hash.rb, line 87
+    def hash_to_params hash
+      params = ''
+      stack = []
+
+      hash.each do |k, v|
+        if v.is_a?(Hash)
+          stack << [k,v]
+        else
+          params << "#{k}=#{v}&"
+        end
+      end
+
+      stack.each do |parent, h|
+        h.each do |k, v|
+          if v.is_a?(Hash)
+            stack << ["#{parent}[#{k}]", v]
+          else
+            params << "#{parent}[#{k}]=#{v}&"
+          end
+        end
+      end
+
+      params.chop! # trailing &
+      params
     end
 end
 

data/lib/howcast/client/search.rb

@@ -25,13 +25,15 @@ require 'cgi'
 
 class Howcast::Client
   # Provides access to the Howcast video search API.
-  # 
+  #
   # === Inputs
   #
-  # * <tt>query</tt> -- The string query which you want to search for 
-  # The options are:
-  # * <tt>:page</tt> -- The page number to retrieve (defaults to 1). There are 10 videos per page.
-  # * <tt>:mode</tt> -- Mode to search, using :extended will allow title:something searches
+  # * <tt>query</tt> -- The string query which you want to search for
+  #   The options are:
+  # ** <tt>:page</tt> -- The page number to retrieve (defaults to 1). There are
+  #    10 videos per page.
+  # ** <tt>:mode</tt> -- Mode to search, using :extended will allow
+  #    title:something searches
   #
   # === Outputs
   #
@@ -39,43 +41,46 @@ class Howcast::Client
   #
   # === Exceptions
   #
-  # * <tt>Howcast::ApiNotFound</tt> -- raised if the requested sort and filter is malformed or not available (404)
-  # * <tt>ArgumentError</tt> -- raised when the required 1 argument isn't supplied
+  # * <tt>Howcast::ApiNotFound</tt> -- raised if the requested sort and filter
+  #   is malformed or not available (404)
+  # * <tt>ArgumentError</tt> -- raised when the required 1 argument isn't
+  #   supplied
   #
   # === Examples
   #
-  # Get the first page of howcast videos matching 'poker'.  
+  # Get the first page of howcast videos matching 'poker'.
   #   Howcast::Client.new.video_search("poker")
   # Get the third page of howcast videos matching 'traveling'
   #   Howcast::Client.new.video_search("traveling", :page => 3)
-	def video_search(query, options = {})
-    uri = search_url(query, options.merge(:view => 'video'))
-    (establish_connection(uri)/:video).inject([]){ |r, i| r << parse_single_xml(i, Video)}
+  def search(query, options = {})
+    defaults = {:view => "videos", :q => query}
+    params = defaults.merge options
+    do_search params
   end
-  
-  # Provides access to the Howcast wiki guide search API.
-  # 
-  # See video_search documentation for inputs, outputs and exceptions
+
+  # Provides low-level access to the Howcast video search API.
   #
-  # === Examples
+  # === Inputs
   #
-  # Get the first page of howcast wiki guides matching 'poker'.  
-  #   Howcast::Client.new.guide_search("poker")
-  # Get the third page of howcast wiki guides matching 'traveling'
-  #   Howcast::Client.new.guide_search("traveling", :page => 3)
-	def guide_search(query, options = {})
-    uri = search_url(query, options.merge(:view => 'guide'))
-    (establish_connection(uri)/:guide).inject([]){ |r, i| r << parse_single_xml(i, Guide) }
+  # * <tt>params</tt> -- A hash of params that will be URL encoded and appended
+  #   to the URI. You'll have to know what you're doing.
+  #
+  # Other than its arguments, this method is identical to +search+.
+  def advanced_search params
+    do_search params
   end
-  	
-	private
-  	def search_url(query, options={})
-      defaults = {:page => nil, :view => nil, :mode => nil}
-      options = defaults.update(options)
-      query = CGI.escape(query)
-      uri = "search.xml?q=#{query}"
-      uri += "&view=#{options[:view]}" unless options[:view].nil?
-      uri += "&mode=extended" if (options[:mode] == :extended)
-      uri + uri_suffix(options.merge(:use_ampersand => true))
+
+  private
+    def do_search params
+      uri = search_url params
+      (establish_connection(uri)/:video).inject([]){ |r, i| r << parse_single_xml(i, Video)}
+    end
+
+    def search_url params
+      uri = "search.xml?"
+      params[:q] = CGI.escape params[:q] if params[:q]
+      uri += hash_to_params params
+      uri += uri_suffix(params.merge(:use_ampersand => true)) unless params[:page]
+      uri
     end
 end

data/lib/howcast/client/video.rb

@@ -90,9 +90,9 @@ class Howcast::Client
   # === Inputs
   #
   # The options are:
-  # * <tt>:page</tt> -- The page number to retrieve (defaults to 1). There are 16 videos per page.
-  # * <tt>:sort</tt> -- One of +most_recent+ (default) | +most_viewed+ | +top_rated+ | +most_emailed+ | +most_discussed+ | +top_favorites+
-  # * <tt>:filter</tt> -- One of +all+ | +featured+ | +howcast_studios+ (default) | +directors_program+ | +community+
+  # * <tt>:page</tt> -- The page number to retrieve (defaults to 1). There are 20 videos per page.
+  # * <tt>:sort</tt> -- One of +most_recent+ (default) | +most_viewed+ | +top_rated+
+  # * <tt>:filter</tt> -- One of +all+ | +howcast_studios+ (default)
   #
   # === Outputs
   # An array of video objects
@@ -105,7 +105,7 @@ class Howcast::Client
   # Get the first page of most recent howcast studios videos.  
   #   Howcast::Client.new.videos
   # Get the third page of top favorites which are featured
-  #   Howcast::Client.new.videos(:page => 3, :sort => "top_favorites", :filter => "featured")
+  #   Howcast::Client.new.videos(:page => 3, :sort => "top_favorites", :filter => "top_rated")
 	def videos(options = {})
     uri = videos_url(options)
     (establish_connection(uri)/:video).inject([]){ |r, i| r << parse_single_xml(i, Video)}