carbon 0.1.5 → 0.1.6

data/VERSION

@@ -1 +1 @@
-0.1.5
+0.1.6

data/carbon.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{carbon}
-  s.version = "0.1.5"
+  s.version = "0.1.6"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Derek Kastner", "Seamus Abshere"]
@@ -25,6 +25,8 @@ Gem::Specification.new do |s|
      "lib/carbon.rb",
      "lib/carbon/base.rb",
      "lib/carbon/emission_estimate.rb",
+     "lib/carbon/emission_estimate/request.rb",
+     "lib/carbon/emission_estimate/response.rb",
      "spec/lib/carbon_spec.rb",
      "spec/spec_helper.rb",
      "spec/specwatchr"

data/lib/carbon.rb

@@ -46,8 +46,6 @@ module Carbon
   REALTIME_URL = 'http://carbon.brighterplanet.com'
   ASYNC_URL = 'https://queue.amazonaws.com/121562143717/cm1_production_incoming'
   
-  class BlankCallback < ArgumentError # :nodoc:
-  end
   class RealtimeEstimateFailed < RuntimeError # :nodoc:
   end
   class QueueingFailed < RuntimeError # :nodoc:
@@ -58,11 +56,6 @@ module Carbon
   # The api key obtained from http://keys.brighterplanet.com
   mattr_accessor :key
     
-  def self.prepare_options(options) # :nodoc:
-    options[:key] ||= key
-    options[:mode] ||= options.has_key?(:callback) ? :async : :realtime
-  end
-
   # You will probably never access this module directly. Instead, you'll use it through the DSL.
   #
   # It's mixed into any class that includes <tt>Carbon</tt>.
@@ -82,123 +75,6 @@ module Carbon
     # japanese-style preferred
     alias :emits_as :emit_as
   end
-  
-  # Used internally, but you can look if you want.
-  #
-  # Returns the URL to which emissions estimate queries will be POSTed.
-  #
-  # For example:
-  #   > my_car._carbon_request_url
-  #   => 'http://carbon.brighterplanet.com/automobiles.json'
-  def _carbon_request_url(options = {})
-    ::Carbon.prepare_options options
-    send "_#{options[:mode]}_carbon_request_url"
-  end
-  
-  def _realtime_carbon_request_url # :nodoc:
-    "#{::Carbon::REALTIME_URL}/#{self.class.carbon_base.emitter_common_name.pluralize}.json"
-  end
-  
-  def _async_carbon_request_url # :nodoc:
-    ::Carbon::ASYNC_URL
-  end
-  
-  # Used internally, but you can look if you want.
-  #
-  # Returns the request body that will be posted.
-  #
-  # For example:
-  #   > my_car._carbon_request_body
-  #   => 'fuel_efficiency=41&model=Ford+Taurus'
-  def _carbon_request_body(options = {})
-    ::Carbon.prepare_options options
-    send "_#{options[:mode]}_carbon_request_body", options
-  end
-
-  def _async_carbon_request_body(options) # :nodoc:
-    params = _carbon_request_params options
-    params[:emitter] = self.class.carbon_base.emitter_common_name
-    raise ::Carbon::BlankCallback unless options[:callback].present?
-    params[:callback] = options[:callback]
-    params[:callback_content_type] = options[:callback_content_type] || 'application/json'
-    {
-      :Action => 'SendMessage',
-      :Version => '2009-02-01',
-      :MessageBody => params.to_query
-    }.to_query
-  end
-
-  def _realtime_carbon_request_body(options) # :nodoc:
-    _carbon_request_params(options).to_query
-  end
-  
-  # Used internally, but you can look if you want.
-  #
-  # Returns the params hash that will be send to the emission estimate server.
-  def _carbon_request_params(options)
-    ::Carbon.prepare_options options
-    params = self.class.carbon_base.translation_table.inject(Hash.new) do |memo, translation|
-      characteristic, as = translation
-      current_value = send as
-      if current_value.present?
-        if characteristic.is_a? Array                                 # [:mixer, :size]
-          memo[characteristic[0]] ||= Hash.new                        # { :mixer => Hash.new }
-          memo[characteristic[0]][characteristic[1]] = current_value  # { :mixer => { :size => 'foo' }}
-        else                                                          # :oven_count
-          memo[characteristic] = current_value                        # { :oven_count => 'bar' }
-        end
-      end
-      memo
-    end
-    params.merge! options.slice(:timeframe, :key)
-    params
-  end
-
-  def _realtime_emission(options = {}) # :nodoc:
-    attempts = 0
-    begin
-      response = _carbon_response options
-      raise ::Carbon::RateLimited if response.status_code == 403 and response.body =~ /Rate Limit/i
-    rescue ::Carbon::RateLimited
-      if attempts < 4
-        attempts += 1
-        sleep 0.2 * attempts
-        retry
-      else
-        raise $!, "Rate limited #{attempts} time(s) in a row"
-      end
-    end
-    raise ::Carbon::RealtimeEstimateFailed unless response.success?
-    ::Carbon::EmissionEstimate.new ::ActiveSupport::JSON.decode(response.body)
-  end
-  
-  def _async_emission(options = {}) # :nodoc:
-    response = _carbon_response options
-    raise ::Carbon::QueueingFailed unless response.success?
-    true
-  end
-    
-  # Used internally, but you can look if you want.
-  #
-  # Runs the query and returns the raw response body, which will be in JSON.
-  #
-  # For example:
-  #   > my_car._carbon_response.body
-  #   => "{ 'emission' => 410.29, 'emission_units' => 'kilograms', [...] }"
-  def _carbon_response(options = {})
-    @last_carbon_request = ::REST::Request.new :post, ::URI.parse(_carbon_request_url(options)), _carbon_request_body(options), {'Content-Type' => 'application/x-www-form-urlencoded; charset=utf-8'}
-    @last_carbon_response = @last_carbon_request.perform
-  end
-  
-  # Returns an object representing the last emission estimate request.
-  def last_carbon_request
-    @last_carbon_request
-  end
-  
-  # Returns an object representing the last emission estimate response.
-  def last_carbon_response
-    @last_carbon_response
-  end
 
   # Returns an emission estimate.
   #
@@ -219,8 +95,10 @@ module Carbon
   # * <tt>:callback</tt> (optional) where to POST the result when it's been calculated. You need a server waiting for it!
   # * <tt>:callback_content_type</tt> (optional if <tt>:callback</tt> is specified, ignored otherwise) pass a MIME type like 'text/yaml' so we know how to format the result when we send it to your waiting server. Defaults to 'application/json'.
   # * <tt>:key</tt> (optional, overrides general <tt>Carbon</tt>.<tt>key</tt> setting just for this query) If you want to use different API keys for different queries.
-  def emission(options = {})
-    ::Carbon.prepare_options options
-    send "_#{options[:mode]}_emission", options
+  def emission_estimate(options = {})
+    @emission_estimate ||= ::Carbon::EmissionEstimate.new self
+    @emission_estimate.take_options options
+    @emission_estimate
   end
+  alias :emission :emission_estimate
 end

data/lib/carbon/emission_estimate.rb

@@ -1,3 +1,6 @@
+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.
   #
@@ -7,52 +10,86 @@ module Carbon
   # 
   # Note: <b>you need to take care of storing emission estimates to local variables!</b> The gem doesn't cache these for you. Every time you call <tt>emission</tt> it will send another query to the server!
   class EmissionEstimate
+    def initialize(emitter)
+      @emitter = emitter
+    end
+    
+    def take_options(options = {})
+      options.each do |k, v|
+        instance_variable_set "@#{k}", v
+      end
+    end
+
+    # I can be compared directly to a number.
+    def ==(other)
+      case other
+      when Numeric
+        other == response.number
+      else
+        super
+      end
+    end
+
+    # You can ask an EmissionEstimate object for any of the response data provided.
+    # This is useful for characteristics that are unique to an emitter.
+    #
+    # For example:
+    #   > my_car.emission.model
+    #   => 'Ford Taurus'
+    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
+        response.number.send method_id, *args, &blk
+      end
+    end
+
+    attr_writer :callback_content_type
+    attr_writer :key
+
+    attr_accessor :callback
+    attr_accessor :timeframe
+    
     attr_reader :data
-    def initialize(data)
-      @data = data
-      @number = data['emission'].to_f.freeze
+    attr_reader :emitter
+    def request
+      @request ||= Request.new self
+    end
+    # Here's where caching takes place.
+    def response
+      current_params = request.params
+      @response ||= {}
+      return @response[current_params] if @response.has_key? current_params
+      @response[current_params] = Response.new self
+    end
+    def mode
+      callback ? :async : :realtime
+    end
+    def callback_content_type
+      @callback_content_type || 'application/json'
     end
-    def ==(other) # :nodoc:
-      other == @number
+    def key
+      @key || ::Carbon.key
     end
     # Another way to access the emission value.
     # Useful if you don't like treating <tt>EmissionEstimate</tt> objects like <tt>Numeric</tt> objects (even though they do quack like numbers...)
     def emission_value
-      @number
+      response.number
     end
     # The units of the emission.
     def emission_units
-      data['emission_units']
-    end
-    # The Timeframe the emission estimate covers.
-    #   > my_car.emission.timeframe.to_param
-    #   => '2009-01-01/2010-01-01'
-    def timeframe
-      Timeframe.interval data['timeframe']
+      response.data['emission_units']
     end
     # Errors (and warnings) as reported in the response.
     # Note: may contain HTML tags like KBD or A
     def errors
-      data['errors']
+      response.data['errors']
     end
     # The URL of the methodology report indicating how this estimate was calculated.
     #   > my_car.emission.methodology
     #   => 'http://carbon.brighterplanet.com/automobiles.html?[...]'
     def methodology
-      data['methodology']
-    end
-    # You can ask an EmissionEstimate object for any of the response data provided.
-    # This is useful for characteristics that are unique to an emitter.
-    #
-    # For example:
-    #   > my_car.emission.model
-    #   => 'Ford Taurus'
-    def method_missing(method_id, *args, &blk)
-      if !block_given? and args.empty? and data.has_key? method_id.to_s
-        data[method_id.to_s]
-      else
-        @number.send method_id, *args, &blk
-      end
+      response.data['methodology']
     end
   end
 end

data/lib/carbon/emission_estimate/request.rb

@@ -0,0 +1,57 @@
+module Carbon
+  class EmissionEstimate
+    class Request
+      attr_reader :parent
+      def initialize(parent)
+        @parent = parent
+      end
+      def body
+        send "#{parent.mode}_body"
+      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
+        {
+          :Action => 'SendMessage',
+          :Version => '2009-02-01',
+          :MessageBody => params.to_query
+        }.to_query
+      end
+      def realtime_body # :nodoc:
+        params.to_query
+      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|
+          characteristic, as = translation
+          current_value = parent.emitter.send as
+          if current_value.present?
+            if characteristic.is_a? Array                                 # [:mixer, :size]
+              memo[characteristic[0]] ||= {}                              # { :mixer => Hash.new }
+              memo[characteristic[0]][characteristic[1]] = current_value  # { :mixer => { :size => 'foo' }}
+            else                                                          # :oven_count
+              memo[characteristic] = current_value                        # { :oven_count => 'bar' }
+            end
+          end
+          memo
+        end
+        params[:timeframe] = parent.timeframe
+        params[:key] = parent.key
+        params
+      end
+      def realtime_url # :nodoc:
+        "#{::Carbon::REALTIME_URL}/#{parent.emitter.class.carbon_base.emitter_common_name.pluralize}.json"
+      end
+      def async_url # :nodoc:
+        ::Carbon::ASYNC_URL
+      end
+      def url
+        send "#{parent.mode}_url"
+      end
+    end
+  end
+end

data/lib/carbon/emission_estimate/response.rb

@@ -0,0 +1,43 @@
+module Carbon
+  class EmissionEstimate
+    class Response
+      attr_reader :parent
+      attr_reader :data
+      attr_reader :number
+      attr_reader :raw_request
+      attr_reader :raw_response
+      def initialize(parent)
+        @parent = parent
+        send "load_#{parent.mode}_data"
+      end
+      def load_realtime_data # :nodoc:
+        attempts = 0
+        begin
+          response = perform
+          raise ::Carbon::RateLimited if response.status_code == 403 and response.body =~ /Rate Limit/i
+        rescue ::Carbon::RateLimited
+          if attempts < 4
+            attempts += 1
+            sleep 0.2 * attempts
+            retry
+          else
+            raise $!, "Rate limited #{attempts} time(s) in a row"
+          end
+        end
+        raise ::Carbon::RealtimeEstimateFailed unless response.success?
+        @data = ::ActiveSupport::JSON.decode response.body
+        @number = data['emission'].to_f.freeze
+      end
+      def load_async_data # :nodoc:
+        response = perform
+        raise ::Carbon::QueueingFailed unless response.success?
+        @data = {}
+        @number = nil
+      end
+      def perform # :nodoc:
+        @raw_request = ::REST::Request.new :post, ::URI.parse(parent.request.url), parent.request.body, {'Content-Type' => 'application/x-www-form-urlencoded; charset=utf-8'}
+        @raw_response = @raw_request.perform
+      end
+    end
+  end
+end

data/spec/lib/carbon_spec.rb

@@ -33,53 +33,90 @@ describe Carbon do
     c.model = 'Acura'
     c.model_year = 2003
     c.fuel_economy = 32
-    e = c.emission
-    e.should == 134.599
-    e.emission_units.should == 'kilograms'
+    c.emission.should == 134.599
+    c.emission.emission_units.should == 'kilograms'
+  end
+  
+  describe 'caching' do
+    it "should keep around estimates if the parameters don't change" do
+      c = RentalCar.new
+      c.model = 'Acura'
+      c.model_year = 2003
+      c.fuel_economy = 32
+      c.emission.should == 134.599
+      first_raw_request = c.emission.response.raw_request
+      c.emission.should == 134.599
+      c.emission.response.raw_request.object_id.should == first_raw_request.object_id
+    end
+    
+    it "should recalculate if parameters change" do
+      c = RentalCar.new
+      c.model = 'Acura'
+      c.model_year = 2003
+      c.fuel_economy = 32
+      c.emission.should == 134.599
+      first_raw_request = c.emission.response.raw_request
+      c.model = 'Honda'
+      c.emission.should == 134.599
+      c.emission.response.raw_request.object_id.should_not == first_raw_request.object_id
+    end
   end
   
   describe 'synchronous (realtime) requests' do
     it 'should handle complex attributes like mixer[size]' do
       d = DonutFactory.new
       d.mixer_size = 20
-      d._carbon_request_body.should =~ /mixer\[size\]=20/
+      d.emission.request.body.should =~ /mixer\[size\]=20/
     end
   
     it 'should not send attributes that are blank' do
       d = DonutFactory.new
       d.mixer_size = 20
-      d._carbon_request_body.should_not =~ /oven_count/
+      d.emission.request.body.should_not =~ /oven_count/
     end
   
     it 'should send the key' do
       d = DonutFactory.new
-      d._carbon_request_body.should =~ /key=valid/
+      d.emission.request.body.should =~ /key=valid/
     end
     
     it 'should override defaults' do
       d = DonutFactory.new
-      d.emission(:key => 'ADifferentOne')
-      d.last_carbon_request.body.should =~ /key=ADifferentOne/
+      key = 'ADifferentOne'
+      d.emission.key.should == 'valid'
+      d.emission.key = key
+      d.emission.key.should == key
     end
   
     it 'should accept timeframes' do
       c = RentalCar.new
-      c.emission :timeframe => Timeframe.new(:year => 2009)
-      c.last_carbon_request.body.should =~ /timeframe=2009-01-01%2F2010-01-01/
+      t = Timeframe.new(:year => 2009)
+      c.emission.timeframe = t
+      c.emission.timeframe.should == t
+    end
+    
+    it 'should accept timeframes inline' do
+      c = RentalCar.new
+      t = Timeframe.new(:year => 2009)
+      c.emission(:timeframe => t)
+      c.emission.timeframe.should == t
     end
   
     it 'should not generate post bodies with lots of empty params' do
       c = RentalCar.new
       c.emission :timeframe => Timeframe.new(:year => 2009)
-      c.last_carbon_request.body.should_not include('&&')
+      c.emission.request.body.should_not include('&&')
     end
   end
   
   describe 'asynchronous (queued) requests' do
     it 'should post a message to SQS' do
       c = RentalCar.new
-      c._carbon_request_url(:callback => 'http://www.postbin.org/1dj0146').should =~ /queue.amazonaws.com/
-      c.emission :timeframe => Timeframe.new(:year => 2009), :callback => 'http://www.postbin.org/1dj0146'
+      c.emission.callback = 'http://www.postbin.org/1dj0146'
+      c.emission.request.url.should =~ /queue.amazonaws.com/
+      lambda {
+        c.emission :timeframe => Timeframe.new(:year => 2009), :callback => 'http://www.postbin.org/1dj0146'
+      }.should_not raise_error
     end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: carbon
 version: !ruby/object:Gem::Version 
-  hash: 17
+  hash: 23
   prerelease: false
   segments: 
   - 0
   - 1
-  - 5
-  version: 0.1.5
+  - 6
+  version: 0.1.6
 platform: ruby
 authors: 
 - Derek Kastner
@@ -118,6 +118,8 @@ files:
 - lib/carbon.rb
 - lib/carbon/base.rb
 - lib/carbon/emission_estimate.rb
+- lib/carbon/emission_estimate/request.rb
+- lib/carbon/emission_estimate/response.rb
 - spec/lib/carbon_spec.rb
 - spec/spec_helper.rb
 - spec/specwatchr