dotanuki 0.0.3 → 0.0.4

data/.gitignore

@@ -1,4 +1,6 @@
 *.gem
 .bundle
+.yardoc
 Gemfile.lock
-pkg/*
+pkg
+doc

data/README.md

@@ -6,17 +6,17 @@ failed commands.
 
 Examples
 ========
-In the following example, if the mkdir fails, none of the other commands will
+In the following example, if the `mkdir` fails, none of the other commands will
 be executed.
 
-	class Foo
-		include 'dotanuki'
+	class Example
+		include Dotanuki
 
 		def test
 			commands = [
 				"mkdir /tmp/foo",
-				"cd /tmp/foo",
-				"cp /etc/hosts ."
+				"cp /etc/hosts /tmp/foo",
+				"cp /etc/passwd /tmp/foo"
 			]
 
 			result = execute(commands)
@@ -25,3 +25,16 @@ be executed.
 			end
 		end
 	end
+
+It can also be used with a `guard` block, which will raise an `ExecError` if a command fails.
+
+    class Example
+		include Dotanuki
+		def test
+			guard do
+				execute "mkdir /tmp/foo"
+				execute "cp /etc/hosts /tmp/foo"
+				execute "cp /etc/passwd /tmp/foo"
+			end
+		end
+    end

data/lib/dotanuki/version.rb

@@ -1,3 +1,4 @@
 module Dotanuki
-  VERSION = "0.0.3"
+  # gem version
+  VERSION = "0.0.4"
 end

data/lib/dotanuki.rb

@@ -1,17 +1,40 @@
 require 'popen4'
 
+# Module intented to be included into classes which execute system commands
+# @author Martin Englund
 module Dotanuki
 
-  # thrown when an execution error occurs
+  # Error raised when an execution error occurs
   class ExecError < StandardError
-    def initialize(msg)
-      super(msg)
+    # Create a new ExecError
+    #
+    # @param [String] message error message
+    def initialize(message)
+      super(message)
     end
   end
 
-  # class for the result of an execution of one or more commands
+  # Result of one or more command executions
   class ExecResult
-    attr_reader :stdout, :stderr, :status, :failed_index
+
+    # Array of stdout from each command executed
+    # @return [Array]
+    attr_reader :stdout
+
+    # Array of stderr from each command executed
+    # @return [Array]
+    attr_reader :stderr
+
+    # Exit status of the command that failed, nil if the command was not found
+    # and 0 if all commands succeeded
+    #
+    # @return [Fixnum]
+    attr_reader :status
+
+    # Index of the command that failed, or nil if all commands succeeded
+    # @return [Fixnum]
+    attr_reader :failed_index
+
     def initialize
       @stdout = []
       @stderr = []
@@ -19,7 +42,7 @@ module Dotanuki
       @failed_index = nil
     end
 
-    # Returns true if the command has failed
+    # Returns true if a command has failed
     def failed?
       status != 0
     end
@@ -29,15 +52,17 @@ module Dotanuki
       stderr[@failed_index]
     end
 
+    # Add the result of a command execution
     def add(stdout, stderr, status)
       @stdout << stdout
       @stderr << stderr
-      @status = status
       if status.nil? || status != 0
+        @status = status
         @failed_index = @stdout.size - 1
       end
     end
 
+    # Add another [ExecResult] to this
     def <<(result)
       raise ArgumentError unless result.is_a?(ExecResult)
       # TODO merge correctly
@@ -45,24 +70,30 @@ module Dotanuki
     end
   end
 
+  # Default options for executing commands
+  DEFAULT_OPTIONS = {:on_error => :exception}
+
+  # @param [Hash] options the options for error handling
+  # @option options [Symbol] :on_error How to handle errors,
+  #   can be either `:exception` or `:silent`
   def initialize(options={})
-    @defaults = {}
-    @defaults[:on_error] = :exception
-    @defaults.merge!(options)
+    @defaults = DEFAULT_OPTIONS.merge(options)
   end
 
-  # Execute commands in a block and return an array of ExecResult
+  # Execute commands wrapped in a block
   #
+  # @param [Hash] options (see #guard)
+  # @return [ExecResult]
   # @example
   #   guard do
   #     execute "uname -a"
   #     execute "ls /does/not/exist"
   #   end
-  #
-  # TODO this is not thread safe
+  # @note this method isn't thread safe
   def guard(options={}, &block)
     opts = @defaults.merge(options)
     validate_options(opts)
+    # TODO this is not thread safe
     @guard = ExecResult.new
     yield
     clear_guard
@@ -72,14 +103,18 @@ module Dotanuki
     result
   end
 
-  # commands can be a string or an array of strings
+  # Execute one or more commands
+  #
+  # @param [String, Array] commands string or array containing the command to be executed
+  # @param [Hash] options (see #guard)
+  # @return [ExecResult]
   def execute(commands, options={})
     validate_options(options)
 
     result = ExecResult.new
 
     [commands].flatten.each do |command|
-      stdout, stderr, exit_status = _execute(command, options)
+      stdout, stderr, exit_status = _execute(command)
       result.add(stdout, stderr, exit_status)
       if options[:on_error] == :exception || @guard
         if exit_status.nil?
@@ -98,7 +133,12 @@ module Dotanuki
     return result
   end
 
-  def _execute(command, options={})
+  # Execute a single command
+  #
+  # @param [String] command string containing the command to be executed
+  # @return [String, String, Fixnum] standard out, standard error and exit
+  #   status of the command
+  def _execute(command)
     stdout = stderr = ""
 
     status =
@@ -110,6 +150,9 @@ module Dotanuki
     return stdout, stderr, status ? status.exitstatus : status
   end
 
+  # Validates options for Dotanuki#execute or Dotanuki#guard
+  #
+  # @raise [ArgumentError] if an unknown option is given
   def validate_options(options)
     options.each do |option, value|
       if option == :on_error && ! [:exception, :silent].include?(value)
@@ -121,6 +164,7 @@ module Dotanuki
 
   private
 
+  # TODO this is not thread safe
   def clear_guard
     result = @guard
     @guard = nil

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dotanuki
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -14,7 +14,7 @@ default_executable:
 dependencies:
 - !ruby/object:Gem::Dependency
   name: popen4
-  requirement: &2157101940 !ruby/object:Gem::Requirement
+  requirement: &2161180600 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -22,10 +22,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2157101940
+  version_requirements: *2161180600
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2157101500 !ruby/object:Gem::Requirement
+  requirement: &2161180020 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -33,10 +33,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2157101500
+  version_requirements: *2161180020
 - !ruby/object:Gem::Dependency
   name: metric_fu
-  requirement: &2157100960 !ruby/object:Gem::Requirement
+  requirement: &2161179480 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -44,7 +44,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2157100960
+  version_requirements: *2161179480
 description: A command executioner which doesn't blindly stumble on when a command
   fails'
 email: