rbatch 2.1.6 → 2.1.7

data/.gitignore

@@ -1,3 +1,4 @@
 pkg/
 sample/log/*.log
 coverage/
+.yardoc/

data/README.ja.md

@@ -1,4 +1,4 @@
-[[English]](https://github.com/fetaro/rbatch/blob/master/README.md "english") [[Japanese]](https://github.com/fetaro/rbatch/blob/master/README.ja.md "japanese")
+[English](https://github.com/fetaro/rbatch/blob/master/README.md "english") | [Japanese ](https://github.com/fetaro/rbatch/blob/master/README.ja.md "japanese") |  [Document (YardDoc)](http://fetaro.github.io/rbatch/index.html)
 
 RBatch:Ruby-base バッチ スクリプト フレームワーク
 =============
@@ -30,7 +30,7 @@ RBatchはRubyで書かれたシンプルなバッチスクリプトのフレー
     $ ruby bin/hello_world.rb
     $ cat log/YYYYMMDD_HHMMSS_hello_world.log
 
-マニュアル
+機能概要
 --------------
 
 ### RBatchホームディレクトリ
@@ -166,6 +166,9 @@ p r.status # => 0
 
 `forbid_double_run`のオプションを利用すれば、RBatchを利用したプログラムの二重起動チェックができます。
 
+ドキュメント
+--------------
+こちらにあります→ [Document (YardDoc)](http://fetaro.github.io/rbatch/index.html)
 
 サンプル
 --------------

data/README.md

@@ -1,4 +1,4 @@
-[[English]](https://github.com/fetaro/rbatch/blob/master/README.md "english") [[Japanese]](https://github.com/fetaro/rbatch/blob/master/README.ja.md "japanese")
+[English](https://github.com/fetaro/rbatch/blob/master/README.md "english") | [Japanese ](https://github.com/fetaro/rbatch/blob/master/README.ja.md "japanese") |  [Document (YardDoc)](http://fetaro.github.io/rbatch/index.html)
 
 RBatch: Framework for Ruby-based Batch Script
 =============
@@ -31,7 +31,7 @@ Quick Start
     $ ruby bin/hello_world.rb
     $ cat log/YYYYMMDD_HHMMSS_hello_world.log
 
-Manual
+Overview
 --------------
 
 ### RBatch home directory
@@ -166,6 +166,11 @@ You have no use for an error handring.
 
 Using `forbid_double_run` option, two same name scripts cannot run at the same time.
 
+Manual
+--------------
+
+Manual -> [Document (YardDoc)](http://fetaro.github.io/rbatch/index.html)
+
 Sample
 --------------
 
@@ -366,14 +371,13 @@ Sample of RBatch Run-Conf `${RB_HOME}/.rbatchrc`.
 # Delete old log files
 #
 #   Default is false.
-#   If this is true, delete old log file when RBatch::Log.new is called.
-#   A log file to delete is a log file which was made by the
-#   RBatch::Log instance, and log filename format include "<date>".
+#   If this is true, delete old log files when RBatch::Log.new is called.
+#   If log filename format does not include "<date>", do nothing.
 #
 #log_delete_old_log : true
 #log_delete_old_log : false
 
-# Expire Date of Log Files
+# Expire Days of Log Files
 #
 #   Default is 7.
 #
@@ -382,8 +386,8 @@ Sample of RBatch Run-Conf `${RB_HOME}/.rbatchrc`.
 # Send Mail
 #
 #   Default is false.
-#   When log.error(msg) or log.fatal(msg) called , send e-mail
-#   including "msg".
+#   When log.error is called, log.fatal is called,
+#   or rescue an Exception, send e-mail.
 #
 #log_send_mail : true
 

data/lib/rbatch/cmd.rb

@@ -4,12 +4,27 @@ require 'tmpdir'
 require 'timeout'
 module RBatch
 
+  # External command wrapper
   class Cmd
+    # @private
     @@def_vars
-    def Cmd.def_vars=(a)    ; @@def_vars=a ; end
+
+    # @private
+    # @param [RBatch::Variables] vars
+    def Cmd.def_vars=(vars)    ; @@def_vars=vars ; end
+
+    # command string
     @cmd_str
+    
+    # option
     @opt
+
+    # @private
     @vars
+
+    # @param [String] cmd_str command string such as "ls -l"
+    # @option opt [Boolean] :raise
+    # @option opt [Integer] :timeout
     def initialize(cmd_str,opt = nil)
       raise(CmdException,"Command string is nil") if cmd_str.nil?
       @cmd_str = cmd_str
@@ -24,6 +39,9 @@ module RBatch
       end
     end
 
+    # Run command
+    # @raise [RBatch::CmdException]
+    # @return [RBatch::CmdResult]
     def run()
       stdout_file = Tempfile::new("rbatch_tmpout",Dir.tmpdir)
       stderr_file = Tempfile::new("rbatch_tmperr",Dir.tmpdir)
@@ -39,7 +57,7 @@ module RBatch
             Process.kill('SIGINT', pid)
             raise(CmdException,"Run time of command \"#{@cmd_str}\" is over #{@vars[:cmd_timeout].to_s} sec. Success to kill process : PID=#{pid}" )
           rescue
-            raise(CmdException,"Run time of command \"#{@cmd_str}\" is over #{@vars[:cmd_timeout].to_s} sec. Fail to kill process : PID=#{pid}" )
+            raise(CmdException,"Run time of command \"#{@cmd_str}\" is over #{@vars[:cmd_timeout].to_s} sec. But Fail to kill process : PID=#{pid}" )
           end
         end
       else
@@ -53,30 +71,53 @@ module RBatch
     end
   end
 
+  # Result of external command wrapper
   class CmdResult
-    @stdout_file
-    @stderr_file
-    @status
-    @cmd_str
+
+    # Tmp file including STDOUT String
+    # @return [File]
+    attr_reader :stdout_file
+
+    # Tmp file including STDERROR String
+    # @return [File]
+    attr_reader :stderr_file
+
+    # Exit status
+    # @return [Integer]
+    attr_reader :status
+
+    # Command string
+    # @return [String]
+    attr_reader :cmd_str
+
+    # @private
     def initialize(stdout_file, stderr_file, status, cmd_str)
       @stdout_file = stdout_file
       @stderr_file = stderr_file
       @status = status
       @cmd_str = cmd_str
     end
-    def stdout_file ; @stdout_file ; end
-    def stderr_file ; @stderr_file ; end
-    def status      ; @status      ; end
-    def cmd_str     ; @cmd_str     ; end
+
+    # STDOUT String
+    # @return [String]
     def stdout
       File.read(@stdout_file)
     end
+
+    # STDERR String
+    # @return [String]
     def stderr
       File.read(@stderr_file)
     end
+
+    # Return hash including cmd_str, std_out, std_err, and status
+    # @return [Hash]
     def to_h
       {:cmd_str => @cmd_str,:stdout => stdout, :stderr => stderr, :status => status}
     end
+    
+    # Return string including cmd_str, std_out, std_err, and status
+    # @return [String]
     def to_s
       to_h.to_s
     end

data/lib/rbatch/config.rb

@@ -4,34 +4,42 @@ require 'pathname'
 module RBatch
 
   class Config
+    # Config file path
     @path
+
+    # Actual data
     @hash
+
+    # @param [String] path Config file path
     def initialize(path)
       @path = path
       begin
-        @hash = YAML::load_file(@path)
+        @hash = ConfigElement.new(YAML::load_file(@path))
       rescue Errno::ENOENT => e
         @hash = nil
       end
     end
+
+    # Config value
+    # @param [Object] key Config key.
+    # @raise [RBatch::ConfigException]
     def[](key)
       if @hash.nil?
         raise RBatch::ConfigException, "Config file \"#{@path}\" does not exist"
-      end
-      if @hash[key].nil?
-        if key.class == Symbol
-          raise RBatch::ConfigException, "Value of key(:#{key} (Symbol)) is nil. By any chance, dou you mistake key class Symbol for String?"
-        elsif key.class == String
-          raise RBatch::ConfigException, "Value of key(\"#{key}\" (String)) is nil"
-        else
-          raise RBatch::ConfigException, "Value of key(#{key}) is nil."
-        end
       else
         @hash[key]
       end
     end
+
+    # Config file path
+    # @return [String]
     def path ; @path ; end
+
+    # Config file exists or not
+    # @return [Boolean]
     def exist? ; ! @hash.nil? ; end
+
+    # @return [Hash]
     def to_h
       if @hash.nil?
         raise RBatch::ConfigException, "Config file \"#{@path}\" does not exist"
@@ -39,6 +47,8 @@ module RBatch
         @hash
       end
     end
+
+    # @return [String]
     def to_s
       if @hash.nil?
         raise RBatch::ConfigException, "Config file \"#{@path}\" does not exist"
@@ -48,6 +58,33 @@ module RBatch
     end
   end
 
+  class ConfigElement < Hash
+    def initialize(hash)
+      hash.each_key do |key|
+        if hash[key].class == Hash
+          self[key] = ConfigElement.new(hash[key])
+        else
+          self[key] = hash[key]
+        end
+      end
+    end
+
+    def[](key)
+      if self.has_key?(key)
+        super
+      else
+        if key.class == Symbol
+          raise RBatch::ConfigException, "Value of key(:#{key} (Symbol)) does not exist. By any chance, dou you mistake key class Symbol for String?"
+        elsif key.class == String
+          raise RBatch::ConfigException, "Value of key(\"#{key}\" (String)) does not exist"
+        else
+          raise RBatch::ConfigException, "Value of key(#{key}) does not exist."
+        end
+        raise
+      end
+    end
+  end
+
   class RBatch::ConfigException < StandardError ; end
 end
 

data/lib/rbatch/controller.rb

@@ -7,6 +7,7 @@ require 'rbatch/config'
 require 'rbatch/cmd'
 
 module RBatch
+  # @private
   class Controller
     attr :vars,:config,:common_config,:journal,:user_logs
     def initialize

data/lib/rbatch/double_run_checker.rb

@@ -1,6 +1,7 @@
 require 'tmpdir'
 require 'tempfile'
 module RBatch
+  # @private
   module DoubleRunChecker
     module_function
     def lock_file_name(p)
@@ -20,5 +21,6 @@ module RBatch
     end
   end
 
+  # @private
   class DoubleRunCheckException < Exception ; end
 end

data/lib/rbatch/journal.rb

@@ -1,4 +1,5 @@
 module RBatch
+  # @private
   class Journal
     @@def_vars
     def Journal.def_vars=(a) ; @@def_vars=a ; end 

data/lib/rbatch/log.rb

@@ -6,6 +6,7 @@ require 'net/smtp'
 
 module RBatch
   class Log
+    # @private
     @@FORMATTER = proc do |severity, datetime, progname, msg|
       head = "[#{datetime}] [" + sprintf("%-5s",severity) +"]"
       if msg.is_a? Exception
@@ -14,6 +15,8 @@ module RBatch
         "#{head} #{msg}\n"
       end
     end
+
+    # @private
     @@STDOUT_FORMATTER = proc do |severity, datetime, progname, msg|
       head = "[" + sprintf("%-5s",severity) +"]"
       if msg.is_a? Exception
@@ -22,6 +25,8 @@ module RBatch
         "#{head} #{msg}\n"
       end
     end
+
+    # @private
     @@LOG_LEVEL_MAP = {
       "debug" => Logger::DEBUG,
       "info"  => Logger::INFO,
@@ -29,20 +34,82 @@ module RBatch
       "error" => Logger::ERROR,
       "fatal" => Logger::FATAL
     }
+
+    # @private
     @@def_vars
-    def Log.def_vars=(a)
-      raise ArgumentError, "type mismatch: #{a} for #RBatch::Variables" if ! a.kind_of?(RBatch::Variables)
-      @@def_vars=a
+
+    # @private
+    # @param [RBatch::Variables] v
+    def Log.def_vars=(v)
+      raise ArgumentError, "type mismatch: #{v} for #RBatch::Variables" if ! v.kind_of?(RBatch::Variables)
+      @@def_vars=v
     end
+
+    # @private
+    # @return [RBatch::Variables]
     def Log.def_vars    ; @@def_vars ; end
+
+    # @private
     @@journal
-    def Log.journal=(a) ; @@journal=a ; end
 
+    # @private
+    # @param [RBatch::Journal] j
+    def Log.journal=(j) ; @@journal=j ; end
+
+    # @private
     @vars
+
+    # @private
     @opt
+
+    # @private
     @log
+
+    # @private
     @stdout_log
 
+    # External command wrapper
+    # @option opt [String] :dir Output directory
+    # @option opt [String] :name 
+    #   Log file name.
+    #   Default is "<date>_<time>_<prog>.log".
+    #   <data> is replaced to YYYYMMDD date string
+    #   <time> is replaced to HHMMSS time string
+    #   <prog> is replaced to Program file base name (except extention).
+    #   <host> is replaced to Hostname.
+    # @option opt [Boolean] :append
+    # @option opt [String] :level
+    #  Effective values are "debug","info","wran","error",and "fatal".
+    # @option opt [Boolean] :stdout
+    #   Print log string both log file and STDOUT
+    # @option opt [Boolean] :delete_old_log
+    #   If this is true, delete old log files when this is called.
+    #   If log filename does not include "<date>", do nothing.
+    # @option opt [Integer] :delete_old_log_date
+    # @option opt [Boolean] :send_mail
+    #   When log.error(str) is called,
+    #   log.fatal(str) is called , or rescue an Exception,
+    #   send e-mail.
+    # @option opt [String] :mail_to
+    # @option opt [String] :mail_from
+    # @option opt [String] :mail_server_host
+    # @option opt [Integer] :mail_server_port
+    # @raise [RBatch::LogException]
+    # @yield [log] RBatch::Log instance
+    # @return [RBatch::Log]
+    # @example
+    #  require 'rbatch'
+    #  RBatch::Log.new{ |log|
+    #    log.info "info string"
+    #    log.error "error string"
+    #    raise "exception" # => rescued in this block
+    #  }
+    # @example use option
+    #  require 'rbatch'
+    #  RBatch::Log.new({:name => "hoge.log"}){ |log|
+    #    log.info "info string"
+    #  }
+
     def initialize(opt=nil)
       @opt = opt
       @vars = @@def_vars.clone
@@ -78,7 +145,7 @@ module RBatch
         @stdout_log.formatter = @@STDOUT_FORMATTER
       end
       # delete old log
-      self.delete_old_log(@vars[:log_delete_old_log_date]) if @vars[:log_delete_old_log]
+      delete_old_log(@vars[:log_delete_old_log_date]) if @vars[:log_delete_old_log]
       # Start logging
       @@journal.put 1,"Logging Start: \"#{@path}\""
       @@journal.add_log(self)
@@ -89,61 +156,63 @@ module RBatch
           if e.status == 0
             exit 0
           else
-            self.fatal(e)
-            self.fatal("Caught SystemExit. RBatch Exit with status " + e.status.to_s)
+            fatal(e)
+            fatal("Caught SystemExit. RBatch Exit with status " + e.status.to_s)
             exit e.status
           end
         rescue Exception => e
-          self.fatal(e)
-          self.fatal("Caught exception. RBatch Exit with status 1")
+          fatal(e)
+          fatal("Caught exception. RBatch Exit with status 1")
           exit 1
         ensure
-          self.close
+          close
         end
       end
     end
 
-    def fatal(a)
-      @stdout_log.fatal(a) if @vars[:log_stdout]
-      @log.fatal(a)
-      send_mail(a) if @vars[:log_send_mail]
-    end
-
-    def error(a)
-      @stdout_log.error(a) if @vars[:log_stdout]
-      @log.error(a)
-      send_mail(a) if @vars[:log_send_mail]
+    # Out put log with ERROR level
+    # @param [String] str log string
+    def fatal(str)
+      @stdout_log.fatal(str) if @vars[:log_stdout]
+      @log.fatal(str)
+      send_mail(str) if @vars[:log_send_mail]
     end
 
-    def warn(a)
-      @stdout_log.warn(a) if @vars[:log_stdout]
-      @log.warn(a)
+    # Out put log with ERROR level
+    # @param [String] str log string
+    def error(str)
+      @stdout_log.error(str) if @vars[:log_stdout]
+      @log.error(str)
+      send_mail(str) if @vars[:log_send_mail]
     end
 
-    def info(a)
-      @stdout_log.info(a) if @vars[:log_stdout]
-      @log.info(a)
+    # Out put log with WARN level
+    # @param [String] str log string
+    def warn(str)
+      @stdout_log.warn(str) if @vars[:log_stdout]
+      @log.warn(str)
     end
 
-    def debug(a)
-      @stdout_log.debug(a) if @vars[:log_stdout]
-      @log.debug(a)
+    # Out put log with INFO level
+    # @param [String] str log string
+    def info(str)
+      @stdout_log.info(str) if @vars[:log_stdout]
+      @log.info(str)
     end
 
-    def journal(a)
-      @log.info("[RBatch] " + a)
+    # Out put log with DEBUG level
+    # @param [String] str log string
+    def debug(str)
+      @stdout_log.debug(str) if @vars[:log_stdout]
+      @log.debug(str)
     end
 
-    def close
-      @log.close
+    # @private
+    def journal(str)
+      @log.info("[RBatch] " + str)
     end
 
-    # Delete old log files.
-    # If @vars[:log_name] is not include "<date>", then do nothing.
-    #
-    # ==== Params
-    # - +date+ (Integer): The day of leaving log files
-    #
+    private
     def delete_old_log(date = 7)
       if Dir.exists?(@vars[:log_dir]) && @vars.raw_value(:log_name).include?("<date>")
         Dir::foreach(@vars[:log_dir]) do |file|
@@ -160,9 +229,10 @@ module RBatch
       end
     end
 
-    private
+    def close
+      @log.close
+    end
 
-    # send mail
     def send_mail(msg)
       body = <<EOT
 From: <#{@vars[:log_mail_from]}>

data/lib/rbatch/run_conf.rb

@@ -1,6 +1,7 @@
 require 'tmpdir'
 require 'yaml'
 module RBatch
+  # @private
   class RunConf
     attr :path,:opt
     @yaml

data/lib/rbatch/variables.rb

@@ -2,6 +2,7 @@ require 'pathname'
 require 'rbatch/run_conf'
 
 module RBatch
+  # @private
   class Variables
     attr :vars,:run_conf,:merged_opt
     def initialize(run_conf=nil)
@@ -74,5 +75,6 @@ module RBatch
     end
 
   end
+  # @private
   class RBatch::VariablesException < StandardError ; end
 end

data/lib/rbatch/version.rb

@@ -1,3 +1,3 @@
 module RBatch
-  VERSION = "2.1.6"
+  VERSION = "2.1.7"
 end

data/lib/rbatch.rb

@@ -3,15 +3,61 @@ $LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__)))
 require 'rbatch/controller'
 
 module RBatch
+  # @private
   @@ctrl = nil
+
   module_function
+
+  # @private
   def init
     @@ctrl = RBatch::Controller.new
   end
+
+  # @private
   def ctrl ; @@ctrl ; end
+
+  # @private
   def vars ; @@ctrl.vars ; end
+
+  # Return Config Object
+  # @raise [RBatch::ConfigException]
+  # @return [RBatch::Config]
+  # @example RB_HOME/conf/hoge.yaml
+  #  key: value
+  #  array:
+  #   - item1
+  #   - item2
+  #   - item3
+  # @example ${RB_HOME}/bin/hoge.rb
+  #   p RBatch.config["key"]   # => "value"
+  #   p RBatch.config["array"] # => ["item1", "item2", "item3"]
+  #   p RBatch.config["not_exist"] # => Raise RBatch::ConfigException
   def config               ; @@ctrl.config ; end
+
+  # Return Common-Config Object
+  # @raise [RBatch::ConfigException]
+  # @return [RBatch::Config]
+  # @example RB_HOME/conf/common.yaml
+  #  key: value
+  #  array:
+  #   - item1
+  #   - item2
+  #   - item3
+  # @example ${RB_HOME}/bin/hoge.rb
+  #   p RBatch.common_config["key"]   # => "value"
+  #   p RBatch.common_config["array"] # => ["item1", "item2", "item3"]
+  #   p RBatch.common_config["not_exist"] # => Raise RBatch::ConfigException
   def common_config        ; @@ctrl.common_config ; end
+
+  # Shortcut of RBatch::Cmd.new(cmd_str,opt).run
+  # @see RBatch::Cmd
+  # @example
+  #   r = RBatch.cmd("ls")
+  #   p r.stdout # => "fileA\nfileB\n"
+  #   p r.stderr # => ""
+  #   p r.status # => 0
+  # @example
+  #   r = RBatch.cmd("rsync /foo /bar",{:timeout => 10})
   def cmd(cmd_str,opt=nil) ; @@ctrl.cmd(cmd_str,opt) ; end
 end
 

data/spec/rbatch/config_spec.rb

@@ -65,3 +65,29 @@ describe RBatch::Config do
     }.to raise_error(RBatch::ConfigException)
   end
 end
+
+describe RBatch::ConfigElement do
+  it "" do
+    hash = {
+      "a" => "av" ,
+      "b" => {
+        "c" => "cv",
+        "d" => {
+          "e" => "ev",
+          "f" => [1,2,3]
+        }
+      }
+    }
+    ce = RBatch::ConfigElement.new(hash)
+    expect(ce["a"]).to eq "av"
+    expect(ce["b"].class).to eq RBatch::ConfigElement
+    expect(ce["b"]["c"]).to eq "cv"
+    expect(ce["b"]["d"].class).to eq RBatch::ConfigElement
+    expect(ce["b"]["d"]["e"]).to eq "ev"
+    expect(ce["b"]["d"]["f"][1]).to eq 2
+    expect { ce["noexist"] }.to raise_error(RBatch::ConfigException)
+    expect { ce["noexist"]["noexist"] }.to raise_error(RBatch::ConfigException)
+    expect { ce["b"]["noexist"] }.to raise_error(RBatch::ConfigException)
+    expect { ce["b"]["d"]["noexist"] }.to raise_error(RBatch::ConfigException)
+  end
+end