Quick start 2: using the library in your application

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
RentalCar that represents a rental car on your lot. (Note that
ActiveRecord models work great with this gem.)

class RentalCar
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 will recognize. In
this case, a review of the available characteristics for Automobile
yields the following map:

If the result isn't available by the time you want it, a standard
synchronous estimate will be provided.

Exceptions

Since this gem connects to a web service, you need to be ready for network
problems and latency. For example:

begin
my_emission = my_car.emission_estimate
rescue ::SocketError, ::EOFError, ::Timeout::Error, ::Errno::ETIMEDOUT, ::Errno::ENETUNREACH, ::Errno::ECONNRESET, ::Errno::ECONNREFUSED
# These are general network errors raised by Net::HTTP.
# Your internet connection might be down.
rescue ::Carbon::RateLimited
# In order to prevent denial-of-service attacks, our servers limit request rates.
# The gem will try up to three times to get an answer back from the server, waiting slightly longer each time.
# If you still get this exception, please contact us at staff@brighterplanet.com and we'll lift your rate.
rescue ::Carbon::RealtimeEstimateFailed
# Our server returned a 4XX or 5XX error.
# Please contact us at staff@brighterplanet.com.
rescue ::Carbon::QueueingFailed
# The gem connects directly to Amazon SQS in order to provide maximum throughput. If that service returns anything other than success, you get this exception.
# Please contact us at staff@brighterplanet.com.
end

Console

This library includes a special console for performing calculations
interactively. Quick Start #1 provides an example session. Here is a
command reference:

Shell mode

help

Displays a list of emitter types.

keyyourkey

Set the developer key that
should be used for this session. Alternatively, put this key in
~/.brighter_planet and it will be auto-selected on console
startup.

emitter_type

(e.g. flight) Enters emitter mode using this emitter type.

emitter_type num

(e.g. flight 0) Recalls a previous emitter from this session.

exit

Quits.

Emitter mode

In Emitter mode, the prompt displays the emitter type in use. If a
timeframe has been set, the timeframe is also included in the prompt.

help

Displays a list of characteristics for this emitter type.

characteristic value

(e.g. origin_airport 'lax') Provide a characteristic.
Remember, this is Ruby we're dealing with, so strings must be quoted.

timeframe

Display the current timeframe in effect on the emission estimate.

timeframe timeframe

(e.g. timeframe '2009-01-01/2010-01-01' or just
timeframe '2009') Set a timeframe on the emission
estimate.

emission

Displays the current emission in kilograms CO2e for this emitter.

lbs, pounds, or tons

Display the emission using different units.

characteristics

Lists the characteristics you have provided so far.

methodology

Summarizes how the calculation is being made.

reports

Displays intermediate calculations that were made in pursuit of the
emission estimate.

url

Generates a methodology URL suitable for pasting into your browser for
further inspection.