carbon 1.1.3 → 2.0.0

data/doc/shell_example

@@ -1,43 +0,0 @@
-carbon> key '123abc'
-  => Using key 123abc
-carbon> help
-  => flight, automobile, ...
-carbon> flight
-  => 974 kg CO2e
-flight> lbs
-  => 123 lbs CO2e
-flight> tons
-  => 1 ton CO2e
-flight> help
-  => origin_airport, destination_airport . . .
-flight> origin_airport 'lax'
-  => 1123 kg CO2e
-flight> destination_airport 'jfk'
-  => 1375 kg CO2e
-flight> characteristics
-  => Origin airport: JFK
-     Destination airport: JFK
-flight> methodology
-  => Emission: from foo and bar
-     Foo: from baz
-     Bar: default
-flight> url
-  => http://carbon.brighterplanet.com/flights?key=123abc&origin_airport[iata_code]=lax&destination_airport[iata_code]=jfk
-flight> done
-  => Origin airport: JFK
-     Destination airport: JFK
-     1375 kg CO2e
-     http://carbon.brighterplanet.com/flights?key=123abc&origin_airport[iata_code]=lax&destination_airport[iata_code]=jfk
-     Saved as flight #1
-carbon> flight 1
-  => Origin airport: JFK
-     Destination airport: JFK
-     1375 kg CO2e
-flight> done
-  => Origin airport: JFK
-     Destination airport: JFK
-     1375 kg CO2e
-     http://carbon.brighterplanet.com/flights?key=123abc&origin_airport[iata_code]=lax&destination_airport[iata_code]=jfk
-     Saved as flight #1
-carbon> exit
-$

data/lib/carbon/base.rb

@@ -1,62 +0,0 @@
-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 :emitter_common_name
-    
-    def initialize(emitter_common_name)
-      @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
-    
-    def reset_translation_table! #:nodoc:
-      @translation_table = Hash.new
-    end
-
-    # Indicate that you will send in a piece of data about the emitter.
-    #
-    # 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_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>.
-    # * <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>.
-    #
-    #                                                                  # 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><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
-        # [ :mpg, :fuel_efficiency ]
-        [attr_name, options[:as]]
-      else
-        # :make
-        attr_name
-      end
-      # translation_table[:make] = 'epa_code'
-      translation_table[characteristic] = options[:key]
-    end
-
-    # Third-person singular preferred.
-    alias :provides :provide
-  end
-end

data/lib/carbon/emission_estimate.rb

@@ -1,165 +0,0 @@
-module Carbon
-  # 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_estimate.to_s</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_estimate.oven_count</tt> (see the tests) and you'd get back the oven count used in the calculation, if any.
-  class EmissionEstimate
-    autoload :Response, 'carbon/emission_estimate/response'
-    autoload :Request, 'carbon/emission_estimate/request'
-    autoload :Storage, 'carbon/emission_estimate/storage'
-    
-    def self.parse(str) #:nodoc:
-      data = ::ActiveSupport::JSON.decode str
-      if data.has_key? 'active_subtimeframe'
-        interval = "#{data['active_subtimeframe']['startDate']}/#{data['active_subtimeframe']['endDate']}"
-        data['active_subtimeframe'] = Timeframe.interval(interval)
-      end
-      data['updated_at'] = ::Time.parse(data['updated_at']) if data.has_key?('updated_at') and data['updated_at'].is_a?(::String)
-      data
-    end
-
-    attr_writer :callback_content_type
-    attr_writer :key
-    attr_writer :timeout
-    attr_writer :defer
-    attr_accessor :callback
-    attr_accessor :timeframe
-    attr_accessor :certified
-    attr_accessor :guid
-    attr_accessor :comply
-    attr_reader :emitter
-    
-    def initialize(emitter, options = {})
-      @emitter = emitter
-      take_options options unless options.empty?
-    end
-    
-    VALID_OPTIONS = [:callback_content_type, :key, :callback, :timeframe, :guid, :timeout, :defer, :certified, :comply]
-    
-    def take_options(options) #:nodoc:
-      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, unless I'm an async request.
-    def ==(other)
-      if other.is_a? ::Numeric and mode == :realtime
-        other == 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_estimate.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]
-      elsif ::Float.method_defined? method_id
-        raise TriedToUseAsyncResponseAsNumber if mode == :async
-        number.send method_id, *args, &blk
-      else
-        super
-      end
-    end
-    
-    def data #:nodoc:
-      if storage.present?
-        storage.data
-      else
-        response.data
-      end
-    end
-
-    def storage #:nodoc:
-      @storage ||= {}
-      return @storage[guid] if @storage.has_key? guid
-      @storage[guid] = Storage.new self
-    end
-
-    def request #:nodoc:
-      @request ||= Request.new self
-    end
-
-    # Here's where caching takes place.
-    def response #:nodoc:
-      current_params = request.params
-      @response ||= {}
-      return @response[current_params] if @response.has_key? current_params
-      response_object = Response.new self
-      response_object.load_data
-      @response[current_params] = response_object
-    end
-
-    def certified? #:nodoc:
-      !!certified
-    end
-
-    def defer? #:nodoc:
-      @defer == true
-    end
-
-    def async? #:nodoc:
-      callback or defer?
-    end
-
-    def mode #:nodoc:
-      async? ? :async : :realtime
-    end
-
-    # Timeout on realtime requests in seconds, if desired.
-    def timeout
-      @timeout
-    end
-
-    def callback_content_type
-      @callback_content_type || 'application/json'
-    end
-
-    def key
-      @key || ::Carbon.key
-    end
-
-    # The timeframe being looked at in the emission calculation.
-    def active_subtimeframe
-      data['active_subtimeframe']
-    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 number
-      async? ? nil : data['emission'].to_f.freeze
-    end
-
-    # The units of the emission.
-    def emission_units
-      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']
-    end
-
-    # The URL of the methodology report indicating how this estimate was calculated.
-    #   > my_car.emission_estimate.methodology
-    #   => 'http://carbon.brighterplanet.com/automobiles.html?[...]'
-    def methodology
-      data['methodology']
-    end
-    
-    def reports
-      data['reports']
-    end
-  end
-end

data/lib/carbon/emission_estimate/request.rb

@@ -1,100 +0,0 @@
-module Carbon
-  class EmissionEstimate
-    class Request #:nodoc:all
-      attr_reader :parent
-
-      def initialize(parent)
-        @parent = parent
-      end
-
-      def body
-        params.to_query
-      end
-
-      def params
-        params = send "#{parent.mode}_params"
-        validate params
-        params
-      end
-
-      def validate(params_hash)
-        unless params_hash.key? :key
-          Carbon.warn 'You have not specified an API key. Please obtain a key from http://keys.brighterplanet.com.'
-        end
-      end
-
-      def async_params
-        raise ::ArgumentError, "When using :callback you cannot specify :defer" if parent.defer? and parent.callback
-        raise ::ArgumentError, "When using :defer => true you must specify :guid" if parent.defer? and parent.guid.blank?
-        hash = _params
-        hash[:emitter] = parent.emitter.class.carbon_base.emitter_common_name
-        hash[:callback] = parent.callback if parent.callback
-        hash[:callback_content_type] = parent.callback_content_type if parent.callback
-        hash[:guid] = parent.guid if parent.defer?
-        {
-          :Action => 'SendMessage',
-          :Version => '2009-02-01',
-          :MessageBody => hash.to_query
-        }
-      end
-
-      def realtime_params
-        _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
-        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]
-            as = characteristic[1]
-          else
-            current_value = parent.emitter.send characteristic
-            as = characteristic
-          end
-          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
-            else
-              memo[as] = current_value
-            end
-          end
-          memo
-        end
-        hash[:timeframe] = parent.timeframe if parent.timeframe
-        hash[:key] = parent.key if parent.key
-        hash[:comply] = parent.comply if parent.comply
-        hash
-      end
-
-      def realtime_url
-        uri = ::URI.parse ''
-        uri.scheme = 'http'
-        uri.host = parent.certified? ? 'certified.carbon.brighterplanet.com' : 'carbon.brighterplanet.com'
-        uri.path = "/#{parent.emitter.class.carbon_base.emitter_common_name.pluralize}.json"
-        uri.to_s
-      end
-
-      def async_url
-        uri = ::URI.parse ''
-        uri.scheme = 'https'
-        uri.host = 'queue.amazonaws.com'
-        uri.path = parent.certified? ? '/121562143717/cm1_production_incoming_certified' : '/121562143717/cm1_production_incoming'
-        uri.to_s
-      end
-
-      def url
-        send "#{parent.mode}_url"
-      end
-    end
-  end
-end

data/lib/carbon/emission_estimate/response.rb

@@ -1,61 +0,0 @@
-module Carbon
-  class EmissionEstimate
-    class Response #:nodoc:all
-      attr_reader :parent
-      attr_reader :data
-      attr_reader :raw_request
-      attr_reader :raw_response
-
-      def initialize(parent)
-        @parent = parent
-      end
-
-      def load_data
-        send "load_#{parent.mode}_data"
-      end
-
-    private
-      def load_realtime_data
-        attempts = 0
-        response = nil
-        begin
-          response = perform
-          raise ::Carbon::RateLimited if response.status_code == 403 and response.body =~ /Rate Limit/i  #TODO: Should we expect an HTTP 402: payment required, instead?
-        rescue ::Carbon::RateLimited
-          if attempts < 4
-            attempts += 1
-            sleep 0.2 * attempts
-            retry
-          else
-            raise $!
-          end
-        end
-        raise ::Carbon::RealtimeEstimateFailed unless response.success? #TODO: should we expect 300s as well as 200s? Also, we may want to include response code and body in our exception.
-        @data = ::Carbon::EmissionEstimate.parse response.body
-      end
-
-      def load_async_data
-        response = perform
-        raise ::Carbon::QueueingFailed unless response.success? #TODO: should we expect 300s as well as 200s? Also, we may want to include response code and body in our exception.
-        @data = {}
-      end
-
-      def perform
-        response = nil
-        if parent.timeout
-          Timeout.timeout(parent.timeout) do
-            response = perform_request
-          end
-        else
-          response = perform_request
-        end
-        response
-      end
-
-      def perform_request
-        @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/lib/carbon/emission_estimate/storage.rb

@@ -1,33 +0,0 @@
-module Carbon
-  class EmissionEstimate
-    class Storage #:nodoc:all
-      attr_accessor :parent
-      attr_reader :raw_request
-      attr_reader :raw_response
-
-      def initialize(parent)
-        @parent = parent
-      end
-
-      def url
-        "http://storage.carbon.brighterplanet.com/#{::Digest::SHA1.hexdigest(parent.key+parent.guid)}"
-      end
-
-      def present?
-        parent.guid.present? and data.present?
-      end
-
-      def data
-        return @data[0] if @data.is_a? ::Array
-        @raw_request = ::REST::Request.new :get, ::URI.parse(url)
-        @raw_response = raw_request.perform
-        if raw_response.success?
-          @data = [::Carbon::EmissionEstimate.parse(raw_response.body)]
-        else
-          @data = []
-        end
-        @data[0]
-      end
-    end
-  end
-end