carbon 0.0.7 → 0.1.1

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/README.rdoc

@@ -0,0 +1,81 @@
+= Carbon
+
+Carbon is a Ruby API wrapper for the {Brighter Planet emission estimate web service}[http://carbon.brighterplanet.com], which is located at 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.
+
+== Quick start
+
+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!)
+
+    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:
+
+    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
+      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.)
+
+    > my_car = RentalCar.new([...])
+    => #<RentalCar [...]>
+    > my_emission = my_car.emission
+    => #<Carbon::EmissionEstimate [...]>
+    > my_emission.to_f
+    => 4919.2
+    > my_emission.emission_units
+    => "kilograms"
+    > my_emission.methodology
+    => "http://carbon.brighterplanet.com/automobiles.html?[...]"
+
+Read the {carbon gem RDoc}[http://rdoc.info/projects/brighterplanet/carbon] for more!
+
+== A note on 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.
+
+== 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

@@ -0,0 +1,58 @@
+require 'rubygems'
+require 'rake'
+
+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.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 'nap', '>=0.4'
+    gemspec.add_dependency 'timeframe', '>=0.0.6'
+
+    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"
+    gemspec.add_development_dependency 'rspec', '>=2.0.0.beta.17'
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "decider #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.1

data/carbon.gemspec

@@ -0,0 +1,67 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{carbon}
+  s.version = "0.1.1"
+
+  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-19}
+  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.email = %q{derek.kastner@brighterplanet.com}
+  s.extra_rdoc_files = [
+    "README.rdoc"
+  ]
+  s.files = [
+    ".gitignore",
+     "MIT-LICENSE.txt",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "carbon.gemspec",
+     "lib/carbon.rb",
+     "lib/carbon/base.rb",
+     "lib/carbon/emission_estimate.rb",
+     "spec/lib/carbon_spec.rb",
+     "spec/spec_helper.rb",
+     "spec/specwatchr"
+  ]
+  s.homepage = %q{http://carbon.brighterplanet.com/libraries}
+  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.test_files = [
+    "spec/lib/carbon_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    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<nap>, [">= 0.4"])
+      s.add_runtime_dependency(%q<timeframe>, [">= 0.0.6"])
+      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<nap>, [">= 0.4"])
+      s.add_dependency(%q<timeframe>, [">= 0.0.6"])
+      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<nap>, [">= 0.4"])
+    s.add_dependency(%q<timeframe>, [">= 0.0.6"])
+    s.add_dependency(%q<fakeweb>, [">= 1.2.8"])
+    s.add_dependency(%q<rspec>, [">= 2.0.0.beta.17"])
+  end
+end
+

data/lib/carbon.rb

@@ -1,29 +1,228 @@
-$:.unshift(File.dirname(__FILE__)) unless $:.include?(File.dirname(__FILE__))
-
-require 'carbon/emitter'
-require 'carbon/emissions_calculation'
+require 'uri'
+require 'blockenspiel'
+require 'rest' # provided by nap gem
+require 'timeframe'
+%w{
+  active_support/core_ext/module/attribute_accessors
+  active_support/core_ext/class/attribute_accessors
+  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|
+  require active_support_3_requirement
+end
+require 'carbon/base'
+require 'carbon/emission_estimate'
 
+# A module (aka mixin) that lets you estimate carbon emissions by querying the {Brighter Planet carbon middleware emission estimate web service}[http://carbon.brighterplanet.com].
+#
+#   class RentalCar
+#     include Carbon
+#     [...]
+#     emit_as :automobile do
+#       provide :make
+#       provide :model
+#       provide :model_year
+#     end
+#   end
+#
+# The DSL consists of the methods <tt>emit_as</tt> and <tt>provide</tt>.
+#
+# In this example, the DSL says:
+# * A rental car emits carbon like an "automobile", which is one of Brighter Planet's recognized emitter classes.
+# * Your implementation can provide up to three data points about a rental car: its make, its model, and its model year (but not necessarily all of them, all the time.)
+#
+# Once you've mixed in <tt>Carbon</tt>, you get the method <tt>emission</tt>, which you can call at any time to request an emission estimate.
 module Carbon
-  class << self
-    def api_key
-      @api_key if defined?(@api_key)
-    end
-    def api_key=(val)
-      @api_key = val
-    end
+  def self.included(klass) # :nodoc:
+    klass.cattr_accessor :carbon_base
+    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:
+  end
+  class QueueingFailed < RuntimeError # :nodoc:
+  end
 
-    def base_url
-      @base_url ||= 'http://carbon.brighterplanet.com'
-    end
-    def base_url=(val)
-      @base_url = val
-    end
+  # The api key obtained from http://keys.brighterplanet.com
+  mattr_accessor :key
 
-    def debug=(val)
-      @debug = val
+  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
+    }
+  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>.
+  module ClassMethods
+    # Indicate that this class "emits as" an <tt>:automobile</tt>, <tt>:flight</tt>, or another of the Brighter Planet emitter classes.
+    #
+    # See the {emission estimate web service use documentation}[http://carbon.brighterplanet.com/use]
+    #
+    # For example,
+    #   emit_as :automobile do
+    #     provide :make
+    #   end
+    def emit_as(emitter_common_name, &block)
+      self.carbon_base ||= ::Carbon::Base.new self, emitter_common_name
+      ::Blockenspiel.invoke block, carbon_base
     end
-    def debug
-      @debug ||= false
+    # 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 = {})
+    options.reverse_merge! ::Carbon.default_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 = {})
+    options.reverse_merge! ::Carbon.default_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.pluralize
+    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)
+    options.reverse_merge! ::Carbon.default_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:
+    response = _carbon_response options
+    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.
+  #
+  # 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.
+  # 
+  # You can use it like a number...
+  #   > my_car.emission + 5.1
+  #   => 415.39
+  # Or you can get information about the response
+  #   > my_car.emission.methodology
+  #   => 'http://carbon.brighterplanet.com/automobiles.html?[...]'
+  #
+  # === 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>: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
+    send "_#{options[:mode]}_emission", options
   end
 end

data/lib/carbon/base.rb

@@ -0,0 +1,52 @@
+module Carbon
+  # You will probably never access this class directly. Instead, you'll touch it through the DSL.
+  #
+  # An instance of this appears on any class that includes <tt>Carbon</tt>.
+  class Base
+    include Blockenspiel::DSL
+    attr_reader :klass
+    attr_reader :emitter_common_name
+    def initialize(klass, emitter_common_name)
+      @klass = klass
+      @emitter_common_name = emitter_common_name.to_s
+    end
+    # A completed translation table will look like:
+    # {[:mixer, :size]=>"mixer_size",
+    # :personnel=>:employees,
+    # :smokestack_size=>"smokestack_size",
+    # :oven_count=>"oven_count",
+    # [:mixer, :wattage]=>"mixer_wattage"}
+    def translation_table # :nodoc:
+      @translation_table ||= Hash.new
+    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.
+    #
+    # 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>.
+    #
+    # 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
+    #    end
+    def provide(attr_name, options = {})
+      options = options.symbolize_keys
+      characteristic = if options.has_key? :of
+        # [ :mixer, :size ]
+        [options[:of], attr_name]
+      else
+        # :oven_count
+        attr_name
+      end
+      # translation_table[[:mixer,:size]] = 'mixer_size'
+      translation_table[characteristic] = options[:as] || Array.wrap(characteristic).join('_')
+    end
+    # japanese-style preferred
+    alias :provides :provide
+  end
+end

data/lib/carbon/emission_estimate.rb

@@ -0,0 +1,58 @@
+module Carbon
+  # Let's start off by saying that <tt>EmissionEstimate</tt> objects quack like numbers.
+  #
+  # So, you can just say <tt>my_car.emission</tt> and you'll get something like <tt>4308.29</tt>.
+  #
+  # At the same time, they contain all the data you get back from the emission estimate web service. For example, you could say <tt>puts my_donut_factor.emission.oven_count</tt> (see the tests) and you'd get back the oven count used in the calculation, if any.
+  # 
+  # 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
+    attr_reader :data
+    def initialize(data)
+      @data = data
+      @number = data['emission'].to_f.freeze
+    end
+    def ==(other) # :nodoc:
+      other == @number
+    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
+    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']
+    end
+    # Errors (and warnings) as reported in the response.
+    # Note: may contain HTML tags like KBD or A
+    def errors
+      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
+    end
+  end
+end

data/spec/lib/carbon_spec.rb

@@ -0,0 +1,109 @@
+require 'spec_helper'
+
+class RentalCar
+  include Carbon
+  attr_accessor :make, :model, :model_year, :fuel_economy
+  emit_as :automobile do
+    provide :make
+    provide :model
+    provide :model_year
+    provide :fuel_efficiency, :as => :fuel_economy
+  end
+end
+
+class DonutFactory
+  include Carbon
+  attr_accessor :smokestack_size, :oven_count, :mixer_size, :mixer_wattage, :employees
+  emit_as :factory do
+    provide :smokestack_size
+    provide :oven_count
+    provide :size, :of => :mixer
+    provide :wattage, :of => :mixer
+    provide :personnel, :as => :employees
+  end
+end
+
+describe Carbon do
+  before(:each) do
+    Carbon.key = 'valid'
+  end
+  
+  it 'should be simple to use' do
+    c = RentalCar.new
+    c.model = 'Acura'
+    c.model_year = 2003
+    c.fuel_economy = 32
+    e = c.emission
+    e.should == 134.599
+    e.emission_units.should == 'kilograms'
+  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
+      d._carbon_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/
+    end
+  
+    it 'should send the key' do
+      d = DonutFactory.new
+      d._carbon_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/
+    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/
+    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('&&')
+    end
+  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.emission :timeframe => Timeframe.new(:year => 2009), :callback => 'http://example.com/callback?id=999'
+    end
+  end
+end
+
+# an average car emits 6 tons of carbon in a year
+# it 'should actually do a request!' do
+#   FakeWeb.clean_registry
+#   c = RentalCar.new
+#   c.emission.to_i.should be_close(5500, 500)
+#   c.emission.emission_units.should == 'kilograms'
+# end
+

data/spec/spec_helper.rb

@@ -0,0 +1,24 @@
+require 'rubygems'
+require 'rspec'
+begin
+  require 'ruby-debug'
+rescue
+end
+
+require 'carbon'
+
+require 'fakeweb'
+{
+  'automobiles' => {
+    'emission' => '134.599',
+    'emission_units' => 'kilograms',
+    'methodology' => 'http://carbon.brighterplanet.com/something'
+  },
+  '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

data/spec/specwatchr

@@ -0,0 +1,60 @@
+# Run me with:
+#
+#   $ watchr specs.watchr.rb
+
+# --------------------------------------------------
+# Convenience Methods
+# --------------------------------------------------
+def all_test_files
+  Dir['spec/**/*_spec.rb'] - ['spec/spec_helper.rb']
+end
+
+def run(cmd)
+  puts "\e[H\e[2J"  #clear console
+  puts(cmd)
+  system(cmd)
+end
+
+def run_all_tests
+  cmd = "spec spec"
+  run(cmd)
+end
+
+def run_spec(file_name)
+  return unless File.exist?(file_name)
+  file_text = File.read(file_name)
+  if file_text =~ /#\s*wip/
+    current_line = 2
+    exec_line = nil
+    file_text.each_line do |line|
+      if line =~ /#\s*wip/
+        exec_line ||= current_line
+      end
+      current_line += 1
+    end
+    run "spec #{file_name}:#{exec_line}"
+  else
+    run "spec #{file_name}"
+  end
+end
+
+# --------------------------------------------------
+# Watchr Rules
+# --------------------------------------------------
+watch('^spec/.+_spec.rb'  ) { |m| run_spec(m[0]) }
+watch('^app/(.+)/(.+)\.rb') { |m| run_spec("spec/#{m[1]}/#{m[2]}_spec.rb") }
+watch('^lib/(.*)\.rb'     ) { |m| run_spec("spec/lib/#{m[1]}_spec.rb") }
+watch('^spec/spec_helper\.rb') { run_all_tests }
+watch('actors_controller') { |m| run "spec spec/controllers" }
+
+# --------------------------------------------------
+# Signal Handling
+# --------------------------------------------------
+# Ctrl-\
+Signal.trap('QUIT') do
+  puts " --- Running all tests ---\n\n"
+  run_all_tests
+end
+
+# Ctrl-C
+Signal.trap('INT') { abort("\n") }

metadata

@@ -1,117 +1,161 @@
 --- !ruby/object:Gem::Specification 
 name: carbon
 version: !ruby/object:Gem::Version 
+  hash: 25
   prerelease: false
   segments: 
   - 0
-  - 0
-  - 7
-  version: 0.0.7
+  - 1
+  - 1
+  version: 0.1.1
 platform: ruby
 authors: 
 - Derek Kastner
+- Seamus Abshere
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2010-04-28 00:00:00 -04:00
+date: 2010-07-19 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: activesupport
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 299253626
         segments: 
+        - 3
+        - 0
         - 0
-        version: "0"
+        - beta2
+        version: 3.0.0.beta2
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
-  name: httparty
+  name: nap
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
         segments: 
         - 0
-        version: "0"
+        - 4
+        version: "0.4"
   type: :runtime
   version_requirements: *id002
 - !ruby/object:Gem::Dependency 
-  name: fakeweb
+  name: timeframe
   prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 19
         segments: 
         - 0
-        version: "0"
-  type: :development
+        - 0
+        - 6
+        version: 0.0.6
+  type: :runtime
   version_requirements: *id003
 - !ruby/object:Gem::Dependency 
-  name: rspec
+  name: fakeweb
   prerelease: false
   requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 15
         segments: 
-        - 0
-        version: "0"
+        - 1
+        - 2
+        - 8
+        version: 1.2.8
   type: :development
   version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 62196417
+        segments: 
+        - 2
+        - 0
+        - 0
+        - beta
+        - 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.
-email: derek@brighterplanet.com
+email: derek.kastner@brighterplanet.com
 executables: []
 
 extensions: []
 
 extra_rdoc_files: 
-- MIT-LICENSE.txt
+- README.rdoc
 files: 
-- lib/carbon/emissions_calculation.rb
-- lib/carbon/emitter/characteristic.rb
-- lib/carbon/emitter/class_methods.rb
-- lib/carbon/emitter/options.rb
-- lib/carbon/emitter.rb
-- lib/carbon.rb
+- .gitignore
 - MIT-LICENSE.txt
+- README.rdoc
+- Rakefile
+- VERSION
+- carbon.gemspec
+- lib/carbon.rb
+- lib/carbon/base.rb
+- lib/carbon/emission_estimate.rb
+- spec/lib/carbon_spec.rb
+- spec/spec_helper.rb
+- spec/specwatchr
 has_rdoc: true
-homepage: 
+homepage: http://carbon.brighterplanet.com/libraries
 licenses: []
 
 post_install_message: 
-rdoc_options: []
-
+rdoc_options: 
+- --charset=UTF-8
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
-      - 1
-      - 3
-      - 1
-      version: 1.3.1
+      - 0
+      version: "0"
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.6
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: A gem for calculating carbon footprints using Brighter Planet's Carbon Middleware service
-test_files: []
-
+test_files: 
+- spec/lib/carbon_spec.rb
+- spec/spec_helper.rb

data/lib/carbon/emissions_calculation.rb

@@ -1,64 +0,0 @@
-require 'uri'
-require 'active_support/inflector'
-require 'httparty'
-
-module Carbon
-  class EmissionsCalculation
-    class NotYetCalculated < StandardError; end
-    class CalculationRequestFailed < StandardError; end
-
-    include HTTParty
-
-    attr_accessor :options, :source
-    attr_reader :value, :methodology_url, :committees
-
-    def initialize(options, source)
-      self.options = options
-      self.source = source
-    end
-
-    def methodology_url
-      raise NotYetCalculated if result.nil?
-      @methodology_url
-    end
-    def value
-      raise NotYetCalculated if result.nil?
-      @value
-    end
-
-    def calculate!
-      fetch_calculation
-      @value = result['emission']
-      @methodology_url = result['methodology']
-      @committees = result['committees']
-    end
-
-  private
-    def result
-      @result
-    end
-
-    def fields
-      fields_hash = options.characteristics.inject({}) do |hsh, characteristic|
-        value = source.send(characteristic.field)
-        hsh[characteristic.name.to_sym] = value if value
-        hsh
-      end
-      { :body => { options.emitter_type => fields_hash } }
-    end
-
-    def fetch_calculation
-      url = URI.join(Carbon.base_url, options.emitter_type.to_s.pluralize)
-      options = fields.merge(:headers => { 'Accept' => 'application/json' }) 
-      response = self.class.post(url.to_s, options)
-
-      unless (200..399).include?(response.code)
-        raise CalculationRequestFailed, response.body
-      end
-
-      puts response.body if Carbon.debug
-
-      @result = JSON.parse(response.body)
-    end
-  end
-end

data/lib/carbon/emitter.rb

@@ -1,18 +0,0 @@
-require 'carbon/emitter/class_methods'
-
-module Carbon
-  module Emitter
-    class NotYetCalculated < StandardError; end
-
-    def self.included(target)
-      target.extend Carbon::Emitter::ClassMethods
-    end
-
-    def emission
-      return @emission unless @emission.nil?
-      @emission = Carbon::EmissionsCalculation.new(self.class.emitter_options, self)
-      @emission.calculate!
-      @emission
-    end
-  end
-end

data/lib/carbon/emitter/characteristic.rb

@@ -1,19 +0,0 @@
-module Carbon
-  module Emitter
-    class Characteristic
-      attr_accessor :name, :field
-
-      def self.from_options_hash(name, options)
-        new(:name => name, :field => options[:with])
-      end
-
-      def initialize(options = {})
-        options.each { |name, value| self.send("#{name}=", value) unless value.nil? }
-      end
-
-      def field
-        @field ||= self.name
-      end
-    end
-  end
-end

data/lib/carbon/emitter/class_methods.rb

@@ -1,20 +0,0 @@
-require 'carbon/emitter/options'
-
-module Carbon
-  module Emitter
-    module ClassMethods
-      def emits_as(emitter_type, &blk)
-        self.emitter_type = emitter_type
-
-        self.emitter_options = Carbon::Emitter::Options.new(emitter_type)
-        self.emitter_options.instance_eval &blk if block_given?
-      end
-
-      def emitter_type; @emitter_type; end
-      def emitter_type=(val); @emitter_type = val; end
-
-      def emitter_options; @emitter_options; end
-      def emitter_options=(val); @emitter_options = val; end
-    end
-  end
-end

data/lib/carbon/emitter/options.rb

@@ -1,30 +0,0 @@
-require 'carbon/emitter/characteristic'
-
-module Carbon
-  module Emitter
-    class Options
-      attr_accessor :emitter_type, :characteristics
-
-      def initialize(emitter_type)
-        self.emitter_type = emitter_type.to_sym
-      end
-
-      def keys
-        characteristics.map { |c| c.name }
-      end
-
-      def [](name)
-        characteristics.find { |c| c.name == name }
-      end
-
-      def characteristics
-        @characteristics ||= []
-      end
-
-      def provides(characteristic_name, options = {})
-        characteristics <<
-          Carbon::Emitter::Characteristic.from_options_hash(characteristic_name, options)
-      end
-    end
-  end
-end