howcast 0.3.1

data/History.txt

@@ -0,0 +1,19 @@
+== 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.txt

@@ -0,0 +1,35 @@
+History.txt
+License.txt
+Manifest.txt
+README.txt
+Rakefile
+config/hoe.rb
+config/requirements.rb
+lib/howcast.rb
+lib/howcast/client.rb
+lib/howcast/version.rb
+lib/howcast/errors.rb
+lib/howcast/client/base.rb
+lib/howcast/client/video.rb
+lib/howcast/client/guide.rb
+lib/howcast/client/search.rb
+log/debug.log
+script/destroy
+script/generate
+script/txt2html
+setup.rb
+spec/spec.opts
+spec/spec_helper.rb
+spec/howcast/client/base_spec.rb
+spec/howcast/client/guide_spec.rb
+spec/howcast/client/video_spec.rb
+spec/howcast/client/search_spec.rb
+tasks/deployment.rake
+tasks/environment.rake
+tasks/rspec.rake
+tasks/website.rake
+website/index.html
+website/index.txt
+website/javascripts/rounded_corners_lite.inc.js
+website/stylesheets/screen.css
+website/template.rhtml

data/README.txt

@@ -0,0 +1,30 @@
+Howcast API Ruby Wrapper
+Copyright (c) 2008 Howcast Media Inc.
+
+== Example
+
+An example ruby script to get some howcast videos
+
+  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 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 v.title
+  end
+
+  puts "Videos matching 'origami'"
+  hc.video_search("origami").each do |v|
+    puts v.title
+  end
+
+  puts "Video with id 946"
+  puts hc.video(946).title

data/Rakefile

@@ -0,0 +1,4 @@
+require 'config/requirements'
+require 'config/hoe' # setup Hoe + all gem configuration
+
+Dir['tasks/**/*.rake'].each { |rake| load rake }

data/config/hoe.rb

@@ -0,0 +1,70 @@
+require 'howcast/version'
+
+AUTHOR = 'Michael Murray'  # can also be an array of Authors
+EMAIL = "michael+gem@howcast.com"
+DESCRIPTION = "Howcast API Ruby Wrapper"
+GEM_NAME = 'howcast' # what ppl will type to install your gem
+RUBYFORGE_PROJECT = 'howcast' # The unix name for your project
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
+
+@config_file = "~/.rubyforge/user-config.yml"
+@config = nil
+RUBYFORGE_USERNAME = "mdmurray"
+def rubyforge_username
+  unless @config
+    begin
+      @config = YAML.load(File.read(File.expand_path(@config_file)))
+    rescue
+      puts <<-EOS
+ERROR: No rubyforge config file found: #{@config_file}
+Run 'rubyforge setup' to prepare your env for access to Rubyforge
+ - See http://newgem.rubyforge.org/rubyforge.html for more details
+      EOS
+      exit
+    end
+  end
+  RUBYFORGE_USERNAME.replace @config["username"]
+end
+
+
+REV = nil 
+# UNCOMMENT IF REQUIRED: 
+# REV = `svn info`.each {|line| if line =~ /^Revision:/ then k,v = line.split(': '); break v.chomp; else next; end} rescue nil
+VERS = Howcast::Version::STRING + (REV ? ".#{REV}" : "")
+RDOC_OPTS = ['--quiet', '--title', 'howcast documentation',
+    "--opname", "index.html",
+    "--line-numbers", 
+    "--main", "README",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps 
+    @extra_deps.reject! { |x| Array(x).first == 'hoe' } 
+    @extra_deps
+  end 
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.developer(AUTHOR, EMAIL)
+  p.description = DESCRIPTION
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/test_*.rb"]
+  p.clean_globs |= ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']  #An array of file patterns to delete on clean.
+  
+  # == Optional
+  p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  p.extra_deps = [['hpricot', '>= 0.6']]     # An array of rubygem dependencies [name, version], e.g. [ ['active_support', '>= 1.3.1'] ]
+  
+  # p.spec_extras = {}    # A hash of extra values to set in the gemspec.
+  
+end
+
+CHANGES = hoe.paragraphs_of('History.txt', 0..1).join("\\n\\n")
+PATH    = (RUBYFORGE_PROJECT == GEM_NAME) ? RUBYFORGE_PROJECT : "#{RUBYFORGE_PROJECT}/#{GEM_NAME}"
+hoe.remote_rdoc_dir = File.join(PATH.gsub(/^#{RUBYFORGE_PROJECT}\/?/,''), 'rdoc')
+hoe.rsync_args = '-av --delete --ignore-errors'

data/config/requirements.rb

@@ -0,0 +1,17 @@
+require 'fileutils'
+include FileUtils
+
+require 'rubygems'
+%w[rake hoe newgem rubigen].each do |req_gem|
+  begin
+    require req_gem
+  rescue LoadError
+    puts "This Rakefile requires the '#{req_gem}' RubyGem."
+    puts "Installation: gem install #{req_gem} -y"
+    exit
+  end
+end
+
+$:.unshift(File.join(File.dirname(__FILE__), %w[.. lib]))
+
+require 'howcast'

data/lib/howcast.rb

@@ -0,0 +1,9 @@
+module Howcast; end
+
+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

@@ -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/guide.rb')
+require_local('howcast/client/search.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 - Guide | Video supported
+    #
+    # Sample input xml
+    #   <guide>
+    #      <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>
+    #    </guide>
+    #
+    # === 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/guide.rb

@@ -0,0 +1,89 @@
+#--
+# 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 Guide
+    extend WatchAttrAccessors
+    attr_accessor :id, :title, :permalink, :category_id, 
+      :views, :username, :created_at, :rating, :description
+    # Creates a new Guide object which is used to encapsulate all the attributes available
+    # from the Howcast Guide API
+    #
+    # === Inputs
+    #
+    # * <tt>attributes</tt> -- A hash to set the various attributes of the guide object
+    #
+    # === Examples
+    # 
+    # Initialize a guide with title "hello" and rating 20
+    #   Guide.new :title => "hello", :rating => 20
+    def initialize(attributes={})
+      attributes.each do |k, v|
+        self.send("#{k}=", v) if self.respond_to?(k)
+      end
+    end
+  end
+    
+  # REFACTOR: Consider combining with videos method
+  # Provides access to the Howcast list guides API.
+  # 
+  # === Inputs
+  #
+  # The options are:
+  # * <tt>:page</tt> -- The page number to retrieve (defaults to 1). There are 16 guides 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_written+ (default) | +community_written+
+  #
+  # === Outputs
+  # An array of guide 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 written guides.  
+  #   Howcast::Client.new.guides
+  # Get the third page of top favorites which are featured
+  #   Howcast::Client.new.guides(:page => 3, :sort => "top_favorites", :filter => "featured")
+	def guides(options = {})
+    uri = guides_url(options)
+    collection = []
+    (establish_connection(uri)/:guide).each do |item|
+      collection << parse_single_xml(item, Guide)
+    end
+    collection
+	end
+	
+	private
+  	def guides_url(options={})
+      defaults = {:page => nil, :sort => "most_recent", :filter => "howcast_written", :category_id => nil}
+      options = defaults.update(options)
+      if options[:category_id].nil?
+        uri = "guides/#{options[:sort]}/#{options[:filter]}.xml"
+      else
+        uri = "guides/#{options[:sort]}/#{options[:filter]}/#{options[:category_id]}.xml"
+      end
+      uri + uri_suffix(options)
+    end
+end