howcast-howcast 0.4.7

data/CHANGELOG

@@ -0,0 +1,60 @@
+== 0.4.7 2009-8-19
+
+* Bump the version number so github will build this
+
+== 0.4.6 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
+
+== 0.4.2 2009-02-04
+
+* Adding embed code to video object
+
+== 0.4.1 2008-11-05
+
+* Support for finding a category ancestor trail from a category object
+
+== 0.4 2008-11-02
+
+* Add support for the new category API to get the name and parent ID
+* Added badges and easy_steps methods for video
+
+== 0.3.4 2008-08-21
+
+* Support for new paging scheme in browse pages - ?page=1 => /1
+
+== 0.3.3 2008-07-25
+
+* Video dimensions
+
+== 0.3.2 2008-06-03
+
+* Clean up with inject
+
+== 0.3.1 2008-04-08
+
+* Ability to search in extended mode
+
+== 0.3 2008-03-27
+
+* API Key support
+
+== 0.2 2008-03-11
+
+* Support for WikiGuide API - list and search
+
+== 0.1.1 2008-03-04
+
+* Minor bug fixes and documentation
+
+== 0.1.0 2008-02-19
+
+* Initial release

data/License.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Howcast Media Inc.
+
+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/Manifest

@@ -0,0 +1,20 @@
+CHANGELOG
+howcast.gemspec
+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

@@ -0,0 +1,46 @@
+# Howcast API Ruby Wrapper
+
+Copyright (c) 2008 Howcast Media Inc.
+
+Author: Jingshen Jimmy Zhang <jimmy@howcast.com>
+
+## Installing
+	
+    sudo gem install howcast
+  
+## Example
+
+    require 'rubygems'
+    require 'howcast'
+
+    hc = Howcast::Client.new(:key => "INSERT API KEY HERE")
+    # Will print out the video titles of the first page of recent howcast studios videos
+    puts "Recent Howcast Studios Videos"
+    hc.videos.each do |v|
+      puts v.title
+    end
+
+    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.search("origami").each do |v|
+      puts v.title
+    end
+
+    puts "Video with id 946"
+    puts hc.video(946).title
+  
+    # Category API
+    piano = hc.category(1105)
+    puts "The parent category of Piano is #{hc.category(piano.parent_id).name}"
+  
+    ancestors = piano.parents.map{|c| c[:name]}
+    # Ancestors will be an array of hash metadata: 
+    # => [{:name=>"Performing Arts", :id=>"1048"}, 
+    #     {:name=>"Musical Instruments", :id=>"1095"}, 
+    #     {:name=>"Keyboards", :id=>"1103"}]
+    puts "The ancestors of piano are: #{ancestors.join(" -> ")}"

data/Rakefile

@@ -0,0 +1,17 @@
+require 'rubygems'
+require 'rake'
+require 'echoe'
+
+Echoe.new('howcast', '0.4.7') do |x|
+  x.summary = "Howcast API Ruby Wrapper"
+  x.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
+  x.url = "http://github.com/howcast/howcast-gem"
+  x.author = "Jingshen Jimmy Zhang"
+  x.email = "jimmy@howcast.com"
+  x.ignore_pattern = ["tmp/*", "script/*"]
+  x.development_dependencies = []
+end
+
+Dir["#{File.dirname(__FILE__)}/tasks/*.rake"].sort.each { |ext| load ext }

data/howcast.gemspec

@@ -0,0 +1,31 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{howcast}
+  s.version = "0.4.7"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Jingshen Jimmy Zhang"]
+  s.date = %q{2009-08-19}
+  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{jimmy@howcast.com}
+  s.extra_rdoc_files = ["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", "README.markdown", "tasks/github.rake"]
+  s.files = ["CHANGELOG", "howcast.gemspec", "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"]
+  s.homepage = %q{http://github.com/howcast/howcast-gem}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Howcast", "--main", "README.markdown"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{howcast}
+  s.rubygems_version = %q{1.3.4}
+  s.summary = %q{Howcast API Ruby Wrapper}
+
+  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
+    else
+    end
+  else
+  end
+end

data/lib/howcast.rb

@@ -0,0 +1,8 @@
+module Howcast; end
+
+def require_local(suffix)
+  require(File.expand_path(File.join(File.dirname(__FILE__), suffix)))
+end
+
+require_local('howcast/client')
+require_local('howcast/errors')

data/lib/howcast/client.rb

@@ -0,0 +1,8 @@
+# Used to query the Howcast REST API.
+class Howcast::Client
+end
+
+require_local('howcast/client/base.rb')
+require_local('howcast/client/video.rb')
+require_local('howcast/client/search.rb')
+require_local('howcast/client/category.rb')

data/lib/howcast/client/base.rb

@@ -0,0 +1,154 @@
+#--
+# Copyright (c) 2008 Howcast Media Inc.
+#
+# 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.
+#++
+
+require 'rubygems'
+require 'hpricot'
+require 'open-uri'
+
+class Howcast::Client
+  attr_accessor :key
+  
+  # Creates a new howcast client to interact with the Howcast API
+  #
+  # === Inputs
+  #
+  # Options include:
+  #
+  # * <tt>key</tt> -- REQUIRED - API key: obtainable from http://www.howcast.com/api_keys/new
+  #
+  # === Exceptions
+  #
+  # * <tt>Howcast::ApiKeyNotFound</tt> -- raised if the options[:key] value is nil
+  def initialize(options={})
+    raise Howcast::ApiKeyNotFound if options[:key].nil?
+    @key = options[:key]
+  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
+    #
+    # === Inputs
+    #
+    # * <tt>relative_path</tt> -- should be the path after <tt>http://www.howcast.com/</tt>
+    #
+    # === Outputs
+    # 
+    # Hpricot object encapsulating the xml returned from the Howcast API
+    #
+    # === Exceptions
+    # 
+    # * <tt>Howcast::ApiNotFound</tt> -- raised if the requested +relative_path+ is malformed or not available (404)
+    # * <tt>Howcast::ApiKeyNotFound</tt> -- raised if the +api_key+ is invalid
+    #
+    # === Examples
+    #
+    # 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}")))
+      puts "Established connection with: '#{url}'"
+      raise Howcast::ApiKeyNotFound if h.at(:error) && h.at(:error).inner_html.match(/Invalid API Key/)
+      return h
+    rescue URI::InvalidURIError, OpenURI::HTTPError
+      raise Howcast::ApiNotFound.new("Invalid URL requested. Refer to the Howcast API for supported URL's")
+    end
+    
+    # Parses the xml for a single item from +xml+ and creates a new +klass+ object
+    #
+    # === Inputs
+    #
+    # * <tt>xml</tt> -- See below for a sample xml input
+    # * <tt>klass</tt> -- Class to create - Video | Category supported
+    #
+    # Sample input xml
+    #   <video>
+    #      <id>1086</id>
+    #      <rating>96</rating>
+    #      <title>How To Choose a Paintbrush</title>
+    #      <category-id>19</category-id>
+    #      <description>
+    #         <![CDATA[Yes, you could just use your fingers, but selecting the best brushes for your painting might achieve a slightly more grown-up result.]]>
+    #      </description>
+    #      <views>362</views>
+    #      <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>
+    #    </video>
+    #
+    # === Outputs 
+    # 
+    # +klass+ object with initialized attributes
+    def parse_single_xml(xml, klass)
+      hash = {}
+      klass.attr_accessors.each do |attribute|
+        node_name = attribute.to_s.gsub("_", "-") # xml schema uses hyphens for spaces, but ruby uses underscores
+        hash[attribute] = !xml.at(node_name).nil? ? xml.at(node_name).inner_text.strip : ""
+      end
+      hash.values.all?{|v| v==""} ? nil : klass.new(hash)
+    end
+      
+    # Creates parameters to append to a uri
+    # 
+    # === Inputs
+    # 
+    # Options are:
+    # * <tt>:page</tt> -- the page number
+    # * <tt>:use_ampersand</tt> -- boolean to return ampersand (defaults to false)
+    #
+    # === Outputs
+    #
+    # A valid suffix string to append to the end of a url
+    #
+    # === Examples
+    #
+    # "?page=2"
+    #   uri_suffix(:page => 2)
+    # "&page=2"
+    #   uri_suffix(:page => 3, :use_ampersand => true)
+    def uri_suffix(opts)
+      opts && opts[:page] ? "#{opts[:use_ampersand] ? '&' : '?'}page=#{opts[:page]}" : ""
+    end
+    
+    # Appends the api key to a url and returns the appended url
+    # 
+    # === Inputs
+    # 
+    # * <tt>url</tt> -- the url to append the api_key to
+    #
+    # === Outputs
+    #
+    # The url with the api_key appended
+    #
+    # === Examples
+    #
+    #   attach_api_key("http://www.howcast.com")
+    #   => "http://www.howcast.com?api_key=APIKEYHERE"
+    #   
+    #   attach_api_key("http://www.howcast.com/videos/most_recent/all?page=2")
+    #   => "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}"
+    end
+end
+

data/lib/howcast/client/category.rb

@@ -0,0 +1,85 @@
+#--
+# Copyright (c) 2008 Howcast Media Inc.
+#
+# 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.
+#++
+
+class Howcast::Client
+  class Category
+    extend WatchAttrAccessors
+    attr_accessor :id, :name, :parent_id, :parents
+    
+    # Creates a new Category object which is used to encapsulate all the attributes available
+    # from the Howcast Category API. The parents attribute will be an array of category 
+    # ancestors of the form:
+    #   [{:id => 1, :name => 'root'}, {:id => 2, :name => 'immediate parent'}]
+    #
+    # === Inputs
+    #
+    # * <tt>attributes</tt> -- A hash to set the various attributes of the category object
+    #
+    # === Examples
+    # 
+    # Initialize a category with name "Arts & Crafts"
+    #   Category.new :name => "Arts & Crafts"
+    def initialize(attributes={})
+      attributes.each do |k, v|
+        self.send("#{k}=", v) if self.respond_to?(k)
+      end
+    end
+  end
+    
+  # Provides access to the Howcast category API.
+  # 
+  # === Inputs
+  #
+  # * <tt>id</tt> -- The id of the category to lookup
+  #
+  # === Outputs
+  # 
+  # Category object if the id exists or nil if the id doesn't exist or is malformed
+  #
+  # === Exceptions
+  # 
+  # * <tt>Howcast::ApiNotFound</tt>
+  #
+  # === Examples
+  # 
+  # Get the Howcast category with id 2
+  #   Howcast::Client.new.category(2)
+  def category(id)
+    response = establish_connection("categories/#{id}.xml")
+    parse_single_category_xml(response.at(:category))
+  end
+  
+  private
+    # Exception here to parse the <parents> tag in a category, will set a category.parents variable
+    # which is an array of parent metadata hases
+    # [{:id => '123', :name => "root"}, {:id => "1234", :name => "parent"}]
+    def parse_single_category_xml(xml)
+      hash = {}
+      Category.attr_accessors.each do |attribute|
+        node_name = attribute.to_s.gsub("_", "-") # xml schema uses hyphens for spaces, but ruby uses underscores
+        hash[attribute] = !xml.at(node_name).nil? ? xml.at(node_name).inner_text.strip : ""
+      end
+      hash[:parents] = (xml.at('parents')/:category).map{ |c| {:id => c['id'], :name => c.inner_html }}
+      hash.values.all?{|v| v==""} ? nil : Category.new(hash)
+    end
+end

data/lib/howcast/client/search.rb

@@ -0,0 +1,66 @@
+#--
+# Copyright (c) 2008 Howcast Media Inc.
+#
+# 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.
+#++
+
+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
+  #
+  # === Outputs
+  #
+  # An array of video objects
+  #
+  # === 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
+  #
+  # === Examples
+  #
+  # 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 search(query, options = {})
+    uri = search_url(query, options)
+    (establish_connection(uri)/:video).inject([]){ |r, i| r << parse_single_xml(i, Video)}
+  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=videos"
+      uri += "&mode=extended" if (options[:mode] == :extended)
+      uri + uri_suffix(options.merge(:use_ampersand => true))
+    end
+end

data/lib/howcast/client/video.rb

@@ -0,0 +1,120 @@
+#--
+# Copyright (c) 2008 Howcast Media Inc.
+#
+# 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.
+#++
+
+class Howcast::Client
+  module WatchAttrAccessors
+    def attr_accessor(*args)
+      super(*args)
+      @attr_accessors ||= []
+      @attr_accessors += args
+    end
+  
+    def attr_accessors
+      @attr_accessors || []
+    end
+  end
+  
+  class Video
+    extend WatchAttrAccessors
+    attr_accessor :id, :title, :permalink, :thumbnail_url, :category_id, 
+      :views, :username, :duration, :created_at, :rating, :description, :width, :height,
+      :badges, :easy_steps, :embed
+    # Creates a new Video object which is used to encapsulate all the attributes available
+    # from the Howcast Video API
+    #
+    # === Inputs
+    #
+    # * <tt>attributes</tt> -- A hash to set the various attributes of the video object
+    #
+    # === Examples
+    # 
+    # Initialize a video with title "hello" and rating 20
+    #   Video.new :title => "hello", :rating => 20
+    def initialize(attributes={})
+      attributes.each do |k, v|
+        self.send("#{k}=", v) if self.respond_to?(k)
+      end
+    end
+    
+    # Return true if the video contains easy step by step directions, else false
+    def easy_steps?
+      easy_steps == "true"
+    end
+  end
+    
+  # Provides access to the Howcast video API.
+  # 
+  # === Inputs
+  #
+  # * <tt>id</tt> -- The id of the video to lookup
+  #
+  # === Outputs
+  # 
+  # Video object if the id exists or nil if the id doesn't exist or is malformed
+  #
+  # === Exceptions
+  # 
+  # * <tt>Howcast::ApiNotFound</tt>
+  #
+  # === Examples
+  # 
+  # Get the Howcast video with id 2
+  #   Howcast::Client.new.video(2)
+  def video(id)
+    response = establish_connection("videos/#{id}.xml")
+    parse_single_xml(response.at(:video), Video)
+  end
+  
+  # Provides access to the Howcast list videos API.
+  # 
+  # === Inputs
+  #
+  # The options are:
+  # * <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
+  #
+  # === Exceptions
+  # * <tt>Howcast::ApiNotFound</tt> -- raised if the requested sort and filter is malformed or not available (404)
+  #
+  # === Examples
+  #
+  # 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 => "top_rated")
+	def videos(options = {})
+    uri = videos_url(options)
+    (establish_connection(uri)/:video).inject([]){ |r, i| r << parse_single_xml(i, Video)}
+	end
+	
+	private
+  	def videos_url(options={})
+      defaults = {:page => nil, :sort => "most_recent", :filter => "howcast_studios", :category_id => nil}
+      options = defaults.update(options)
+      "videos/#{options[:sort]}/#{options[:filter]}#{"/#{options[:category_id]}" if options[:category_id]}#{"/#{options[:page]}" if options[:page]}.xml"
+    end
+end

data/lib/howcast/errors.rb

@@ -0,0 +1,8 @@
+
+class Howcast::ApiNotFound < Exception
+  
+end
+
+class Howcast::ApiKeyNotFound < Exception
+  
+end

data/spec/howcast/client/base_spec.rb

@@ -0,0 +1,14 @@
+require File.dirname(__FILE__) + '/../../spec_helper'
+
+describe Howcast::Client, "initialize" do
+  it "should create a client object with all the inputted attributes" do
+    client = Howcast::Client.new :key => "myapikey"
+    client.should be_instance_of(Howcast::Client)
+  end
+  
+  it "should raise a Howcast::ApiKeyNotFound error when no key is supplied" do
+    lambda {
+      Howcast::Client.new
+    }.should raise_error(Howcast::ApiKeyNotFound)
+  end
+end

data/spec/howcast/client/category_spec.rb

@@ -0,0 +1,45 @@
+require File.dirname(__FILE__) + '/../../spec_helper'
+
+describe Howcast::Client::Category, "initialize" do
+  it "should create a category object with all the inputted attributes" do
+    category = Howcast::Client::Category.new :name => "category_title"
+    category.name.should == 'category_title'
+  end
+  
+  it "should ignore inputs which are not category attributes" do
+    category = Howcast::Client::Category.new :not_an_attribute => "value", :name => "category_title"
+    category.respond_to?(:not_an_attribute).should be_false
+    category.name.should == "category_title"
+  end
+end
+
+describe Howcast::Client, "category" do  
+  before do
+    @hc = Howcast::Client.new(:key => "myapikey")
+    @hc.stub!(:open).and_return(category_xml)
+  end
+  
+  it "should establish a connection with the correct category url" do
+    @hc.should_receive(:open).with("http://www.howcast.com/categories/2.xml?api_key=myapikey").and_return(category_xml)
+    @hc.category(2)
+  end  
+  
+  it "should raise Howcast::ApiKeyNotFound error when the response contains Invalid API Key" do
+    lambda {
+      @hc.stub!(:open).and_return(invalid_api_key_xml)
+      @hc.category(2)
+    }.should raise_error(Howcast::ApiKeyNotFound)
+  end
+
+  it "should set the title attribute in the category model response" do
+    @hc.category(2).name.should == "General African Travel"
+  end
+  
+  it "should set the parent_id attribute in the category model response" do
+    @hc.category(2).parent_id.should == "1584"
+  end  
+  
+  it "should set the parents metadata hash" do
+    @hc.category(2).parents.should == [{:id => "1571", :name => "Travel"}, {:id => "1584", :name => "African Travel"}]
+  end
+end

data/spec/howcast/client/search_spec.rb

@@ -0,0 +1,47 @@
+require File.dirname(__FILE__) + '/../../spec_helper'
+
+describe Howcast::Client, "search" do
+  before do
+    @hc = Howcast::Client.new(:key => "myapikey")
+  end
+  
+  it "should establish a connection with search.xml?q=something&view=videos when query is 'something'" do
+    @hc.should_receive(:open).with("http://www.howcast.com/search.xml?q=something&view=videos&api_key=myapikey").and_return(videos_xml)
+    @hc.search("something")
+  end
+  
+  it "should establish a connection with search.xml?q=something&view=videos&page=2 when query is 'something' and :page => 2" do
+    @hc.should_receive(:open).with("http://www.howcast.com/search.xml?q=something&view=videos&page=2&api_key=myapikey").and_return(videos_xml)
+    @hc.search("something", :page => 2)
+  end
+  
+  it "should escape the query when esablishing the connection" do
+    @hc.should_receive(:open).with("http://www.howcast.com/search.xml?q=something+%26+something&view=videos&api_key=myapikey").and_return(videos_xml)
+    @hc.search("something & something")
+  end
+  
+  it "should append mode=extended when passed in as an option" do
+    @hc.should_receive(:open).with("http://www.howcast.com/search.xml?q=something&view=videos&mode=extended&api_key=myapikey").and_return(videos_xml)
+    @hc.search("something", :mode => :extended)
+  end
+  
+  it "should raise a Howcast::ApiNotFound if url is invalid" do
+    lambda {
+      @hc.should_receive(:open).and_raise(URI::InvalidURIError)
+      @hc.search("something")
+    }.should raise_error(Howcast::ApiNotFound)
+  end
+  
+  it "should return an empty array if there are no results" do
+    @hc.should_receive(:open).and_return(blank_videos_xml)
+    @hc.search("something").should be_empty
+  end
+  
+  it "should return an array of video objects if there are some returned" do
+    @hc.should_receive(:open).and_return(videos_xml)
+    videos = @hc.search("something")
+    videos.size.should == 3
+    videos.first.permalink.should == "http://www.howcast.com/videos/1101-How-To-Pretend-Youre-a-Real-New-Yorker"
+    videos.last.permalink.should == "http://www.howcast.com/videos/866-How-To-Make-a-Water-Gun-Alarm-Clock"
+  end
+end

data/spec/howcast/client/video_spec.rb

@@ -0,0 +1,121 @@
+require File.dirname(__FILE__) + '/../../spec_helper'
+
+describe Howcast::Client::Video, "initialize" do
+  it "should create a video object with all the inputted attributes" do
+    video = Howcast::Client::Video.new :title => "video_title"
+    video.title.should == 'video_title'
+  end
+  
+  it "should ignore inputs which are not video attributes" do
+    video = Howcast::Client::Video.new :not_an_attribute => "value", :title => "video_title"
+    video.respond_to?(:not_an_attribute).should be_false
+    video.title.should == "video_title"
+  end
+end
+
+describe Howcast::Client, "video" do  
+  before do
+    @hc = Howcast::Client.new(:key => "myapikey")
+    @hc.stub!(:open).and_return(video_xml)
+  end
+  
+  it "should establish a connection with the correct video url" do
+    @hc.should_receive(:open).with("http://www.howcast.com/videos/2.xml?api_key=myapikey").and_return(video_xml)
+    @hc.video(2)
+  end  
+  
+  it "should raise Howcast::ApiKeyNotFound error when the response contains Invalid API Key" do
+    lambda {
+      @hc.stub!(:open).and_return(invalid_api_key_xml)
+      @hc.video(2)
+    }.should raise_error(Howcast::ApiKeyNotFound)
+  end
+
+  it "should return nil whenever the result xml is empty" do
+    @hc.stub!(:open).and_return(blank_video_xml)
+    @hc.video(2).should be_nil
+  end
+
+  it "should set the embed attribute in the video model response" do
+    @hc.video(2).embed.should == %(<object width="425" height="352" classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" id="howcastplayer"><param name="movie" value="http://www.howcast.com/flash/howcast_player.swf?file=233"></param><param name="allowFullScreen" value="true"></param><param name="allowScriptAccess" value="always"></param><embed src="http://www.howcast.com/flash/howcast_player.swf?file=233" type="application/x-shockwave-flash" width="425" height="352" allowFullScreen="true" allowScriptAccess="always" ></embed></object>)
+  end
+  
+  it "should set the title attribute in the video model response" do
+    @hc.video(2).title.should == "How To Do a Noble Pose"
+  end
+  
+  it "should set the views attribute in the video model response" do
+    @hc.video(2).views.should == "38"
+  end
+  
+  it "should set the badges in the video model response" do
+    @hc.video(2).badges.should == "Howcast Studios"
+  end
+  
+  it "should set the easy_steps boolean in the video model response" do
+    @hc.video(2).easy_steps?.should be_true
+  end
+  
+  it "should set the rating attribute in the video model response" do
+    @hc.video(2).rating.should == "2.0"
+  end
+  
+  it "should set the description attribute in the video model response" do
+    @hc.video(2).description.should == "You recognize the Noble Pose as the dreaded \"sit-and-reach\" from your childhood gym class. A sample <a href=\"howcast.com\">link</a>"
+  end
+  
+  it "should set the permalink attribute in the video model response" do
+    @hc.video(2).permalink.should == "http://www.howcast.com/videos/233-How-To-Do-a-Noble-Pose"
+  end
+end
+
+describe Howcast::Client, "videos" do
+  before do
+    @hc = Howcast::Client.new(:key => "myapikey")
+  end
+  
+  it "should establish a connection with videos/most_recent/howcast_studios.xml by default" do
+    @hc.should_receive(:open).with("http://www.howcast.com/videos/most_recent/howcast_studios.xml?api_key=myapikey").and_return(videos_xml)
+    @hc.videos
+  end
+  
+  it "should establish a connection with videos/most_recent/howcast_studios/2.xml when :page => 2" do
+    @hc.should_receive(:open).with("http://www.howcast.com/videos/most_recent/howcast_studios/2.xml?api_key=myapikey").and_return(videos_xml)
+    @hc.videos(:page => 2)
+  end
+  
+  it "should establish a connection with videos/most_viewed/howcast_studios.xml when :sort => most_viewed" do
+    @hc.should_receive(:open).with("http://www.howcast.com/videos/most_viewed/howcast_studios.xml?api_key=myapikey").and_return(videos_xml)
+    @hc.videos(:sort => "most_viewed")    
+  end
+  
+  it "should establish a connection with videos/most_viewed/directors_program.xml when :sort => most_viewed and :filter => directors_program" do
+    @hc.should_receive(:open).with("http://www.howcast.com/videos/most_viewed/directors_program.xml?api_key=myapikey").and_return(videos_xml)
+    @hc.videos(:sort => "most_viewed", :filter => "directors_program")    
+  end
+  
+  it "should establish a connection with videos/top_rated/directors_program.xml when :sort => most_viewed and :filter => directors_program" do
+    @hc.should_receive(:open).with("http://www.howcast.com/videos/top_rated/directors_program.xml?api_key=myapikey").and_return(videos_xml)
+    @hc.videos(:sort => "top_rated", :filter => "directors_program")    
+  end
+  
+  it "should raise a Howcast::ApiNotFound if url is invalid" do
+    lambda {
+      @hc.should_receive(:open).and_raise(URI::InvalidURIError)
+      @hc.videos
+    }.should raise_error(Howcast::ApiNotFound)
+  end
+  
+  it "should return an empty array if there are no results" do
+    @hc.should_receive(:open).and_return(blank_videos_xml)
+    @hc.videos.should be_empty
+  end
+  
+  it "should return an array of video objects if there are some returned" do
+    @hc.should_receive(:open).and_return(videos_xml)
+    videos = @hc.videos
+    videos.size.should == 3
+    videos.first.permalink.should == "http://www.howcast.com/videos/1101-How-To-Pretend-Youre-a-Real-New-Yorker"
+    videos.last.permalink.should == "http://www.howcast.com/videos/866-How-To-Make-a-Water-Gun-Alarm-Clock"
+  end
+end

data/spec/spec.opts

@@ -0,0 +1 @@
+--colour

data/spec/spec_helper.rb

@@ -0,0 +1,207 @@
+ENV["RAILS_ENV"] ||= "test"
+begin
+  require 'spec'
+rescue LoadError
+  require 'rubygems'
+  require 'spec'
+end
+
+require File.expand_path(File.dirname(__FILE__) + "/../lib/howcast")
+
+Spec::Runner.configure do |config|
+  def invalid_api_key_xml
+    <<-INVALID
+    <?xml version="1.0" encoding="UTF-8"?>
+    <howcast version="0.1">
+      <error>Invalid API Key</error>
+    </howcast>
+    INVALID
+  end
+  
+  def blank_video_xml
+    <<-VID
+    <?xml version="1.0" encoding="UTF-8"?>
+    <howcast version="0.1">
+      <video>
+      </video>
+    </howcast>
+    VID
+  end
+    
+  def blank_guides_xml
+    <<-GUID
+    <?xml version="1.0" encoding="UTF-8"?>
+    <howcast version="0.1">
+      <guides>
+      </guides>
+    </howcast>
+    GUID
+  end
+  
+  def blank_videos_xml
+    <<-VID
+    <?xml version="1.0" encoding="UTF-8"?>
+    <howcast version="0.1">
+      <videos>
+      </videos>
+    </howcast>
+    VID
+  end
+  
+  def category_xml
+    <<-CAT
+    <?xml version="1.0" encoding="UTF-8"?>
+    <howcast version="0.1">
+      <category>
+        <id>1255</id>
+        <name>General African Travel</name>
+        <parent-id>1584</parent-id>
+        <parents>
+          <category id="1571">Travel</category>
+          <category parent_id="1571" id="1584">African Travel</category>
+        </parents>
+        <subcategories>
+          <category>
+            <id>1265</id>
+            <name>African Travel</name>
+          </category>
+          <category>
+            <id>1289</id>
+            <name>European Travel</name>
+          </category>
+          <category>
+            <id>1256</id>
+            <name>General Travel</name>
+          </category>
+          <category>
+            <id>1311</id>
+            <name>General U.S. Travel</name>
+          </category>
+        </subcategories>
+      </category>
+    </howcast>
+    CAT
+  end
+  
+  def video_xml
+    <<-VID
+    <?xml version="1.0" encoding="UTF-8"?>
+    <howcast version="0.1">
+      <video>
+        <category-id>2</category-id>
+        <duration>22</duration>
+        <id>233</id>
+        <easy-steps>true</easy-steps>
+        <badges>Howcast Studios</badges>
+        <title>How To Do a Noble Pose</title>
+        <embed>
+          <![CDATA[<object width="425" height="352" classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" id="howcastplayer"><param name="movie" value="http://www.howcast.com/flash/howcast_player.swf?file=233"></param><param name="allowFullScreen" value="true"></param><param name="allowScriptAccess" value="always"></param><embed src="http://www.howcast.com/flash/howcast_player.swf?file=233" type="application/x-shockwave-flash" width="425" height="352" allowFullScreen="true" allowScriptAccess="always" ></embed></object>]]>
+        </embed>
+        <description>
+          <![CDATA[You recognize the Noble Pose as the dreaded "sit-and-reach" from your childhood gym class. A sample <a href="howcast.com">link</a>]]>
+        </description>
+        <permalink>http://www.howcast.com/videos/233-How-To-Do-a-Noble-Pose</permalink>
+        <username>joekulak</username>
+        <thumbnail-url>http://www.howcast.com/system/thumbnails/233/Mind.How_to_Do_the_Noble_Pose_SD_xxlarge.jpg</thumbnail-url>
+        <views>38</views>
+        <rating>2.0</rating>
+        <created-at>#{Time.now.rfc822}</created-at>
+      </video>
+    </howcast>
+    VID
+  end
+  
+  def guides_xml
+    <<-VID
+    <?xml version="1.0" encoding="UTF-8"?>
+    <howcast version="0.1">
+      <title>Howcast - Top Favorites Howcast Written Guides </title>
+      <guides>
+        <guide>
+          <rating>94</rating>
+          <title>How To Pretend You&#8217;re a Real New Yorker</title>
+          <permalink>http://www.howcast.com/guides/1101-How-To-Pretend-Youre-a-Real-New-Yorker</permalink>
+          <id>1101</id>
+          <category-id>1642</category-id>
+          <description>There&#8217;s nothing wrong with being a tourist in New York City. But if you want to blend in, here&#8217;s what you need to know.</description>
+          <views>2739</views>
+          <username>vinzfeller</username>
+          <created-at>2008-02-05T19:41:21-08:00</created-at>
+        </guide>
+        <guide>
+          <rating>96</rating>
+          <title>How To Look Great in Photographs</title>
+          <permalink>http://www.howcast.com/guides/577-How-To-Look-Great-in-Photographs</permalink>
+          <id>577</id>
+          <category-id>22</category-id>
+          <description>Sure, a beautiful photograph takes some skill behind the lens, but it takes a little skill in front of it, too.</description>
+          <views>3831</views>
+          <username>nicholas</username>
+          <created-at>2008-01-12T09:33:06-08:00</created-at>
+        </guide>
+        <guide>
+          <rating>98</rating>
+          <title>How To Make a Water Gun Alarm Clock</title>
+          <permalink>http://www.howcast.com/guides/866-How-To-Make-a-Water-Gun-Alarm-Clock</permalink>
+          <id>866</id>
+          <category-id>1728</category-id>
+          <description>Having a little trouble waking up in the morning? There&#8217;s nothing like a good soaking to get you going.</description>
+          <views>2663</views>
+          <username>Howcast</username>
+          <created-at>2008-01-31T20:47:08-08:00</created-at>
+        </guide>
+      </guides>
+    </howcast>
+    VID
+  end
+  
+  def videos_xml
+    <<-VID
+    <?xml version="1.0" encoding="UTF-8"?>
+    <howcast version="0.1">
+      <title>Howcast - Top Favorites Howcast Studios Videos </title>
+      <videos>
+        <video>
+          <rating>94</rating>
+          <title>How To Pretend You&#8217;re a Real New Yorker</title>
+          <permalink>http://www.howcast.com/videos/1101-How-To-Pretend-Youre-a-Real-New-Yorker</permalink>
+          <id>1101</id>
+          <category-id>1642</category-id>
+          <description>There&#8217;s nothing wrong with being a tourist in New York City. But if you want to blend in, here&#8217;s what you need to know.</description>
+          <thumbnail-url>http://www.howcast.com/system/thumbnails/1101/ppn_feller_real_newyorker_sd_medium.jpg</thumbnail-url>
+          <views>2739</views>
+          <username>vinzfeller</username>
+          <duration>203</duration>
+          <created-at>2008-02-05T19:41:21-08:00</created-at>
+        </video>
+        <video>
+          <rating>96</rating>
+          <title>How To Look Great in Photographs</title>
+          <permalink>http://www.howcast.com/videos/577-How-To-Look-Great-in-Photographs</permalink>
+          <id>577</id>
+          <category-id>22</category-id>
+          <description>Sure, a beautiful photograph takes some skill behind the lens, but it takes a little skill in front of it, too.</description>
+          <thumbnail-url>http://www.howcast.com/system/thumbnails/577/Arts.How_to_Look_Great_in_Photographs_SD_medium.jpg</thumbnail-url>
+          <views>3831</views>
+          <username>nicholas</username>
+          <duration>156</duration>
+          <created-at>2008-01-12T09:33:06-08:00</created-at>
+        </video>
+        <video>
+          <rating>98</rating>
+          <title>How To Make a Water Gun Alarm Clock</title>
+          <permalink>http://www.howcast.com/videos/866-How-To-Make-a-Water-Gun-Alarm-Clock</permalink>
+          <id>866</id>
+          <category-id>1728</category-id>
+          <description>Having a little trouble waking up in the morning? There&#8217;s nothing like a good soaking to get you going.</description>
+          <thumbnail-url>http://www.howcast.com/system/thumbnails/866/watergunthumb2_medium.jpg</thumbnail-url>
+          <views>2663</views>
+          <username>Howcast</username>
+          <duration>108</duration>
+          <created-at>2008-01-31T20:47:08-08:00</created-at>
+        </video>
+      </videos>
+    </howcast>
+    VID
+  end
+end

data/tasks/github.rake

@@ -0,0 +1,3 @@
+task :build_for_github => [:manifest, :build_gemspec] do
+  p `ruby script/github-test.rb howcast.gemspec`
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification 
+name: howcast-howcast
+version: !ruby/object:Gem::Version 
+  version: 0.4.7
+platform: ruby
+authors: 
+- Jingshen Jimmy Zhang
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-08-19 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: "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."
+email: jimmy@howcast.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- 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
+- README.markdown
+- tasks/github.rake
+files: 
+- CHANGELOG
+- howcast.gemspec
+- 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
+has_rdoc: false
+homepage: http://github.com/howcast/howcast-gem
+licenses: 
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Howcast
+- --main
+- README.markdown
+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: "1.2"
+  version: 
+requirements: []
+
+rubyforge_project: howcast
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Howcast API Ruby Wrapper
+test_files: []
+