laborantin 0.0.14 → 0.0.21

data/lib/laborantin/core/completeable.rb

@@ -0,0 +1,30 @@
+
+module Laborantin
+  module Metaprog
+    module Completeable
+      # A block to propose completion on this option
+      attr_reader :completion_block
+
+      # Stores the block argument in the completion_block, usage is for DSLs
+      def complete(&blk)
+        @completion_block = blk
+      end
+
+
+      # Provides completion facility for comma-separated lists of args, and returns the propositions
+      # - removes items already in list
+      # - prepends commas for items not already in list
+      def completion_propositions_iterating_on(cmd, list)
+        envs_on_cli = cmd.split.last.split(',').reject{|s| s.start_with?('-')}
+        last_env_on_cli = envs_on_cli.last unless cmd.end_with?(',')
+        last_env_on_cli ||= ''
+        complete_envs_on_cli = envs_on_cli - [last_env_on_cli]
+
+        list = list.select{|str| str.start_with?(last_env_on_cli)}
+        candidate_envs = list - envs_on_cli
+        candidate_envs.map{|str| (complete_envs_on_cli + [str]).join(',') } 
+      end
+
+    end
+  end
+end

data/lib/laborantin/core/configurable.rb

@@ -0,0 +1,28 @@
+
+module Laborantin
+  module Metaprog
+    module Configurable
+      # A hash placeholder for extra config (e.g. git revision for the git implementation)
+      attr_accessor :config
+
+      # saves the @config in a YAML config file
+      def save_config
+        File.open(config_path, 'w') do |f|
+          f.puts YAML.dump(config)
+        end
+      end
+
+      # restore the configuration from the config file
+      def load_config!(path=config_path)
+        if File.file?(path)
+          @config = YAML.load_file(path)
+        end
+        @config ||= {}
+      end
+
+      def config_path
+        "config.yaml"
+      end
+    end
+  end
+end

data/lib/laborantin/core/datable.rb

@@ -0,0 +1,13 @@
+
+module Laborantin
+  module Metaprog
+    module Datable
+      attr_accessor :date
+
+      # Format the date of as a string (rounded at 1second).
+      def date_str
+        date.strftime("%Y-%h-%d_%H-%M-%S")
+      end
+    end
+  end
+end

data/lib/laborantin/core/describable.rb

@@ -0,0 +1,11 @@
+
+module Laborantin
+  module Metaprog
+    module Describable
+      # A description used for printing summary and debug purposes.
+      attr_accessor :description
+
+      alias :describe :description=
+    end
+  end
+end

data/lib/laborantin/core/environment.rb

@@ -21,9 +21,15 @@ Copyright (c) 2009, Lucas Di Cioccio
 
 =end
 
-require 'time'
-require 'logger'
-require 'fileutils'
+autoload :Time, 'time'
+autoload :Logger, 'logger'
+autoload :FileUtils, 'fileutils'
+
+require 'laborantin/core/datable'
+require 'laborantin/core/describable'
+require 'laborantin/core/hookable'
+require 'laborantin/core/configurable'
+require 'laborantin/core/multi_name'
 
 module Laborantin
 
@@ -37,26 +43,38 @@ module Laborantin
   # If you want to do that, you must know that Environment @@all class variable
   # holds a reference to every child class from Environment.
   class Environment
+    include Metaprog::Datable
+    include Metaprog::Configurable
+    extend Metaprog::Describable
+    extend Metaprog::Hookable
+    extend Metaprog::MultiName
+
     @@all = []
 
     # Populates loaded (i.e. put in @@all class variable when self.inherited 
     # is called) environment classes from existing results that are stored in
     # the dir parameter.
     def self.scan_resdir(dir)
-      ret = []
+      list = []
       Dir.entries(dir).each do |f| 
-        envklass = Laborantin::Environment.all.find{|e| e.name.duck_case == f} 
+        envklass = Laborantin::Environment.all.find{|e| e.fs_name == f} 
         if envklass
           Dir.entries(envklass.envdir).each do |e|
             if e =~ /\d+-\w+-\d+_\d+-\d+-\d+/
-              env = envklass.new #XXX don't prepare! it hence don't overwrite logs
-              env.rundir = File.join(envklass.envdir, e)
-              ret << env
+              env = envklass.new_loading_from_dir(File.join(envklass.envdir, e))
+              list << env
             end
           end
         end
       end
-      ret
+      list
+    end
+
+    def self.new_loading_from_dir(path)
+      obj = self.new
+      obj.load_config!
+      obj.rundir = path
+      obj
     end
 
     class << self
@@ -66,15 +84,6 @@ module Laborantin
       # CURRENTLY NOT HERITED
       attr_accessor :verifications
 
-      # A description used for printing summary and debug purposes. Will be 
-      # used to create .tex report in the future.
-      # CURRENTLY NOT HERITED
-      attr_accessor :description
-
-      # A hash to store setup/teardown hooks.
-      # CURRENTLY NOT HERITED
-      attr_accessor :hooks
-
       # Prepares attributes' default values whenever a subclass is created.
       def inherited(klass)
         klass.verifications = []
@@ -83,40 +92,20 @@ module Laborantin
         @@all << klass
       end
 
-      # Registers new verifiers.
+      # Registers new verifiers methods that will be verified at beginning.
       def verify(*args)
         self.verifications = [*args].flatten
       end
 
-      # Sets the description.
-      def describe(str)
-        self.description = str
-      end
-
-      # Registers setup hooks, called before any scenario is instantiated.
-      def setup(*args)
-        self.hooks[:setup] = [*args].flatten
-      end
-
-      # Registers teardown hooks, called after every scenarii has been 
-      # performed and analyzed.
-      def teardown(*args)
-        self.hooks[:teardown] = [*args].flatten
-      end
-
-      def to_s
-        "#{self.name}:\n\t#{self.description}"
-      end
-
       # Returns all the known subklasses of Environment.
       def all
         @@all
       end
 
       # The path where the results for instance of a subklass of Environment
-      # are stored (needs the Laborantin.resultdir).
+      # are stored (needs the Runner's resultdir).
       def envdir
-        File.join(Laborantin.resultdir, self.name.duck_case)
+        File.join(Runner.instance.resultdir, self.fs_name)
       end
     end
 
@@ -124,28 +113,76 @@ module Laborantin
     # are stored. Can be overridden (e.g. Environment.scan_resdir does that).
     attr_accessor :rundir
 
-    # A date that holds the creation of the instance, it is not meaningful 
-    # when an env was created by a call to Environment.scan_resdir.
-    # TODO better
-    attr_accessor :date
-
     # An array of loggers objects.
     attr_accessor :loggers
 
-    def initialize
+    # The (optional) commmand instanciating this environment
+    attr_accessor :command
+
+    # Initializes a new instance:
+    # the date is Time.now
+    # the rundir is the Environment.envdir followed by the date_str
+    # the loggers contains an empty Array
+    # Does NOT create any directory, so the accessors can be overwritten if needed.
+    def initialize(command=nil)
+      @command = command
       @date = Time.now
       @rundir = File.join(self.class.envdir, date_str)
       @loggers = []
+      @config = {}
     end
 
+    def runner
+      command.runner if command
+    end
+
+    # sends all the methods registered in Environment.verify
+    # returns the method symbol of the failed verification if any
     def valid?
       self.class.verifications.find{|v| not send(v)}.nil?
     end
 
+    # complete path to the environment.log file
     def logfile_path
       File.join(rundir, 'environment.log')
     end
 
+    # complete path to the config.yaml file
+    def config_path
+      File.join(rundir, 'config.yaml')
+    end
+
+    def scenarii_dirs
+      config[:scenarii_dirs]
+    end
+
+    def record_scenario_dir(dir, save=false)
+      config[:scenarii_dirs] ||= []
+      config[:scenarii_dirs] << dir
+      save_config if save
+    end
+
+    # gets the state of the environment
+    def state
+      config[:state]
+    end
+
+    # changes the state of the environment
+    def state=(val, save=true)
+      config[:state] = val
+      save_config if save
+    end
+
+    # returns if the environment succeeded
+    def successful?
+      config[:state] == :success
+    end
+
+    # returns if the environment exited with error
+    def failed?
+      config[:state] == :error
+    end
+
     # In the following order:
     # * Creates the envdir if needed.
     # * Adds some loggers.
@@ -159,6 +196,8 @@ module Laborantin
       @loggers << Logger.new(STDOUT)
       log(self.class.description, :info) unless self.class.description.empty?
       log "Directories prepared"
+      log "Writing config file"
+      save_config
       call_hooks :setup
     end
 
@@ -178,15 +217,14 @@ module Laborantin
       Laborantin::Scenario.scan_env(self)
     end
 
-    def date_str
-      date.strftime("%Y-%h-%d_%H-%M-%S")
-    end
-
     private
 
     def call_hooks(name)
       log "Calling #{name} hooks"
-      self.class.hooks[name].each{|sym| send sym}
+      self.class.hooks[name].each do |sym| 
+        log "(#{sym})" 
+        send sym
+      end
     end
 
   end # class

data/lib/laborantin/core/hookable.rb

@@ -0,0 +1,20 @@
+
+module Laborantin
+  module Metaprog
+    module Hookable
+      # A hash to store setup/teardown hooks.
+      attr_accessor :hooks
+
+      # Registers setup hooks.
+      def setup(*args)
+        hooks[:setup] = [*args].flatten
+      end
+
+      # Register teardown hooks.
+      def teardown(*args)
+        hooks[:teardown] = [*args].flatten
+      end
+    end
+  end
+end
+      

data/lib/laborantin/core/monkey_patches.rb

@@ -35,4 +35,3 @@ class String
     self.gsub(/([A-Z])/){|s| "_#{$1.downcase}"}.sub(/^_/,'')
   end
 end
-

data/lib/laborantin/core/multi_name.rb

@@ -0,0 +1,25 @@
+
+module Laborantin
+  module Metaprog
+    module MultiName
+      AVAILABLE_NAMES = [:cli, :fs]
+
+      def set_name(sym, val)
+        raise ArgumentError, "invalid name sym: #{sym}, expected in #{AVAILABLE_NAMES.inspect}" unless AVAILABLE_NAMES.include?(sym)
+        send "#{sym}_name=", val
+      end
+
+      # a way to name on the command line
+      attr_writer :cli_name
+      def cli_name
+        @cli_name || name.duck_case
+      end
+
+      # a way to name on the filesystem
+      attr_writer :fs_name
+      def fs_name
+        @fs_name || name.duck_case
+      end
+    end
+  end
+end

data/lib/laborantin/core/parameter.rb

@@ -21,19 +21,20 @@ Copyright (c) 2009, Lucas Di Cioccio
 
 =end
 
+require 'laborantin/core/describable'
+
 module Laborantin
 
   # A ParameterRange instance is more or less a wrapper over an Array of allowed values.
   class ParameterRange
 
+    include Metaprog::Describable
+
     # The name of the parameter (should be unique in a Scenario's parameters)
     # Usually a symbol.
     attr_accessor :name
 
-    # A description used for printing summary and debug purposes. Will be 
-    # used to create .tex report in the future.
-    attr_accessor :description
-
+    # initialize a new instance with the desired name
     def initialize(name)
       @name = name
       @values = []
@@ -54,13 +55,5 @@ module Laborantin
       end
     end
 
-    # Sets the description.
-    def describe(str)
-      @description = str
-    end
-
-    def to_s
-      "#{values.inspect}\n\t\t#{@description}"
-    end
   end
 end

data/lib/laborantin/core/parameter_hash.rb

@@ -40,8 +40,12 @@ module Laborantin
       end
     end
 
-    def to_s
-      keys.inject(''){|s,k| s + "\t- #{k}: #{self[k]}.\n"}
+    def each_config_with_index
+      idx = 0
+      each_config do |cfg|
+        yield cfg, idx
+        idx += 1
+      end
     end
   end
 end

data/lib/laborantin/core/scenario.rb

@@ -21,11 +21,18 @@ Copyright (c) 2009, Lucas Di Cioccio
 
 =end
 
-require File.join(File.dirname(__FILE__), 'parameter')
-require File.join(File.dirname(__FILE__), 'parameter_hash')
+require 'laborantin/core/parameter'
+require 'laborantin/core/parameter_hash'
 
-require 'fileutils'
-require 'yaml'
+autoload :FileUtils, 'fileutils'
+autoload :YAML, 'yaml'
+
+require 'laborantin/core/datable'
+require 'laborantin/core/describable'
+require 'laborantin/core/hookable'
+require 'laborantin/core/configurable'
+require 'laborantin/core/multi_name'
+require 'laborantin/core/table'
 
 module Laborantin
 
@@ -41,42 +48,45 @@ module Laborantin
   # Like the Environment, all the subklasses will be stored in a @@all 
   # class variable for convenience purpose.
   class Scenario
+    include Metaprog::Datable
+    include Metaprog::Configurable
+    extend Metaprog::Describable
+    extend Metaprog::Hookable
+    extend Metaprog::MultiName
+
     @@all = []
 
     # Scans the env's envdir (should be an Environment) for scenarii results.
-    # It will set their configuration according to the stored config.yaml 
-    # in YAML format.
-    # Returns an array of such built scenarii.
+    # It will set their configuration (i.e. run date and parameters hash)
+    # according to the stored config.yaml in YAML format.  Returns an array of
+    # such built scenarii.
     def self.scan_env(env)
-      scs = []
+      list = []
       Dir.entries(env.rundir).each do |s|
-        scklass = Laborantin::Scenario.all.find{|t| t.name.duck_case == s}
+        scklass = Laborantin::Scenario.all.find{|t| t.fs_name == s}
         if scklass
           Dir.entries(scklass.scenardir(env)).each do |r|
             if r =~ /\d+-\w+-\d+_\d+-\d+-\d+/
-              scenar = scklass.new(env)
-              scs << scenar
-              scenar.rundir = File.join(scklass.scenardir(env), r)
-              tst, params = YAML.load_file(File.join(scenar.rundir, 'config.yaml'))
-              scenar.params = params
+              scenar = scklass.new_loading_from_dir(env, File.join(scklass.scenardir(env), r))
+              list << scenar
             end
           end
         end
       end
-      scs
+      list
     end
 
-    class << self
-
-      # A description used for printing summary and debug purposes. Will be 
-      # used to create .tex report in the future.
-      # CURRENTLY NOT HERITED
-      attr_accessor :description
-
-      # A hash to store setup/teardown hooks.
-      # CURRENTLY NOT HERITED
-      attr_accessor :hooks
+    def self.new_loading_from_dir(env, path)
+      obj = self.new(env)
+      yml_path = File.join(path, 'config.yaml')
+      tst, params = obj.load_config!(yml_path)
+      obj.params = params
+      obj.date = tst
+      obj.rundir = path
+      obj
+    end
 
+    class << self
       # The set of parameters that will vary for this Scenario.
       attr_accessor :parameters
 
@@ -95,21 +105,6 @@ module Laborantin
         @@all << klass
       end
 
-      # Sets the description.
-      def describe(str)
-        self.description = str
-      end
-
-      # Registers setup hooks.
-      def setup(*args)
-        self.hooks[:setup] = [*args].flatten
-      end
-
-      # Register teardown hooks.
-      def teardown(*args)
-        self.hooks[:teardown] = [*args].flatten
-      end
-
       # Defines a new ParameterRange instance for this Scenario.
       # A block should be passed that will be evaluated in this 
       # ParameterRange instance's context.
@@ -133,10 +128,6 @@ module Laborantin
         self.products = [*args].flatten
       end
 
-      def to_s
-        "#{self.name}:\n\t#{self.description}\n#{self.parameters}"
-      end
-
       # Returns all the known subklasses of Scenario.
       def all
         @@all
@@ -147,7 +138,7 @@ module Laborantin
       # will use '.' as rootdir for the Scenario results.
       def scenardir(env=nil)
         envdir = env.rundir || '.'
-        File.join(envdir, self.name.duck_case)
+        File.join(envdir, self.fs_name)
       end
     end # class << 
 
@@ -157,19 +148,20 @@ module Laborantin
     # The environment in which we run this scenario.
     attr_accessor :environment
 
-    # A date that holds the creation of the instance, it is not meaningful 
-    # when an env was created by a call to Environment.scan_resdir.
-    # TODO better
-    attr_accessor :date
-
     # An attribute that holds the directory where the config and the results
     # are stored. Can be overridden (e.g. Scenario.scan_env does that).
     attr_accessor :rundir
 
+    # Initializes a new instance contains in the env Environment, and 
+    # for the parameter set params.
+    # Sets the date to Time.now for unicity (with 1sec granularity)
+    # Sets the rundir accessor in the directory.
+    # Does NOT create any directory, so the accessors can be overwritten if needed.
     def initialize(env, params={})
       @environment = env
       @params = params
       @date = Time.now
+      @config = {}
       @rundir = File.join(self.class.scenardir(environment), date_str)
     end
 
@@ -185,8 +177,10 @@ module Laborantin
       log self.params.inspect, :info
       log "Preparing directory #{rundir}"
       FileUtils.mkdir_p(rundir)  #TODO: ensure unicity
+      environment.record_scenario_dir(rundir, true)
       log "Storing configuration in YAML format"
-      File.open( config_path, 'w') {|f| f.puts YAML.dump( [date, params] ) }
+      @config = [date, params]
+      save_config
     end
 
     # In the following order:
@@ -216,53 +210,82 @@ module Laborantin
     # Appends each yielded line from this method.
     def analyze!
       self.class.products.each do |name|
-        log "Producing #{name}"
+        log "(#{name})"
         product_file(name.to_s, 'w') do |f|
-          send name do |l|
+          send(name) do |l|
             f.puts l
           end
         end
-        log "Product #{name} done"
       end
     end
 
-    def date_str
-      date.strftime("%Y-%h-%d_%H-%M-%S")
-    end
-
-    private
-
-    def call_hooks(name)
-      log "Calling #{name} hooks"
-      self.class.hooks[name].each{|sym| send sym}
-    end
-
-    def log(*args)
-      environment.log *args
-    end
-
+    # Returns the absolute path to a product file (see File.join) If brutname
+    # is true, then resultname is appended to the rundir of the scenario.  If
+    # brutname is false, then before being appended to the rundir of the
+    # scenario, the name is surronded by result.<resultname>.txt 
+    #
+    # The idea behind this is to avoid name collisions between simple users of
+    # Laborantin, and people developping extensions or modules.
     def product_path(resultname, brutname=false)
       resultname = "result.#{resultname}.txt" unless brutname
       File.join(rundir, resultname)
     end
 
+    # Yields an open file for a given product, will make sure it is closed.
+    # mode is the mode in which the file is opened (you should leave it to 'r')
+    # see the doc for product_path to understand the role of brutname
     def product_file(resultname, mode='r', brutname=false)
       File.open(product_path(resultname, brutname), mode) do |f|
         yield f
       end
     end
 
+    # The path to the config.yaml file that holds the scenario parameters.
     def config_path
       product_path('config.yaml', true)
     end
 
+    # The path to the "raw result", i.e. the one built when you yield in the
+    # run method.
     def raw_result_path
       product_path('result.raw', true)
     end
 
+    # Yield the opened raw result file, will close it afterwards.
+    # mode is the mode in which the file is opened (default to 'r')
+    # never open the file in another mode, unless you know what you're doing,
+    # because this file most likely contains the value of your work, i.e., your
+    # data.
     def raw_result_file(mode='r')
-      product_file('result.raw', mode, true){|f| yield f}
+      product_file('result.raw', mode, true) do |f| 
+        yield f
+      end
+    end
+
+    def table(name, struct)
+      Table.new(name, struct, self.product_path(name))
     end
 
+    private
+
+    def call_hooks(name)
+      log "Calling #{name} hooks"
+      self.class.hooks[name].each do |sym| 
+        log "(#{sym})" 
+        send sym
+      end
+    end
+
+    def log(*args)
+      environment.log *args
+    end
+
+    def command
+      environment.command
+    end
+
+    def runner
+      environment.runner
+    end
   end # class
 end