amee_rails_layer 0.3.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

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

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 AMEE UK Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,89 @@
+The rails abstraction layer gem provides a series of common abstractions that are typically used when
+creating rails models that store carbon data in AMEE.  This is an opinionated gem and whilst it will 
+suit a lot of projects well it will not be right for every project.  In those cases use the lower level 
+amee-ruby gem (http://github.com/floppy/amee-ruby).
+
+== Installation
+
+Command line installation:
+
+  sudo gem install amee_rails_layer
+
+== Configuration
+
+For models that store carbon data in AMEE, several additional fields required in the database.  Normally
+these would be:
+  * name (string) - a name for the object, often set by user but can be assigned automatically
+  * amee_profile_item_id (string) - the AMEE profile Item ID used to store the carbon data
+  * carbon_output_cache (float) - the amount of carbon produced
+  * units (string) - the units the amount field is in
+  * amount (float) - the amount of the thing being recorded, eg 6 (kg), 9 (litres)
+with either:
+  * amee_profile (string) - the AMEE profile identifier under which all data is stored
+  * or profile_id (integer) - the record id of the model holding the amee_profile (and of course that model to have an amee_profile field)
+Extra fields may also be required depending on the options used.  See AmeeCarbonStore for full details
+
+== Usage
+
+All data in AMEE is stored under a profile and there are two ways to encapsulate this knowledge in your
+application:
+
+1) Models belong_to another object that has the amee_profile.  Exactly what this parent will be called 
+will depend on the application, but common examples will be Project or User.  In this case it is up to
+the developer to add the has_amee_profile declaration to this class.
+
+2) Each model has its own profile.  The has_amee_profile declaration is handled automatically.
+
+The best way to determine which approach to take is to read the AMEE documentation (link at end of 
+README) and see which unit in the application logically maps to an AMEE profile.  In either case the
+model will require an amee_profile field to store the profile identifier.
+
+The models that are to store carbon data in AMEE need the has_carbon_data_stored_in_amee declaration with
+any appropriate options and must implement the amee_category method.  For this, there are two main
+options:
+
+1) If the model is always the same type just return a AmeeCategory with relevant options for where the
+data should be stored in AMEE
+
+2) If the model has multiple types, for example a Journey that can be a Car, Bus Journey etc, a pattern
+like the following can be used:
+   
+   class Journey < ActiveRecord::Base
+     TYPE = {
+       :bus => AmeeCategory.new("Bus", :journey_distance, "/transport/bus/generic/defra", :type => "typical"),
+       :car => AmeeCategory.new("Car", :distance, "/transport/car/generic/defra/bysize", :fuel => "average", :size => "average"),
+       ...
+     }
+
+     def amee_category
+       TYPE[journey_type.to_sym]
+     end
+   end
+     
+Note the need for a column called journey_type in the database to store the type of the Journey.
+
+The database caches the carbon value returned by AMEE to keep the local application fast when
+displaying this data.  As a result of this a cronjob should be run at a regular interval to update
+the carbon value.  This is because AMEE alters the underlying calculations as more accurate data 
+and formulas becomes available.  See AmeeCarbonStore#update_carbon_caches for more details.
+
+Further information on AMEE can be found at: http://my.amee.com/developers
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a future version unintentionally.
+* Commit, do not mess with rakefile, version, or history (if you want to have your own version, that is fine 
+  but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== TODO
+* Integrate rails.rb from amee-ruby   In AmeeCarbonStore has_amee_profile call can be removed from
+  the has_carbon_data_stored_in_amee method and connection_to_amee can be named back to the more
+  logically amee_connection
+* Full test coverage
+
+== Copyright
+
+Copyright (c) 2010 AMEE UK ltd. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "amee_rails_layer"
+    gem.summary = %Q{An abstraction layer for building applications around the AMEE API}
+    gem.description = %Q{We need a longer description of your gem}
+    gem.email = "george.palmer@gmail.com"
+    gem.homepage = "http://github.com/georgepalmer/amee-abstraction-layer-gem"
+    gem.authors = ["George Palmer"]
+    gem.add_development_dependency "amee-ruby", ">= 0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) 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 = "amee-abstraction-layer-gem #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.3.0

data/amee_rails_layer.gemspec

@@ -0,0 +1,58 @@
+# 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{amee_rails_layer}
+  s.version = "0.3.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["George Palmer"]
+  s.date = %q{2010-03-30}
+  s.description = %q{We need a longer description of your gem}
+  s.email = %q{george.palmer@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "amee_rails_layer.gemspec",
+     "lib/amee_rails_layer.rb",
+     "lib/amee_rails_layer/amee_carbon_store.rb",
+     "lib/amee_rails_layer/amee_category.rb",
+     "lib/amee_rails_layer/unit.rb",
+     "rails/init.rb",
+     "test/helper.rb",
+     "test/test_amee-abstraction-layer-gem.rb"
+  ]
+  s.homepage = %q{http://github.com/georgepalmer/amee-abstraction-layer-gem}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{An abstraction layer for building applications around the AMEE API}
+  s.test_files = [
+    "test/helper.rb",
+     "test/test_amee-abstraction-layer-gem.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<amee-ruby>, [">= 0"])
+    else
+      s.add_dependency(%q<amee-ruby>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<amee-ruby>, [">= 0"])
+  end
+end
+

data/lib/amee_rails_layer/amee_carbon_store.rb

@@ -0,0 +1,264 @@
+# Module that abstracts some common patterns for data storage/retrieval in AMEE.  This is 
+# automatically included in ActiveRecord::Base object when used with Rails.  See the gem
+# README for more information on the application structure this gem assumes.
+# 
+# Classes that have the has_carbon_data_stored_in_amee decleartion require the following
+# database columns:
+# * name (string) - a name for the object, often set by user but can be assigned automatically
+# * amee_profile_item_id (string) - the AMEE profile Item ID used to store the carbon data
+# * carbon_output_cache (float) - the amount of carbon produced
+# * units (string) - the units the amount field is in
+# * amount (float) - the amount of the thing being recorded, eg 6 (kg), 9 (litres)
+# * amee_profile (string) - optional.  The amee profile identifier under which all the data
+#   is stored.  Although this field is optional, either this or profile_id is required
+# * profile_id (integer) - optional.  Used when the model belongs_to a parent that has the
+#   amee_profile identifier.  Name is changed according to the :profile option passed into 
+#   the has_carbon_data_stored_in_amee.  Although this field is optional, either this or 
+#   amee_profile is required.
+# * repetitions (integer) - optional.  Used when the model object is composed of several
+#   repetitions - for example 6 x 3 miles would make the repetitions 6  
+# * start_date (date) - optional.  Used in combination with the has_date_range option on
+#   has_carbon_data_stored_in_amee to store the start date for the data
+# * end_date (date) - optional.  Used in combination with the has_date_range option on
+#   has_carbon_data_stored_in_amee to store the end date for the data
+module AmeeCarbonStore
+  def self.included(base)
+    base.extend ClassMethods
+  end
+
+  module ClassMethods
+    # Class method that configures a class for storing carbon data in amee.  Options are as follows:
+    # * profile - if set will use this model (through a belongs_to relationship) to access the amee
+    #   profile to store the data under rather than the model itself.  Pass the model to use as symbol
+    #   - eg :user or :project.  Introduces the need for the profile_id field as described in header
+    #   and the referenced model must store the amee profile key under the field amee_profile (as 
+    #   would be provided by the has_amee_profile decleration)
+    # * nameless - if set then automatically assign the name field so the user doesn't have to
+    #   (still requires the name field in the database as a name must be set to store in amee)
+    # * has_date_range - will check for the presence of a start_date and end_date on the object
+    #   and pass that through to AMEE to store with the data.  Will also check the name is unique 
+    #   given the dates unless used in conjunction with :nameless option (the two together are
+    #   therefore not recommended as it will be easy to create overlapping data).  Requires the 
+    #   start_date and end_date database fields as described in header.
+    # * repetitions - allows repetitions of the data at a database level where AMEE doesn't support
+    #   it natively.  For example multiple journeys can be setup with this option.  The value stored
+    #   in AMEE will be the total for all journeys.  Requires the repetitions database field as 
+    #   described in header.
+    # * singular_types - if using a structure where multiple types are available for a model and 
+    #   the type is stored in the field "#{model}_type", this option enforces that only one instance
+    #   of each type may exist in the database (for a given project if using a project structure)
+    def has_carbon_data_stored_in_amee(options = {})
+      
+      if options[:profile]
+        belongs_to options[:profile]
+      else
+        has_amee_profile
+      end
+      
+      validates_numericality_of :amount
+      validate_on_create :units_are_valid
+      validates_presence_of :start_date, :end_date if options[:has_date_range]
+      unless options[:nameless]
+        if options[:has_date_range]
+          validate :name_is_unique_given_date_range
+        else
+          uniqueness_options = options[:profile] ? {:scope => "#{options[:profile]}_id".to_sym} : {}
+          validates_uniqueness_of :name, uniqueness_options
+        end
+        validates_format_of :name, :with => /\A[\w -]+\Z/, 
+          :message => "must be letters, numbers, spaces or underscores only"
+        validates_length_of :name, :maximum => 250
+      end
+      if options[:singular_types]
+        validate_on_create :maximum_one_instance_for_each_type
+      end
+      if options[:repetitions]
+        validates_numericality_of :repetitions, :only_integer => true
+      end
+      
+      before_create :add_to_amee
+      before_update :update_amee
+      after_destroy :delete_from_amee
+      
+      write_inheritable_attribute(:amee_profile_class, options[:profile]) if options[:profile]
+      write_inheritable_attribute(:repetitions, true) if options[:repetitions]
+      write_inheritable_attribute(:nameless_entries, true) if options[:nameless]
+      write_inheritable_attribute(:has_date_range, true) if options[:has_date_range]
+      
+      include AmeeCarbonStore::InstanceMethods
+    end
+    
+    # This method updates all the carbon caches for instances of this model.  Be aware this may
+    # take some time depending on the number of rows.
+    def update_carbon_caches
+      find(:all).each do |item|
+        item.update_carbon_output_cache
+      end.size
+    end
+  end
+
+  module InstanceMethods
+    # Updates the carbon cache for this instance
+    def update_carbon_output_cache
+      update_attributes(:carbon_output_cache => amee_profile_item.total_amount)
+    end
+    
+    # Returns whether the passed date lies between this instances start and end date.  This is only
+    # useful when using with date ranges - ie has_date_range is passed as option into
+    # has_carbon_data_stored_in_amee
+    def covers_date?(date)
+      start_date <= date && end_date > date
+    end
+
+    protected
+    # The AmeeCategory the model instance is associated with must be returned by this method.  The
+    # version in this module raises an exception so this method must be overriden in the class
+    # including this module.  See README for an examples of how to do this for models that are just
+    # one type and models that can be many types.
+    def amee_category
+      raise "Must be implemented in model"
+    end
+    
+    # Override this method to pass additional options to AMEE on creation of the AMEE profile item
+    # for the model instance.  For example if you were creating an item in /home/waste/lifecycle 
+    # and wanted to set disposalEmissionsOnly as true you could override this method in the model 
+    # with {:disposalEmissionsOnly => true}
+    def additional_options
+      nil
+    end
+    
+    # Override this method when the category type used in AmeeCategory does not result in the 
+    # correct key to store the data against in the AMEE API (the key is looked up from category
+    # type in AmeeCategory::CATEGORY_TYPES).  Normally this lookup would result in values such
+    # as distancePerJourney, mass etc but in some cases it won't be directly inferable from the
+    # category type you want.  If using this for multiple types in a model be sure to only
+    # override when the model type is the correct one and not for all types.
+    # 
+    # For example if you were using /home/waste/lifecyclewaste with waste type "other waste" and
+    # category_type :weight, you might want to specify a landfill amount rather than a mass.  This
+    # could be achieved by overriding this method to return "quantityLandfill".
+    def amount_symbol
+      amee_category.category_type_from_amee_api_unit(get_units)
+    end
+
+    private
+    def units_are_valid
+      errors.add("units", "are not valid") if amount_symbol.nil?
+    end
+    
+    def name_is_unique_given_date_range
+      conditions = amee_profile_class_scoping.merge(:name => self.name)
+      self.class.find(:all, :conditions => conditions).each do |record|
+        next if record.id == self.id
+        unless (self.start_date < record.start_date && self.end_date <= record.start_date) ||
+               (self.start_date >= record.end_date && self.end_date > record.end_date)
+          errors.add_to_base("Entry already added covering dates within that range")
+          return false
+        end
+      end
+    end
+
+    def maximum_one_instance_for_each_type
+      model_type = "#{self.class.name.underscore}_type".to_sym
+      conditions = amee_profile_class_scoping.merge(model_type => send(model_type))
+      if self.class.send(:find, :first, :conditions => conditions)
+        errors.add_to_base "Only one #{amee_category.name} entry allowed"
+      end
+    end
+
+    def add_to_amee
+      profile = create_amee_profile
+      self.amee_profile_item_id = profile.uid
+      self.carbon_output_cache = profile.total_amount
+      return true
+    end
+    
+    def update_amee
+      result = AMEE::Profile::Item.update(connection_to_amee, amee_profile_item_path, 
+        :name => get_name, amount_symbol => get_amount, :get_item => true)
+      self.carbon_output_cache = result.total_amount
+      return true
+    end
+
+    def delete_from_amee
+      AMEE::Profile::Item.delete(connection_to_amee, amee_profile_item_path)
+    rescue Exception => e
+      logger.error "Unable to remove '#{amee_profile_item_path}' from AMEE"
+    end
+
+    def create_amee_profile
+      options = {:name => get_name, amount_symbol => get_amount,
+        amount_unit_symbol => get_units, :get_item => true}
+      if self.class.read_inheritable_attribute(:has_date_range)
+        options.merge!(:start_date => self.start_date, :end_date => self.end_date)
+      end
+      options.merge!(additional_options) if additional_options
+      AMEE::Profile::Item.create(amee_profile_category, amee_data_category_uid, options)
+    end
+
+    # TODO can be renamed to amee_connection once ruby-amee rails lib merged in
+    def connection_to_amee
+      method = self.class.read_inheritable_attribute(:amee_profile_class)
+      method ? send(method).amee_connection : amee_connection
+    end
+    
+    def amee_profile_path
+      method = self.class.read_inheritable_attribute(:amee_profile_class)
+      method ? "/profiles/#{send(method).amee_profile}" : "/profiles/#{amee_profile}"
+    end
+    
+    def amee_profile_class_scoping
+      method = self.class.read_inheritable_attribute(:amee_profile_class)
+      method ? {"#{method}_id".to_sym => send(method).id} : {}
+    end
+
+    def amee_profile_item
+      @amee_profile_item_cache ||= AMEE::Profile::Item.get(connection_to_amee, 
+        amee_profile_item_path)
+    end
+
+    def amee_profile_item_path
+      "#{amee_profile_path}#{amee_category.path}/#{amee_profile_item_id}"
+    end
+    
+    def amee_profile_category
+      AMEE::Profile::Category.get(connection_to_amee, "#{amee_profile_path}#{amee_category.path}")
+    end
+
+    def amee_data_category_uid
+      Rails.cache.fetch("#{DRILLDOWN_CACHE_PREFIX}_#{amee_category.drill_down_path.gsub(/[^\w]/, '')}") do
+        AMEE::Data::DrillDown.get(connection_to_amee, amee_category.drill_down_path).choices.first
+      end
+    end
+
+    def amount_unit_symbol
+      (amount_symbol.to_s + "Unit").to_sym
+    end
+    
+    def get_name
+      self.class.read_inheritable_attribute(:nameless_entries) ? "#{self.class.name}_#{Time.now.to_i}" : self.name
+    end
+    
+    def get_amount      
+      if self.class.read_inheritable_attribute(:repetitions)
+        result = self.amount * self.repetitions
+      else
+        result = self.amount
+      end
+      
+      if amee_category.has_alternative_unit?(self.units)
+        result * amee_category.alternative_unit_conversion_factor(self.units)
+      else
+        result
+      end
+    end
+    
+    def get_units
+      if amee_category.has_alternative_unit?(self.units)
+        amee_category.alternative_unit_converts_to(self.units).to_s
+      else
+        self.units
+      end
+    end
+  end
+end

data/lib/amee_rails_layer/amee_category.rb

@@ -0,0 +1,162 @@
+require 'amee_rails_layer/unit'
+
+# Encapsulates information on the AMEE category used to store data against.  For example, in an 
+# application modelling Car Trips the model would have an AmeeCategory representing the chosen Car
+# Category in AMEE.  In an application with a more generic Journey model with multiple possible 
+# types, the Journey model would have an AmeeCategory for each type that Journey could take - ie 
+# Car, Bus, Van...  In all cases the model will need the amee_category method to return the correct
+# AmeeCategory object as described in AmeeCarbonStore.  See the README for more information on the
+# application structure this gem assumes and examples of how to use it.
+#
+# There are several types the AmeeCategory can be constructed with:
+# * :distance - the total distance (units available are km or mile)
+# * :journey_distance - the distance of the journey (units available are km or miles)
+# * :weight - the total weight (units available are kg or tonned)
+# * :energy - the energy consumed (units available are kWh)
+# * :volumable_energy - the energy consumed specified either as a volume of fuel or energy unit 
+#   (units available are litres or kWh)
+#
+# The CATEGORY_TYPES constant maps these symbols to the corresponding field names used in amee to
+# store the amount of whatever is being specified.  So for a given data item path you must ensure
+# the item value supports the field named there.  For example: assuming we've gone with 
+# :journey_distance as the type and a path of /transport/bus/generic/defra then this would work as 
+# the amount of miles is specified in the distancePerJourney field in amee.  For 
+# /transport/car/generic/defra/bysize however it would not work as the only available field in amee
+# is distance (so the type :distance must be used).
+#
+# The type also determines the units that instances of the model can be created with.  The available 
+# units are specified in the constant CATEGORY_TYPES_TO_UNITS but are also listed in the bullets
+# above above for convience.  Developers can provide additional units by (manually) passing in a 
+# unit conversion factor in the constructor. See the constructor documentation for more on how to
+# do this.
+class AmeeCategory
+  
+  attr_accessor :name, :path
+  
+  CATEGORY_TYPES = {
+    :distance => [:distance],
+    :journey_distance => [:distancePerJourney],
+    :weight => [:mass],
+    :energy => [:energyConsumption],
+    :volumable_energy => [:volumePerTime, :energyConsumption]
+  }
+
+  CATEGORY_TYPES_TO_UNITS = {
+    :distance => [Unit.km, Unit.miles],
+    :distancePerJourney => [Unit.km, Unit.miles],
+    :mass => [Unit.kg, Unit.tonnes],
+    :energyConsumption => [Unit.kwh],
+    :volumePerTime => [Unit.litres],
+  }
+  
+  # Create an AmeeCategory.  The initializer takes the following parameters:
+  # * name - a human readable name to refer to the category by.  This is not used in the storing or
+  #   retrieving of data in amee but is useful for exposing in the view where a user chooses the 
+  #   type they would like for the model
+  # * category_type - either :distance, :journey_distance, :weight, :energy or :volumable_energy.  See 
+  #   notes in class header for more on this
+  # * profile_category_path - the path to the amee category - eg "/transport/car/generic/defra/bysize"
+  # * options - any additional options required with the profile_category_path to make the path 
+  #   refer to just one amee categorgy (typically these are passed in as a query string URL in amee 
+  #   explorer).  For example: {:fuel => "average", :size => "average"}
+  #   
+  #   This option can also take an optional hash for unit conversions, for example:
+  #     :unit_conversions => {:kg => [:m3 => 2.5, :abc => 0.3], :xyz => [:efg => 0.6]}
+  #   which would make m3 available as a unit (converted to kg by * 2.5).  The hash keys, :kg and 
+  #   :xyz in this case, must map to the unit types provided by the corresponding category_type 
+  #   option - ie :kg would work if this option was :weight but not :energy
+  def initialize(name, category_type, profile_category_path, options = {}, *args)
+    @name = name
+    @category_type = category_type
+    @path = profile_category_path
+    @conversions = options.delete(:unit_conversions)
+    @path_options = options
+  end
+  
+  # The drill down path as derived from the path and options arguments in the constructor
+  def drill_down_path
+    "/data#{@path}/drill?#{@path_options.to_query}"
+  end
+
+  # Returns an array of the available unit names and amee api unit string representations.  This
+  # will also include any units provided by the user through the unit_conversions option.  The
+  # resulting array can be passed straight through to a options_for_select view helper.
+  #
+  # For example if the instance is constructed with the :weight category_type option then this 
+  # will produce: [["kg", "kg"], ["tonnes", "t"]]
+  def unit_options
+    unit_options = category_units.map{|unit| [unit.name, unit.amee_api_unit]}
+    unit_options += alternative_unit_options if has_alternative_units?
+    unit_options
+  end
+
+  # Given an AMEE API unit string return the category type
+  def category_type_from_amee_api_unit(amee_unit)
+    category_types.each do |type|
+      return type if amee_api_units(type).include?(amee_unit)
+    end
+    return nil
+  end
+  
+  # For a given unit returns true if the passed unit is an alternative one - ie conversion
+  # factor supplied by user in the constructor
+  def has_alternative_unit?(unit)
+    return false unless has_alternative_units?    
+    units = @conversions.values.map(&:first).map(&:keys).flatten
+    units.include?(unit.to_sym)
+  end
+  
+  # Given an alternative unit, returns the units it converts to
+  def alternative_unit_converts_to(unit_name)
+    units_to_alternates = merge_hashes(@conversions.map {|k,v| {k => v.first.keys}})
+    units_to_alternates.each do |amee_unit, alt_units|
+      return amee_unit if alt_units.include?(unit_name.to_sym)
+    end
+    return nil
+  end
+  
+  # Given an alternative unit, returns the factor needed to convert it to the unit it
+  # can be derived from
+  def alternative_unit_conversion_factor(unit_name)
+    alternative_units_to_conversions.each do |alt_unit, conversion|
+      return conversion if alt_unit == unit_name.to_sym
+    end
+    return nil
+  end
+  
+  private
+  def category_types
+    CATEGORY_TYPES[@category_type]
+  end
+  
+  def category_units
+    category_types.map{|t| CATEGORY_TYPES_TO_UNITS[t]}.flatten
+  end
+  
+  def has_alternative_units?
+    !@conversions.nil?
+  end
+  
+  def amee_api_units(name)
+    CATEGORY_TYPES_TO_UNITS[name].map{|u| u.amee_api_unit}
+  end
+  
+  def alternative_units_to_conversions
+    merge_hashes(@conversions.map {|k,v| v.first})
+  end
+  
+  def alternative_unit_options
+    alternative_units_to_conversions.keys.map {|unit| [unit.to_s, unit.to_s]}
+  end
+  
+  # Does [{:a => 1, :b => 2}, {:c => 3}, {:d => 4}]  to  {:a => 1, :b => 2, :c => 3, :d => 4}
+  def merge_hashes(array_of_hashes)
+    result = {}
+    array_of_hashes.each do |item|
+      item.keys.each do |k|
+        result[k] = item[k]
+      end
+    end
+    result
+  end
+end

data/lib/amee_rails_layer/unit.rb

@@ -0,0 +1,77 @@
+# Encapsulates the Units used by the AMEE API.  Possible types are currently
+# :km, :miles, :kg, :tonnes, :kwh, :litres and :uk_gallons  Convience class
+# methods are provided to construct an object of each of these types
+class Unit
+
+  NAME = {
+    :km => "km",
+    :miles => "miles",
+    :kg => "kg",
+    :tonnes => "tonnes",
+    :kwh => "kWh",
+    :litres => "litres",
+    :uk_gallons => "UK Gallons"
+  }
+
+  AMEE_API_UNITS = {
+    :km => "km",
+    :miles => "mi",
+    :kg => "kg",
+    :tonnes => "t",
+    :kwh => "kWh",
+    :litres => "L",
+    :uk_gallons => "gal_uk"
+  }
+
+  # Creates a new Unit object from the symbol representing the unit (see class doc)
+  def initialize(type, *args)
+    @type = type
+  end
+  
+  # Creates a new Unit class from the string used by AMEE to represent the unit.  For example
+  # pass in "t" to initialize an Unit object for tonnes
+  def self.from_amee_unit(unit)
+    AMEE_API_UNITS.each do |key, value|
+      return new(key) if value == unit
+    end
+    return nil
+  end
+  
+  # A human readable form of the unit
+  def name
+    NAME[@type]
+  end
+  
+  # The string used by the AMEE API to represent the unit
+  def amee_api_unit
+    AMEE_API_UNITS[@type]
+  end
+  
+  def self.km
+    new(:km)
+  end
+  
+  def self.miles
+    new(:miles)
+  end
+  
+  def self.kg
+    new(:kg)
+  end
+  
+  def self.tonnes
+    new(:tonnes)
+  end
+  
+  def self.kwh
+    new(:kwh)
+  end
+  
+  def self.litres
+    new(:litres)
+  end
+  
+  def self.uk_gallons
+    new(:uk_gallons)
+  end
+end

data/lib/amee_rails_layer.rb

@@ -0,0 +1,5 @@
+require 'rubygems'
+require 'active_record'
+require 'amee'
+require 'amee_rails_layer/amee_category'
+require 'amee_rails_layer/amee_carbon_store'

data/rails/init.rb

@@ -0,0 +1,3 @@
+ActiveRecord::Base.class_eval do
+  include AmeeCarbonStore
+end

data/test/helper.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'amee-abstraction-layer-gem'
+
+class Test::Unit::TestCase
+end

data/test/test_amee-abstraction-layer-gem.rb

@@ -0,0 +1,7 @@
+require 'helper'
+
+class TestAmeeAbstractionLayerGem < Test::Unit::TestCase
+  should "probably rename this file and start testing for real" do
+    flunk "hey buddy, you should probably rename this file and start testing for real"
+  end
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification 
+name: amee_rails_layer
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 3
+  - 0
+  version: 0.3.0
+platform: ruby
+authors: 
+- George Palmer
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-03-30 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: amee-ruby
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+description: We need a longer description of your gem
+email: george.palmer@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- amee_rails_layer.gemspec
+- lib/amee_rails_layer.rb
+- lib/amee_rails_layer/amee_carbon_store.rb
+- lib/amee_rails_layer/amee_category.rb
+- lib/amee_rails_layer/unit.rb
+- rails/init.rb
+- test/helper.rb
+- test/test_amee-abstraction-layer-gem.rb
+has_rdoc: true
+homepage: http://github.com/georgepalmer/amee-abstraction-layer-gem
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: An abstraction layer for building applications around the AMEE API
+test_files: 
+- test/helper.rb
+- test/test_amee-abstraction-layer-gem.rb