eeml 0.0.1 → 0.0.2

data/lib/eeml/environment.rb

@@ -1,13 +1,25 @@
 module Eeml
   include Eeml::Constants
 
+  # One of the component classes of Environment. Represents the location of the environment. Environments can only have a single location object.
   class Location
     attr_accessor :name, :latitude, :longitude, :elevation
     attr_accessor :domain, :exposure, :disposition
+
+    def initialize(options = {})
+      @name = options[:name]
+      @latitude = options[:latitude]
+      @longitude = options[:longitude]
+      @elevation = options[:elevation]
+      @domain = options[:domain]
+      @exposure = options[:exposure]
+      @disposition = options[:disposition]
+    end
   end
 
+  # One of the component classes of Environment. Represents an individual datastream, and provides access to it's value
+  # and other attributes. Environments can have zero or more datastreams.
   class DataStream
-    # include FeedOutput::DataStreamNode
     attr_accessor :identifier, :value, :tags, :min_value, :max_value, :unit_symbol, :unit_type, :unit_value
 
     def initialize(options = {})
@@ -26,26 +38,17 @@ module Eeml
     end
 
   end
-  
+
+  # This class represents the main point of entry to this library. In general we will be creating instances of this class, either
+  # by manually specifying the parameters, or probably more commonly, by passing in either an EEML or JSON formatted string which
+  # will be parsed to initialize the object.
   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
-
+    # Create a new Environment object by passing parameters in a hash (just like creating an ActiveRecord object)
     def initialize(options = {})
       @datastreams = []
       @identifier = options[:identifier]
@@ -53,6 +56,10 @@ module Eeml
       @title = options[:title]
       @status = options[:status]
       @feed_url = options[:feed_url]
+      @description = options[:description]
+      @website = options[:website]
+      @email = options[:email]
+      @icon = options[:icon]
     end
 
     def add_datastream(datastream)
@@ -64,11 +71,19 @@ module Eeml
       datastreams.pop
     end
 
+    # Create multiple Environment objects from an EEML string containing multiple `environment` stanzas.
+    def self.new_list_from_eeml(xml_str)
+      parser = ParserRegistry.get_xml_parser_for(xml_str)
+      return parser.make_environments_from_xml(xml_str)
+    end
+
+    # Create a new Environment object from an EEML string.
     def self.new_from_eeml(xml_str)
       parser = ParserRegistry.get_xml_parser_for(xml_str)
       return parser.make_environment_from_xml(xml_str)
     end
 
+    # Create a new Environment object from a JSON string.
     def self.new_from_json(json_str)
       parser =  ParserRegistry.get_json_parser_for(json_str)
       return parser.make_environment_from_json(json_str)
@@ -95,19 +110,16 @@ module Eeml
       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
 
+    def to_json
+      outputter = OutputRegistry.get_json_output_for
+      outputter.to_json(self)
+    end
+    
   end
 
 end

data/lib/eeml/exceptions.rb

@@ -1,59 +1,63 @@
 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(',')
+  # Exception classes used by the EEML gem.
+  module Exceptions
+  
+  #--
+  # TODO: have these inherit from a base parser error
+  #++
+
+    # Eeml being parsed was valid XML, but bad EEML.
+    class BadEeml < StandardError 
+      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
-  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 
+    # Eeml being parsed was bad XML.
+    class BadXML < StandardError; end 
+    class DataMissingValue < BadEeml; end
+    class DataHasMultipleUnits < BadEeml; end
+    class DataHasMultipleValues < BadEeml; end
+    class NoDataStreams < BadEeml; end
+    class MissingNamespace < 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
 end
 

data/lib/eeml/json_environment_parser_v005.rb

@@ -0,0 +1,69 @@
+module Eeml
+  #a parser for json environments
+  class JsonEnvironmentParserV005 # :nodoc:
+    def make_environment_from_json(json_str)
+      env_hash = JSON.parse(json_str)
+      env = Environment.new(:title => env_hash["title"],
+                            :description => env_hash["description"],
+                            :feed_url => env_hash["feed"],
+                            :website => env_hash["website"],
+                            :email => env_hash["email"],
+                            :icon => env_hash["icon"],
+                            :status => env_hash["status"],
+                            :identifier => env_hash["id"])
+
+      env.updated = Time.mktime(*ParseDate.parsedate(env_hash['updated'])) unless env_hash['updated'].nil?
+
+      env.location = buildLocation(env_hash)
+
+      env.datastreams = buildDatastreams(env_hash)
+  
+      return env
+    end
+
+    private
+
+    def buildLocation(env_hash)
+      location_hash = env_hash["location"]
+      return if location_hash.nil?
+      Location.new(:name => location_hash["name"],
+                   :latitude => location_hash["lat"],
+                   :longitude => location_hash["lon"],
+                   :elevation => location_hash["ele"],
+                   :domain => location_hash["domain"],
+                   :disposition => location_hash["disposition"],
+                   :exposure => location_hash["exposure"])
+    end
+
+    def buildDatastreams(env_hash)
+      datastreams_hash = env_hash["datastreams"]
+      return if datastreams_hash.nil?
+      datastreams = []
+      datastreams_hash.each do |datastream_hash|
+        datastream = DataStream.new
+        raise MissingAttribute.new('id', "data") if datastream_hash['id'].nil?
+        datastream.identifier = datastream_hash['id']
+        datastream.tags = datastream_hash['tags'] unless datastream_hash['tags'].nil?
+        
+        value_hash = datastream_hash["value"]
+        raise DataMissingValue if value_hash.nil?
+        # raise DataHasMultipleValues if value_hash.size > 1
+        datastream.value = value_hash["current_value"]
+        datastream.min_value = value_hash["min_value"]
+        datastream.max_value = value_hash["max_value"]
+
+        unit_hash = datastream_hash["unit"]
+        unless unit_hash.nil?
+          datastream.unit_symbol = unit_hash["symbol"]
+          datastream.unit_type = unit_hash["type"]
+          datastream.unit_value = unit_hash["label"]
+        end
+
+        datastreams << datastream
+      end
+      return datastreams
+    end
+  end
+end
+
+

data/lib/eeml/json_output.rb

@@ -0,0 +1,86 @@
+module Eeml
+
+  class JsonOutput # :nodoc:
+
+    def to_json(environment, options = { :full => true })
+      hash = to_public_json_data(environment, options)
+      hash.to_json
+    end
+
+    def to_public_json_data(environment, options = { :full => true })
+      environment_hash = { :id => Integer(environment.identifier), #we WANT this to fail early when we start using non-numeric identifiers
+                           :title => environment.title, 
+                           :feed => environment.feed_url, 
+                           :status => environment.status,
+                           :description => environment.description,
+                           :website => environment.website,
+                           :email => environment.email,
+                           :icon => environment.icon,
+                           :version => EEML_VERSION}
+
+      environment_hash[:updated] = environment.updated.strftime("%Y-%m-%dT%H:%M:%SZ") unless environment.updated.nil?  #TODO: was retrieved_at
+
+      environment_hash.delete_if { |key, value| value.blank? }
+
+      unless environment.location.nil?
+
+        # add location data
+        location_hash = { :domain => environment.location.domain,
+                          :exposure => environment.location.exposure,
+                          :disposition => environment.location.disposition,
+                          :name => environment.location.name,
+                          :ele => environment.location.elevation #currently, ele is output as a string
+                        }
+        location_hash[:lat] = Float(environment.location.latitude) if environment.location.latitude
+        location_hash[:lon] = Float(environment.location.longitude) if environment.location.longitude
+
+        location_hash.delete_if { |key, value| value.blank? }
+
+        environment_hash[:location] = location_hash unless location_hash.empty?
+      end
+
+      # if :full option given, add our datastream data into the returned json
+      if options[:full] == true
+        datastream_array = []
+
+        # add datastream data
+        environment.datastreams.each do |datastream|
+          datastream_array << datastream_to_json(datastream)
+        end
+
+        environment_hash[:datastreams] = datastream_array unless datastream_array.empty?
+      end
+
+      return environment_hash
+    end
+    
+    protected
+    def datastream_to_json(datastream)
+      datastream_hash = { :id => datastream.identifier }
+
+      datastream_hash[:tags] = datastream.tags unless datastream.tags.empty?
+
+      value_hash = { :min_value => datastream.min_value.to_s,
+                     :max_value => datastream.max_value.to_s,
+                     :current_value => datastream.value.to_s }
+
+      value_hash.delete_if { |key, value| value.blank? }
+
+      datastream_hash[:value] = value_hash unless value_hash.empty?
+
+      unit_hash = { :type => datastream.unit_type.to_s,
+                    :symbol => datastream.unit_symbol.to_s,
+                    :label => datastream.unit_value.to_s }
+
+      unit_hash.delete_if { |key, value| value.blank? }
+
+      datastream_hash[:unit] = unit_hash unless unit_hash.empty?
+
+      return datastream_hash
+    end
+
+
+
+  end
+end
+

data/lib/eeml/libxml_eeml_parser_v005.rb

@@ -1,15 +1,28 @@
 require "parsedate.rb"
 module Eeml
+  include Exceptions
   #a parser for xml eeml v005, implemented with LibXML
   class LibXMLEemlParserV005 # :nodoc:
     include LibXML
 
     #main method
     
-    #take an xml string, and create an Environment from it
-    def make_environment_from_xml(xml_str)
+    #take an xml string, and create an Environment from it. 
+    #If an optional environment is given, that will be populated (overwritten) instead of a new environment.
+    def make_environment_from_xml(xml_str, given_environment = nil)
       doc = parse_xml(xml_str)
-      return extract_environment(doc)
+      raise MissingNamespace if doc.root.namespaces.namespace.blank?
+      env = given_environment || Environment.new
+      #TODO: what has to be reset in a given environment before passing it for re-population?
+      return extract_environment_from_doc(doc, env)
+    end
+
+    #take an xml string containing zero or more environment nodes, and create an array of Environment objects from it. 
+    def make_environments_from_xml(xml_str, given_environment = nil)
+      doc = parse_xml(xml_str)
+      raise MissingNamespace if doc.root.namespaces.namespace.blank?
+      env = Environment.new
+      return extract_environments_from_doc(doc)
     end
 
     protected
@@ -39,11 +52,23 @@ module Eeml
     end
 
 
-    def extract_environment(doc)
-      env = Environment.new
+    #multiple (zero or more)
+    def extract_environments_from_doc(doc)
       doc.root.namespaces.default_prefix = 'x'
+      env_nodes = doc.find('x:environment')
+      return env_nodes.map{|env_node| new_env = Environment.new; extract_environment_from_node(env_node, new_env)}
+    end
 
+    #single, mandatory
+    def extract_environment_from_doc(doc, env_to_populate)
+      doc.root.namespaces.default_prefix = 'x'
       env_node = find_first_node_or_fail(doc, 'x:environment', 'environment')
+      return extract_environment_from_node(env_node, env_to_populate)
+    end
+
+    #single, from node (everyone uses this to get the work done)
+    def extract_environment_from_node(env_node, env_to_populate)
+      env = env_to_populate
       env.identifier = env_node['id']
       env.updated = Time.mktime(*ParseDate.parsedate(env_node['updated'])) if !env_node['updated'].nil?
 

data/lib/eeml/output_registry.rb

@@ -1,12 +1,12 @@
 module Eeml
-  class OutputRegistry
+  class OutputRegistry # :nodoc:
     #look at the given xml, build and return a new v005 or 006 parser, accordingly
     def self.get_xml_output_for(version = EEML_VERSION)
       LibXMLEemlOutputV005.new
     end
 
     def self.get_json_output_for(version = EEML_VERSION)
-      JsonEnvironmentParser.new
+      JsonOutput.new
     end
 
   end

data/lib/eeml/parser_registry.rb

@@ -1,12 +1,13 @@
 module Eeml
-  class ParserRegistry
+  class ParserRegistry # :nodoc:
     #look at the given xml, build and return a new v005 or 006 parser, accordingly
+    #this should work whether the xml given is for a single environment, or for a results list
     def self.get_xml_parser_for(xml_str)
       LibXMLEemlParserV005.new
     end
 
     def self.get_json_parser_for(json_str)
-      JsonEnvironmentParser.new
+      JsonEnvironmentParserV005.new
     end
 
   end

data/lib/eeml.rb

@@ -1,35 +1,28 @@
-#TODO: what's going on here and why? 
-#add this dir to the search path (?)
+# TODO: what's going on here and why? 
+# add this dir to the search path (?)
 $:.unshift(File.dirname(__FILE__))
 
-require 'logger' #std lib
 require 'blank'
 require 'libxml'
 require 'json'
 require 'eeml/constants'
 require 'eeml/exceptions'
-require 'eeml/feed_output'
 require 'eeml/environment'
 require 'eeml/libxml_eeml_parser_v005'
-require 'eeml/json_environment_parser'
+require 'eeml/json_environment_parser_v005'
 require 'eeml/parser_registry'
 require 'eeml/output_registry'
 require 'eeml/libxml_eeml_output_v005'
-
+require 'eeml/json_output'
 
 module Eeml
 
-  # enable logger before including everything else, in case we ever want to log initialization 
-  ##TODO: this config should be environment-specific (e.g. test/production).  Tests can stub.
-  Environment.logger = Logger.new(STDERR)
-
   # library version number
-  VERSION = '0.0.1'
-  #TODO: put in some configuration file, not here
+  VERSION = '0.0.2'
+
+  # TODO: put in some configuration file, not here
   LOCAL_EEML_SCHEMA_LOCATION = 'schemas/eeml/005.xsd'
 
 
 
 end #module
-
-

data/test/data/doc_1.json

@@ -1,2 +1,30 @@
-foo
-
+{"datastreams":[
+  {"tags":["tagD0"],
+  "value":{"current_value":"0","min_value":"-9999.0","max_value":"1022.0"},
+  "unit":{"type":"basicSI","label":"Celsius","symbol":"C"},
+  "id":"0"},
+  {"value":{"current_value":"33","min_value":"0.0","max_value":"1023.0"},
+  "id":"1"},
+  {"tags":["tagD2a","tagD2b","tagD2c"],
+  "value":{"current_value":"42.1","min_value":"23.4","max_value":"1021.0"},
+  "id":"2"}
+],
+"description":"description here",
+"updated":"2009-02-11T10:56:56Z",
+"status":"frozen",
+"website":"http:\/\/example.com\/studio\/",
+"email":"someone@example.com",
+"feed":"http:\/\/example.com\/api\/1247.xml",
+"location":{
+  "lat":"50.1",
+  "lon":"48.7",
+  "ele":"1.34",
+  "name":"Up on the roof (somewhere)",
+  "domain":"physical",
+  "exposure":"outdoor",
+  "disposition":"mobile"
+},
+"icon":"http:\/\/example.com\/some\/icon.gif",
+"id":"1247",
+"title":"title here",
+"version":"5"}

data/test/data/doc_2.xml

@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<eeml xmlns="http://www.eeml.org/xsd/005" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="5" xsi:schemaLocation="http://www.eeml.org/xsd/005 http://www.eeml.org/xsd/005/005.xsd">
+  <environment updated="2009-04-17T23:59:16Z" id="1044" creator="http://www.haque.co.uk">
+    <title>Deployable External Insulation Pavilion</title>
+    <feed>http://www.pachube.com/api/1044.xml</feed>
+    <status>live</status>
+    <description>The Deployable External Insulation (DEI) pavilion is an experimental low-energy pavilion.</description>
+    <website>http://www.deployable.org.uk</website>
+    <email>chris@example.com</email>
+    <location domain="physical" exposure="outdoor" disposition="fixed">
+      <name>Shipping Container rooftop Trinity Buoy Wharf</name>
+      <lat>51.508255</lat>
+      <lon>0.0091516666666667</lon>
+      <ele>16.2</ele>
+    </location>
+    <data id="0">
+      <tag>Roof vent wax-piston stroke length</tag>
+      <value minValue="137.0" maxValue="932.0">300</value>
+    </data>
+    <data id="1">
+      <tag>Thermal shutter bay one wax-piston stroke length</tag>
+      <value minValue="132.0" maxValue="930.0">300</value>
+    </data>
+    <data id="2">
+      <value minValue="0.0" maxValue="0.0">0</value>
+    </data>
+    <data id="3">
+      <tag>Horizontal angle of  thermal shutter's opening in front of window bay one (0=fully closed)</tag>
+      <value minValue="181.8" maxValue="324.7">200</value>
+    </data>
+    <data id="4">
+      <tag>Air temperature of wax-piston mechanism enclosure</tag>
+      <value minValue="5.0" maxValue="27.5">10</value>
+    </data>
+  </environment>
+</eeml>

data/test/data/doc_2_expected.json

@@ -0,0 +1,35 @@
+{"version":"5",
+"description":"The Deployable External Insulation (DEI) pavilion is an experimental low-energy pavilion.",
+"updated":"2009-04-17T23:59:16Z",
+"website":"http:\/\/www.deployable.org.uk",
+"status":"live",
+"title":"Deployable External Insulation Pavilion",
+"location":{
+  "lon":0.0091516666666667,
+  "exposure":"outdoor",
+  "ele":"16.2",
+  "name":"Shipping Container rooftop Trinity Buoy Wharf",
+  "domain":"physical",
+  "lat":51.508255,
+  "disposition":"fixed"
+  },
+"email":"chris@example.com",
+"feed":"http:\/\/www.pachube.com\/api\/1044.xml",
+"id":1044,
+"datastreams":[
+  {"value":{"current_value":"300","min_value":"137.0","max_value":"932.0"},
+  "tags":["Roof vent wax-piston stroke length"],
+  "id":"0"},
+  {"value":{"current_value":"300","min_value":"132.0","max_value":"930.0"},
+  "tags":["Thermal shutter bay one wax-piston stroke length"],
+  "id":"1"},
+  {"value":{"current_value":"0","min_value":"0.0","max_value":"0.0"},
+  "id":"2"},
+  {"value":{"current_value":"200","min_value":"181.8","max_value":"324.7"},
+  "tags":["Horizontal angle of  thermal shutter's opening in front of window bay one (0=fully closed)"],
+  "id":"3"},
+  {"value":{"current_value":"10","min_value":"5.0","max_value":"27.5"},
+  "tags":["Air temperature of wax-piston mechanism enclosure"],
+  "id":"4"}
+  ]
+}

data/test/data/list.xml

@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<eeml xmlns="http://www.eeml.org/xsd/005" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="5" xsi:schemaLocation="http://www.eeml.org/xsd/005 http://www.eeml.org/xsd/005/005.xsd">
+  <environment updated="2009-02-12T05:12:58Z" id="1202" creator="http://www.haque.co.uk">
+    <title>Badgerpower</title>
+    <feed>http://localhost:3000/api/1202.xml</feed>
+    <status>live</status>
+    <description>Output from currentcost meter in Badger Towers</description>
+    <website>http://example.com/badgerpower</website>
+    <location domain="physical" exposure="indoor" disposition="fixed">
+      <name>OX4 XXX</name>
+      <lat>51.7177447203256</lat>
+      <lon>-1.22573090018705</lon>
+    </location>
+  </environment>
+  <environment updated="2009-02-12T05:12:48Z" id="1280" creator="http://www.haque.co.uk">
+    <title>CurrentCost for house</title>
+    <feed>http://localhost:3000/api/1280.xml</feed>
+    <status>live</status>
+    <description>Desc of currentcost env</description>
+    <website>http://example.com/currentcost</website>
+    <location domain="physical" exposure="indoor" disposition="fixed">
+      <lat>51.5946518173021</lat>
+      <lon>-0.149892568588257</lon>
+    </location>
+  </environment>
+  <environment updated="2009-02-12T05:12:48Z" id="1347" creator="http://www.haque.co.uk">
+    <title>Power and Temperature</title>
+    <feed>http://localhost:3000/api/1347.xml</feed>
+    <status>live</status>
+    <website>http://example.com/power</website>
+    <location domain="virtual" exposure="indoor" disposition="fixed">
+      <name>London, England</name>
+      <lat/>
+      <lon/>
+    </location>
+  </environment>
+</eeml>
+