laborantin 0.0.9 → 0.0.10

data/Rakefile

@@ -3,7 +3,7 @@ require 'rake/gempackagetask'
 
 spec = Gem::Specification.new do |s|
         s.name = 'laborantin'
-        s.version = '0.0.9'
+        s.version = '0.0.10'
         s.platform = Gem::Platform::RUBY
         s.summary = "A measurement batch facilitator"
 
@@ -33,7 +33,7 @@ spec = Gem::Specification.new do |s|
 	s.bindir = 'bin'
 	s.executables = ['labor']
 
-        s.has_rdoc = false
+        s.has_rdoc = true
 end
 
 Rake::GemPackageTask.new(spec) do |pkg|

data/TODO

@@ -3,6 +3,4 @@ replay / pause / restart
 => interaction with rubydrill?
 => or direct stats
 
-export results via ftp
-
 creation of a script that doesn't depends on laborantin for export?

data/bin/labor

@@ -1,9 +1,9 @@
 #!/usr/bin/env ruby
 
-require	'optparse'
 require 'rubygems'
 require 'laborantin'
 #require '../lib/laborantin'
+require	'optparse'
 require	'fileutils'
 require 'find'
 require 'erb'

data/lib/laborantin.rb

@@ -28,8 +28,27 @@ require File.join(File.dirname(__FILE__), 'laborantin', 'core', 'environment')
 require File.join(File.dirname(__FILE__), 'laborantin', 'core', 'monkey_patches')
 
 module Laborantin
-  VERSION = '0.0.9'
+  VERSION = '0.0.10'
   AUTHORS = ['Lucas Di Cioccio']
   WEBSITE = 'http://dicioccio.fr'
   LICENSE = 'GNU GPL version 3'
+
+  @@rootdir = '.'
+
+  # The root of the arborescence for Laborantin. Usually the directory created
+  # via the scripts.
+  def self.rootdir
+    @@rootdir || '.'
+  end
+
+  # Specifies the rootdir, dir is a path (instance of String, not a Dir object).
+  def self.rootdir=(dir='.')
+    @@rootdir = dir
+  end
+
+  # The path to the results (needs the Laborantin.rootdir).
+  def self.resultdir
+    File.join(Laborantin.rootdir, 'results')
+  end
+
 end

data/lib/laborantin/core/environment.rb

@@ -26,10 +26,22 @@ require 'logger'
 require 'fileutils'
 
 module Laborantin
+  
+  # An Environment represents the surrounding of an experiment. Basically, it
+  # should only contains things that are hard to change during an experiment.
+  # Let's say you have two computers, A and B. A can be a server and B a client
+  # or vice-versa. Hence, this is a good choice for two differents environments.
+  #
+  # As a normal user, you should only subclass Environment, and let the script
+  # creates it for you. But it is easy to monkey-patch or to subclass by hand.
+  # 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
     @@all = []
-    @@rootdir = '.'
 
+    # 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 = []
       Dir.entries(dir).each do |f| 
@@ -48,20 +60,22 @@ module Laborantin
     end
 
     class << self
-      attr_accessor :verifications, :description, :envdir, :hooks
 
-      def rootdir=(dir='.')
-	@@rootdir = dir
-      end
+      # An array of methods called to ensure that the environment run is the
+      # wanted one (e.g. a way to specify a RUBY_PLATFORM).
+      # CURRENTLY NOT HERITED
+      attr_accessor :verifications
 
-      def rootdir
-	@@rootdir || '.'
-      end
+      # 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
 
-      def resultdir
-	@@resultdir = File.join(@@rootdir, 'results')
-      end
+      # 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 = []
 	klass.description = ''
@@ -69,18 +83,23 @@ module Laborantin
 	@@all << klass
       end
 
+      # Registers new verifiers.
       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
@@ -89,20 +108,31 @@ module Laborantin
 	"#{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).
       def envdir
-	File.join(resultdir, self.name.duck_case)
+	File.join(Laborantin.resultdir, self.name.duck_case)
       end
-
     end
 
-    #XXX: rundir is the easier way to override the rundir (instead of parsing a date)
-    attr_accessor :rundir, :date, :loggers
+    # An attribute that holds the directory where the logfile and the scenarii results
+    # 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(dir='.')
+    def initialize
       @date = Time.now
       @rundir = File.join(self.class.envdir, date_str)
       @loggers = []
@@ -112,6 +142,13 @@ module Laborantin
       self.class.verifications.find{|v| not send(v)}.nil?
     end
 
+    # In the following order:
+    # * Creates the envdir if needed.
+    # * Adds some loggers.
+    # * Calls the setup hooks methods
+    # BEWARE : currently does not ensure unicity of envdir, 
+    # so wait one sec between several runs of same env
+    #
     def prepare!
       FileUtils.mkdir_p(rundir) #TODO: ensure unicity
       @loggers << Logger.new(File.join(rundir, 'environment.log'))
@@ -121,14 +158,18 @@ module Laborantin
       call_hooks :setup
     end
 
+    # Calls the teardown hooks methods.
     def teardown!
       call_hooks :teardown
     end
 
+    # Send str log message at the levele lvl to every loggers.
     def log(str, lvl=:debug)
       @loggers.each{|l| l.send(lvl, str)}
     end
 
+    # Returns an array of Scenario objects from the results in the envdir.
+    # The scenarii classes must be loaded before, else, some results might be ignored.
     def populate
       Laborantin::Scenario.scan_env(self)
     end

data/lib/laborantin/core/monkey_patches.rb

@@ -21,10 +21,16 @@ Copyright (c) 2009, Lucas Di Cioccio
 
 =end
 
+# Some monkey patches on String. Will be moved later to a subclass.
 class String
+  # Returns a camelized version of a duck_case self
+  #   'some_string'.camelize # => 'SomeString'
   def camelize
     self.split('_').map{|i| i.capitalize}.join('')
   end
+
+  # Returns a duck cased version of camel-like self
+  #   'SomeString'.duck_case # => 'some_string'
   def duck_case
     self.gsub(/([A-Z])/){|s| "_#{$1.downcase}"}.sub(/^_/,'')
   end

data/lib/laborantin/core/parameter.rb

@@ -22,25 +22,39 @@ Copyright (c) 2009, Lucas Di Cioccio
 =end
 
 module Laborantin
+
+  # A ParameterRange instance is more or less a wrapper over an Array of allowed values.
   class ParameterRange
-    attr_accessor :name, :description
+
+    # 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
+
     def initialize(name)
       @name = name
       @values = []
       @description = ''
     end
 
+    # Sets the allowed values. Currently only supports Array like. 
+    # It is planned to support Iterable, but deterministic ones only.
     def values(*args)
       @values = args.flatten unless args.empty?
       @values
     end
 
+    # Iterates on allowed values for this parameter.
     def each
       @values.each do |v| 
-	yield v
+        yield v
       end
     end
 
+    # Sets the description.
     def describe(str)
       @description = str
     end

data/lib/laborantin/core/parameter_hash.rb

@@ -23,16 +23,20 @@ Copyright (c) 2009, Lucas Di Cioccio
 
 
 module Laborantin
+  # A kind of Hash that can yields all possible configuration recursively.
+  # It should contains ParameterRange like definitions objects.
   class ParameterHash < Hash
+    # Recursively yields all the possible configurations of parameters (a new hash).
+    # No order is supported on the recursion, and it is not planned to.
     def each_config(remaining=self.keys, cfg={}, &blk)
       key = remaining.pop
       if key
-	self[key].each do |val|
-	  cfg[key] = val
-	  each_config(remaining.dup, cfg, &blk)
-	end
+        self[key].each do |val|
+          cfg[key] = val
+          each_config(remaining.dup, cfg, &blk)
+        end
       else
-	yield cfg
+        yield cfg
       end
     end
 

data/lib/laborantin/core/scenario.rb

@@ -28,9 +28,25 @@ require 'fileutils'
 require 'yaml'
 
 module Laborantin
+
+  # A Scenario represents a measurement done in a given environment. Some of
+  # its parameters will change, and we are interested in varying these parameters and
+  # then study their impact.
+  #
+  # An user will usually creates a Scenario subklass which represents such 
+  # a measurement. For that he must defines a run method that will yield consecutive
+  # lines added to the raw result file. Then this file can be processed to give 
+  # intermediary or final results.
+  #
+  # Like the Environment, all the subklasses will be stored in a @@all 
+  # class variable for convenience purpose.
   class Scenario
     @@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.
     def self.scan_env(env)
       scs = []
       Dir.entries(env.rundir).each do |s|
@@ -50,8 +66,26 @@ module Laborantin
     end
 
     class << self
-      attr_accessor :description, :parameters, :products, :hooks
 
+      # 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
+
+      # The set of parameters that will vary for this Scenario.
+      attr_accessor :parameters
+
+      # Some special products that are done after an analysis on a measurement
+      # scenario. The intended way is to store raw results (e.g. a command output) in
+      # a file and then parse them and store the parsed result in another file etc.
+      # TODO : products that compares scenarii
+      attr_accessor :products
+
+      # Prepares attributes' default values whenever a subclass is created.
       def inherited(klass)
         klass.parameters = ParameterHash.new
         klass.description = ''
@@ -60,19 +94,30 @@ 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.
+      #
+      #   parameter(:size) do
+      #     values 10, 20, 30
+      #     describe "We expect a linear RTT increase with the size"
+      #   end
+      #
       def parameter(name, &blk)
         raise ArgumentError.new("Parameter #{name} already exists") if self.parameters[name]
         param = ParameterRange.new(name)
@@ -80,6 +125,9 @@ module Laborantin
         self.parameters[name] = param
       end
 
+      # Defines the products names.
+      # IMPORTANT: products are built in the provided order, and they must be 
+      # valid instance methods name for a Scenario object (hence user defined).
       def produces(*args)
         self.products = [*args].flatten
       end
@@ -88,17 +136,34 @@ module Laborantin
         "#{self.name}:\n\t#{self.description}\n#{self.parameters}"
       end
 
+      # Returns all the known subklasses of Scenario.
       def all
         @@all
       end
 
+      # Returns the path where the results of the instances of this Scenario
+      # will be stored given that we are in the env Environment. If env is nil,
+      # will use '.' as rootdir for the Scenario results.
       def scenardir(env=nil)
         envdir = env.rundir || '.'
         File.join(envdir, self.name.duck_case)
       end
     end # class << 
 
-    attr_accessor :params, :environment, :date, :rundir
+    # A hash of parameters for this run.
+    attr_accessor :params
+
+    # 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
 
     def initialize(env, params={})
       @environment = env
@@ -107,6 +172,13 @@ module Laborantin
       @rundir = File.join(self.class.scenardir(environment), date_str)
     end
 
+    # In the following order:
+    # * Log some info in the environment
+    # * Creates the rundir to store the result and the config
+    # * Stores the configuration as well as the run date
+    # BEWARE : currently does not ensure unicity of rundir, 
+    # so wait one sec between several runs of same Scenario
+    #
     def prepare!
       log(self.class.description, :info) unless self.class.description.empty?
       log self.params.inspect, :info
@@ -116,6 +188,15 @@ module Laborantin
       File.open( config_path, 'w') {|f| f.puts YAML.dump( [date, params] ) }
     end
 
+    # In the following order:
+    # * Calls the setup hooks
+    # * Logs some info
+    # * Creates the raw result file
+    # * Calls the run method (user defined)
+    # * ... for each yielded line, store it into the raw result file
+    # * once completed (or on error) closes the raw result file
+    # * Logs some info
+    # * Calls the teardown hooks
     def perform!
       call_hooks :setup
       log "Starting measurement"
@@ -128,6 +209,10 @@ module Laborantin
       call_hooks :teardown
     end
 
+    # For each product define with Scenario.produces, and in its order,
+    # create a file with a canonic name in the scenario rundir.
+    # Call the instance method which has the product name.
+    # Appends each yielded line from this method.
     def analyze!
       self.class.products.each do |name|
         log "Producing #{name}"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: laborantin
 version: !ruby/object:Gem::Version 
-  version: 0.0.9
+  version: 0.0.10
 platform: ruby
 authors: 
 - Di Cioccio Lucas
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-07-27 00:00:00 +02:00
+date: 2009-07-28 00:00:00 +02:00
 default_executable: 
 dependencies: []
 
@@ -40,7 +40,7 @@ files:
 - lib/laborantin/core/parameter_hash.rb
 - lib/laborantin/core/scenario.rb
 - lib/laborantin/core/monkey_patches.rb
-has_rdoc: false
+has_rdoc: true
 homepage: http://rubyforge.org/projects/laborantin
 post_install_message: 
 rdoc_options: []