amee-data-abstraction 1.0.0

data/lib/amee-data-abstraction/output.rb

@@ -0,0 +1,16 @@
+# Copyright (C) 2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+# :title: Class: AMEE::DataAbstraction::Output
+
+module AMEE
+  module DataAbstraction
+
+    # Subclass of <tt>Term</tt> providing methods and attributes appropriate for
+    # representing AMEE return values specifically
+    #
+    class Output < Term
+
+    end
+  end
+end

data/lib/amee-data-abstraction/profile.rb

@@ -0,0 +1,108 @@
+# Copyright (C) 2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+# :title: Class: AMEE::DataAbstraction::Profile
+
+module AMEE
+  module DataAbstraction
+
+    # Subclass of <tt>Input</tt> providing methods and attributes appropriate for
+    # representing AMEE profile item values specifically
+    #
+    class Profile < Input
+      
+      # Represents a list of acceptable choices for the value of <tt>self</tt>. 
+      # Set the list of choices by passing an argument. Retrieve the choices by 
+      # calling without an argument, e.g.,
+      #
+      #  my_term.choices 'industrial', 'commercial', 'residential'
+      #
+      #  my_term.choices                      #=> [ 'industrial',
+      #                                             'commercial', 
+      #                                             'residential' ]
+      #  
+      # A single value of <tt>nil</tt> represents an unrestricted value
+      # .
+      attr_property :choices
+
+      # Initialization of <i>Input</i> objects follows that of the parent
+      # <i>Term</i> class. The <tt>interface</tt> attribute of <tt>self</tt> is
+      # set to <tt>:drop_down</tt> by default if a list of choices is defined
+      # using the <tt>choices</tt> attribute. Otherwise the <tt>interface</tt>
+      # attribute is set to <tt>:test_box</tt>, but can be manually configured if
+      # required.
+      #
+      def initialize(options={},&block)
+        super
+        interface :drop_down unless choices.blank?
+        choice_validation_message unless choices.blank?
+        interface :text_box unless interface
+      end
+
+      # Return <tt>true</tt> if the value of <tt>self</tt> is NOT required before
+      # the parent calculation can be calculated. Otherwise, return <tt>false</tt>.
+      #
+      # If no argument is provided, optional status is determined according to the
+      # current usage of the parent calculation. Optionality can be determined for
+      # a specific usage by passing in the usage path as an argument
+      #
+      def optional?(usage=nil)
+        usage||=parent.current_usage
+        usage ? amee_ivd.optional?(usage) : super()
+      end
+
+      # Return <tt>true</tt> if the value of <tt>self</tt> is required before
+      # the parent calculation can be calculated. Otherwise, return <tt>false</tt>.
+      #
+      # If no argument is provided, compulsory status is determined according to
+      # the current usage of the parent calculation. Compulsory status can be
+      # determined for a specific usage by passing in the usage path as an argument
+      #
+      def compulsory?(usage=nil)
+        usage||=parent.current_usage
+        usage ? amee_ivd.compulsory?(usage) : super()
+      end
+
+      # Return <tt>true</tt> if the value of <tt>self</tt> is either compulsory
+      # OR optional in the owning calculation, i.e. is NOT forbidden.
+      #
+      # If no argument is provided, the optional/compulsory status is defined
+      # according to the current usage of the parent caluclation. Otherwise,
+      # optional/compulsory status is determined on the basis of the usage whose
+      # AMEE platform path matches <tt>usage</tt>
+      #
+      def in_use?(usage)
+        compulsory?(usage)||optional?(usage)
+      end
+
+      # Return <tt>true</tt> if the value of <tt>self</tt> is neither compulsory
+      # OR optional in the owning calculation, i.e. is forbidden.
+      #
+      # If no argument is provided, forbbiden status is defined according to the
+      # current usage of the parent caluclation. Otherwise, it is determined on
+      # the basis of the usage whose AMEE platform path matches <tt>usage</tt>
+      #
+      def out_of_use?(usage)
+        !in_use?(usage)
+      end
+
+      # Return the <i>AMEE::Admin::ItemValueDefinition</i> object associated
+      # with <tt>self</tt>.
+      #
+      def amee_ivd
+        parent.amee_ivds.detect{|x|x.path==path}
+      end
+
+      # Returns <tt>true</tt> if the value set for <tt>self</tt> is valid. If
+      # <tt>self</tt> contains neither a custom validation pattern nor any
+      # defined choices, <tt>true</tt> is returned. Otherwise, validity depends
+      # on the custom validation being successful (if present) and the the value
+      # of <tt>self</tt> matching one of the entries in the <tt>choices</tt>
+      # attribute (if defined). Otherwise, returns <tt>false</tt>.
+      #
+      def valid?
+        super && (choices.blank? || choices.include?(value))
+      end
+    end
+  end
+end

data/lib/amee-data-abstraction/prototype_calculation.rb

@@ -0,0 +1,350 @@
+# Copyright (C) 2011 AMEE UK Ltd. - http://www.amee.com
+# Released as Open Source Software under the BSD 3-Clause license. See LICENSE.txt for details.
+
+# :title: Class: AMEE::DataAbstraction::PrototypeCalculation
+
+module AMEE
+  module DataAbstraction
+
+    # The <i>PrototypeCalculation</i> class represents a template for a potential
+    # calculation within the AMEE platfom.
+    # 
+    # The class inherits from the <i>Calculation</i> class and is therefore primarly
+    # characterised by the <tt>label</tt>, <tt>name</tt>, and <tt>path</tt> attributes,
+    # as well as an associated instance of the <tt>TermsList</tt> class which represents
+    # each of the values (input, outputs, metdata) involved in the calculation. Unlike
+    # the <i>OngoingCalculation</i>, the terms associated with an instance of
+    # <i>PrototypeCalculation</i> will typically contains blank (nil) values.
+    #
+    # Objects of the class <i>PrototypeCalculation</tt> are typically instantiated
+    # using block ('DSL') syntax, within which each of the attributes and associated
+    # terms are defined. Thus,
+    #
+    #   calculation = PrototypeCalculation.new {
+    #
+    #     label :electricity
+    #     name "Domestic electricity consumption"
+    #     path "some/path/in/amee"
+    #     drill { ... }
+    #     profile { ... }
+    #     ...
+    #
+    #   }
+    #
+    class PrototypeCalculation < Calculation
+
+      public
+
+      # Initialize a new instance of <i>PrototypeCalculation</i>.
+      # 
+      # The calculation can be configured in place by passing a block (evaluated
+      # in the context of the new instance) which defines the calculation properties
+      # using the macro-style instance helper methods.
+      #      
+      #   calculation = PrototypeCalculation.new {
+      #   
+      #     label :transport
+      #     path "some/other/path/in/amee"
+      #     terms_from_amee
+      #     metadatum { ... }
+      #     start_and_end_dates
+      #     ...
+      #     
+      #   }
+      #
+      def initialize(options={},&block)
+        super()
+        instance_eval(&block) if block
+      end
+
+      # Associate a new instance of the <i>Profile</i> class (subclass of the 
+      # <i>Term</i> class) with <tt>self</tt>, for representing an AMEE profile item input
+      # 
+      # The newly instantiated <i>Term</i> object is configured according to the
+      # ('DSL') block passed in.
+      #
+      #   my_protptype.profile {
+      #     label :energy_used
+      #     path 'energyUsed'
+      #     default_unit :kWh
+      #   }
+      #
+      def profile(options={},&block)
+        construct(Profile,options,&block)
+      end
+
+      # Associate a new instance of the <i>Drill</i> class (subclass of the
+      # <i>Term</i> class) with <tt>self</tt>, for representing an AMEE drill down choice
+      #
+      # The newly instantiated <i>Term</i> object is configured according to the
+      # ('DSL') block passed in.
+      #
+      #   my_protptype.drill {
+      #     label :fuel_type
+      #     path 'fuelType'
+      #     fixed 'diesel'
+      #   }
+      #
+      def drill(options={},&block)
+        construct(Drill,options,&block)
+      end
+
+      # Associate a new instance of the <i>Output</i> class (subclass of the
+      # <i>Term</i> class) with <tt>self</tt>, for representing an AMEE return value
+      #
+      # The newly instantiated <i>Term</i> object is configured according to the
+      # ('DSL') block passed in.
+      #
+      #   my_protptype.output {
+      #     label :co2
+      #     path 'CO2'
+      #   }
+      #
+      def output(options={},&block)
+        construct(Output,options,&block)
+      end
+
+      # Associate a new instance of the <i>Metadatum</i> class (subclass of the
+      # <i>Term</i> class) with <tt>self</tt>, for representing arbitrary metadata which
+      # is to be associated with each calculation. These may represent unique
+      # references to location, equipment (vehicles, furnaces), reporting periods,
+      # for example.
+      #
+      # The newly instantiated <i>Term</i> object is configured according to the
+      # ('DSL') block passed in.
+      #
+      #   my_protptype.metadatum {
+      #     label :reporting_period
+      #     value "July 2010"
+      #   }
+      #
+      def metadatum(options={},&block)
+        construct(Metadatum,options,&block)
+      end
+
+      # Helper method for automatically instantiating <i>Drill</i> class term
+      # objects representing all drill down choices based on those associated with
+      # the AMEE platform category with which <tt>self</tt> corresponds.
+      #
+      def all_drills
+        # Need to use #drill_downs rather than simply finding drills
+        # directly from #amee_ivds in order to establish drill order
+        amee_item_definition.drill_downs.each do |apath|
+          amee_ivds.each do |ivd|
+            next unless ivd.path == apath
+            drill {
+              path ivd.path
+              name ivd.name
+            }
+          end
+        end
+      end
+
+      # Helper method for automatically instantiating <i>Profile</i> class term
+      # objects representing all profile item values based on those associated with
+      # the AMEE platform category with which <tt>self</tt> corresponds.
+      #
+      # Each term is instantiated with path, name, choices, default_unit and
+      # default_per_unit attributes corresponding to those defined in the AMEE
+      # platform.
+      #
+      def all_profiles
+        amee_ivds.each do |ivd|
+          next unless ivd.profile?
+          construct_from_ivd(Profile,ivd)
+        end
+      end
+
+      # Helper method for automatically instantiating <i>Output</i> class term
+      # objects representing all return values based on those associated with
+      # the AMEE platform category with which <tt>self</tt> corresponds.
+      #
+      # Each term is instantiated with path, default_unit and default_per_unit
+      # attributes corresponding to those defined in the AMEE platform.
+      #
+      def all_outputs
+        amee_return_values.each do |rvd|
+          output {
+            path rvd.name
+            default_unit rvd.unit
+            default_per_unit rvd.perunit
+          }
+        end
+      end
+
+      # Helper method for automatically instantiating <i>Profile</i> class term
+      # objects representing only the profile item values associated with a
+      # particular usage (specified by <tt>usage</tt>) for the AMEE platform
+      # category with which <tt>self</tt> corresponds.
+      #
+      # This method does not permit dynamic usage switching during run-time.
+      #
+      # Each term is instantiated with path, name, choices, default_unit and
+      # default_per_unit attributes corresponding to those defined in the AMEE
+      # platform.
+      #
+      def profiles_from_usage(usage)
+        self.fixed_usage usage
+        amee_ivds.each do |ivd|
+          next unless ivd.profile?
+          construct_from_ivd(Profile,ivd) if ivd.compulsory?(usage) || ivd.optional?(usage)
+        end
+      end
+
+      # Helper method for automatically instantiating <i>Profile</i>, <i>Drill</i>
+      # and <i>Output</i> class term objects representing all profile item values,
+      # drill choices and return values associated with the AMEE platform category 
+      # with which <tt>self</tt> corresponds.
+      # 
+      # Optionally, instantiate only those profile terms corresponding to a
+      # particular usage by passing the path of the required usage as an argument.
+      # The latter case does not allow dynamic usage switching at run-time.
+      #
+      # Each term is instantiated with path, name, choices, default_unit and
+      # default_per_unit attributes corresponding to those defined in the AMEE
+      # platform.
+      #
+      def terms_from_amee(usage=nil)
+        all_drills
+        if usage
+          profiles_from_usage(usage)
+        else
+          all_profiles
+        end
+        all_outputs
+      end
+
+      # Helper method for automatically instantiating <i>Profile</i>, <i>Drill</i>
+      # and <i>Output</i> class term objects representing all profile item values, 
+      # drill choices and return values associated with the AMEE platform category 
+      # with which <tt>self</tt> corresponds.
+      # 
+      # Also automatically defines a usage term for the usage represented by
+      # <tt>ausage</tt> to enable dynamic usage switching. The profile terms
+      # associated with the specified usage are automatically activated and
+      # deactivated as appropriate, but this can be switched at run-time by
+      # changing the value of the instantiated usage term.
+      #
+      # Each term is instantiated with path, name, choices, default_unit and
+      # default_per_unit attributes (where appropriate) corresponding to those
+      # defined in the AMEE platform.
+      #
+      def terms_from_amee_dynamic_usage(ausage)
+        all_drills
+        usage{ value ausage}
+        all_outputs
+      end
+
+      # Helper method for automatically instantiating <i>Profile</i> class term
+      # objects representing all profile item values associated with the AMEE
+      # platform category represented by <tt>self</tt>, and instantiating a new instance
+      # of the <i>Usage</i> term class which can be used for dynamically switching
+      # usages at run-time.
+      #
+      # Each term is instantiated with path, name, choices, default_unit and
+      # default_per_unit attributes corresponding to those defined in the AMEE
+      # platform.
+      #
+      # The newly instantiated <i>Usage</i> object can be configured in place
+      # according to the ('DSL') block passed in, e.g.,
+      #
+      #   my_protptype.usage {
+      #     inactive :disabled
+      #     value nil
+      #   }
+      #
+      def usage(options={},&block)
+        all_profiles
+        construct(Usage,options.merge(:first=>true),&block)
+      end
+
+      # Helper method for automatically instantiating <i>Metadatum</i> class term 
+      # objects explicitly configured for storing start and end dates for an AMEE
+      # platform profile item.
+      #
+      def start_and_end_dates
+        metadatum {
+          path 'start_date'
+          name 'Start date'
+          interface :date
+          type :datetime
+          validation lambda{|v| v.is_a?(Time) || v.is_a?(DateTime) || (v.is_a?(String) && Date.parse(v) rescue false)}
+        }
+        metadatum {
+          path 'end_date'
+          name 'End date'
+          interface :date
+          type :datetime
+          validation lambda{|v| v.is_a?(Time) || v.is_a?(DateTime) || (v.is_a?(String) && Date.parse(v) rescue false)}
+        }
+      end
+
+      # Helper method for reopening and modifying the definition of the term with
+      # the label attribute matching <tt>label</tt>. Modification is specified in
+      # the passed block, which is evaluated in the context of the respective term
+      # instance.
+      #
+      # This is typically used to override (customize) the attributes and behaviour
+      # of term autoloaded from the AMEE platform using one of the instance helper
+      # methods of <tt>self</tt>.
+      #
+      def correcting(label,&block)
+        return unless contents[label]
+        contents[label].instance_eval(&block)
+      end
+
+      #Instantiate an OngoingCalculation based on this prototype, ready for
+      #communication with AMEE.
+      def begin_calculation
+        result=OngoingCalculation.new
+        contents.each do |k,v|
+          result.contents[k]=v.clone
+          result.contents[k].parent=result
+        end
+        result.path path
+        result.name name
+        result.label label
+        result.fixed_usage fixed_usage
+        result.save_amee saved_amee
+        result
+      end
+
+      private
+
+      def construct_from_ivd(klass,ivd)
+        # Initialize boolean values as ruby boolean objects
+        if (ivd.valuetype == "BOOLEAN") && (ivd.default == ("true"||"TRUE"))
+          default_value = true
+        elsif (ivd.valuetype == "BOOLEAN") && (ivd.default == ("false"||"FALSE"))
+          default_value = false
+        else
+          default_value = ivd.default
+        end
+
+        construct(klass) {
+          path ivd.path
+          name ivd.name
+          note ivd.meta.wikidoc
+          type ivd.valuetype.downcase
+          value default_value
+          choices ivd.choices
+          default_unit ivd.unit
+          default_per_unit ivd.perunit
+        }
+      end
+
+      # Construct a term of class klass, and evaluate a DSL block in its context.
+      def construct(klass,options={},&block)
+        new_content=klass.new(options.merge(:parent=>self),&block)
+        raise Exceptions::DSL.new(
+          "Attempt to create #{klass} without a label") unless new_content.label
+        if options[:first]
+          @contents.insert_at_start(new_content.label,new_content)
+        else
+          @contents[new_content.label]=new_content
+        end
+      end
+
+    end
+  end
+end