AMEE-Ruby

A gem to provide a Ruby interface to the AMEE carbon calculator (amee.cc)

Licensed under the MIT license (See COPYING file for details)

Author: James Smith (james@floppy.org.uk / www.floppy.org.uk)

Homepage: github.com/Floppy/amee-ruby

Documentation: docs.github.com/Floppy/amee-ruby

INSTALLATION

1) Enable gems from github, if you haven’t already done so (rubygems >= 1.2):

> sudo gem sources -a http://gems.github.com

2) Install gem

> sudo gem install Floppy-amee

USAGE

Currently, you can read DataCategories, DataItems and DataItemValues. See examples/view_data_*.rb for simple usage examples. You can also get the list of available Profiles, and create and delete them. See examples/list_profiles.rb and examples/create_profile.rb for details. You can also load ProfileCategories, and load, create and update ProfileItems.

The gem will use the AMEE JSON API if the JSON gem is installed on the local system. Otherwise the XML API will be used.

SUPPORT

Create    Read     Update    Delete

DataCategories N Y N N DataItems N Y N N DataItemValues N Y N Y Profile List - Y - - Profiles Y - - Y ProfileCategories - Y - -

- drilldown           -        Y         -         -

ProfileItems Y Y Y Y

INTERACTIVE SHELL

You can use the ‘ameesh’ app to interactively explore the AMEE data area. Run ‘ameesh -u USERNAME -p PASSWORD -s SERVER’ to try it out. Source code for this tool is in bin/ameesh and lib/amee/shell.rb. Profiles are not accessible through this interface yet.

RAILS

This gem can also be used as a Rails plugin. You can either extract it into vendor/plugins, or use the new-style config.gem command in environment.rb. For example:

config.gem "Floppy-amee", :lib => "amee", :source => "http://gems.github.com", :version => '>= 0.3.0'

If you copy amee.example.yml from the gem source directory to amee.yml in your app’s config directory, a persistent AMEE connection available called $amee, will be automatically set up for you, which you can pass into the other objects to fetch data. For instance:

data = AMEE::Data::Category.root($amee)

If you do not use this facility, you will have to create your own connection objects and manage them yourself.

There is a helper for ActiveRecord models which should be linked to an AMEE profile. By adding:

has_amee_profile

to your model, and by adding an amee_profile:string field to the model in the database, an AMEE profile will be automatically created and destroyed with your model. By overriding the function amee_save in your model, you can store data in AMEE when your model is saved.

CACHING

The AMEE::Connection object implements an optional cache for GET requests. This is currently a versy simple implementation which caches the result of all GET requests until a POST, PUT, or DELETE is executed, at which point the cache is cleared. To enable caching, set the enable_caching parameter of AMEE::Connection.new to true. Caching is disabled by default.

UPGRADING TO VERSION > 2

There are a few changes to the API exposed by this gem for version 2. The main ones are:

1) AMEE::Connection#new takes a hash of options instead of an explicit parameter list.

Whereas before you would have used new(server, username, password, use_json, enable_cache, enable_debug)
you would now use new(server, username, password, :format => :json, :enable_caching => true, :enable_debug => true)

2) Many get functions take a hash of options instead of explicit date and itemsPerPage parameters.

get(... , :start_date => {your_date}, :itemsPerPage => 20)

3) total_amount_per_month functions have been replaced with total_amount. There are also

total_amount_unit and total_amount_per_unit functions which give the units that the total
amount is in.