amee-data-abstraction 1.2.0 → 1.3.0

data/CHANGELOG.txt

@@ -1,4 +1,7 @@
 = Changelog
 
+== 1.3.0
+  * Reconfigure storage and API for Calculation Sets
+
 == 1.0.0
   * Initial public release

data/README.txt

@@ -25,9 +25,9 @@ Documentation: http://rubydoc.info/gems/amee-data-abstraction
  All gem requirements should be installed as part of the rubygems installation process 
  above, but are listed here for completeness.
 
- * amee ~> 3.0
+ * amee ~> 3.1
  * uuidtools = 2.1.2
- * quantify = 1.1.0
+ * quantify = 1.2.2
  
 == USAGE
 
@@ -117,16 +117,10 @@ Submit to AMEE for calculation
 
 Typical practice is initialize the calculation prototypes required for an
 application via a configuration file which creates the required calculation
-templates within an instance of CalculationSet. If the calculation set is assigned
-to a global variable or constant, the set of prototypes is available for
-initializing new calculations and templating view structures (e.g. tables, forms)
-from anywhere in the application.
+templates within an instance of CalculationSet. Such a configuration file can
+be structured the follow DSL:
 
-Adding a configuration to /config or /config/initializers may be appropriate
-
-  # e.g. /config/initializers/calculations.rb
-
-   Calculations = AMEE::DataAbstraction::CalculationSet {
+  # e.g. /config/calculations/my_emissions_calculations.rb
 
     calculation {
       label :electricity
@@ -148,17 +142,36 @@ Adding a configuration to /config or /config/initializers may be appropriate
       path "/some/fuel/associated/path/in/amee"
       terms_from_amee
     }
-  }
+
+The default location for such files within Rails applications is under
+/config/calculations. If such an approach is taken, the configuration can be
+read and a calculation set generated by using the filename, thus:
+
+  CalculationSet.find('my_emissions_calculations')
+
+                          #=> <AMEE::DataAbstraction::CalculationSet ... >
+
+Otherwise, the path to the configuration file can be provided:
+
+  CalculationSet.find('some/directory/my_emissions_calculations')
+
+                          #=> <AMEE::DataAbstraction::CalculationSet ... >
+
+The calculation set is accessible as follow using the same argument as used
+by the Find method (filename if conventional Rails location, path otherwise):
+
+  CalculationSet.sets['my_emissions_calculations']
 
                           #=> <AMEE::DataAbstraction::CalculationSet ... >
 
-From this global calculation set, initialize a new calculation
+And a new calcualtion can be initialized by providing the prototype calculation
+label:
 
-  my_fuel_calculation = Calculations[:fuel].begin_calculation
+  my_fuel_calculation = CalculationSet.sets['my_emissions_calcualtions'][:fuel].begin_calculation
 
                           #=> <AMEE::DataAbstraction::OngoingCalculation ... >
 
-  a_different_transport_calculation = Calculations[:transport].begin_calculation
+  a_different_transport_calculation = CalculationSet.sets['my_emissions_calcualtions'][:transport].begin_calculation
 
                           #=> <AMEE::DataAbstraction::OngoingCalculation ... >
 

data/Rakefile

@@ -74,22 +74,7 @@ Jeweler::Tasks.new do |gem|
 end
 Jeweler::RubygemsDotOrgTasks.new
 
-require 'rake/testtask'
-Rake::TestTask.new(:test) do |test|
-  test.libs << 'lib' << 'test'
-  test.pattern = 'test/**/test_*.rb'
-  test.verbose = true
-end
-
-require 'rcov/rcovtask'
-Rcov::RcovTask.new do |test|
-  test.libs << 'test'
-  test.pattern = 'test/**/test_*.rb'
-  test.verbose = true
-  test.rcov_opts << '--exclude "gems/*"'
-end
-
-task :default => :test
+task :default => :spec
 
 require 'rake/rdoctask'
 Rake::RDocTask.new do |rdoc|

data/VERSION

@@ -1 +1 @@
-1.2.0
+1.3.0

data/amee-data-abstraction.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{amee-data-abstraction}
-  s.version = "1.2.0"
+  s.version = "1.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["James Hetherington", "Andrew Berkeley", "James Smith", "George Palmer"]
-  s.date = %q{2011-10-10}
+  s.date = %q{2011-10-18}
   s.description = %q{Part of the AMEEappkit this gem provides a data abstraction layer, decreasing the amount and detail of development required}
   s.email = %q{help@amee.com}
   s.extra_rdoc_files = [
@@ -64,9 +64,10 @@ Gem::Specification.new do |s|
     "spec/core-extensions/hash_spec.rb",
     "spec/core-extensions/ordered_hash_spec.rb",
     "spec/core-extensions/proc_spec.rb",
-    "spec/fixtures/electricity.rb",
-    "spec/fixtures/electricity_and_transport.rb",
-    "spec/fixtures/transport.rb",
+    "spec/fixtures/config/calculations/electricity.rb",
+    "spec/fixtures/config/calculations/electricity_and_transport.rb",
+    "spec/fixtures/config/calculations/transport.rb",
+    "spec/fixtures/config/electricity.rb",
     "spec/spec.opts",
     "spec/spec_helper.rb"
   ]

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

@@ -132,7 +132,7 @@ module AMEE
       end
 
       def explorer_url
-         Rails.logger.info "#explorer_url method deprecated. Use #discover_url" if defined? Rails
+         Rails.logger.info "#explorer_url method deprecated. Use #discover_url" if defined?(Rails) && Rails.logger.present?
          discover_url
       end
        

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

@@ -36,22 +36,95 @@ module AMEE
     #
     class CalculationSet
 
-      # Initialize a <i>CalculationSet</i> with a "DSL" block, i.e. a block to be
-      # evaluated in the context of the instantiated CalculationSet
+      # Class variable holding all instantiated calculation sets keyed on the set
+      # name.
       #
-      def initialize(options={},&block)
-        @calculations=ActiveSupport::OrderedHash.new
+      @@sets = {}
+
+      # Convenience method for accessing the @@sets class variable
+      def self.sets
+        @@sets
+      end
+
+      # Retrieve a calculation set on the basis of a configuration file name or
+      # relatiev/absolute file path. If configuration files are location within
+      # the default Rails location under '/config/calculations' then the path and
+      # the .rb extenstion can be omitted from the name.
+      #
+      def self.find(name)
+        @@sets[name.to_sym] or load_set(name)
+      end
+
+      # Regenerate a configuration lock file assocaited with the master
+      # configuration file <tt>name</tt>. Optionally set a custom path for the
+      # lock file as <tt>output_path</tt>, otherwise the lock file path and
+      # filename will be based upon the master file with the extension .lock.rb.
+      #
+      def self.regenerate_lock_file(name,output_path=nil)
+        set = CalculationSet.find(name)
+        set.generate_lock_file(output_path)
+      end
+
+      # Find a specific prototype calculation instance without specifying the set
+      # to which it belongs.
+      #
+      def self.find_prototype_calculation(label)
+        @@sets.each_pair do |name,set|
+          set = find(name)
+          return set[label] if set[label]
+        end
+        return nil
+      end
+
+      protected
+
+      # Load a calculation set based on a filename or full path.
+      def self.load_set(name)
+        CalculationSet.new(name,:file => name) do
+          instance_eval(File.open(self.config_path).read)
+        end
+      end
+
+      DEFFAULT_RAILS_CONFIG_DIR = "config/calculations"
+
+      # Find the config file assocaited with <tt>name</tt>. The method first checks
+      # the default Rails configuration location (config/calculations) then the
+      # file path described by <tt>name</tt> relative to the Rails root and by
+      # absolute path.
+      def self.find_config_file(name)
+        default_config_dir = defined?(::Rails) ? "#{::Rails.root}/#{DEFFAULT_RAILS_CONFIG_DIR}" : nil
+        if defined?(::Rails) && File.exists?("#{default_config_dir}/#{name.to_s}.rb")
+          "#{default_config_dir}/#{name.to_s}.rb"
+        elsif defined?(::Rails) && File.exists?("#{default_config_dir}/#{name.to_s}")
+          "#{default_config_dir}/#{name.to_s}"
+        elsif defined?(::Rails) && File.exists?("#{::Rails.root}/#{name}")
+          "#{::Rails.root}/#{name}"
+        elsif File.exists?(name)
+          name
+        else
+          raise ArgumentError, "The config file '#{name}' could not be located"
+        end
+      end
+
+      public
+      
+      attr_accessor :calculations, :name, :file
+
+      # Initialise a new Calculation set. Specify the name of the calculation set 
+      # as the first argument. This name is used as the set key within the class
+      # variable @@sets hash.
+      #
+      def initialize(name,options={},&block)
+        raise ArgumentError, "Calculation set must have a name" unless name
+        @name = name
+        @file = CalculationSet.find_config_file(options[:file]) if options[:file]
+        @calculations = ActiveSupport::OrderedHash.new
         @all_blocks=[]
         @all_options={}
         instance_eval(&block) if block
+        @@sets[@name.to_sym] = self
       end
 
-      # Access the @calculations instance variable ordered hash. Keys are labels
-      # assocaited with each prototype calculation; values are the instantiated
-      # <i>PrototypeCalculation</i> objects
-      #
-      attr_accessor :calculations
-
       # Shorthand method for returning the prototype calculation which is represented
       # by a label matching <tt>sym</tt>
       #
@@ -94,8 +167,77 @@ module AMEE
             instance_exec(usage,&dsl_block)
           }
         end
+      end
 
+      # Returns the path to the configuration file for <tt>self</tt>. If a .lock
+      # file exists, this takes precedence, otherwise the master config file
+      # described by the <tt>#file</tt> attribute is returned.
+      #
+      def config_path
+        lock_file_exists? ? lock_file_path : @file
       end
+
+      # Returns the path to the configuration lock file
+      def lock_file_path
+        @file.gsub(".rb",".lock.rb") rescue nil
+      end
+
+      # Returns <tt>true</tt> if a configuration lock file exists. Otherwise,
+      # returns <tt>false</tt>.
+      #
+      def lock_file_exists?
+        File.exists?(lock_file_path)
+      end
+
+      # Generates a lock file for the calcuation set configuration. If no argument
+      # is provided the, the lock file is generated using the filename and path
+      # described by the <tt>#lock_file_path</tt> method. If a custom output
+      # location is required, this can be provided optionally as an argument.
+      #
+      def generate_lock_file(output_path=nil)
+        file = output_path || lock_file_path or raise ArgumentError,
+          "No path for lock file known. Either set path for the master config file using the #file accessor method or provide as an argument"
+        string = ""
+        @calculations.values.each do |prototype_calculation|
+          string += "calculation {\n\n"
+          string += "  name \"#{prototype_calculation.name}\"\n"
+          string += "  label :#{prototype_calculation.label}\n"
+          string += "  path \"#{prototype_calculation.path}\"\n\n"
+          prototype_calculation.terms.each do |term|
+            string += "  #{term.class.to_s.split("::").last.downcase} {\n"
+            string += "    name \"#{term.name}\"\n" unless term.name.blank?
+            string += "    label :#{term.label}\n" unless term.label.blank?
+            string += "    path \"#{term.path}\"\n" unless term.path.blank?
+            string += "    value \"#{term.value}\"\n" unless term.value.blank?
+
+            if term.is_a?(AMEE::DataAbstraction::Input)
+              string += "    fixed \"#{term.value}\"\n" if term.fixed? && !term.value.blank?
+              if term.is_a?(AMEE::DataAbstraction::Drill)
+                string += "    choices \"#{term.choices.join('\',\'')}\"\n" if term.instance_variable_defined?("@choices")  && !term.choices.blank?
+              elsif term.is_a?(AMEE::DataAbstraction::Profile)
+                string += "    choices [\"#{term.choices.join('\"','\"')}\"]\n" if term.instance_variable_defined?("@choices")  && !term.choices.blank?
+              end
+              string += "    optional!\n" if term.optional?
+            end
+
+            string += "    default_unit :#{term.default_unit.label}\n" unless term.default_unit.blank?
+            string += "    default_per_unit :#{term.default_per_unit.label}\n" unless term.default_per_unit.blank?
+            string += "    alternative_units :#{term.alternative_units.map(&:label).join(', :')}\n" unless term.alternative_units.blank?
+            string += "    alternative_per_units :#{term.alternative_per_units.map(&:label).join(', :')}\n" unless term.alternative_per_units.blank?
+            string += "    unit :#{term.unit.label}\n" unless term.unit.blank?
+            string += "    per_unit :#{term.per_unit.label}\n" unless term.per_unit.blank?
+            string += "    type :#{term.type}\n" unless term.type.blank?
+            string += "    interface :#{term.interface}\n" unless term.interface.blank?
+            string += "    note \"#{term.note}\"\n" unless term.note.blank?
+            string += "    disable!\n" if !term.is_a?(AMEE::DataAbstraction::Drill) && term.disabled?
+            string += "    hide!\n" if term.hidden?
+            string += "  }\n\n"
+          end
+          string += "}\n\n"
+        end
+        File.open(file,'w') { |f| f.write string }
+      end
+
     end
   end
 end

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

@@ -42,8 +42,14 @@ module AMEE
       def choices(*args)
         if args.empty?
           if @choices.blank?
-            c=parent.amee_drill(:before=>label).choices
-            c.length==1 ? [value] : c
+            drill_down = parent.amee_drill(:before=>label)
+            if single_choice = drill_down.selections[path]
+              disable!
+              [single_choice]
+            else
+              enable!
+              drill_down.choices
+            end
           else
             @choices
           end

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

@@ -11,6 +11,8 @@ module AMEE
     #
     class Input < Term
 
+      attr_accessor :dirty
+
       # Returns the valid choices for this input
       # (Abstract, implemented only for subclasses of input.)
       def choices
@@ -29,6 +31,7 @@ module AMEE
         @validation = nil
         validation_message {"#{name} is invalid."}
         super
+        @dirty = false
       end
 
       # Configures the value of <tt>self</tt> to be fixed to <tt>val</tt>, i.e.
@@ -67,6 +70,7 @@ module AMEE
           if args.first.to_s != @value.to_s
             raise Exceptions::FixedValueInterference if fixed?
             parent.dirty! if parent and parent.is_a? OngoingCalculation
+            mark_as_dirty
           end
         end
         super
@@ -155,6 +159,16 @@ module AMEE
         !optional?(usage)
       end
 
+      # Manually set the term as optional
+      def optional!
+        @optional=true
+      end
+
+      # Manually set the term as compuslory
+      def compulsory!
+        @optional=false
+      end
+
       # Check that the value of <tt>self</tt> is valid. If invalid, and is defined
       # as part of a calculation, add the invalidity message to the parent
       # calculation's error list. Otherwise, raise a <i>ChoiceValidation</i>
@@ -185,6 +199,10 @@ module AMEE
         super || fixed?
       end
 
+      def dirty?
+        @dirty
+      end
+
       protected
       # Returns <tt>true</tt> if the value set for <tt>self</tt> is either blank
       # or passes custom validation criteria. Otherwise, returns <tt>false</tt>.
@@ -192,6 +210,12 @@ module AMEE
       def valid?
         validation.blank? || validation === @value_before_cast
       end
+
+      def mark_as_dirty
+        @dirty = true
+        parent.dirty! if parent and parent.is_a? OngoingCalculation
+      end
+      
     end
   end
 end

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

@@ -235,6 +235,10 @@ module AMEE
         reset_invalidity_messages
       end
 
+      def clear_outputs
+        outputs.each {|output| output.value nil }
+      end
+
       def ==(other_calc)
         !terms.inject(false) do |boolean,term|
           boolean || term != other_calc[term.label]
@@ -254,7 +258,7 @@ module AMEE
       def load_outputs
         outputs.each do |output|
           res=nil
-          if output.path==:default
+          if output.path.to_s=='default'
             res= profile_item.amounts.find{|x| x[:default] == true}
           else
             res= profile_item.amounts.find{|x| x[:type] == output.path}
@@ -283,7 +287,7 @@ module AMEE
       # and units for any unset <i>Profile</i> terms (profile item values) from
       # the AMEE platform
       #
-      def load_profile_item_values  
+      def load_profile_item_values
         return unless profile_item
         profiles.unset.each do |term|
           ameeval=profile_item.values.find { |value| value[:path] == term.path }
@@ -305,6 +309,7 @@ module AMEE
       def load_drills
         return unless profile_item
         drills.each do |term|
+          next unless term.value.nil? || term.dirty?
           ameeval=data_item.value(term.path)
           raise Exceptions::Syncronization if term.set? && ameeval!=term.value
           term.value ameeval
@@ -325,6 +330,7 @@ module AMEE
           load_drills
         rescue Exceptions::Syncronization
           delete_profile_item
+          clear_outputs
         end
         load_metadata
         # We could create an unsatisfied PI, and just check drilled? here
@@ -451,10 +457,8 @@ module AMEE
       # <i>Profile</i> term values and attributes
       #
       def set_profile_item_values
-        AMEE::Profile::Item.update(connection,profile_item_path, 
-          profile_options.merge(:get_item=>false))
-        #Clear the memoised profile item, to reload with updated values
-        @profile_item=nil
+        @profile_item = AMEE::Profile::Item.update(connection,profile_item_path, 
+          profile_options.merge(:get_item=>true))
       end
 
       # Delete the profile item which is associated with <tt>self</tt> from the
@@ -463,7 +467,7 @@ module AMEE
       #
       def delete_profile_item
         AMEE::Profile::Item.delete(connection,profile_item_path)
-        self.profile_item_uid=false
+        self.profile_item_uid=nil
         @profile_item=nil
       end
 
@@ -509,6 +513,8 @@ module AMEE
         @profile_category||=AMEE::Profile::Category.get(connection, profile_category_path)
       end
 
+      public
+      
       # Automatically set the value of a drill term if there is only one choice
       def autodrill
         
@@ -529,8 +535,6 @@ module AMEE
         end
       end
 
-      public
-
       # Instantiate an <tt>AMEE::Data::DrillDown</tt> object representing the
       # drill down sequence defined by the drill terms associated with
       # <tt>self</tt>. As with <tt>#drill_options</tt>, An optional hash argument