howkast 0.0.0

data/RELEASENOTES

@@ -0,0 +1,2 @@
+0.0.0 [UNRELEASED]
+- Initial release.

data/Rakefile

@@ -0,0 +1,49 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "howkast"
+  gem.homepage = "http://github.com/jurisgalang/howkast"
+  gem.summary = %Q{Ruby bindings for the [Howcast](http://howcast.com) API}
+  gem.description = %Q{
+    This gem implements Ruby bindings for the [Howcast](http://howcast.com) API
+    Howcast empowers people with engaging, useful how-to information wherever, whenever they need to know how.
+  }
+  gem.email = "jurisgalang@gmail.com"
+  gem.authors = ["Juris Galang"]
+  gem.license = ["MIT", "GPL"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+require 'cucumber/rake/task'
+Cucumber::Rake::Task.new(:features)
+
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/VERSION

@@ -0,0 +1 @@
+0.0.0

data/features/howkast.feature

@@ -0,0 +1,9 @@
+Feature: something something
+  In order to something something
+  A user something something
+  something something something
+
+  Scenario: something something
+    Given inspiration
+    When I create a sweet new gem
+    Then everyone should see how awesome I am

data/features/support/env.rb

@@ -0,0 +1,13 @@
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+
+$LOAD_PATH.unshift(File.dirname(__FILE__) + '/../../lib')
+require 'howkast'
+
+require 'rspec/expectations'

data/howkast.gemspec

@@ -0,0 +1,109 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{howkast}
+  s.version = "0.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Juris Galang"]
+  s.date = %q{2011-01-03}
+  s.description = %q{
+    This gem implements Ruby bindings for the [Howcast](http://howcast.com) API
+    Howcast empowers people with engaging, useful how-to information wherever, whenever they need to know how.
+  }
+  s.email = %q{jurisgalang@gmail.com}
+  s.extra_rdoc_files = [
+    "README.md"
+  ]
+  s.files = [
+    ".document",
+    ".rspec",
+    "GPL-LICENSE",
+    "Gemfile",
+    "Gemfile.lock",
+    "MIT-LICENSE",
+    "README.md",
+    "RELEASENOTES",
+    "Rakefile",
+    "VERSION",
+    "features/howkast.feature",
+    "features/step_definitions/howkast_steps.rb",
+    "features/support/env.rb",
+    "howkast.gemspec",
+    "lib/howkast.rb",
+    "lib/howkast/api.rb",
+    "lib/howkast/base.rb",
+    "lib/howkast/configuration.rb",
+    "lib/howkast/errors.rb",
+    "lib/howkast/ext/icebox.rb",
+    "lib/howkast/ext/string.rb",
+    "lib/howkast/model.rb",
+    "lib/howkast/processors/base.rb",
+    "lib/howkast/processors/categories.rb",
+    "lib/howkast/processors/playlists.rb",
+    "lib/howkast/processors/search.rb",
+    "lib/howkast/processors/users.rb",
+    "lib/howkast/processors/videos.rb",
+    "sample/adhoc.rb",
+    "sample/quickstart.rb",
+    "spec/howkast/api_service_spec.rb",
+    "spec/howkast/api_spec.rb",
+    "spec/howkast/model_spec.rb",
+    "spec/howkast/processors/categories_spec.rb",
+    "spec/howkast/processors/playlists_spec.rb",
+    "spec/howkast/processors/search_spec.rb",
+    "spec/howkast/processors/users_spec.rb",
+    "spec/howkast/processors/videos_spec.rb",
+    "spec/howkast_spec.rb",
+    "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/jurisgalang/howkast}
+  s.licenses = [["MIT", "GPL"]]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Ruby bindings for the [Howcast](http://howcast.com) API}
+  s.test_files = [
+    "spec/howkast/api_service_spec.rb",
+    "spec/howkast/api_spec.rb",
+    "spec/howkast/model_spec.rb",
+    "spec/howkast/processors/categories_spec.rb",
+    "spec/howkast/processors/playlists_spec.rb",
+    "spec/howkast/processors/search_spec.rb",
+    "spec/howkast/processors/users_spec.rb",
+    "spec/howkast/processors/videos_spec.rb",
+    "spec/howkast_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::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, ["~> 2.3.0"])
+      s.add_development_dependency(%q<yard>, ["~> 0.6.0"])
+      s.add_development_dependency(%q<cucumber>, [">= 0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.5.2"])
+      s.add_development_dependency(%q<rcov>, [">= 0"])
+    else
+      s.add_dependency(%q<rspec>, ["~> 2.3.0"])
+      s.add_dependency(%q<yard>, ["~> 0.6.0"])
+      s.add_dependency(%q<cucumber>, [">= 0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+      s.add_dependency(%q<rcov>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rspec>, ["~> 2.3.0"])
+    s.add_dependency(%q<yard>, ["~> 0.6.0"])
+    s.add_dependency(%q<cucumber>, [">= 0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+    s.add_dependency(%q<rcov>, [">= 0"])
+  end
+end
+

data/lib/howkast.rb

@@ -0,0 +1,22 @@
+# encoding: utf-8
+
+require 'rubygems'
+
+require 'time'
+require 'singleton'
+require 'active_support/memoizable'
+require 'httparty'
+require 'named-parameters'
+
+require 'howkast/ext/string'
+#require 'howkast/ext/icebox'
+
+require 'howkast/configuration'
+require 'howkast/errors'
+require 'howkast/model'
+require 'howkast/base'
+require 'howkast/api'
+
+Dir[File.join(File.dirname(__FILE__), 'howkast', 'processors', '*')].each do |processor|
+  require processor
+end

data/lib/howkast/api.rb

@@ -0,0 +1,37 @@
+# encoding: utf-8
+
+module Howkast
+  class API
+    service :video,
+      processor: :videos,
+        options: { :required => :id }
+        
+    service :videos,
+        options: { :required => [ :sort, :filter ],
+                   :optional => [ :category, :page ] }
+
+    service :search, 
+        options: { :required => :query, 
+                   :optional => { :view => :video } }
+
+    service :user,
+      processor: :users,
+        options: { :required => [ :id, :resource ] }
+
+    service :playlist,
+      processor: :playlists,
+        options: { :required => :id }
+      
+    service :category,
+      processor: :categories,
+        options: { :required => :id }
+
+    service :categories
+       
+    recognizes :api_key
+    def initialize opts = { }
+      key = opts[:api_key]
+      configuration.api_key = key if key
+    end
+  end
+end

data/lib/howkast/base.rb

@@ -0,0 +1,90 @@
+# encoding: utf-8
+
+module Howkast
+  def self.configure config = { }
+    configuration = Configuration.instance
+    config.each{ |k, v| configuration.send "#{k}=", v }
+  end
+  
+  module Base
+    HOWCAST_BASE_URI = 'www.howcast.com'
+    extend ActiveSupport::Memoizable
+    
+    def self.included base
+      base.send     :include, HTTParty
+      #base.send     :include, HTTParty::Icebox
+      
+      base.base_uri HOWCAST_BASE_URI
+      base.format   :xml
+      #base.cache    :store    => Configuration.instance.cache_store,
+      #              :timeout  => Configuration.instance.cache_timeout,
+      #              :location => Configuration.instance.cache_location
+                    
+      base.extend ClassMethods
+    end
+    
+    def configuration
+      Configuration.instance
+    end
+
+    private
+    def request *args
+      r = self.class.get *args
+      raise Howkast::Error::RequestError(r.code, r.parsed_response['howcast']) \
+        unless r.code == 200
+      r.parsed_response['howcast']
+    end
+    memoize :request
+    
+    module ClassMethods
+      def configuration
+        Configuration.instance
+      end
+
+      def services
+        @services
+      end
+      
+      def service name, spec = { }
+        arguments_guard = ->(argcount) do
+          maxarity = spec[:maxarity] || 1
+          raise ArgumentError, "wrong number of arguments (#{argcount} for #{maxarity})" \
+            unless maxarity == argcount
+        end
+        
+        has_named_parameters name, spec[:options] || { }
+        (@services ||= []) << name.to_sym
+        
+        define_method name do |*args, &block|
+          arguments_guard[args.count]
+          
+          self.class.default_params api_key: configuration.api_key
+          procname  = (spec[:processor] || name).to_s.modulize
+          processor = Processor.const_defined?(procname) ?
+                        Processor.const_get(procname) :
+                        Processor::Base
+                        
+          path  = "/#{processor.path || name}"
+          query = args.last
+          args  = args[0..-2] if query.instance_of? Hash
+          query = { } unless query.instance_of? Hash
+          
+          processor.filter args, query
+          
+          path << "/#{args.join('/')}" unless args.empty?
+          path << '.xml'
+          
+          data = request(path, query: query)
+          processor.parse_element data
+        end
+      end
+    end
+  end
+
+  class API
+    include Base
+  end
+
+  module Processor
+  end
+end

data/lib/howkast/configuration.rb

@@ -0,0 +1,17 @@
+# encoding: utf-8
+
+module Howkast
+  class Configuration
+    include Singleton
+    attr_accessor :api_key
+    attr_accessor :cache_timeout
+    attr_accessor :cache_location
+    attr_accessor :cache_store
+    
+    def initialize
+      @cache_timeout  = 600
+      @cache_location = '/tmp/howkast/cache'
+      @cache_store    = 'file'
+    end
+  end
+end

data/lib/howkast/errors.rb

@@ -0,0 +1,18 @@
+# encoding: utf-8
+
+module Howkast
+  module Error
+    class RequestError < StandardError; end
+  
+    def self.RequestError(code, data)
+      msg   = data['response']['err']['msg'] unless data.nil?
+      const = msg ? "#{msg.gsub(/\w+/){ $&.modulize }.gsub(/ /, '')}" : "HTTP#{code}"
+      klass = if Howkast::Error.const_defined? const
+        Howkast::Error.const_get const
+      else
+        Howkast::Error.const_set const, Class.new(RequestError)
+      end
+      klass.new(msg)
+    end
+  end
+end

data/lib/howkast/ext/icebox.rb

@@ -0,0 +1,261 @@
+# encoding: utf-8
+#
+# See: https://gist.github.com/209605
+#
+# = Icebox : Caching for HTTParty
+# 
+# Cache responses in HTTParty models [http://github.com/jnunemaker/httparty]
+# 
+# === Usage
+#
+#   class Foo
+#     include HTTParty
+#     include HTTParty::Icebox
+#     cache :store => 'file', :timeout => 600, :location => MY_APP_ROOT.join('tmp', 'cache')
+#   end
+#
+# Modeled after Martyn Loughran's APICache [http://github.com/newbamboo/api_cache]
+# and Ruby On Rails's caching [http://api.rubyonrails.org/classes/ActiveSupport/Cache.html]
+#
+# Author: Karel Minarik [www.karmi.cz]
+# 
+# === Notes
+# 
+# Thanks to Amit Chakradeo to point out objects have to be stored marhalled on FS
+# Thanks to Marlin Forbes to point out query parameters have to be include in the cache key
+# 
+require 'logger'
+#require 'ftools'
+require 'tmpdir'
+require 'pathname'
+require 'digest/md5'
+
+module HTTParty #:nodoc:
+  module Icebox
+
+    module ClassMethods
+
+      # Enable caching and set cache options
+      # Returns memoized cache object
+      #
+      # Following options are available, default values are in []:
+      #
+      # +store+::       Storage mechanism for cached data (memory, filesystem, your own) [memory]
+      # +timeout+::     Cache expiration in seconds [60]
+      # +logger+::      Path to logfile or logger instance [STDOUT]
+      # 
+      # Any additional options are passed to the Cache constructor
+      #
+      # Usage:
+      #
+      #   # Enable caching in HTTParty, in memory, for 1 minute
+      #   cache # Use default values
+      #
+      #   # Enable caching in HTTParty, on filesystem (/tmp), for 10 minutes
+      #   cache :store => 'file', :timeout => 600, :location => '/tmp/'
+      #
+      #   # Use your own cache store (see AbstractStore class below)
+      #   cache :store => 'memcached', :timeout => 600, :server => '192.168.1.1:1001'
+      #
+      def cache(options={})
+        options[:store]   ||= 'memory'
+        options[:timeout] ||= 60
+        logger = options[:logger]
+        @cache ||= Cache.new( options.delete(:store), options )
+      end
+
+    end
+
+    # When included, extend class with +cache+ method
+    # and redefine +get+ method to use cache
+    # 
+    def self.included(receiver) #:nodoc:
+      receiver.extend ClassMethods
+      receiver.class_eval do
+
+        # Get reponse from network
+        # TODO: Why alias :new :old is not working here? Returns NoMethodError
+        # 
+        def self.get_without_caching(path, options={})
+          perform_request Net::HTTP::Get, path, options
+        end
+
+        # Get response from cache, if available
+        # 
+        def self.get_with_caching(path, options={})
+          key = path.clone
+          key << options[:query].to_s if defined? options[:query]
+          
+          if cache.exists?(key) and not cache.stale?(key)
+            Cache.logger.debug "CACHE -- GET #{path}#{options[:query]}"
+            return cache.get(key)
+          else
+            Cache.logger.debug "/!\\ NETWORK -- GET #{path}#{options[:query]}"
+            response = get_without_caching(path, options)
+            cache.set(key, response) if response.code == 200
+            return response
+          end
+        end
+
+        # Redefine original HTTParty +get+ method to use cache
+        # 
+        def self.get(path, options={})
+          self.get_with_caching(path, options)
+        end
+
+      end
+    end
+
+    # === Cache container
+    # 
+    # Pass a store name ('memory', etc) to initializer
+    # 
+    class Cache
+      attr_accessor :store
+
+      def initialize(store, options={})
+        self.class.logger = options[:logger]
+        @store = self.class.lookup_store(store).new(options)
+      end
+
+      def get(key);            @store.get encode(key) unless stale?(key);        end
+      def set(key, value);     @store.set encode(key), value;                    end
+      def exists?(key);        @store.exists? encode(key);                       end
+      def stale?(key);         @store.stale?  encode(key);                       end
+
+      def self.logger; @logger || default_logger; end
+      def self.default_logger; logger = ::Logger.new(STDERR); end
+
+      # Pass a filename (String), IO object, Logger instance or +nil+ to silence the logger
+      def self.logger=(device); @logger = device.kind_of?(::Logger) ? device : ::Logger.new(device); end
+
+      private
+
+      # Return store class based on passed name
+      def self.lookup_store(name)
+        store_name = "#{name.capitalize}Store"
+        return Store::const_get(store_name)
+      rescue NameError => e
+        raise Store::StoreNotFound, "The cache store '#{store_name}' was not found. Did you loaded any such class?"
+      end
+
+      def encode(key); Digest::MD5.hexdigest(key); end
+    end
+
+
+    # === Cache stores
+    # 
+    module Store
+
+      class StoreNotFound < StandardError; end #:nodoc:
+
+      # ==== Abstract Store
+      # Inherit your store from this class
+      # *IMPORTANT*: Do not forget to call +super+ in your +initialize+ method!
+      # 
+      class AbstractStore
+        def initialize(options={})
+          raise ArgumentError, "You need to set the :timeout parameter" unless options[:timeout]
+          @timeout = options[:timeout]
+          message =  "Cache: Using #{self.class.to_s.split('::').last}"
+          message << " in location: #{options[:location]}" if options[:location]
+          message << " with timeout #{options[:timeout]} sec"
+          Cache.logger.info message unless options[:logger].nil?
+          return self
+        end
+        %w{set get exists? stale?}.each do |method_name|
+          define_method(method_name) { raise NoMethodError, "Please implement method set in your store class" }
+        end
+      end
+
+      # ===== Store objects in memory
+      #
+      Struct.new("Response", :code, :body, :headers) { def to_s; self.body; end }
+      class MemoryStore < AbstractStore
+        def initialize(options={})
+          super; @store = {}; self
+        end
+        def set(key, value)
+          Cache.logger.info("Cache: set (#{key})")
+          @store[key] = [Time.now, value]; true
+        end
+        def get(key)
+          data = @store[key][1]
+          Cache.logger.info("Cache: #{data.nil? ? "miss" : "hit"} (#{key})")
+          data
+        end
+        def exists?(key)
+          !@store[key].nil?
+        end
+        def stale?(key)
+          return true unless exists?(key)
+          Time.now - created(key) > @timeout
+        end
+        private
+        def created(key)
+          @store[key][0]
+        end
+      end
+
+      # ===== Store objects on the filesystem
+      # 
+      class FileStore < AbstractStore
+        def initialize(options={})
+          super
+          options[:location] ||= Dir::tmpdir
+          @path = Pathname.new( options[:location] )
+          FileUtils.mkdir_p( @path )
+          self
+        end
+        def set(key, value)
+          Cache.logger.info("Cache: set (#{key})")
+          File.open( @path.join(key), 'w' ) { |file| file << Marshal.dump(value)  }
+          true
+        end
+        def get(key)
+          data = Marshal.load(File.read( @path.join(key)))
+          Cache.logger.info("Cache: #{data.nil? ? "miss" : "hit"} (#{key})")
+          data
+        end
+        def exists?(key)
+          File.exists?( @path.join(key) )
+        end
+        def stale?(key)
+          return true unless exists?(key)
+          Time.now - created(key) > @timeout
+        end
+        private
+        def created(key)
+          File.mtime( @path.join(key) )
+        end
+      end
+    end
+
+  end
+end
+#
+# Major parts of this code are based on architecture of ApiCache.
+# Copyright (c) 2008 Martyn Loughran
+# 
+# Other parts are inspired by the ActiveSupport::Cache in Ruby On Rails.
+# Copyright (c) 2005-2009 David Heinemeier Hansson
+# 
+# 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.
+#