carbon 0.3.0 → 1.0.0

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec :path => '.'

data/Gemfile.lock

@@ -0,0 +1,45 @@
+PATH
+  remote: .
+  specs:
+    carbon (0.3.0)
+      activesupport (>= 2.3.5)
+      blockenspiel (>= 0.3.2)
+      conversions (~> 1)
+      nap (>= 0.4)
+      timeframe (>= 0.0.7)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activesupport (3.0.0)
+    blockenspiel (0.4.1)
+    conversions (1.4.5)
+      activesupport (>= 2.3.4)
+    diff-lcs (1.1.2)
+    fakeweb (1.3.0)
+    nap (0.4)
+    rspec (2.0.0.rc)
+      rspec-core (= 2.0.0.rc)
+      rspec-expectations (= 2.0.0.rc)
+      rspec-mocks (= 2.0.0.rc)
+    rspec-core (2.0.0.rc)
+    rspec-expectations (2.0.0.rc)
+      diff-lcs (>= 1.1.2)
+    rspec-mocks (2.0.0.rc)
+      rspec-core (= 2.0.0.rc)
+      rspec-expectations (= 2.0.0.rc)
+    timeframe (0.0.8)
+      activesupport (>= 2.3.5)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport (>= 2.3.5)
+  blockenspiel (>= 0.3.2)
+  carbon!
+  conversions (~> 1)
+  fakeweb (>= 1.2.8)
+  nap (>= 0.4)
+  rspec (>= 2.0.0.beta.17)
+  timeframe (>= 0.0.7)

data/MIT-LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2007 Bryan Helmkamp, Seth Fitzsimmons
+Copyright (c) 2010 Brighter Planet, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.rdoc

@@ -1,16 +1,82 @@
 = 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.
+Carbon is a Ruby API wrapper and command-line console 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.
 
-== Full documentation
+Full documentation: {RDoc}[http://rdoc.info/projects/brighterplanet/carbon]
 
-Give the quick start a try! Once you've exhausted that, read the {carbon gem RDoc}[http://rdoc.info/projects/brighterplanet/carbon] for more.
+== Quick start 1: experimenting with the console
 
-== Real-life integration guide
+<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
+
+Then start the console:
+
+    $ carbon
+    carbon->
+
+Provide your key:
+
+    carbon-> key '123ABC'
+      => Using key 123ABC
+      
+Start a flight calculation:
+
+    carbon-> flight
+      => 1210.66889895298 kg CO2e
+    flight*>
+
+Start providing characteristics:
+
+    flight*> origin_airport 'jfk'
+      => 1593.46008200024 kg CO2e
+    flight*> destination_airport 'lax'
+      => 1766.55536727522 kg CO2e
+
+Review what you've entered:
+
+    flight*> characteristics
+      => origin_airport: jfk
+         destination_airport: lax
+
+See how the calculation's being made:
+
+    flight*> methodology
+      => emission: from fuel and passengers with coefficients
+         [ ... ]
+         cohort: from t100
+         
+See intermediate calculations:
+
+    flight*> reports
+      => emission: 1766.55536727522
+         [ ... ]
+         cohort: {"members"=>262}
+
+Generate a methodology URL:
+
+    flight*> url
+      => http://carbon.brighterplanet.com/flights.json?origin_airport=jfk&destination_airport=lax&key=123ABC
+
+And when you're done:
+
+    flight*> done
+      => Saved as flight #0
+    carbon->
 
-In addition to the quick start and full documentation, check out the {integration guide}[http://github.com/brighterplanet/carbon/blob/master/doc/INTEGRATION_GUIDE.rdoc]. It has code examples from our real-life migration followed by brief developer commentary.
+You can recall this flight anytime during this same session:
 
-== Quick start
+    carbon-> flight 0
+      => 1766.55536727522 kg CO2e
+    flight*> characteristics
+      => origin_airport: jfk
+         destination_airport: lax
+         
+For more, see the "Console" section below.
+
+== Quick start 2: using the library in your application
 
 <b>You'll need a Brighter Planet API key. See the "API keys" section below for details.</b>
 
@@ -67,52 +133,59 @@ 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 <tt>#to_characteristic</tt> and <tt>#to_param</tt>
-
-Once you understand how to map attributes using the DSL, you might still be confused about what the gem actually calls on your objects.
+== Attribute serialization
 
-The answer: <tt>#to_characteristic</tt> and, failing that, <tt>#to_param</tt>.
+Your objects' attributes are serialized via <tt>#to_characteristic</tt> or <tt>#to_param</tt> (in that order of preference) before being submitted to the web service. 
 
-Let's say <tt>RentalCar#make</tt> returns a <tt>Make</tt> object. You should define either <tt>Make#to_characteristic</tt> or <tt>Make#to_param</tt>. The gem <b>doesn't know</b> that you want it to call <tt>Make#name</tt> or <tt>Make#epa_code</tt> or anything else.
+For example:
 
-== A note on asynchronous queries
+    class RentalCar < ActiveRecord::Base
+      belongs_to :automobile_make
+      emit_as :automobile do
+        provide :automobile_make, :as => :make
+      end
+    end
+    
+    class AutomobileMake < ActiveRecord::Base # schema includes :name
+      has_many :rental_cars
+      alias :to_characteristic :name
+    end
+    
+Without <tt>AutomobileMake#to_characteristic</tt>, the library would have no way of knowing how to serialize.
 
-To specify that the result of a query should be POSTed back to you, simply pass an URL as the <tt>:callback</tt> option to <tt>#emission_estimate</tt>:
+== Using timeouts
 
-    > RentalCar.new.emission_estimate :callback => 'http://example.com/my/callback/handler'
+    > RentalCar.new.emission_estimate :timeout => 100
+    
+Runs a realtime request but allows timing out the network call. Raises <tt>Timeout::Error</tt> if timeout is exceeded.
 
-A good way to test this is to set up a {PostBin}[http://postbin.org].
+== Persisted queries
 
-You can specify that the result be stored on S3 so that future identical requests can use the same estimate:
+You can specify that the result be persisted in low-latency storage so that future identical requests can use the same estimate:
 
     > RentalCar.new.emission_estimate :guid => 'A_GLOBALLY_UNIQUE_IDENTIFIER_FOR_THIS_EMISSION_ESTIMATE'
 
-You might think of <tt>:guid</tt> as a hash key or a cache key, but it is not necessarily unique to the emitter object... rather it should identify the particular set of characteristics on that emitter. That way other emitters, if they have the same characteristics, can use the same estimate.
+== Asynchronous queries
 
-If you combine <tt>:guid</tt> and <tt>:defer => true</tt>, you have an easy, cheap 2-pass reporting system:
+=== Using a callback
 
-    # pass 1: cron job runs a whole bunch of these
-    > car51.emission_estimate :guid => '[...]', :defer => true
-    > car52.emission_estimate :guid => '[...]', :defer => true
-    > car96.emission_estimate :guid => '[...]', :defer => true
-    
-    # pass 2: a while later, cron job runs these
-    > car51.emission_estimate :guid => '[...]'
-    > car52.emission_estimate :guid => '[...]'
-    > car96.emission_estimate :guid => '[...]'
+To specify that the result of a query should be POSTed back to you, simply pass an URL as the <tt>:callback</tt> option to <tt>#emission_estimate</tt>:
+
+    > RentalCar.new.emission_estimate :callback => 'http://example.com/my/callback/handler'
+
+A good way to test this is to set up a {PostBin}[http://postbin.org].
 
-Most of these will be pre-calculated by the time you run pass #2. If any of them aren't done processing yet, it will revert to a real-time estimate... no big deal!
+=== Using polling
 
-== Possible combinations
+By combining <tt>:guid</tt> and <tt>:defer => true</tt>, you can poll for a result:
 
-* () Runs a normal realtime request.
-* (timeout) Runs a realtime request but allows timing out the network call. Raises <tt>Timeout::Error</tt> if timeout is exceeded.
-* (guid) Runs a realtime request, but first checks if there is a result pre-calculated on S3. Stores result to S3 if there isn't.
-* (callback) Runs an async request (so you don't immediately get the result back). The result will be POSTed to the URL you specify.
-* (guid,defer) Runs an async request (so you don't immediately get the result back). The result will be stored to S3 as <tt>hxxp://storage.carbon.brighterplanet.com/SHA1-hexdigest-of-key+guid</tt>
-* (guid,timeout) (NOT IMPLEMENTED) A hybrid "best effort" request that is as cheap as an async request but will try to return the full result data immediately. It keeps trying S3 until your timeout is exceeded, at which point it's just a normal async request.
+    > batmobile.emission_estimate :guid => '[...]', :defer => true
+    # Do other things . . . and then:
+    > batmobile.emission_estimate :guid => '[...]'
 
-== A note on exceptions
+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:
 
@@ -120,21 +193,42 @@ Since this gem connects to a web service, you need to be ready for network probl
       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, or our servers might be down.
+      # Your internet connection might be down.
     rescue ::Carbon::RateLimited
-      # Realtime mode only.
-      # In order to prevent denial-of-service attacks, our servers rate limit requests.
+      # 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
-      # Realtime mode only.
       # Our server returned a 4XX or 5XX error.
-      # Please contact us at staff@brighterplanet.com if you get these more than a couple times.
+      # Please contact us at staff@brighterplanet.com.
     rescue ::Carbon::QueueingFailed
-      # Async mode only.
       # 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 if you see too many of these.
+      # 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.
+[+key+ _yourkey_]                  Set the {developer key}[http://keys.brighterplanet.com] that should be used for this session. Alternatively, put this key in <tt>~/.carbon_middleware</tt> and it will be auto-selected on console startup.
+[+_emitter_type_+]                 (e.g. +flight+) Enters emitter mode using this emitter type.
+[<tt><i>emitter_type num</i></tt>] (e.g. <tt>flight 0</tt>) Recalls a previous emitter from this session.
+[+exit+]                           Quits.
+  
+=== Emitter mode
+
+[+help+]                               Displays a list of characteristics for this emitter type.
+[<tt><i>characteristic value</i></tt>] (e.g. <tt>origin_airport 'lax'</tt>) Provide a characteristic. Remember, this is Ruby we're dealing with, so strings must be quoted.
+[+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.
+[+done+]                               Saves this emitter and returns to shell mode.
 
 == Copyright
 

data/Rakefile

@@ -10,11 +10,13 @@ begin
     gemspec.email = 'derek.kastner@brighterplanet.com'
     gemspec.homepage = 'http://carbon.brighterplanet.com/libraries'
     gemspec.authors = ['Derek Kastner', 'Seamus Abshere', 'Andy Rossmeissl']
+
+    gemspec.required_ruby_version = '~>1.9.1'
+
     gemspec.add_dependency 'activesupport', '>=2.3.5'
     gemspec.add_dependency 'nap', '>=0.4'
     gemspec.add_dependency 'timeframe', '>=0.0.7'
     # This is still only on Rubyforge
-    gemspec.add_dependency 'SystemTimer', '>=1.2'
     gemspec.add_dependency 'blockenspiel', '>=0.3.2'
     gemspec.add_dependency 'conversions', '~>1'
 

data/VERSION

@@ -1 +1 @@
-0.3.0
+1.0.0

data/carbon.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{carbon}
-  s.version = "0.3.0"
+  s.version = "1.0.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Derek Kastner", "Seamus Abshere", "Andy Rossmeissl"]
-  s.date = %q{2010-10-01}
+  s.date = %q{2010-10-06}
   s.default_executable = %q{carbon}
   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}
@@ -19,6 +19,8 @@ Gem::Specification.new do |s|
   ]
   s.files = [
     ".gitignore",
+     "Gemfile",
+     "Gemfile.lock",
      "MIT-LICENSE.txt",
      "README.rdoc",
      "Rakefile",
@@ -50,6 +52,7 @@ Gem::Specification.new do |s|
   s.homepage = %q{http://carbon.brighterplanet.com/libraries}
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
+  s.required_ruby_version = Gem::Requirement.new("~> 1.9.1")
   s.rubygems_version = %q{1.3.7}
   s.summary = %q{Carbon is a Ruby API wrapper for the Brighter Planet emission estimate web service (http://carbon.brighterplanet.com).}
   s.test_files = [
@@ -66,7 +69,6 @@ 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<SystemTimer>, [">= 1.2"])
       s.add_runtime_dependency(%q<blockenspiel>, [">= 0.3.2"])
       s.add_runtime_dependency(%q<conversions>, ["~> 1"])
       s.add_development_dependency(%q<fakeweb>, [">= 1.2.8"])
@@ -75,7 +77,6 @@ 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<SystemTimer>, [">= 1.2"])
       s.add_dependency(%q<blockenspiel>, [">= 0.3.2"])
       s.add_dependency(%q<conversions>, ["~> 1"])
       s.add_dependency(%q<fakeweb>, [">= 1.2.8"])
@@ -85,7 +86,6 @@ 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<SystemTimer>, [">= 1.2"])
     s.add_dependency(%q<blockenspiel>, [">= 0.3.2"])
     s.add_dependency(%q<conversions>, ["~> 1"])
     s.add_dependency(%q<fakeweb>, [">= 1.2.8"])

data/lib/carbon.rb

@@ -3,8 +3,6 @@ require 'blockenspiel'
 require 'timeframe'
 require 'digest/sha1'
 require 'rest'    # provided by nap gem
-gem 'SystemTimer' # >=1.2, so as not to be confused with system_timer 1.0
-require 'system_timer'
 require 'active_support'
 require 'active_support/version'
 %w{

data/lib/carbon/emission_estimate/response.rb

@@ -43,7 +43,7 @@ module Carbon
       def perform # :nodoc:
         response = nil
         if parent.timeout
-          ::SystemTimer.timeout_after(parent.timeout) do
+          Timeout.timeout(parent.timeout) do
             response = perform_request
           end
         else

metadata

@@ -1,13 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: carbon
 version: !ruby/object:Gem::Version 
-  hash: 19
   prerelease: false
   segments: 
+  - 1
   - 0
-  - 3
   - 0
-  version: 0.3.0
+  version: 1.0.0
 platform: ruby
 authors: 
 - Derek Kastner
@@ -17,7 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-01 00:00:00 -05:00
+date: 2010-10-06 00:00:00 -04:00
 default_executable: carbon
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -28,7 +27,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 9
         segments: 
         - 2
         - 3
@@ -44,7 +42,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
         segments: 
         - 0
         - 4
@@ -59,7 +56,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 17
         segments: 
         - 0
         - 0
@@ -67,76 +63,57 @@ dependencies:
         version: 0.0.7
   type: :runtime
   version_requirements: *id003
-- !ruby/object:Gem::Dependency 
-  name: SystemTimer
-  prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 11
-        segments: 
-        - 1
-        - 2
-        version: "1.2"
-  type: :runtime
-  version_requirements: *id004
 - !ruby/object:Gem::Dependency 
   name: blockenspiel
   prerelease: false
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  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: *id005
+  version_requirements: *id004
 - !ruby/object:Gem::Dependency 
   name: conversions
   prerelease: false
-  requirement: &id006 !ruby/object:Gem::Requirement 
+  requirement: &id005 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        hash: 1
         segments: 
         - 1
         version: "1"
   type: :runtime
-  version_requirements: *id006
+  version_requirements: *id005
 - !ruby/object:Gem::Dependency 
   name: fakeweb
   prerelease: false
-  requirement: &id007 !ruby/object:Gem::Requirement 
+  requirement: &id006 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 15
         segments: 
         - 1
         - 2
         - 8
         version: 1.2.8
   type: :development
-  version_requirements: *id007
+  version_requirements: *id006
 - !ruby/object:Gem::Dependency 
   name: rspec
   prerelease: false
-  requirement: &id008 !ruby/object:Gem::Requirement 
+  requirement: &id007 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 62196417
         segments: 
         - 2
         - 0
@@ -145,7 +122,7 @@ dependencies:
         - 17
         version: 2.0.0.beta.17
   type: :development
-  version_requirements: *id008
+  version_requirements: *id007
 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,6 +133,8 @@ extra_rdoc_files:
 - README.rdoc
 files: 
 - .gitignore
+- Gemfile
+- Gemfile.lock
 - MIT-LICENSE.txt
 - README.rdoc
 - Rakefile
@@ -195,18 +174,18 @@ require_paths:
 required_ruby_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
-  - - ">="
+  - - ~>
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
-      - 0
-      version: "0"
+      - 1
+      - 9
+      - 1
+      version: 1.9.1
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"