carbon 2.0.0 → 2.0.1

data/.gitignore

@@ -3,3 +3,4 @@ Gemfile.lock
 .rvmrc
 .yardoc/
 doc/
+*.gem

data/CHANGELOG

@@ -1,3 +1,13 @@
+2.0.1 / 2012-03-12
+
+* Bug fixes
+
+  * Don't send blank (incl. nil) characteristics
+
+* Documentation changes
+
+  * Recommend people use Object#try when passing a block to #provide
+
 2.0.0 / 2012-03-09
 
 * Breaking changes

data/README.markdown

@@ -82,7 +82,38 @@ For more, see the "Console" section below.
 
 Carbon works by extending any Ruby class to be an emission source. You `include Carbon` and then use the `emit_as` DSL...
 
-{render:Carbon::ClassMethods#emit_as}
+    # see Carbon::ClassMethods#emit_as for more details
+    class MyFlight
+      def airline
+        # ... => MyAirline(:name, :icao_code, ...)
+      end
+      def aircraft
+        # ... => MyAircraft(:name, :icao_code, ...)
+      end
+      def origin
+        # ... => String
+      end
+      def destination
+        # ... => String
+      end
+      def segments_per_trip
+        # ... => Integer
+      end
+      def trips
+        # ... => Integer
+      end
+      include Carbon
+      emit_as 'Flight' do
+        provide :segments_per_trip
+        provide :trips
+        provide :origin, :as => :origin_airport, :key => :iata_code
+        provide :destination, :as => :destination_airport, :key => :iata_code
+        provide(:airline, :key => :iata_code) { |f| f.airline.try(:iata_code) }
+        provide(:aircraft, :key => :icao_code) { { |f| f.aircraft.try(:icao_code) }
+      end
+    end
+
+See [RDoc on `Carbon::ClassMethods#emit_as`](http://rdoc.info/github/brighterplanet/carbon/Carbon/ClassMethods#emit_as-instance_method) for all the details.
 
 The final URL will be something like
 
@@ -90,7 +121,18 @@ The final URL will be something like
 
 When you want to calculate impacts, simply call `MyFlight#impact`.
 
-{render:Carbon#impact}
+    ?> my_flight = MyFlight.new([...])
+    => #<MyFlight [...]>
+    ?> my_impact = my_flight.impact(:timeframe => Timeframe.new(:year => 2009))
+    => #<Hashie::Mash [...]>
+    ?> my_impact.decisions.carbon.object.value
+    => 1014.92
+    ?> my_impact.decisions.carbon.object.units
+    => "kilograms"
+    ?> my_impact.methodology
+    => "http://impact.brighterplanet.com/flights?[...]"
+
+See [RDoc on `Carbon#impact`](http://rdoc.info/github/brighterplanet/carbon/Carbon#impact-instance_method) for all the details.
 
 ## API keys
 

data/lib/carbon.rb

@@ -169,8 +169,8 @@ module Carbon
     #       provide :trips
     #       provide :origin, :as => :origin_airport, :key => :iata_code
     #       provide :destination, :as => :destination_airport, :key => :iata_code
-    #       provide(:airline, :key => :iata_code) { |f| f.airline.iata_code }
-    #       provide(:aircraft, :key => :icao_code) { { |f| f.aircraft.icao_code }
+    #       provide(:airline, :key => :iata_code) { |f| f.airline.try(:iata_code) }
+    #       provide(:aircraft, :key => :icao_code) { { |f| f.aircraft.try(:icao_code) }
     #     end
     #   end
     def emit_as(emitter, &blk)
@@ -194,7 +194,9 @@ module Carbon
       else
         send method_id
       end
-      memo[k] = v
+      if v.present?
+        memo[k] = v
+      end
       memo
     end
   end

data/lib/carbon/registry.rb

@@ -2,17 +2,16 @@ require 'singleton'
 
 module Carbon
   # Used internally to hold the information about how each class that has called `emit_as`.
-  # @private
   class Registry < ::Hash
     include ::Singleton
 
     # Used internally to record the emitter and parameters (characteristics) provided by a class that has called `emit_as`.
+    # Can't use my magic sprinkles (::Struct) because of yardoc
     # @private
-    class Registration < ::Struct.new(:emitter, :characteristics)
+    class Registration < Struct.new(:emitter, :characteristics)
     end
 
-    # Used internally when instance-eval'ing the `emit_as` DSL.
-    # @private
+    # Used internally when instance-eval'ing the +emit_as+ DSL.
     class Registrar
       # @private
       def initialize(klass, emitter)
@@ -29,16 +28,20 @@ module Carbon
       # @option translation_options [Symbol] :as (name of the method) If your method name does not match the Brighter Planet characteristic name.
       # @option translation_options [Symbol] :key (a number of columns) What you are keying on. By default, we do a fuzzy match against a number of fields, including full names and various codes.
       #
+      # @return [nil]
+      #
+      # @note It's suggested that you use {http://api.rubyonrails.org/classes/Object.html#method-i-try Object#try} to cheaply avoid +undefined method `iata_code` for nil:NilClass+. It will be available because this class includes +active_support/core_ext+ anyway.
+      #
       # @yield [] Pass a block for the common use case of calling a method on a object.
       #
       # @example Your method is named one thing but should be sent +:as+ something else.
       #   provide :my_distance, :as => :distance
       #
       # @example You are keying on something well-known like {http://en.wikipedia.org/wiki/Airline_codes IATA airline codes}.
-      #   provide(:airline, :key => :iata_code) { |f| f.airline.iata_code }
+      #   provide(:airline, :key => :iata_code) { |f| f.airline.try(:iata_code) }
       #
       # @example Better to use a block
-      #   provide(:airline, :key => :iata_code) { |f| f.airline.iata_code }
+      #   provide(:airline, :key => :iata_code) { |f| f.airline.try(:iata_code) }
       #   # is equivalent to
       #   def airline_iata_code
       #     airline.iata_code

data/lib/carbon/version.rb

@@ -1,3 +1,3 @@
 module Carbon
-  VERSION = "2.0.0"
+  VERSION = "2.0.1"
 end

data/test/carbon_test.rb

@@ -45,12 +45,17 @@ class MyNissanAltima
   def      model; 'Altima'     end
   def model_year; @model_year  end # what BP knows as "year"
   def  fuel_type; 'R'          end # what BP knows as "automobile_fuel" and keys on "code"
+  def   nil_make; nil          end
+  def  nil_model; nil          end
   include Carbon
   emit_as 'Automobile' do
-    provide(:make) { |my_nissan_altima| my_nissan_altima.make.name }
+    provide(:make) { |my_nissan_altima| my_nissan_altima.make.try(:name) }
     provide :model
     provide :model_year, :as => :year
     provide :fuel_type, :as => :automobile_fuel, :key => :code
+    
+    provide(:nil_make) { |my_nissan_altima| my_nissan_altima.nil_make.try(:blam!) }
+    provide :nil_model
   end
 end
 
@@ -147,6 +152,13 @@ describe Carbon do
         Carbon::Registry.instance['MyFoo'].characteristics.keys.must_equal [:model]
       end
     end
+    describe '#impact_params' do
+      it "only takes non-nil params" do
+        a = MyNissanAltima.new(2006)
+        a.impact_params.keys.wont_include :nil_model
+        a.impact_params.keys.wont_include :nil_make
+      end
+    end
     describe '#impact' do
       it "works" do
         impact = MyNissanAltima.new(2006).impact

metadata

@@ -1,132 +1,103 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: carbon
-version: !ruby/object:Gem::Version 
-  hash: 15
+version: !ruby/object:Gem::Version
+  version: 2.0.1
   prerelease: 
-  segments: 
-  - 2
-  - 0
-  - 0
-  version: 2.0.0
 platform: ruby
-authors: 
+authors:
 - Seamus Abshere
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-03-09 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-03-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: em-http-request
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &2153238540 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: activesupport
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: *2153238540
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: &2153260780 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: multi_json
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: *2153260780
+- !ruby/object:Gem::Dependency
+  name: multi_json
+  requirement: &2153260300 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
-  name: hashie
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  version_requirements: *2153260300
+- !ruby/object:Gem::Dependency
+  name: hashie
+  requirement: &2153259860 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id004
-- !ruby/object:Gem::Dependency 
-  name: bombshell
   prerelease: false
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  version_requirements: *2153259860
+- !ruby/object:Gem::Dependency
+  name: bombshell
+  requirement: &2153259340 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id005
-- !ruby/object:Gem::Dependency 
-  name: conversions
   prerelease: false
-  requirement: &id006 !ruby/object:Gem::Requirement 
+  version_requirements: *2153259340
+- !ruby/object:Gem::Dependency
+  name: conversions
+  requirement: &2153258840 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id006
-- !ruby/object:Gem::Dependency 
-  name: brighter_planet_metadata
   prerelease: false
-  requirement: &id007 !ruby/object:Gem::Requirement 
+  version_requirements: *2153258840
+- !ruby/object:Gem::Dependency
+  name: brighter_planet_metadata
+  requirement: &2153258380 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id007
+  prerelease: false
+  version_requirements: *2153258380
 description: Brighter Planet API client for Ruby
-email: 
+email:
 - seamus@abshere.net
 - dkastner@gmail.com
 - andy@rossmeissl.net
-executables: 
+executables:
 - carbon
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - CHANGELOG
 - Gemfile
@@ -146,38 +117,29 @@ files:
 - test/carbon_test.rb
 homepage: https://github.com/brighterplanet/carbon
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+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 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.8.17
+rubygems_version: 1.8.15
 signing_key: 
 specification_version: 3
 summary: Brighter Planet API client for Ruby
-test_files: 
+test_files:
 - features/shell.feature
 - features/support/env.rb
 - test/carbon_test.rb