carbon 0.2.0 → 0.2.1

data/README.rdoc

@@ -4,6 +4,10 @@ Carbon is a Ruby API wrapper for the {Brighter Planet emission estimate web serv
 
 By querying the web service, it can estimate the carbon emissions of many real-life objects, such as cars and houses, based on particular attributes that they may have.
 
+== Full documentation
+
+Give the quick start a try! Once you've exhausted that, read the {carbon gem RDoc}[http://rdoc.info/projects/brighterplanet/carbon] for more.
+
 == Quick start
 
 <b>You'll need a Brighter Planet API key. See the "API keys" section below for details.</b>
@@ -52,20 +56,32 @@ When you want to calculate emissions, simply call <tt>RentalCar#emission</tt>.
     => "kilograms"
     > my_emission.methodology
     => "http://carbon.brighterplanet.com/automobiles.html?[...]"
-    
-=== Asynchronous queries
 
-To request an emission estimate asynchronously, simply pass an URL as the <tt>:callback</tt> option to <tt>#emission</tt>:
+== API keys
 
-    > RentalCar.new.emission :callback => http://example.com/my/callback/handler
+You should get an API key from http://keys.brighterplanet.com and set it globally:
 
-A good way to test this is to set up a {PostBin}[http://postbin.org]
+    Carbon.key = '12903019230128310293'
 
-== Documentation
+Now all of your queries will use that key.
+
+== A note on <tt>#to_param</tt>
+
+Once you understand how to map attributes using the DSL, you might still be confused about what the gem actually calls on your objects.
 
-Read the {carbon gem RDoc}[http://rdoc.info/projects/brighterplanet/carbon] for more.
+The answer: <tt>#to_characteristic</tt> and, failing that, <tt>#to_param</tt>.
 
-== Exceptions
+Let's say <tt>RentalCar#make</tt> returns a <tt>Make</tt> object. You should define either <tt>Make#to_characteristic</tt> or <tt>Make#to_param</tt>. The gem <b>doesn't know</b> that you want it to call <tt>Make#name</tt> or <tt>Make#epa_code</tt> or anything else.
+
+== A note on asynchronous queries
+
+To request an emission estimate asynchronously, simply pass an URL as the <tt>:callback</tt> option to <tt>#emission</tt>:
+
+    > RentalCar.new.emission :callback => http://example.com/my/callback/handler
+
+A good way to test this is to set up a {PostBin}[http://postbin.org].
+
+== A note on exceptions
 
 Since this gem connects to a web service, you need to be ready for network problems and latency. For example:
 
@@ -89,14 +105,6 @@ Since this gem connects to a web service, you need to be ready for network probl
       # Please contact us at staff@brighterplanet.com if you see too many of these.
     end
 
-== API keys
-
-You should get an API key from http://keys.brighterplanet.com and set it globally:
-
-    Carbon.key = '12903019230128310293'
-
-Now all of your queries will use that key.
-
 == Copyright
 
 Copyright (c) 2010 Brighter Planet.

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.2.1

data/carbon.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{carbon}
-  s.version = "0.2.0"
+  s.version = "0.2.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Derek Kastner", "Seamus Abshere", "Andy Rossmeissl"]

data/lib/carbon.rb

@@ -51,6 +51,8 @@ module Carbon
   end
   class RateLimited < RuntimeError # :nodoc:
   end
+  class TriedToUseAsyncResponseAsNumber < RuntimeError # :nodoc:
+  end
 
   # The api key obtained from http://keys.brighterplanet.com
   mattr_accessor :key

data/lib/carbon/base.rb

@@ -23,7 +23,7 @@ module Carbon
     #
     # Two general rules:
     # * Take note of what Brighter Planet expects to receive. If you send <tt>fuel_economy</tt> and we're expecting <tt>fuel_efficiency</tt>, we won't understand! (Hint: use the <tt>:as</tt> option.)
-    # * Make sure <tt>#to_param</tt> is set up. The gem always calls <tt>#to_param</tt> before sending, so that's your change to key things by "EPA code" (fictional) or whatever else you want. (Hint: use the <tt>:key</tt> option.)
+    # * Make sure <tt>#to_characteristic</tt> or <tt>#to_param</tt> is set up. The gem always calls one of these (it will try <tt>#to_characteristic</tt> first) before sending, so that's your change to key things by "EPA code" (fictional) or whatever else you want. (Hint: use the <tt>:key</tt> option.)
     #
     # There are two optional parameters:
     # * <tt>:as</tt> - if Brighter Planet expects <tt>fuel_efficiency</tt>, and you say <tt>mpg</tt>, you can write <tt>provide :mpg, :as => :fuel_efficiency</tt>. This will result in a query like <tt>?fuel_efficiency=XYZ</tt>.
@@ -37,7 +37,7 @@ module Carbon
     #      provide :manufacturer, :as => :make, :key => :epa_code      # make[epa_code]=my_car.manufacturer.to_param
     #    end
     #
-    # Note that no matter what you send to us, the gem always calls <b>to_param</b> on the emitter. In this example, it's up to you to make sure my_car.manufacturer.to_param returns an epa_code.
+    # Note that no matter what you send to us, the gem always calls <b><tt>#to_characteristic</tt></b> (or, failing that, <tt>#to_param</tt>) on the emitter. In this example, it's up to you to make sure my_car.manufacturer.to_param returns an epa_code.
     def provide(attr_name, options = {})
       options = options.symbolize_keys
       characteristic = if options.has_key? :as

data/lib/carbon/emission_estimate.rb

@@ -2,7 +2,9 @@ require 'carbon/emission_estimate/response'
 require 'carbon/emission_estimate/request'
 
 module Carbon
-  # Let's start off by saying that <tt>EmissionEstimate</tt> objects quack like numbers.
+  # Let's start off by saying that realtime <tt>EmissionEstimate</tt> objects quack like numbers.
+  #
+  # If you ask for a callback, on the other hand, you can't use them as numbers.
   #
   # So, you can just say <tt>my_car.emission</tt> and you'll get something like <tt>4308.29</tt>.
   #
@@ -14,16 +16,17 @@ module Carbon
       @emitter = emitter
     end
     
-    def take_options(options = {})
-      options.each do |k, v|
+    VALID_OPTIONS = [:callback_content_type, :key, :callback, :timeframe]
+    def take_options(options)
+      return if options.blank?
+      options.slice(*VALID_OPTIONS).each do |k, v|
         instance_variable_set "@#{k}", v
       end
     end
 
-    # I can be compared directly to a number.
+    # I can be compared directly to a number, unless I'm an async request.
     def ==(other)
-      case other
-      when Numeric
+      if other.is_a? ::Numeric and mode == :realtime
         other == response.number
       else
         super
@@ -39,8 +42,11 @@ module Carbon
     def method_missing(method_id, *args, &blk)
       if !block_given? and args.empty? and response.data.has_key? method_id.to_s
         response.data[method_id.to_s]
-      else
+      elsif ::Float.method_defined? method_id
+        raise TriedToUseAsyncResponseAsNumber if mode == :async
         response.number.send method_id, *args, &blk
+      else
+        super
       end
     end
 
@@ -50,7 +56,6 @@ module Carbon
     attr_accessor :callback
     attr_accessor :timeframe
     
-    attr_reader :data
     attr_reader :emitter
     def request
       @request ||= Request.new self

data/lib/carbon/emission_estimate/request.rb

@@ -6,27 +6,30 @@ module Carbon
         @parent = parent
       end
       def body
-        send "#{parent.mode}_body"
+        params.to_query
+      end
+      def params
+        send "#{parent.mode}_params"
       end
-      def async_body # :nodoc:
-        params = params
-        params[:emitter] = parent.emitter.class.carbon_base.emitter_common_name
-        params[:callback] = parent.callback
-        params[:callback_content_type] = parent.callback_content_type
+      def async_params # :nodoc:
+        hash = _params
+        hash[:emitter] = parent.emitter.class.carbon_base.emitter_common_name
+        hash[:callback] = parent.callback
+        hash[:callback_content_type] = parent.callback_content_type
         {
           :Action => 'SendMessage',
           :Version => '2009-02-01',
-          :MessageBody => params.to_query
-        }.to_query
+          :MessageBody => hash.to_query
+        }
       end
-      def realtime_body # :nodoc:
-        params.to_query
+      def realtime_params # :nodoc:
+        _params
       end
       # Used internally, but you can look if you want.
       #
       # Returns the params hash that will be send to the emission estimate server.
-      def params
-        params = parent.emitter.class.carbon_base.translation_table.inject({}) do |memo, translation|
+      def _params
+        hash = parent.emitter.class.carbon_base.translation_table.inject({}) do |memo, translation|
           characteristic, key = translation
           if characteristic.is_a? ::Array
             current_value = parent.emitter.send characteristic[0]
@@ -35,8 +38,12 @@ module Carbon
             current_value = parent.emitter.send characteristic
             as = characteristic
           end
-          current_value = current_value.to_param
-          if current_value.present?
+          current_value = begin
+            current_value.to_characteristic
+          rescue NoMethodError
+            current_value.to_param
+          end
+          if current_value.is_a?(FalseClass) or current_value.present?
             if key
               memo[as] ||= {}
               memo[as][key] = current_value
@@ -46,9 +53,9 @@ module Carbon
           end
           memo
         end
-        params[:timeframe] = parent.timeframe if parent.timeframe
-        params[:key] = parent.key if parent.key
-        params
+        hash[:timeframe] = parent.timeframe if parent.timeframe
+        hash[:key] = parent.key if parent.key
+        hash
       end
       def realtime_url # :nodoc:
         "#{::Carbon::REALTIME_URL}/#{parent.emitter.class.carbon_base.emitter_common_name.pluralize}.json"

data/spec/lib/carbon_spec.rb

@@ -1,5 +1,7 @@
 require 'spec_helper'
 
+CALLBACK_URL = 'http://www.postbin.org/1dj0146'
+
 class RentalCar
   include Carbon
   attr_accessor :model, :model_year, :fuel_economy
@@ -26,6 +28,9 @@ class DonutFactory
   class Mixer
     attr_accessor :upc
     def to_param
+      raise "Use #to_characteristic instead please"
+    end
+    def to_characteristic
       upc
     end
   end
@@ -88,6 +93,15 @@ describe Carbon do
       c.emission(:timeframe => Timeframe.new(:year => 2009)).should == 134.599
       c.emission.response.raw_request.object_id.should_not == first_raw_request.object_id
     end
+    
+    it "should recalculate if the callback changes" do
+      c = RentalCar.new
+      c.model = 'Acura'
+      c.emission.should == 134.599
+      first_raw_request = c.emission.response.raw_request
+      c.emission.callback = CALLBACK_URL
+      c.emission.response.raw_request.object_id.should_not == first_raw_request.object_id
+    end
   end
   
   describe 'synchronous (realtime) requests' do
@@ -100,7 +114,7 @@ describe Carbon do
     it 'send complex params' do
       d = DonutFactory.new
       d.mixer.upc = 123
-      d.emission.request.body.should =~ /mixer\[upc\]=123/
+      d.emission.request.body.should include({:mixer => { :upc => 123 }}.to_query)
     end
   
     it 'should not send attributes that are blank' do
@@ -109,6 +123,12 @@ describe Carbon do
       d.emission.request.body.should_not =~ /oven_count/
       d.emission.request.body.should_not =~ /timeframe/
     end
+    
+    it 'should send attributes that are false' do
+      d = DonutFactory.new
+      d.mixer.upc = false
+      d.emission.request.body.should include({:mixer => { :upc => 'false' }}.to_query)
+    end
   
     it 'should send the key' do
       d = DonutFactory.new
@@ -127,30 +147,81 @@ describe Carbon do
       c = RentalCar.new
       t = Timeframe.new(:year => 2009)
       c.emission.timeframe = t
-      c.emission.timeframe.should == t
+      c.emission.request.body.should include(t.to_query(:timeframe))
     end
     
     it 'should accept timeframes inline' do
       c = RentalCar.new
       t = Timeframe.new(:year => 2009)
       c.emission(:timeframe => t)
-      c.emission.timeframe.should == t
+      c.emission.request.body.should include(t.to_query(:timeframe))
     end
   
     it 'should not generate post bodies with lots of empty params' do
       c = RentalCar.new
       c.emission :timeframe => Timeframe.new(:year => 2009)
       c.emission.request.body.should_not include('&&')
+      c.emission.request.body.should_not =~ /=[^a-z0-9]/i
     end
   end
   
   describe 'asynchronous (queued) requests' do
     it 'should post a message to SQS' do
       c = RentalCar.new
-      c.emission.callback = 'http://www.postbin.org/1dj0146'
+      c.emission.callback = CALLBACK_URL
       c.emission.request.url.should =~ /queue.amazonaws.com/
+    end
+    
+    it 'should have nil data in its response' do
+      c = RentalCar.new
+      c.emission.callback = CALLBACK_URL
+      c.emission.emission_value.should be_nil
+      c.emission.emission_units.should be_nil
+      c.emission.methodology.should be_nil
+    end
+    
+    it "should not compare itself to numbers" do
+      c = RentalCar.new
+      c.emission.callback = CALLBACK_URL
+      c.emission.should_not == 0.0
+    end
+    
+    it 'should not allow itself to be treated as a number' do
+      c = RentalCar.new
+      c.emission.callback = CALLBACK_URL
+      lambda {
+        c.emission + 5
+      }.should raise_error(::Carbon::TriedToUseAsyncResponseAsNumber)
+      lambda {
+        c.emission.to_f
+      }.should raise_error(::Carbon::TriedToUseAsyncResponseAsNumber)
+    end
+  end
+  
+  describe 'internally' do
+    it "should ignore invalid options passed to #emission" do
+      c = RentalCar.new
+      t = Timeframe.new(:year => 2009)
+      c.emission :timeframe => t, :method_missing => 'helo there', :response => 'foo'
+      c.emission.instance_variable_get(:@timeframe).object_id.should == t.object_id
+      c.emission.instance_variable_get(:@method_missing).should be_nil
+      c.emission.instance_variable_get(:@response).should be_nil
+    end
+    
+    it "should raise an error on EmissionEstimate if method isn't found" do
+      c = RentalCar.new
+      lambda {
+        c.emission.foobar
+      }.should raise_error(NoMethodError, /EmissionEstimate/)
+    end
+    
+    it "should use #to_characteristic instead of #to_param if it's available" do
+      d = DonutFactory.new
+      lambda {
+        d.mixer.to_param
+      }.should raise_error(RuntimeError, /instead please/)
       lambda {
-        c.emission :timeframe => Timeframe.new(:year => 2009), :callback => 'http://www.postbin.org/1dj0146'
+        d.emission.to_f
       }.should_not raise_error
     end
   end

data/spec/spec_helper.rb

@@ -10,17 +10,20 @@ require 'active_support/json/encoding'
 require 'carbon'
 
 require 'fakeweb'
-{
-  'automobiles' => {
+[
+  [ /http:\/\/carbon.brighterplanet.com\/automobiles/, {
     'emission' => '134.599',
     'emission_units' => 'kilograms',
     'methodology' => 'http://carbon.brighterplanet.com/something'
-  },
-  'factories' => {
+  }.to_json],
+  [ /http:\/\/carbon.brighterplanet.com\/factories/, {
     'emission' => 1000.0,
     'emission_units' => 'kilograms',
     'methodology' => 'http://carbon.brighterplanet.com/something'
-  }
-}.each do |k, v|
-  FakeWeb.register_uri :post, /http:\/\/carbon.brighterplanet.com\/#{k}/, :body => v.to_json
-end
+  }.to_json],
+  [ /https:\/\/queue.amazonaws.com/,
+    'Nothing to see here.']
+].each do |url_matcher, response|
+  FakeWeb.register_uri :post, url_matcher, :body => response
+end
+

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: carbon
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 21
   prerelease: false
   segments: 
   - 0
   - 2
-  - 0
-  version: 0.2.0
+  - 1
+  version: 0.2.1
 platform: ruby
 authors: 
 - Derek Kastner