monster_mash 0.1.0 → 0.1.1

data/.gitignore

@@ -19,3 +19,4 @@ rdoc
 pkg
 
 ## PROJECT::SPECIFIC
+README.markdown.html

data/README.markdown

@@ -0,0 +1,146 @@
+monster_mash
+============
+
+* Typhoeus is an ancient monster.
+* A monster mash is a dance party.
+* This library inspired by John Nunemaker's awesomely useful HTTParty.
+* By law, all Ruby libraries have to have dumbass names.
+
+This library wraps `Typhoeus` and `Typhoeus::Hydra` and exposes an easy-to-use DSL for quickly building libraries to interact with HTTP resources. Every method you write will automatically export serial (blocking) and parallel (non-blocking) methods, so you can easily parallelize your HTTP code when possible.
+
+Writing a method
+----------------
+
+monster_mash has a Sinatra-like syntax, and lets you build client API methods using the 
+4 HTTP verbs:
+
+* `get(method_name, &definition_block)`
+* `post(method_name, &definition_block)`
+* `put(method_name, &definition_block)`
+* `delete(method_name, &definition_block)`
+
+Within each `definition_block`, you can set various Typhoeus options.
+
+* `uri` **(required)** - the URI to hit
+* `handler` **(required)** - a block to handle an HTTP response
+* `params` - hash of URI params
+* `body` - post body
+* `headers` - hash of HTTP headers to send
+* `timeout` - how long to timeout
+* `cache_timeout` - how long to keep HTTP calls cached
+* `user_agent` - a User-Agent string to send
+* `max_redirects` - max number of redirects to follow
+* `disable_ssl_peer_verification` - whether to disable SSL verification
+
+Example: Google JSON search
+---------------------------
+
+    class GoogleJson < MonsterMash::Base
+      VERSION = '1.0'
+
+      # Creates a method called +search+ that takes
+      # a single +query+ parameter.
+      get(:search) do |query|
+        uri "http://ajax.googleapis.com/ajax/services/search/web"
+        params 'v' => VERSION,
+               'q' => query,
+               'rsz' => 'large'
+        handler do |response|
+          json = JSON.parse(response.body)
+
+          # returns results
+          json['responseData']['results']
+        end
+      end
+    end
+
+To make serial (blocking) calls using this code, you would then call the class method:
+
+    # blocks
+    results = GoogleJson.search("my search query")
+    results.each do |result|
+      puts result['unescapedUrl']
+      # do other stuff with the response
+    end
+
+The `search(query)` method returns whatever your `handler` block returns.
+
+To make parallel (non-blocking) calls, you need an instance of Typhoeus::Hydra:
+
+    hydra = Typhoeus::Hydra.new
+    google = GoogleJson.new(hydra)
+    10.times do
+      google.search("my query") do |results, error|
+        if error
+          # handle error
+        else
+          results.each do |result|
+            puts result['unescapedUrl']
+          end
+        end
+      end
+    end
+
+    # blocks until all 10 queries complete.
+    hydra.run
+
+Setting defaults
+----------------
+
+If you have Typhoeus settings you want to happen for every request, you can set them in a defaults block:
+
+    class GoogleJson < MonsterMash::Base
+      defaults do
+        user_agent "GoogleJson Ruby Library"
+        disable_ssl_peer_verification true
+      end
+
+      # ...
+    end
+
+As well, if you set `params` or `headers` in the `defaults` block, any `params` or `headers` added later will be `merge`d into the hash.
+
+    class GoogleJson < MonsterMash::Base
+      defaults do
+        params 'api_key' => 'fdas'
+      end
+
+      # The full params hash will look like:
+      #   :q => +query+,
+      #   :v => '1.0',
+      #   :api_key => 'fdas'
+      get(:search) do |query|
+        params 'q' => query,
+               'v' => '1.0'
+        uri "..."
+        handler do |response|
+          # ...
+        end
+      end
+    end
+
+Error Handling
+--------------
+
+* All serial (blocking) methods will simply raise an error if anything wrong happens. You just need to `rescue` said error.
+* When interacting with Hydra requests, the block you pass to it will receive an error to it if any error was caught during the `handler`'s run. You need to check for the error in your block and handle it there.
+
+Example Projects using monster_mash
+-----------------------------------
+* http://github.com/dbalatero/alchemy_api
+
+Note on Patches/Pull Requests
+-----------------------------
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+Copyright
+---------
+
+Copyright (c) 2010 David Balatero. See LICENSE for details.

data/Rakefile

@@ -10,7 +10,7 @@ begin
     gem.email = "dbalatero@gmail.com"
     gem.homepage = "http://github.com/dbalatero/monster_mash"
     gem.authors = ["David Balatero"]
-    gem.add_dependency "typhoeus", ">= 0.1.23"
+    gem.add_dependency "typhoeus", ">= 0.1.25"
     gem.add_development_dependency "rspec", ">= 1.2.9"
     gem.add_development_dependency "typhoeus_spec_cache", ">= 0.2.1"
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

data/lib/monster_mash.rb

@@ -1,6 +1,5 @@
 require 'typhoeus'
 
-require File.dirname(__FILE__) + '/monster_mash/inheritable_attributes'
 files = Dir.glob(File.dirname(__FILE__) + '/**/*.rb')
 files.each { |f| require f }
 

data/lib/monster_mash/base.rb

@@ -4,9 +4,10 @@ module MonsterMash
   end
 
   class Base
-    include ClassLevelInheritableAttributes
-    inheritable_attributes :defaults
+    @defaults = []
+    @has_defaults = false
 
+    attr_accessor :defaults
     attr_accessor :hydra
     attr_accessor :options
 
@@ -32,8 +33,9 @@ module MonsterMash
     end
 
     def self.defaults(&block)
-      if block_given?
-        @defaults = block
+      if block_given? and !@has_defaults
+        @has_defaults = true
+        @defaults << block
       else
         @defaults
       end
@@ -73,10 +75,15 @@ module MonsterMash
       end
     end
 
+    def self.inherited(subclass)
+      subclass.instance_variable_set("@defaults", defaults.dup)
+    end
+
     private
     def self.execute(http_method, hydra, block, *args, &setup_block)
       # Create the request with defaults.
-      request = MonsterMash::Request.new(http_method, &defaults)
+      request = MonsterMash::Request.new(http_method)
+      request.apply_defaults(defaults)
 
       # Add in user-set values.
       request.execute_dsl(*args, &setup_block)

data/lib/monster_mash/request.rb

@@ -5,6 +5,9 @@ module MonsterMash
     attr_accessor :options
     attr_accessor :errors
 
+    # Creates a new Request wrapper object.
+    #
+    # @param [Symbol] type of HTTP request - :get, :post, :delete, :put
     def initialize(http_method, *args, &block)
       @handler = nil
       @value = nil
@@ -13,6 +16,10 @@ module MonsterMash
       execute_dsl(*args, &block)
     end
 
+    def apply_defaults(default_blocks)
+      default_blocks.each { |block| execute_dsl(&block) }
+    end
+
     def execute_dsl(*args, &block)
       instance_exec(*args, &block) if block_given?
     end

data/monster_mash.gemspec

@@ -5,27 +5,27 @@
 
 Gem::Specification.new do |s|
   s.name = %q{monster_mash}
-  s.version = "0.1.0"
+  s.version = "0.1.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["David Balatero"]
-  s.date = %q{2010-05-04}
+  s.date = %q{2010-05-15}
   s.description = %q{Provides a fun HTTP interface on top of Typhoeus!}
   s.email = %q{dbalatero@gmail.com}
   s.extra_rdoc_files = [
     "LICENSE",
-     "README.rdoc"
+     "README.markdown",
+     "README.markdown.html"
   ]
   s.files = [
     ".document",
      ".gitignore",
      "LICENSE",
-     "README.rdoc",
+     "README.markdown",
      "Rakefile",
      "VERSION",
      "lib/monster_mash.rb",
      "lib/monster_mash/base.rb",
-     "lib/monster_mash/inheritable_attributes.rb",
      "lib/monster_mash/instance_exec.rb",
      "lib/monster_mash/request.rb",
      "monster_mash.gemspec",
@@ -52,16 +52,16 @@ Gem::Specification.new do |s|
     s.specification_version = 3
 
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<typhoeus>, [">= 0.1.23"])
+      s.add_runtime_dependency(%q<typhoeus>, [">= 0.1.25"])
       s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
       s.add_development_dependency(%q<typhoeus_spec_cache>, [">= 0.2.1"])
     else
-      s.add_dependency(%q<typhoeus>, [">= 0.1.23"])
+      s.add_dependency(%q<typhoeus>, [">= 0.1.25"])
       s.add_dependency(%q<rspec>, [">= 1.2.9"])
       s.add_dependency(%q<typhoeus_spec_cache>, [">= 0.2.1"])
     end
   else
-    s.add_dependency(%q<typhoeus>, [">= 0.1.23"])
+    s.add_dependency(%q<typhoeus>, [">= 0.1.25"])
     s.add_dependency(%q<rspec>, [">= 1.2.9"])
     s.add_dependency(%q<typhoeus_spec_cache>, [">= 0.2.1"])
   end

data/spec/monster_mash/base_spec.rb

@@ -5,41 +5,46 @@ end
 
 describe MonsterMash::Base do
   describe "inheriting defaults from superclasses" do
-    class A < MonsterMash::Base
-      defaults do
-        cache_timeout 9999
+    before(:all) do
+      class A < MonsterMash::Base
+        defaults do
+          cache_timeout 9999
+          timeout 500
+        end
       end
-    end
 
-    class B < A
-    end
+      class B < A
+      end
 
-    class C < A
-      defaults do
-        cache_timeout 100
+      class C < A
+        defaults do
+          cache_timeout 100
+        end
       end
     end
 
     it "should propagate defaults to B" do
       B.defaults.should == A.defaults
+      B.defaults.should have(1).thing
     end
 
     it "should allow override of defaults by C" do
       C.defaults.should_not == A.defaults
+      C.defaults.should have(2).things
     end
   end
 
   describe "#self.defaults" do
-    it "should default to nil" do
-      MockApi.defaults.should == nil
+    it "should default to empty array" do
+      MockApi.defaults.should == []
     end
 
     it "should save a defaults proc in the class" do
       defaults_block = lambda { nil }
       MockApi.defaults(&defaults_block)
 
-      MockApi.defaults.should == defaults_block
-      MonsterMash::Base.defaults.should == nil
+      MockApi.defaults.should == [defaults_block]
+      MonsterMash::Base.defaults.should be_empty
     end
   end
 

data/spec/monster_mash/request_spec.rb

@@ -44,6 +44,31 @@ describe MonsterMash::Request do
     end
   end
 
+  describe "#apply_defaults" do
+    before(:all) do
+      class ApplyDefaultsA < MonsterMash::Base
+        defaults do
+          timeout 100
+          cache_timeout 9999
+        end
+      end
+
+      class ApplyDefaultsB < ApplyDefaultsA
+        defaults do
+          timeout 50
+        end
+      end
+    end
+
+    it "should apply the defaults in inheritance order" do
+      request = MonsterMash::Request.new(:get)
+      request.apply_defaults(ApplyDefaultsB.defaults)
+
+      request.options[:timeout].should == 50
+      request.options[:cache_timeout].should == 9999
+    end
+  end
+
   describe "#handler" do
     before(:each) do
       @request = MonsterMash::Request.new(:get)

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 1
-  - 0
-  version: 0.1.0
+  - 1
+  version: 0.1.1
 platform: ruby
 authors: 
 - David Balatero
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-05-04 00:00:00 -07:00
+date: 2010-05-15 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -27,8 +27,8 @@ dependencies:
         segments: 
         - 0
         - 1
-        - 23
-        version: 0.1.23
+        - 25
+        version: 0.1.25
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
@@ -67,17 +67,17 @@ extensions: []
 
 extra_rdoc_files: 
 - LICENSE
-- README.rdoc
+- README.markdown
+- README.markdown.html
 files: 
 - .document
 - .gitignore
 - LICENSE
-- README.rdoc
+- README.markdown
 - Rakefile
 - VERSION
 - lib/monster_mash.rb
 - lib/monster_mash/base.rb
-- lib/monster_mash/inheritable_attributes.rb
 - lib/monster_mash/instance_exec.rb
 - lib/monster_mash/request.rb
 - monster_mash.gemspec
@@ -87,6 +87,7 @@ files:
 - spec/monster_mash/request_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb
+- README.markdown.html
 has_rdoc: true
 homepage: http://github.com/dbalatero/monster_mash
 licenses: []

data/README.rdoc

@@ -1,19 +0,0 @@
-= monster_mash
-
-* Typhoeus is an ancient monster.
-* A monster mash is a dance party.
-* This library inspired by John Nunemaker's awesomely useful HTTParty.
-
-== Note on Patches/Pull Requests
- 
-* Fork the project.
-* Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
-  future version unintentionally.
-* Commit, do not mess with rakefile, version, or history.
-  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
-
-== Copyright
-
-Copyright (c) 2010 David Balatero. See LICENSE for details.

data/lib/monster_mash/inheritable_attributes.rb

@@ -1,25 +0,0 @@
-module ClassLevelInheritableAttributes
-  def self.included(base)
-    base.extend(ClassMethods)
-  end
-
-  module ClassMethods
-    def inheritable_attributes(*args)
-      @inheritable_attributes ||= [:inheritable_attributes]
-      @inheritable_attributes += args
-      args.each do |arg|
-        class_eval %(
-          class << self; attr_accessor :#{arg} end
-        )
-      end
-      @inheritable_attributes
-    end
-
-    def inherited(subclass)
-      @inheritable_attributes.each do |inheritable_attribute|
-        instance_var = "@#{inheritable_attribute}"
-        subclass.instance_variable_set(instance_var, instance_variable_get(instance_var))
-      end
-    end
-  end
-end