ztk 1.4.4 → 1.4.5

data/README.md

@@ -30,7 +30,7 @@ Issues:
 
 ZTK - Zachary's (DevOp) Tool Kit
 
-* Author: Zachary Patten <zachary@jovelabs.com> [![endorse](http://api.coderwall.com/zpatten/endorsecount.png)](http://coderwall.com/zpatten)
+* Author: Zachary Patten <zachary AT jovelabs DOT com> [![endorse](http://api.coderwall.com/zpatten/endorsecount.png)](http://coderwall.com/zpatten)
 * Copyright: Copyright (c) Zachary Patten
 * License: Apache License, Version 2.0
 

data/Rakefile

@@ -1,6 +1,6 @@
 ################################################################################
 #
-#      Author: Zachary Patten <zachary@jovelabs.net>
+#      Author: Zachary Patten <zachary AT jovelabs DOT com>
 #   Copyright: Copyright (c) Zachary Patten
 #     License: Apache License, Version 2.0
 #

data/lib/ztk.rb

@@ -1,24 +1,4 @@
-################################################################################
-#
-#      Author: Zachary Patten <zachary@jovelabs.net>
-#   Copyright: Copyright (c) Zachary Patten
-#     License: Apache License, Version 2.0
-#
-#   Licensed under the Apache License, Version 2.0 (the "License");
-#   you may not use this file except in compliance with the License.
-#   You may obtain a copy of the License at
-#
-#       http://www.apache.org/licenses/LICENSE-2.0
-#
-#   Unless required by applicable law or agreed to in writing, software
-#   distributed under the License is distributed on an "AS IS" BASIS,
-#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-#   See the License for the specific language governing permissions and
-#   limitations under the License.
-#
-################################################################################
-
-require "ztk/version"
+require 'ztk/version'
 
 # Main ZTK module
 #
@@ -26,12 +6,12 @@ require "ztk/version"
 # in mind.  It provides several classes that ease SSH and SFTP, templating,
 # and a myraid of other activities.
 #
-# @author Zachary Patten <zachary@jovelabs.net>
+# @author Zachary Patten <zachary AT jovelabs DOT com>
 module ZTK
 
   # ZTK error class
   #
-  # @author Zachary Patten <zachary@jovelabs.net>
+  # @author Zachary Patten <zachary AT jovelabs DOT com>
   class Error < StandardError; end
 
   autoload :Base, "ztk/base"

data/lib/ztk/ansi.rb

@@ -1,44 +1,25 @@
-################################################################################
-#
-#      Author: Zachary Patten <zachary@jovelabs.net>
-#   Copyright: Copyright (c) Zachary Patten
-#     License: Apache License, Version 2.0
-#
-#   Licensed under the Apache License, Version 2.0 (the "License");
-#   you may not use this file except in compliance with the License.
-#   You may obtain a copy of the License at
-#
-#       http://www.apache.org/licenses/LICENSE-2.0
-#
-#   Unless required by applicable law or agreed to in writing, software
-#   distributed under the License is distributed on an "AS IS" BASIS,
-#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-#   See the License for the specific language governing permissions and
-#   limitations under the License.
-#
-################################################################################
 module ZTK
 
   # ANSI Error Class
-  # @author Zachary Patten <zachary@jovelabs.net>
+  #
+  # @author Zachary Patten <zachary AT jovelabs DOT com>
   class ANSIError < Error; end
 
   # ANSI Mixin Module
   #
-  # Include this module to enable easy ANSI coloring methods like:
+  # Standard use is to mix this module into String.
   #
+  # @example Mix this module into String to enable easy ANSI coloring methods like:
   #   "bold red".red.bold
   #
-  # Or
-  #
+  # @example Or
   #   "green".green
   #
-  # Standard use is to mix this module into String.
-  #
-  # @author Zachary Patten <zachary@jovelabs.net>
+  # @author Zachary Patten <zachary AT jovelabs DOT com>
   module ANSI
 
-    COLOR_MATRIX = {
+    # Defines our ANSI color codes
+    ANSI_COLORS = {
       :black   => 30,
       :red     => 31,
       :green   => 32,
@@ -49,20 +30,91 @@ module ZTK
       :white   => 37
     }
 
-    ATTRIBUTE_MATRIX = {
+    # @!method black(string=nil, &block)
+    #   Sets the foreground color to black for the supplied string.
+    #   @param [String] string The string to operate on.
+    #   @yieldreturn [String] The string to operate on.
+    #   @return [String] The colored string.
+    #
+    # @!method red(string=nil, &block)
+    #   Sets the foreground color to red for the supplied string.
+    #   @param [String] string The string to operate on.
+    #   @yieldreturn [String] The string to operate on.
+    #   @return [String] The colored string.
+    #
+    # @!method green(string=nil, &block)
+    #   Sets the foreground color to green for the supplied string.
+    #   @param [String] string The string to operate on.
+    #   @yieldreturn [String] The string to operate on.
+    #   @return [String] The colored string.
+    #
+    # @!method yellow(string=nil, &block)
+    #   Sets the foreground color to yellow for the supplied string.
+    #   @param [String] string The string to operate on.
+    #   @yieldreturn [String] The string to operate on.
+    #   @return [String] The colored string.
+    #
+    # @!method blue(string=nil, &block)
+    #   Sets the foreground color to blue for the supplied string.
+    #   @param [String] string The string to operate on.
+    #   @yieldreturn [String] The string to operate on.
+    #   @return [String] The colored string.
+    #
+    # @!method magenta(string=nil, &block)
+    #   Sets the foreground color to magenta for the supplied string.
+    #   @param [String] string The string to operate on.
+    #   @yieldreturn [String] The string to operate on.
+    #   @return [String] The colored string.
+    #
+    # @!method cyan(string=nil, &block)
+    #   Sets the foreground color to cyan for the supplied string.
+    #   @param [String] string The string to operate on.
+    #   @yieldreturn [String] The string to operate on.
+    #   @return [String] The colored string.
+    #
+    # @!method white(string=nil, &block)
+    #   Sets the foreground color to white for the supplied string.
+    #   @param [String] string The string to operate on.
+    #   @yieldreturn [String] The string to operate on.
+    #   @return [String] The colored string.
+
+    # Defines our ANSI attribute codes
+    ANSI_ATTRIBUTES = {
       :normal => 0,
       :bold   => 1
     }
 
+    # @!method normal(string=nil, &block)
+    #   Sets the foreground color to normal for the supplied string.
+    #   @param [String] string The string to operate on.
+    #   @yieldreturn [String] The string to operate on.
+    #   @return [String] The colored string.
+    #
+    # @!method bold(string=nil, &block)
+    #   Sets the foreground color to bold for the supplied string.
+    #   @param [String] string The string to operate on.
+    #   @yieldreturn [String] The string to operate on.
+    #   @return [String] The colored string.
+
+    # Defines a RegEx for stripping ANSI codes from strings
     ANSI_REGEX = /\e\[(?:(?:[349]|10)[0-7]|[0-9]|[34]8;5;\d{1,3})?m/
 
+    # Build ANSI Methods
+    #
+    # Dynamicly constructs our color methods based on the ANSI code hash passed
+    # in.
+    #
+    # @param [Hash] hash A hash where the keys represent the method names and
+    #   the values are the ANSI codes.
+    # @return [Boolean] True if successful.
     def build_ansi_methods(hash)
       hash.each do |key, value|
         define_method(key) do |string=nil, &block|
           result = Array.new
+
           result << %(\e[#{value}m)
           if block_given?
-            result << yield
+            result << block.call
           elsif string.respond_to?(:to_str)
             result << string.to_str
           elsif respond_to?(:to_str)
@@ -75,11 +127,20 @@ module ZTK
           result.join
         end
       end
+
+      true
     end
 
-    def uncolor(string=nil)
+    # Uncolor String
+    #
+    # Removes ANSI code sequences from a string.
+    #
+    # @param [String] string The string to operate on.
+    # @yieldreturn [String] The string to operate on.
+    # @return [String] The supplied string stripped of ANSI codes.
+    def uncolor(string=nil, &block)
       if block_given?
-        yield.to_str.gsub(ANSI_REGEX, '')
+        block.call.to_str.gsub(ANSI_REGEX, '')
       elsif string.respond_to?(:to_str)
         string.to_str.gsub(ANSI_REGEX, '')
       elsif respond_to?(:to_str)
@@ -91,8 +152,8 @@ module ZTK
 
     extend self
 
-    build_ansi_methods(COLOR_MATRIX)
-    build_ansi_methods(ATTRIBUTE_MATRIX)
+    build_ansi_methods(ANSI_COLORS)
+    build_ansi_methods(ANSI_ATTRIBUTES)
 
   end
 

data/lib/ztk/background.rb

@@ -1,29 +1,10 @@
-################################################################################
-#
-#      Author: Zachary Patten <zachary@jovelabs.net>
-#   Copyright: Copyright (c) Zachary Patten
-#     License: Apache License, VersIOn 2.0
-#
-#   Licensed under the Apache License, VersIOn 2.0 (the "License");
-#   you may not use this file except in compliance with the License.
-#   You may obtain a copy of the License at
-#
-#       http://www.apache.org/licenses/LICENSE-2.0
-#
-#   Unless required by applicable law or agreed to in writing, software
-#   distributed under the License is distributed on an "AS IS" BASIS,
-#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-#   See the License for the specific language governing permissIOns and
-#   limitatIOns under the License.
-#
-################################################################################
-require "base64"
+require 'base64'
 
 module ZTK
 
-  # ZTK::Background General Error Class
+  # Background Error Class
   #
-  # @author Zachary Patten <zachary@jovelabs.net>
+  # @author Zachary Patten <zachary AT jovelabs DOT com>
   class BackgroundError < Error; end
 
   # Background Processing Class
@@ -99,7 +80,7 @@ module ZTK
   #     1
   #     => nil
   #
-  # @author Zachary Patten <zachary@jovelabs.net>
+  # @author Zachary Patten <zachary AT jovelabs DOT com>
   class Background < ZTK::Base
 
     # Result Set

data/lib/ztk/base.rb

@@ -1,32 +1,13 @@
-################################################################################
-#
-#      Author: Zachary Patten <zachary@jovelabs.net>
-#   Copyright: Copyright (c) Zachary Patten
-#     License: Apache License, Version 2.0
-#
-#   Licensed under the Apache License, Version 2.0 (the "License");
-#   you may not use this file except in compliance with the License.
-#   You may obtain a copy of the License at
-#
-#       http://www.apache.org/licenses/LICENSE-2.0
-#
-#   Unless required by applicable law or agreed to in writing, software
-#   distributed under the License is distributed on an "AS IS" BASIS,
-#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-#   See the License for the specific language governing permissions and
-#   limitations under the License.
-#
-################################################################################
-require "ostruct"
+require 'ostruct'
 
 module ZTK
 
-  # ZTK::Base General Error Class
+  # Base Error Class
   #
-  # @author Zachary Patten <zachary@jovelabs.net>
+  # @author Zachary Patten <zachary AT jovelabs DOT com>
   class BaseError < Error; end
 
-  # ZTK Base Class
+  # Base Class
   #
   # This is the base class inherited by most of the other classes in this
   # library.  It provides a standard set of features to control STDOUT, STDERR
@@ -35,7 +16,7 @@ module ZTK
   # You should never interact with this class directly; you should inherit it
   # and extend functionality as appropriate.
   #
-  # @author Zachary Patten <zachary@jovelabs.net>
+  # @author Zachary Patten <zachary AT jovelabs DOT com>
   class Base
 
     class << self

data/lib/ztk/benchmark.rb

@@ -1,32 +1,13 @@
-################################################################################
-#
-#      Author: Zachary Patten <zachary@jovelabs.net>
-#   Copyright: Copyright (c) Zachary Patten
-#     License: Apache License, Version 2.0
-#
-#   Licensed under the Apache License, Version 2.0 (the "License");
-#   you may not use this file except in compliance with the License.
-#   You may obtain a copy of the License at
-#
-#       http://www.apache.org/licenses/LICENSE-2.0
-#
-#   Unless required by applicable law or agreed to in writing, software
-#   distributed under the License is distributed on an "AS IS" BASIS,
-#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-#   See the License for the specific language governing permissions and
-#   limitations under the License.
-#
-################################################################################
 require 'benchmark'
 
 module ZTK
 
-  # ZTK::Benchmark General Error Class
+  # Benchmark Error Class
   #
-  # @author Zachary Patten <zachary@jovelabs.net>
+  # @author Zachary Patten <zachary AT jovelabs DOT com>
   class BenchmarkError < Error; end
 
-  # ZTK Benchmark Class
+  # Benchmark Class
   #
   # This class contains a benchmarking tool which doubles to supply indications
   # of activity to the console user during long running tasks.
@@ -55,7 +36,7 @@ module ZTK
   #     I wonder how long this will take?  ...looks like it took 1.5229 seconds!
   #     => 1.522871547
   #
-  # @author Zachary Patten <zachary@jovelabs.net>
+  # @author Zachary Patten <zachary AT jovelabs DOT com>
   class Benchmark
 
     class << self

data/lib/ztk/command.rb

@@ -1,70 +1,79 @@
-################################################################################
-#
-#      Author: Zachary Patten <zachary@jovelabs.net>
-#   Copyright: Copyright (c) Zachary Patten
-#     License: Apache License, Version 2.0
-#
-#   Licensed under the Apache License, Version 2.0 (the "License");
-#   you may not use this file except in compliance with the License.
-#   You may obtain a copy of the License at
-#
-#       http://www.apache.org/licenses/LICENSE-2.0
-#
-#   Unless required by applicable law or agreed to in writing, software
-#   distributed under the License is distributed on an "AS IS" BASIS,
-#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-#   See the License for the specific language governing permissions and
-#   limitations under the License.
-#
-################################################################################
-require "ostruct"
-require "timeout"
+require 'ostruct'
+require 'timeout'
 
 module ZTK
 
-  # ZTK::Command Error Class
-  # @author Zachary Patten <zachary@jovelabs.net>
+  # Command Error Class
+  #
+  # @author Zachary Patten <zachary AT jovelabs DOT com>
   class CommandError < Error; end
 
   # Command Execution Class
   #
-  # We can get a new instance of Command like so:
-  #
+  # @example We can get a new instance of Command like so:
   #     cmd = ZTK::Command.new
   #
-  # If we wanted to redirect STDOUT and STDERR to a StringIO we can do this:
-  #
+  # @example If we wanted to redirect STDOUT and STDERR to a StringIO we can do this:
   #     std_combo = StringIO.new
   #     ui = ZTK::UI.new(:stdout => std_combo, :stderr => std_combo)
-  #     cmd = ZTK::Command.new(:ui => ui)
+  #     cmd = ZTK::Command.new(:ui => ui, :silence => true)
+  #     puts cmd.exec("hostname", :silence => false).inspect
   #
-  # @author Zachary Patten <zachary@jovelabs.net>
+  # @author Zachary Patten <zachary AT jovelabs DOT com>
   class Command < ZTK::Base
 
+    # @param [Hash] configuration Sets the overall default configuration for the
+    #   class.  For example, all calls to *exec* against this instance will use
+    #   the configuration options specified here by default.  These options can
+    #   be overriden on a per call basis as well.
+    # @option configuration [Integer] :timeout (600) How long in seconds before
+    #   the command will timeout.
+    # @option configuration [Boolean] :ignore_exit_status (false) Whether or not
+    #   we should ignore the exit status of the the process we spawn.  By
+    #   default we do not ignore the exit status and throw an exception if it is
+    #   non-zero.
+    # @option configuration [Integer] :exit_code (0) The exit code we expect the
+    #   process to return.  This is ignore if *ignore_exit_status* is true.
+    # @option configuration [Boolean] :silence (false) Whether or not we should
+    #   squelch the output of the process.  The output will always go to the
+    #   logging device supplied in the ZTK::UI object.  The output is always
+    #   available in the return value from the method additionally.
     def initialize(configuration={})
       super({
         :timeout => 600,
-        :ignore_exit_status => false
+        :ignore_exit_status => false,
+        :exit_code => 0,
+        :silence => false
       }.merge(configuration))
       config.ui.logger.debug { "config=#{config.send(:table).inspect}" }
     end
 
-    # Executes a local command.
+    # Execute Command
+    #
+    # @example Execute a command:
+    #   cmd = ZTK::Command.new(:silence => true)
+    #   puts cmd.exec("hostname", :silence => false).inspect
     #
     # @param [String] command The command to execute.
     # @param [Hash] options The options hash for executing the command.
+    # @option options [Integer] :timeout (600) How long in seconds before
+    #   the command will timeout.
+    # @option options [Boolean] :ignore_exit_status (false) Whether or not
+    #   we should ignore the exit status of the the process we spawn.  By
+    #   default we do not ignore the exit status and throw an exception if it is
+    #   non-zero.
+    # @option options [Integer] :exit_code (0) The exit code we expect the
+    #   process to return.  This is ignore if *ignore_exit_status* is true.
+    # @option options [Boolean] :silence (false) Whether or not we should
+    #   squelch the output of the process.  The output will always go to the
+    #   logging device supplied in the ZTK::UI object.  The output is always
+    #   available in the return value from the method additionally.
     #
     # @return [OpenStruct#output] The output of the command, both STDOUT and
     #   STDERR combined.
     # @return [OpenStruct#exit_code] The exit code of the process.
-    #
-    # @example Execute a command:
-    #
-    #   cmd = ZTK::Command.new
-    #   puts cmd.exec("hostname").inspect
-    #
     def exec(command, options={})
-      options = OpenStruct.new({ :exit_code => 0, :silence => false }.merge(config.send(:table)).merge(options))
+      options = OpenStruct.new(config.send(:table).merge(options))
 
       options.ui.logger.debug { "config=#{options.send(:table).inspect}" }
       options.ui.logger.debug { "options=#{options.send(:table).inspect}" }
@@ -177,14 +186,14 @@ module ZTK
   private
 
     # Returns a string in the format of "user@hostname" for the current
-    #   shell.
+    # shell.
     def tag
       @@hostname ||= %x(hostname).chomp
       "#{ENV['USER']}@#{@hostname}"
     end
 
     # Formats a header suitable for writing to the direct logger when logging
-    #   sessions.
+    # sessions.
     def log_header(what)
       count = 8
       sep = ("=" * count)