eeml 0.0.1

data/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2009, Neill Bogie, Samuel Mulube.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, 
+are permitted provided that the following conditions are met:
+
+  * Redistributions of source code must retain the above copyright notice, this 
+    list of conditions and the following disclaimer.
+  * Redistributions in binary form must reproduce the above copyright notice, 
+    this list of conditions and the following disclaimer in the documentation 
+    and/or other materials provided with the distribution.
+  * Neither the name of the <ORGANIZATION> nor the names of its contributors 
+    may be used to endorse or promote products derived from this software without 
+    specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 
+OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/Manifest

@@ -0,0 +1,30 @@
+example.rb
+eeml.gemspec
+LICENSE
+CHANGELOG
+README
+test/test_environment.rb
+test/test_libxml_test_helper.rb
+test/libxml_test_helper.rb
+test/test_libxml_eeml_parser_v005.rb
+test/test_helper.rb
+test/data/minimal.xml
+test/data/out_empty.xml
+test/data/doc_1.xml
+test/data/doc_1.json
+lib/eeml.rb
+lib/eeml/constants.rb
+lib/eeml/feed_retriever.rb
+lib/eeml/json_environment_parser.rb
+lib/eeml/output_registry.rb
+lib/eeml/parser_registry.rb
+lib/eeml/libxml_eeml_output_v005.rb
+lib/eeml/feed_output.rb
+lib/eeml/libxml_eeml_parser_v005.rb
+lib/eeml/exceptions.rb
+lib/eeml/csv_parser.rb
+lib/eeml/environment.rb
+lib/blank.rb
+schemas/eeml/005.xsd
+Rakefile
+Manifest

data/README

@@ -0,0 +1,8 @@
+= eeml
+
+* http://eeml.rubyforge.org
+
+== DESCRIPTION:
+
+Library for interacting with the API of pachube.com. Also aims to simplify
+the process of creating, parsing and manipulating EEML documents.

data/Rakefile

@@ -0,0 +1,25 @@
+require 'echoe'
+
+$:.unshift(File.join(File.dirname(__FILE__), "lib"))
+
+require 'eeml'
+
+Echoe.new("eeml") do |p|
+  p.author = "Neill Bogie, Sam Mulube"
+  p.email = "sam.mulube@gmail.com"
+  p.description = "Simple little library for programmatically manipulating EEML documents, in particular this library is designed to work with the Pachube web service."
+  p.summary = "Simple little library for programmatically manipulating EEML documents."
+  p.version = Eeml::VERSION
+  p.runtime_dependencies = [
+    "libxml-ruby >= 1.1.3",
+    "json >= 1.1.3"
+  ]
+  p.development_dependencies = [
+    "rake >= 0.8.4",
+    "mocha >= 0.9.6"
+  ] 
+  p.ignore_pattern = [ 
+  "test/data/real_xmls/v005/oks/*",
+  "test/data/real_xmls/v005/*"
+  ]
+end

data/eeml.gemspec

@@ -0,0 +1,46 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{eeml}
+  s.version = "0.0.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Neill Bogie, Sam Mulube"]
+  s.cert_chain = ["/home/sam/.gem/gem-public_cert.pem"]
+  s.date = %q{2009-04-17}
+  s.description = %q{Simple little library for programmatically manipulating EEML documents, in particular this library is designed to work with the Pachube web service.}
+  s.email = %q{sam.mulube@gmail.com}
+  s.extra_rdoc_files = ["LICENSE", "CHANGELOG", "README", "lib/eeml.rb", "lib/eeml/constants.rb", "lib/eeml/feed_retriever.rb", "lib/eeml/json_environment_parser.rb", "lib/eeml/output_registry.rb", "lib/eeml/parser_registry.rb", "lib/eeml/libxml_eeml_output_v005.rb", "lib/eeml/feed_output.rb", "lib/eeml/libxml_eeml_parser_v005.rb", "lib/eeml/exceptions.rb", "lib/eeml/csv_parser.rb", "lib/eeml/environment.rb", "lib/blank.rb"]
+  s.files = ["example.rb", "eeml.gemspec", "LICENSE", "CHANGELOG", "README", "test/test_environment.rb", "test/test_libxml_test_helper.rb", "test/libxml_test_helper.rb", "test/test_libxml_eeml_parser_v005.rb", "test/test_helper.rb", "test/data/minimal.xml", "test/data/out_empty.xml", "test/data/doc_1.xml", "test/data/doc_1.json", "lib/eeml.rb", "lib/eeml/constants.rb", "lib/eeml/feed_retriever.rb", "lib/eeml/json_environment_parser.rb", "lib/eeml/output_registry.rb", "lib/eeml/parser_registry.rb", "lib/eeml/libxml_eeml_output_v005.rb", "lib/eeml/feed_output.rb", "lib/eeml/libxml_eeml_parser_v005.rb", "lib/eeml/exceptions.rb", "lib/eeml/csv_parser.rb", "lib/eeml/environment.rb", "lib/blank.rb", "schemas/eeml/005.xsd", "Rakefile", "Manifest"]
+  s.has_rdoc = true
+  s.homepage = %q{}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Eeml", "--main", "README"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{eeml}
+  s.rubygems_version = %q{1.3.1}
+  s.signing_key = %q{/home/sam/.gem/gem-private_key.pem}
+  s.summary = %q{Simple little library for programmatically manipulating EEML documents.}
+  s.test_files = ["test/test_environment.rb", "test/test_libxml_test_helper.rb", "test/test_libxml_eeml_parser_v005.rb", "test/test_helper.rb"]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<libxml-ruby>, [">= 0", "= 1.1.3"])
+      s.add_runtime_dependency(%q<json>, [">= 0", "= 1.1.3"])
+      s.add_development_dependency(%q<rake>, [">= 0", "= 0.8.4"])
+      s.add_development_dependency(%q<mocha>, [">= 0", "= 0.9.6"])
+    else
+      s.add_dependency(%q<libxml-ruby>, [">= 0", "= 1.1.3"])
+      s.add_dependency(%q<json>, [">= 0", "= 1.1.3"])
+      s.add_dependency(%q<rake>, [">= 0", "= 0.8.4"])
+      s.add_dependency(%q<mocha>, [">= 0", "= 0.9.6"])
+    end
+  else
+    s.add_dependency(%q<libxml-ruby>, [">= 0", "= 1.1.3"])
+    s.add_dependency(%q<json>, [">= 0", "= 1.1.3"])
+    s.add_dependency(%q<rake>, [">= 0", "= 0.8.4"])
+    s.add_dependency(%q<mocha>, [">= 0", "= 0.9.6"])
+  end
+end

data/example.rb

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+
+#should invoke this with (e.g.) ruby -Ilib example.rb in order to add lib/ to your search path
+
+require 'rubygems' #only if your libxml is installed under rubygems
+require 'eeml'
+
+include Eeml #allows you to refer to Environment rather than Eeml::Environment
+
+#Example: make an environment from scratch
+env = Environment.new(:creator => 'http://www.example.com/ourstudio/', :feed_url => 'http://www.example.com/ourstudio/feeds/house.xml')
+
+env.title = 'my example feed'
+env.datastreams << DataStream.new(:value => 93.0, :identifier => 'room.1.humidity')
+env.datastreams << DataStream.new(:value => 91.0, :identifier => 'room.2.humidity')
+
+#print out its eeml representation
+puts env.to_eeml
+
+
+#Example: parse an environment from an eeml doc:
+eeml_str = File.read('test/data/doc_1.xml')
+env2 = Environment.new_from_eeml(eeml_str)
+env2.datastreams.each do |ds|
+puts "ds %8s value is %6s (min:%8s, max:%8s)" %[ds.identifier, ds.value, ds.min_value, ds.max_value]
+end
+
+#TODO: Example: http-fetch an environment
+
+#TODO: Example: publish an environment to pachube
+
+#TODO: Example: configure a different logger (to file; to stderr; different timestamp / format; use an existing rails logger)
+

data/lib/blank.rb

@@ -0,0 +1,50 @@
+class Object
+  # An object is blank if it's nil, empty, or a whitespace string.
+  # For example, "", "   ", nil, [], and {} are blank.
+  #
+  # This simplifies
+  #   if !address.nil? && !address.empty?
+  # to
+  #   if !address.blank?
+  def blank?
+    respond_to?(:empty?) ? empty? : !self
+  end
+end
+
+class NilClass #:nodoc:
+  def blank?
+    true
+  end
+end
+
+class FalseClass #:nodoc:
+  def blank?
+    true
+  end
+end
+
+class TrueClass #:nodoc:
+  def blank?
+    false
+  end
+end
+
+class Array #:nodoc:
+  alias_method :blank?, :empty?
+end
+
+class Hash #:nodoc:
+  alias_method :blank?, :empty?
+end
+
+class String #:nodoc:
+  def blank?
+    self !~ /\S/
+  end
+end
+
+class Numeric #:nodoc:
+  def blank?
+    false
+  end
+end

data/lib/eeml/constants.rb

@@ -0,0 +1,17 @@
+module Eeml
+  module Constants
+    #LOCAL_EEML_SCHEMA_LOCATION = "schemas/eeml/005.xsd"
+    EEML_HREF = "http://www.eeml.org/xsd/005"
+    EEML_VERSION = "5"
+    EEML_SCHEMA_LOCATION = "http://www.eeml.org/xsd/005 http://www.eeml.org/xsd/005/005.xsd"
+
+    EEML_NAMESPACE = ":#{EEML_HREF}"
+    XSI_NAMESPACE = "http://www.w3.org/2001/XMLSchema-instance"
+
+    #TODO: better encapsulated as a set of methods.
+    XML_TIME_FORMAT_STRING = "%Y-%m-%dT%H:%M:%SZ"
+
+    DEFAULT_HOST = 'pachube.com'
+  end
+end
+

data/lib/eeml/csv_parser.rb

@@ -0,0 +1,16 @@
+module Eeml
+  class CsvParser
+
+    #update the datastreams for the given environment, using the content in the given csv string.
+    def update_datastreams_from_csv(csv_content, environment)
+      # split values at commas
+      datastream_values = csv_content.split(/,/)
+
+      # now strip any whitespace
+      datastream_values.map! { |d| d.strip }
+
+      logger.debug("*** New datastream values: #{datastream_values}")
+    end
+
+  end
+end

data/lib/eeml/environment.rb

@@ -0,0 +1,113 @@
+module Eeml
+  include Eeml::Constants
+
+  class Location
+    attr_accessor :name, :latitude, :longitude, :elevation
+    attr_accessor :domain, :exposure, :disposition
+  end
+
+  class DataStream
+    # include FeedOutput::DataStreamNode
+    attr_accessor :identifier, :value, :tags, :min_value, :max_value, :unit_symbol, :unit_type, :unit_value
+
+    def initialize(options = {})
+      @identifier = options[:identifier]
+      @value = options[:value]
+      @max_value = options[:max_value]
+      @min_value = options[:min_value]
+      @tags = []
+      @unit_symbol = options[:unit_symbol]
+      @unit_type = options[:unit_type]
+      @unit_value = options[:unit_value]
+    end
+
+    def to_s
+      "identifier: '#{@identifier}', value: '#{@value}', min_value: '#{@min_value}', max_value: '#{@max_value}', tags: '#{@tags.join(", ")}'"
+    end
+
+  end
+  
+  class Environment
+    include FeedOutput::EnvironmentNode
+    attr_accessor :identifier, :updated, :creator
+    attr_accessor :title, :description, :feed_url, :website, :email, :icon, :status
+    attr_accessor :location
+    attr_accessor :datastreams
+
+    # stuff so far needed only for FeedOutput module
+    # attr_accessor :retrieved_at
+    
+    @@logger = nil
+    def self.logger=(logger)
+      @@logger = logger
+    end
+    
+    def logger
+      return @@logger
+    end
+
+    def initialize(options = {})
+      @datastreams = []
+      @identifier = options[:identifier]
+      @creator = options[:creator]
+      @title = options[:title]
+      @status = options[:status]
+      @feed_url = options[:feed_url]
+    end
+
+    def add_datastream(datastream)
+      #TODO: consider checking for unique identifier
+      datastreams << datastream
+    end
+
+    def remove_last_datastream
+      datastreams.pop
+    end
+
+    def self.new_from_eeml(xml_str)
+      parser = ParserRegistry.get_xml_parser_for(xml_str)
+      return parser.make_environment_from_xml(xml_str)
+    end
+
+    def self.new_from_json(json_str)
+      parser =  ParserRegistry.get_json_parser_for(json_str)
+      return parser.make_environment_from_json(json_str)
+    end
+  
+    def update_datastreams_from_csv_values!(csv_values)
+
+      csv_values.each_with_index do |new_val, index|
+        datastream = datastreams[index]
+        #if we don't have an existing datastream at same index, create new one
+        if datastream.nil?
+          self.datastreams << DataStream.new(:identifier => index, :value => new_val, :ordering => index)          
+        else
+          #we had a match, so update the existing datastream
+          datastream.value = new_val
+        end
+      end
+
+      # if the csv specifies FEWER feeds than the env currently has.
+      if csv_values.size < self.datastreams.size
+        # remove the excess from the end of the env's list.
+        num_extra = datastreams.size - csv_values.size
+        1.upto(num_extra) { remove_last_datastream }
+      end
+    end
+
+    #--------------------------------------------------------------------------
+    #----- state tracking stuff -----------------------------------------------
+    #--------------------------------------------------------------------------
+    def live?
+      #TODO
+      true
+    end
+    
+    def to_eeml(version = Constants::EEML_VERSION)
+      outputter = OutputRegistry.get_xml_output_for(version)
+      outputter.to_eeml(self)
+    end
+
+  end
+
+end

data/lib/eeml/exceptions.rb

@@ -0,0 +1,59 @@
+module Eeml
+  # exceptions
+  #TODO: have these inherit from a base parser error
+  class Unavailable < StandardError; end
+  class BadResponse < StandardError; end
+  class ApiKeyMissing < StandardError; end
+  class AuthenticationFailure < StandardError; end
+
+  class BadEeml < StandardError #eeml being parsed was ok xml but bad eeml
+    attr_accessor :line_num, :node_name #no guarantees either is available
+    def to_s
+      extras = []
+      extras << " node name: '" + node_name + "'" if node_name
+      extras << " line_num: #{line_num}" if line_num
+      super.to_s + extras.join(',')
+    end
+  end
+
+  class BadXML < StandardError; end #xml being parsed was malformed
+  class DataMissingValue < BadEeml; end
+  class DataHasMultipleUnits < BadEeml; end
+  class DataHasMultipleValues < BadEeml; end
+  class NoDataStreams < BadEeml; end
+
+
+  #A structured exception which holds info about what was missing and from where.
+  #Note: Some reasons we don't just hold everything in an unstructured exception message:
+  #1. some bits might be useful for dev but not for the public, 
+  #2. testing is simplified by having the missing node name recorded explicitly (rather than in a human-readable, changeable string).
+  class MissingNode < BadEeml
+    attr_accessor :base_node_name, :sought_description, :sought_xpath
+
+    def initialize(base_node_name, sought_description, sought_xpath = nil)
+      @base_node_name = base_node_name
+      @sought_description = sought_description
+      @sought_xpath = sought_xpath
+    end
+
+    def to_s
+      "Missing '#@sought_description' node from base node: '#@base_node_name'" +
+      (@sought_xpath ? "with xpath: '#@sought_xpath'" : "")
+    end
+  end 
+
+
+  class MissingAttribute < BadEeml
+    attr_accessor :node_name, :attribute_name
+
+    def initialize(node_name, attribute_name)
+      @node_name = node_name
+      @attribute_name = attribute_name
+    end
+
+    def to_s
+      "Missing attribute '#@attribute_name' from node '#@node_name'"
+    end
+  end 
+end
+

data/lib/eeml/feed_output.rb

@@ -0,0 +1,169 @@
+module FeedOutput # :nodoc:
+  #TODO: move away from mixins for this functionality.
+  #TODO: This is v005-specific.
+  module EnvironmentNode # :nodoc:
+  include LibXML
+    #assumes a logger()
+    #assumes retrieved_at()
+
+    #TODO: Move these (now unused) methods to the publisher (e.g. a rails controller?) which will decide where it's going to host the env, 
+    #      and which will set the feed property accordingly before serialising the env.
+    # def public_feed_url
+    #   return "http://#{DEFAULT_HOST}/api/#{self.id}.xml"
+    # end
+
+    # def public_csv_url
+    #   return "http://#{DEFAULT_HOST}/api/#{self.id}.csv"
+    # end
+
+    # def public_json_url
+    #   return "http://#{DEFAULT_HOST}/api/#{self.id}.json"
+    # end
+
+
+    def create_eeml_document
+      doc = XML::Document.new
+      eeml = doc.root = XML::Node.new('eeml')
+      XML::Namespace.new(eeml, nil, Eeml::EEML_HREF)
+      XML::Namespace.new(eeml, 'xsi', Eeml::XSI_NAMESPACE)
+      eeml['version'] = Eeml::EEML_VERSION
+      eeml['xsi:schemaLocation'] = Eeml::EEML_SCHEMA_LOCATION
+      return doc
+    end
+
+    # Create a csv representation of this environment by iterating through all datastreams and returning 
+    # their values.
+    def to_csv
+      return self.datastreams.map { |d| d.value }.join(",")
+    end
+
+    # Create an xml representation of this environment. The document returned should be valid EEML.
+    # def to_eeml(options = { :full => true })
+    # # Returns the public feed URL for this environment.
+
+
+    #   logger.debug("*** Returning eeml representation of environment: #{self.identifier}")
+
+    #   doc = create_eeml_document
+
+    #   doc.root << to_xml_node(options)
+
+    #   return doc.to_s(:encoding => XML::Encoding::UTF_8)
+    # end
+
+    def to_xml_node_old(options = { :full => true })
+      logger.debug("*** Creating xml node for environment: #{self.identifier}")
+
+      environment_node = XML::Node.new('environment')
+      #TODO: this was retrieved_at in the db, but it's 'updated' in the xml.  Clarify w sam...   
+      #      ... env.retrieved_at doesn't make much sense to clients generating eeml using the gem.
+      environment_node['updated'] = self.updated.strftime(XML_TIME_FORMAT_STRING) unless self.updated.nil?      
+      environment_node['id'] = self.identifier.to_s unless self.identifier.blank?
+      #TODO: write all these strings out safely for xml
+      environment_node['creator'] = self.creator.to_s unless self.creator.blank?
+
+      #TODO: these all should really appear, even when absent?  likely make conditional.
+      unless self.title.blank?
+        environment_node << title_node = XML::Node.new('title')
+        title_node << self.title
+      end
+
+      unless self.feed_url.blank?
+        environment_node << feed_node = XML::Node.new('feed')
+        feed_node << self.feed_url
+      end
+      
+      unless self.status.blank?
+        environment_node << status_node = XML::Node.new('status')
+        status_node << self.status
+      end
+
+      unless self.description.blank?
+        environment_node << description_node = XML::Node.new('description')
+        description_node << self.description
+      end
+
+      unless self.icon.blank?
+        environment_node << icon_node = XML::Node.new('icon')
+        icon_node << self.icon
+      end
+
+      unless self.website.blank?
+        environment_node << website_node = XML::Node.new('website')
+        website_node << self.website
+      end
+
+      unless self.email.blank?
+        environment_node << email_node = XML::Node.new('email')
+        email_node << self.email
+      end
+
+      unless self.location.nil?
+        environment_node << location_node = XML::Node.new('location')
+        location_node['domain'] = self.location.domain
+        location_node['exposure'] = self.location.exposure unless self.location.exposure.blank?
+        location_node['disposition'] = self.location.disposition unless self.location.disposition.blank?
+        
+        unless self.location.name.blank?
+          location_node << location_name_node = XML::Node.new('name')
+          location_name_node << self.location.name
+        end
+
+        location_node << lat_node = XML::Node.new('lat')
+        lat_node << self.location.latitude
+
+        location_node << lng_node = XML::Node.new('lon')
+        lng_node << self.location.longitude
+
+        unless self.location.elevation.blank?
+          location_node << elevation_node = XML::Node.new('ele')
+          elevation_node << self.location.elevation
+        end
+      end
+
+      if options[:full] == true
+        self.datastreams.each do |datastream|
+          environment_node << datastream.to_xml_node unless datastream.nil?
+        end
+      end
+
+      return environment_node
+    end
+  end
+
+
+
+  module DataStreamNode # :nodoc:
+    include LibXML
+    # Create and return an XML::Node object representing this datastream. This method creates all
+    # required child nodes of the datastream object, including the list of tag elements, any units element
+    # and the value.
+    def to_xml_node
+      datastream_node = XML::Node.new('data')
+      datastream_node['id'] = self.identifier.to_s
+
+      self.tags.each do |tag|
+        tag_node = XML::Node.new('tag')
+        tag_node << tag
+        datastream_node << tag_node
+      end    
+
+      datastream_node << value_node = XML::Node.new('value')
+
+      value_node['minValue'] = self.min_value.to_s unless self.min_value.to_s.empty?
+      value_node['maxValue'] = self.max_value.to_s unless self.max_value.to_s.empty?
+
+      value_node << self.value.to_s
+      
+      unless self.unit_value.to_s.empty? && self.unit_type.to_s.empty? && self.unit_symbol.to_s.empty?
+        datastream_node << unit_node = XML::Node.new('unit')
+        unit_node['type'] = self.unit_type.to_s unless self.unit_type.to_s.empty?
+        unit_node['symbol'] = self.unit_symbol.to_s unless self.unit_symbol.to_s.empty?
+        unit_node << self.unit_value.to_s unless self.unit_value.to_s.empty?
+      end
+
+      return datastream_node
+    end
+  end
+
+end