carbon 0.1.6 → 0.2.0

data/README.rdoc

@@ -6,35 +6,41 @@ By querying the web service, it can estimate the carbon emissions of many real-l
 
 == Quick start
 
-*You'll need a Brighter Planet API key. See the "API keys" section below for details.*
+<b>You'll need a Brighter Planet API key. See the "API keys" section below for details.</b>
 
 First get the gem:
 
     $ gem install carbon
 
-Carbon works by extending any Ruby class you're using to represent an emission source. For instance, let's say you have a Ruby class <tt>RentalCar</tt> that represents a rental car on your lot. (Note that ActiveRecord models work great with carbon.)
+Carbon works by extending any Ruby class you're using to represent an emission source. For instance, let's say you have a Ruby class <tt>RentalCar</tt> that represents a rental car on your lot. (Note that ActiveRecord models work great with this gem.)
 
     class RentalCar
-      attr_accessor :year, :make, :model, :fuel_efficiency, :daily_distance_average, :purchase_date, :retirement_date
+      attr_accessor :model, :model_year, :fuel_economy
+      class Make
+        attr_accessor :name
+        def to_param
+          name
+        end
+      end
+      def make
+        @make ||= Make.new
+      end
     end
 
 In order to calculate carbon emissions, we need to map the car's relevant attributes to characteristics that the {web service}[http://carbon.brighterplanet.com] will recognize. In this case, a review of the available characteristics for Automobile[http://carbon.brighterplanet.com/automobiles/options] yields the following map:
 
     class RentalCar
+      # [...]
       include Carbon
-      [...]
       emit_as :automobile do
-        provide :model_year, :as => :year # you say tomayto, I say tomahto
         provide :make
         provide :model
-        provide :fuel_efficiency
-        provide :daily_distance_estimate, :as => daily_distance_average
-        provide :acquisition, :as => :purchase_date
-        provide :retirement, :as => :retirement_date
+        provide :model_year
+        provide :fuel_economy, :as => :fuel_efficiency
       end
     end
 
-When you want to calculate emissions, simply call <tt>RentalCar</tt>#<tt>emission</tt>. Memoize this method on your class or store the result; <tt>#emision</tt> makes a web service call every time it is invoked.
+When you want to calculate emissions, simply call <tt>RentalCar#emission</tt>.
 
     > my_car = RentalCar.new([...])
     => #<RentalCar [...]>
@@ -49,7 +55,7 @@ When you want to calculate emissions, simply call <tt>RentalCar</tt>#<tt>emissio
     
 === Asynchronous queries
 
-To request an emission estimate asynchronously, simply pass an URL as the +:callback+ option to +#emission+:
+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
 

data/Rakefile

@@ -5,14 +5,15 @@ begin
   require 'jeweler'
   Jeweler::Tasks.new do |gemspec|
     gemspec.name = 'carbon'
-    gemspec.summary = %q{A gem for calculating carbon footprints using Brighter Planet's Carbon Middleware service}
-    gemspec.description = %q{Carbon allows you to easily calculate the carbon footprint of various activities. This is an API for the Brighter Planet Carbon Middleware service.}
+    gemspec.summary = %q{Carbon is a Ruby API wrapper for the Brighter Planet emission estimate web service (http://carbon.brighterplanet.com).}
+    gemspec.description = %q{Carbon is a Ruby API wrapper for the Brighter Planet emission estimate web service (http://carbon.brighterplanet.com). 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.}
     gemspec.email = 'derek.kastner@brighterplanet.com'
     gemspec.homepage = 'http://carbon.brighterplanet.com/libraries'
-    gemspec.authors = ['Derek Kastner', 'Seamus Abshere']
+    gemspec.authors = ['Derek Kastner', 'Seamus Abshere', 'Andy Rossmeissl']
     gemspec.add_dependency 'activesupport', '>=2.3.5'
     gemspec.add_dependency 'nap', '>=0.4'
     gemspec.add_dependency 'timeframe', '>=0.0.7'
+    gemspec.add_dependency 'blockenspiel', '>=0.3.2'
 
     gemspec.add_development_dependency 'fakeweb', '>=1.2.8'
     # sabshere 7/16/10 if you're having trouble running specs, try "rspec spec" and/or "sudo gem install rspec --pre"

data/VERSION

@@ -1 +1 @@
-0.1.6
+0.2.0

data/carbon.gemspec

@@ -5,12 +5,12 @@
 
 Gem::Specification.new do |s|
   s.name = %q{carbon}
-  s.version = "0.1.6"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Derek Kastner", "Seamus Abshere"]
-  s.date = %q{2010-07-20}
-  s.description = %q{Carbon allows you to easily calculate the carbon footprint of various activities. This is an API for the Brighter Planet Carbon Middleware service.}
+  s.authors = ["Derek Kastner", "Seamus Abshere", "Andy Rossmeissl"]
+  s.date = %q{2010-07-21}
+  s.description = %q{Carbon is a Ruby API wrapper for the Brighter Planet emission estimate web service (http://carbon.brighterplanet.com). 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.}
   s.email = %q{derek.kastner@brighterplanet.com}
   s.extra_rdoc_files = [
     "README.rdoc"
@@ -35,7 +35,7 @@ Gem::Specification.new do |s|
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
   s.rubygems_version = %q{1.3.7}
-  s.summary = %q{A gem for calculating carbon footprints using Brighter Planet's Carbon Middleware service}
+  s.summary = %q{Carbon is a Ruby API wrapper for the Brighter Planet emission estimate web service (http://carbon.brighterplanet.com).}
   s.test_files = [
     "spec/lib/carbon_spec.rb",
      "spec/spec_helper.rb"
@@ -49,12 +49,14 @@ Gem::Specification.new do |s|
       s.add_runtime_dependency(%q<activesupport>, [">= 2.3.5"])
       s.add_runtime_dependency(%q<nap>, [">= 0.4"])
       s.add_runtime_dependency(%q<timeframe>, [">= 0.0.7"])
+      s.add_runtime_dependency(%q<blockenspiel>, [">= 0.3.2"])
       s.add_development_dependency(%q<fakeweb>, [">= 1.2.8"])
       s.add_development_dependency(%q<rspec>, [">= 2.0.0.beta.17"])
     else
       s.add_dependency(%q<activesupport>, [">= 2.3.5"])
       s.add_dependency(%q<nap>, [">= 0.4"])
       s.add_dependency(%q<timeframe>, [">= 0.0.7"])
+      s.add_dependency(%q<blockenspiel>, [">= 0.3.2"])
       s.add_dependency(%q<fakeweb>, [">= 1.2.8"])
       s.add_dependency(%q<rspec>, [">= 2.0.0.beta.17"])
     end
@@ -62,6 +64,7 @@ Gem::Specification.new do |s|
     s.add_dependency(%q<activesupport>, [">= 2.3.5"])
     s.add_dependency(%q<nap>, [">= 0.4"])
     s.add_dependency(%q<timeframe>, [">= 0.0.7"])
+    s.add_dependency(%q<blockenspiel>, [">= 0.3.2"])
     s.add_dependency(%q<fakeweb>, [">= 1.2.8"])
     s.add_dependency(%q<rspec>, [">= 2.0.0.beta.17"])
   end

data/lib/carbon.rb

@@ -9,7 +9,6 @@ require 'active_support/version'
   active_support/core_ext/hash/keys
   active_support/core_ext/hash/reverse_merge
   active_support/core_ext/object/to_query
-  active_support/core_ext/array/wrap
   active_support/inflector/inflections
   active_support/json/decoding
 }.each do |active_support_3_requirement|
@@ -78,9 +77,7 @@ module Carbon
 
   # Returns an emission estimate.
   #
-  # Note: <b>You need to take care of storing the return value to a local variable!</b> Every call to <tt>emission</tt> runs a query.
-  #
-  # Note also: please see the README about exceptions that you should watch out for.
+  # Note: please see the README about <b>exceptions that you should watch out for</b>.
   # 
   # You can use it like a number...
   #   > my_car.emission + 5.1

data/lib/carbon/base.rb

@@ -21,30 +21,34 @@ module Carbon
     end
     # Indicate that you will send in a piece of data about the emitter.
     #
-    # If you don't use the <tt>:as</tt> option, the name of the getter method will be guessed.
+    # 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.)
     #
     # There are two optional parameters:
-    # * <tt>:of</tt> - the owner of a nested characteristic. So to send <tt>model[name]</tt> you write <tt>provide :name, :of => :model</tt>
-    # * <tt>:as</tt> - the local getter name. So if Brighter Planet expects <tt>fuel_efficiency</tt>, and you only have <tt>fuel_economy</tt>, you can write <tt>provide :fuel_efficiency, :as => :fuel_economy</tt>.
+    # * <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>.
+    # * <tt>:key</tt> - if Brighter Planet expects a make's name ("Nissan") and you want to look things up by (fictional) "EPA code", you could say <tt>provide :make, :key => :epa_code</tt>. This will result in a query like <tt>?make[epa_code]=ABC</tt>.
     #
-    # For example:
-    #
-    #    emit_as :automobile do
-    #                                                       # Official Brighter Planet characteristic name       Your name for it
-    #      provide :model, :as => :carline_class            # model                                              carline_class
-    #      provide :name,  :of => :make, :as => :mfr_name   # make[name]                                         mfr_name
+    #                                                                  # What's sent to Brighter Planet
+    #    emit_as :automobile do                                        
+    #      provide :mpg,  :as => :fuel_efficiency                      # fuel_efficiency=my_car.mpg.to_param
+    #      provide :make, :key => :epa_code                            # make[epa_code]=my_car.make.to_param
+    #      # or really shaking things up...
+    #      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.
     def provide(attr_name, options = {})
       options = options.symbolize_keys
-      characteristic = if options.has_key? :of
-        # [ :mixer, :size ]
-        [options[:of], attr_name]
+      characteristic = if options.has_key? :as
+        # [ :mpg, :fuel_efficiency ]
+        [attr_name, options[:as]]
       else
-        # :oven_count
+        # :make
         attr_name
       end
-      # translation_table[[:mixer,:size]] = 'mixer_size'
-      translation_table[characteristic] = options[:as] || Array.wrap(characteristic).join('_')
+      # translation_table[:make] = 'epa_code'
+      translation_table[characteristic] = options[:key]
     end
     # japanese-style preferred
     alias :provides :provide

data/lib/carbon/emission_estimate/request.rb

@@ -27,20 +27,27 @@ module Carbon
       # 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
+          characteristic, key = translation
+          if characteristic.is_a? ::Array
+            current_value = parent.emitter.send characteristic[0]
+            as = characteristic[1]
+          else
+            current_value = parent.emitter.send characteristic
+            as = characteristic
+          end
+          current_value = current_value.to_param
           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' }
+            if key
+              memo[as] ||= {}
+              memo[as][key] = current_value
+            else
+              memo[as] = current_value
             end
           end
           memo
         end
-        params[:timeframe] = parent.timeframe
-        params[:key] = parent.key
+        params[:timeframe] = parent.timeframe if parent.timeframe
+        params[:key] = parent.key if parent.key
         params
       end
       def realtime_url # :nodoc:

data/spec/lib/carbon_spec.rb

@@ -2,24 +2,41 @@ require 'spec_helper'
 
 class RentalCar
   include Carbon
-  attr_accessor :make, :model, :model_year, :fuel_economy
+  attr_accessor :model, :model_year, :fuel_economy
+  class Make
+    attr_accessor :name
+    def to_param
+      name
+    end
+  end
+  def make
+    @make ||= Make.new
+  end
   emit_as :automobile do
     provide :make
     provide :model
     provide :model_year
-    provide :fuel_efficiency, :as => :fuel_economy
+    provide :fuel_economy, :as => :fuel_efficiency
   end
 end
 
 class DonutFactory
   include Carbon
-  attr_accessor :smokestack_size, :oven_count, :mixer_size, :mixer_wattage, :employees
+  attr_accessor :smokestack_size, :oven_count, :employees
+  class Mixer
+    attr_accessor :upc
+    def to_param
+      upc
+    end
+  end
+  def mixer
+    @mixer ||= Mixer.new
+  end
   emit_as :factory do
     provide :smokestack_size
     provide :oven_count
-    provide :size, :of => :mixer
-    provide :wattage, :of => :mixer
-    provide :personnel, :as => :employees
+    provide :employees, :as => :personnel
+    provide :mixer, :key => :upc
   end
 end
 
@@ -60,19 +77,37 @@ describe Carbon do
       c.emission.should == 134.599
       c.emission.response.raw_request.object_id.should_not == first_raw_request.object_id
     end
+    
+    it "should recalculate if parameters change (though the options hash)" 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(:timeframe => Timeframe.new(:year => 2009)).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
+    it 'should send simple params' do
+      d = DonutFactory.new
+      d.oven_count = 12_000
+      d.emission.request.body.should =~ /oven_count=12000/
+    end
+    
+    it 'send complex params' do
       d = DonutFactory.new
-      d.mixer_size = 20
-      d.emission.request.body.should =~ /mixer\[size\]=20/
+      d.mixer.upc = 123
+      d.emission.request.body.should =~ /mixer\[upc\]=123/
     end
   
     it 'should not send attributes that are blank' do
       d = DonutFactory.new
-      d.mixer_size = 20
+      d.mixer.upc = 123
       d.emission.request.body.should_not =~ /oven_count/
+      d.emission.request.body.should_not =~ /timeframe/
     end
   
     it 'should send the key' do

metadata

@@ -5,18 +5,19 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 1
-  - 6
-  version: 0.1.6
+  - 2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Derek Kastner
 - Seamus Abshere
+- Andy Rossmeissl
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2010-07-20 00:00:00 -05:00
+date: 2010-07-21 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -67,9 +68,25 @@ dependencies:
   type: :runtime
   version_requirements: *id003
 - !ruby/object:Gem::Dependency 
-  name: fakeweb
+  name: blockenspiel
   prerelease: false
   requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 0
+        - 3
+        - 2
+        version: 0.3.2
+  type: :runtime
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: fakeweb
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -81,11 +98,11 @@ dependencies:
         - 8
         version: 1.2.8
   type: :development
-  version_requirements: *id004
+  version_requirements: *id005
 - !ruby/object:Gem::Dependency 
   name: rspec
   prerelease: false
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  requirement: &id006 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -99,8 +116,8 @@ dependencies:
         - 17
         version: 2.0.0.beta.17
   type: :development
-  version_requirements: *id005
-description: Carbon allows you to easily calculate the carbon footprint of various activities. This is an API for the Brighter Planet Carbon Middleware service.
+  version_requirements: *id006
+description: Carbon is a Ruby API wrapper for the Brighter Planet emission estimate web service (http://carbon.brighterplanet.com). 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.
 email: derek.kastner@brighterplanet.com
 executables: []
 
@@ -156,7 +173,7 @@ rubyforge_project:
 rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
-summary: A gem for calculating carbon footprints using Brighter Planet's Carbon Middleware service
+summary: Carbon is a Ruby API wrapper for the Brighter Planet emission estimate web service (http://carbon.brighterplanet.com).
 test_files: 
 - spec/lib/carbon_spec.rb
 - spec/spec_helper.rb