carbon 0.1.4 → 0.1.5

data/README.rdoc

@@ -6,17 +6,19 @@ By querying the web service, it can estimate the carbon emissions of many real-l
 
 == Quick start
 
-First get the gem!
+*You'll need a Brighter Planet API key. See the "API keys" section below for details.*
+
+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 plain Ruby class <tt>RentalCar</tt> that represents a rental car on your lot: (<tt>ActiveRecord</tt> models work fine too!)
+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.)
 
     class RentalCar
       attr_accessor :year, :make, :model, :fuel_efficiency, :daily_distance_average, :purchase_date, :retirement_date
     end
 
-In order to calculate carbon emissions, we need to map the car's relevant attributes to correctly-named characteristics that the {web service}[http://carbon.brighterplanet.com] will recognize:
+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
@@ -32,7 +34,7 @@ In order to calculate carbon emissions, we need to map the car's relevant attrib
       end
     end
 
-When you want to calculate emissions, simply call <tt>RentalCar</tt>#<tt>emission</tt>... (and <b>store the result to a local variable!</b> Otherwise it will make a web service call every time.)
+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.
 
     > my_car = RentalCar.new([...])
     => #<RentalCar [...]>
@@ -44,10 +46,20 @@ When you want to calculate emissions, simply call <tt>RentalCar</tt>#<tt>emissio
     => "kilograms"
     > my_emission.methodology
     => "http://carbon.brighterplanet.com/automobiles.html?[...]"
+    
+=== Asynchronous queries
+
+To request an emission estimate asynchronously, simply pass an URL as the +:callback+ option to +#emission+:
+
+    > 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]
 
-Read the {carbon gem RDoc}[http://rdoc.info/projects/brighterplanet/carbon] for more!
+== Documentation
 
-== Exceptions to watch out for
+Read the {carbon gem RDoc}[http://rdoc.info/projects/brighterplanet/carbon] for more.
+
+== Exceptions
 
 Since this gem connects to a web service, you need to be ready for network problems and latency. For example:
 
@@ -71,7 +83,7 @@ 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
 
-== A note on API keys
+== API keys
 
 You should get an API key from http://keys.brighterplanet.com and set it globally:
 
@@ -79,27 +91,6 @@ You should get an API key from http://keys.brighterplanet.com and set it globall
 
 Now all of your queries will use that key.
 
-== A note on modes
-
-When you send in a query, you have two options for how you want the result back:
-
-* realtime - you get the answer back immediately. More expensive.
-* async - the answer is POSTed back to a URL that you specify. You must have a server waiting for it! Cheaper.
-
-The default is realtime:
-
-    > my_emission = RentalCar.new.emission
-    => #<Carbon::EmissionEstimate [...]>
-
-A good way to test the "async" mode is to set up a {PostBin}[http://postbin.org]
-
-    > RentalCar.new.emission :mode => :async, :callback => 'http://postbin.org/1dj0145'
-    => true # useless, but go check out http://postbin.org/1dj0145
-
-You can set the mode globally with
-
-    Carbon.mode = :async
-
 == Copyright
 
 Copyright (c) 2010 Brighter Planet.

data/Rakefile

@@ -10,12 +10,13 @@ begin
     gemspec.email = 'derek.kastner@brighterplanet.com'
     gemspec.homepage = 'http://carbon.brighterplanet.com/libraries'
     gemspec.authors = ['Derek Kastner', 'Seamus Abshere']
-    gemspec.add_dependency 'activesupport', '>=3.0.0.beta2'
+    gemspec.add_dependency 'activesupport', '>=2.3.5'
     gemspec.add_dependency 'nap', '>=0.4'
-    gemspec.add_dependency 'timeframe', '>=0.0.6'
+    gemspec.add_dependency 'timeframe', '>=0.0.7'
 
     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"
+    # sabshere 7/20/10 this might not work with activesupport 2
     gemspec.add_development_dependency 'rspec', '>=2.0.0.beta.17'
   end
   Jeweler::GemcutterTasks.new
@@ -52,7 +53,7 @@ Rake::RDocTask.new do |rdoc|
   version = File.exist?('VERSION') ? File.read('VERSION') : ""
 
   rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "decider #{version}"
+  rdoc.title = "carbon #{version}"
   rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end

data/VERSION

@@ -1 +1 @@
-0.1.4
+0.1.5

data/carbon.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{carbon}
-  s.version = "0.1.4"
+  s.version = "0.1.5"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Derek Kastner", "Seamus Abshere"]
@@ -44,22 +44,22 @@ Gem::Specification.new do |s|
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<activesupport>, [">= 3.0.0.beta2"])
+      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.6"])
+      s.add_runtime_dependency(%q<timeframe>, [">= 0.0.7"])
       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>, [">= 3.0.0.beta2"])
+      s.add_dependency(%q<activesupport>, [">= 2.3.5"])
       s.add_dependency(%q<nap>, [">= 0.4"])
-      s.add_dependency(%q<timeframe>, [">= 0.0.6"])
+      s.add_dependency(%q<timeframe>, [">= 0.0.7"])
       s.add_dependency(%q<fakeweb>, [">= 1.2.8"])
       s.add_dependency(%q<rspec>, [">= 2.0.0.beta.17"])
     end
   else
-    s.add_dependency(%q<activesupport>, [">= 3.0.0.beta2"])
+    s.add_dependency(%q<activesupport>, [">= 2.3.5"])
     s.add_dependency(%q<nap>, [">= 0.4"])
-    s.add_dependency(%q<timeframe>, [">= 0.0.6"])
+    s.add_dependency(%q<timeframe>, [">= 0.0.7"])
     s.add_dependency(%q<fakeweb>, [">= 1.2.8"])
     s.add_dependency(%q<rspec>, [">= 2.0.0.beta.17"])
   end

data/lib/carbon.rb

@@ -2,6 +2,7 @@ require 'uri'
 require 'blockenspiel'
 require 'rest' # provided by nap gem
 require 'timeframe'
+require 'active_support/version'
 %w{
   active_support/core_ext/module/attribute_accessors
   active_support/core_ext/class/attribute_accessors
@@ -13,7 +14,7 @@ require 'timeframe'
   active_support/json/decoding
 }.each do |active_support_3_requirement|
   require active_support_3_requirement
-end
+end if ActiveSupport::VERSION::MAJOR == 3
 require 'carbon/base'
 require 'carbon/emission_estimate'
 
@@ -42,12 +43,9 @@ module Carbon
     klass.extend ClassMethods
   end
   
-  MODES = [ :realtime, :async ]
   REALTIME_URL = 'http://carbon.brighterplanet.com'
   ASYNC_URL = 'https://queue.amazonaws.com/121562143717/cm1_production_incoming'
   
-  class UnrecognizedMode < ArgumentError # :nodoc:
-  end
   class BlankCallback < ArgumentError # :nodoc:
   end
   class RealtimeEstimateFailed < RuntimeError # :nodoc:
@@ -59,30 +57,15 @@ module Carbon
 
   # The api key obtained from http://keys.brighterplanet.com
   mattr_accessor :key
-
-  mattr_accessor :_mode
-  # Return the current mode. Defaults to <tt>:realtime</tt>.
-  def self.mode
-    _mode || :realtime
-  end
-  # Set the current mode.
-  # * Realtime mode (<tt>:realtime</tt>) means you get the answer back immediately.
-  # * Async mode (<tt>:async</tt>) means the answer will be POSTed back to you at a URL you specify. You must have a server waiting to receive it!
-  def self.mode=(str)
-    self._mode = str.to_sym
-    raise UnrecognizedMode unless MODES.include? mode
-  end
-  
-  def self.default_options # :nodoc:
-    {
-      :key => key,
-      :mode => mode
-    }
+    
+  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>.
+
+  # 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>.
   module ClassMethods
     # Indicate that this class "emits as" an <tt>:automobile</tt>, <tt>:flight</tt>, or another of the Brighter Planet emitter classes.
     #
@@ -108,7 +91,7 @@ module Carbon
   #   > my_car._carbon_request_url
   #   => 'http://carbon.brighterplanet.com/automobiles.json'
   def _carbon_request_url(options = {})
-    options.reverse_merge! ::Carbon.default_options
+    ::Carbon.prepare_options options
     send "_#{options[:mode]}_carbon_request_url"
   end
   
@@ -128,7 +111,7 @@ module Carbon
   #   > my_car._carbon_request_body
   #   => 'fuel_efficiency=41&model=Ford+Taurus'
   def _carbon_request_body(options = {})
-    options.reverse_merge! ::Carbon.default_options
+    ::Carbon.prepare_options options
     send "_#{options[:mode]}_carbon_request_body", options
   end
 
@@ -153,7 +136,7 @@ module Carbon
   #
   # Returns the params hash that will be send to the emission estimate server.
   def _carbon_request_params(options)
-    options.reverse_merge! ::Carbon.default_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
@@ -233,12 +216,11 @@ module Carbon
   # === Options:
   #
   # * <tt>:timeframe</tt> (optional) pass an instance of Timeframe[http://github.com/rossmeissl/timeframe] to request an emission for a specific time period.
-  # * <tt>:callback</tt> (required in <tt>:async</tt> mode, ignored otherwise) where to POST the result when it's been calculated. You need a server waiting for it!
-  # * <tt>:callback_content_type</tt> (optional in <tt>:async</tt> mode, 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>:mode</tt> (optional, overrides general <tt>Carbon</tt>.<tt>mode</tt> setting just for this query) If some of your queries are realtime and some are asynchronous, you can override the setting here.
+  # * <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 = {})
-    options.reverse_merge! ::Carbon.default_options
+    ::Carbon.prepare_options options
     send "_#{options[:mode]}_emission", options
   end
 end

data/spec/lib/carbon_spec.rb

@@ -39,10 +39,6 @@ describe Carbon do
   end
   
   describe 'synchronous (realtime) requests' do
-    before(:each) do
-      Carbon.mode = :realtime
-    end
-    
     it 'should handle complex attributes like mixer[size]' do
       d = DonutFactory.new
       d.mixer_size = 20
@@ -80,20 +76,9 @@ describe Carbon do
   end
   
   describe 'asynchronous (queued) requests' do
-    before(:each) do
-      Carbon.mode = :async
-    end
-    
-    it 'should raise an exception if no callback is provided' do
-      c = RentalCar.new
-      lambda {
-        c.emission :timeframe => Timeframe.new(:year => 2009)
-      }.should raise_error(Carbon::BlankCallback)
-    end
-    
     it 'should post a message to SQS' do
       c = RentalCar.new
-      c._carbon_request_url.should =~ /queue.amazonaws.com/
+      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'
     end
   end

data/spec/spec_helper.rb

@@ -5,6 +5,8 @@ begin
 rescue
 end
 
+require 'active_support/json/encoding'
+
 require 'carbon'
 
 require 'fakeweb'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: carbon
 version: !ruby/object:Gem::Version 
-  hash: 19
+  hash: 17
   prerelease: false
   segments: 
   - 0
   - 1
-  - 4
-  version: 0.1.4
+  - 5
+  version: 0.1.5
 platform: ruby
 authors: 
 - Derek Kastner
@@ -27,13 +27,12 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 299253626
+        hash: 9
         segments: 
+        - 2
         - 3
-        - 0
-        - 0
-        - beta2
-        version: 3.0.0.beta2
+        - 5
+        version: 2.3.5
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
@@ -59,12 +58,12 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 19
+        hash: 17
         segments: 
         - 0
         - 0
-        - 6
-        version: 0.0.6
+        - 7
+        version: 0.0.7
   type: :runtime
   version_requirements: *id003
 - !ruby/object:Gem::Dependency