ztk 0.3.1 → 1.0.0.rc.0

data/lib/ztk/spinner.rb

@@ -17,7 +17,6 @@
 #   limitations under the License.
 #
 ################################################################################
-
 require "ostruct"
 
 module ZTK
@@ -25,33 +24,53 @@ module ZTK
   # ZTK::Spinner Error Class
   #
   # @author Zachary Patten <zachary@jovelabs.net>
-  # @author Stephen Nelson-Smith <stephen@atalanta-systems.com>
   class SpinnerError < Error; end
 
-  # Spinner Class
+  # ZTK Spinner Class
+  #
+  # This class can be used to display an "activity indicator" to a user while
+  # a task is executed in the supplied block.  This indicator takes the form
+  # of a spinner.
   #
   # @author Zachary Patten <zachary@jovelabs.net>
-  # @author Stephen Nelson-Smith <stephen@atalanta-systems.com>
   class Spinner
 
     class << self
 
+      # Spinner Character Set
+      CHARSET = %w( | / - \\ )
+
+      # UI Spinner
+      #
+      # Displays a "spinner" while executing the supplied block.  It is
+      # advisable that no output is sent to the console during this time.
+      #
+      # @param [Hash] options Configuration options hash.
+      # @option options [Float,Integer] :step (0.1) How long to sleep for in
+      #   between cycles, while cycling through the *CHARSET*.
+      #
+      # @yield Block should execute the tasks for which they wish the user to
+      #   have a false sense of security in the fact that something is actually
+      #   taking place "behind the scenes".
+      # @return [Object] The return value of the block.
+      #
+      # @author Zachary Patten <zachary@jovelabs.net>
+      # @author Stephen Nelson-Smith <stephen@atalanta-systems.com>
       def spin(options={}, &block)
         options = Base.build_config({
-          :sleep => 0.1
+          :step => 0.1
         }.merge(options))
         options.logger.debug { "options(#{options.send(:table).inspect})" }
 
         !block_given? and Base.log_and_raise(options.logger, SpinnerError, "You must supply a block!")
 
-        charset = %w( | / - \\ )
         count = 0
         spinner = Thread.new do
           while count do
-            options.stdout.print(charset[(count += 1) % charset.length])
+            options.stdout.print(CHARSET[(count += 1) % CHARSET.length])
             options.stdout.print("\b")
             options.stdout.respond_to?(:flush) and options.stdout.flush
-            sleep(options.sleep)
+            sleep(options.step)
           end
         end
         yield.tap do

data/lib/ztk/ssh.rb

@@ -17,7 +17,6 @@
 #   limitations under the License.
 #
 ################################################################################
-
 require "ostruct"
 require "net/ssh"
 require "net/ssh/proxy/command"
@@ -85,6 +84,7 @@ module ZTK
   # @author Zachary Patten <zachary@jovelabs.net>
   class SSH < ZTK::Base
 
+    # Exit Signal Mappings
     EXIT_SIGNALS = {
       1 => "SIGHUP",
       2 => "SIGINT",
@@ -115,7 +115,7 @@ module ZTK
       27 => "SIGPROF"
     }
 
-    # @param [Hash] config Configuration options hash.
+    # @param [Hash] configuration Configuration options hash.
     # @option config [String] :host_name Server hostname to connect to.
     # @option config [String] :user Username to use for authentication.
     # @option config [String, Array<String>] :keys A single or series of
@@ -142,23 +142,6 @@ module ZTK
       config.logger.debug { "config=#{config.send(:table).inspect}" }
     end
 
-    def inspect
-      tags = Array.new
-
-      if config.proxy_host_name
-        proxy_user_host = "#{config.proxy_user}@#{config.proxy_host_name}"
-        proxy_port = (config.proxy_port ? ":#{config.proxy_port}" : nil)
-        tags << [proxy_user_host, proxy_port].compact.join
-        tags << " >>> "
-      end
-
-      user_host = "#{config.user}@#{config.host_name}"
-      port = (config.port ? ":#{config.port}" : nil)
-      tags << [user_host, port].compact.join
-
-      tags.join.strip
-    end
-
     # Starts an SSH session.  Can also be used to get the Net::SSH object.
     #
     # Primarily used internally.
@@ -166,7 +149,7 @@ module ZTK
       @ssh ||= Net::SSH.start(config.host_name, config.user, ssh_options)
     end
 
-    # Starts an SFTP session.  Can also be used to get the Net::SSH object.
+    # Starts an SFTP session.  Can also be used to get the Net::SFTP object.
     #
     # Primarily used internally.
     def sftp
@@ -219,14 +202,6 @@ module ZTK
     #   end
     #   puts ssh.exec("hostname -f").inspect
     def exec(command, options={})
-
-      def log_header(tag)
-        count = 8
-        sep = ("=" * count)
-        header = [sep, "[ #{tag} ]", sep, "[ #{self.inspect} ]", sep, "[ #{tag} ]", sep].join
-        "#{header}\n"
-      end
-
       options = OpenStruct.new({ :exit_code => 0, :silence => false }.merge(options))
 
       config.logger.debug { "config=#{config.send(:table).inspect}" }
@@ -470,6 +445,32 @@ module ZTK
       options
     end
 
+    # Builds a human readable tag about our connection.  Used for internal
+    # logging purposes.
+    def tag
+      tags = Array.new
+
+      if config.proxy_host_name
+        proxy_user_host = "#{config.proxy_user}@#{config.proxy_host_name}"
+        proxy_port = (config.proxy_port ? ":#{config.proxy_port}" : nil)
+        tags << [proxy_user_host, proxy_port].compact.join
+        tags << " >>> "
+      end
+
+      user_host = "#{config.user}@#{config.host_name}"
+      port = (config.port ? ":#{config.port}" : nil)
+      tags << [user_host, port].compact.join
+
+      tags.join.strip
+    end
+
+    def log_header(what)
+      count = 8
+      sep = ("=" * count)
+      header = [sep, "[ #{what} ]", sep, "[ #{tag} ]", sep, "[ #{what} ]", sep].join
+      "#{header}\n"
+    end
+
   end
 
 end

data/lib/ztk/tcp_socket_check.rb

@@ -17,7 +17,6 @@
 #   limitations under the License.
 #
 ################################################################################
-
 require 'socket'
 require 'timeout'
 
@@ -83,7 +82,7 @@ module ZTK
   # @author Zachary Patten <zachary@jovelabs.net>
   class TCPSocketCheck < ZTK::Base
 
-    # @param [Hash] config Configuration options hash.
+    # @param [Hash] configuration Configuration options hash.
     # @option config [String] :host Host to connect to.
     # @option config [Integer, String] :port Port to connect to.
     # @option config [String] :data Data to send to host to provoke a response.

data/lib/ztk/template.rb

@@ -17,7 +17,6 @@
 #   limitations under the License.
 #
 ################################################################################
-
 require "erubis"
 
 module ZTK

data/lib/ztk/ui.rb

@@ -0,0 +1,47 @@
+################################################################################
+#
+#      Author: Zachary Patten <zachary@jovelabs.net>
+#   Copyright: Copyright (c) Jove Labs
+#     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"
+
+module ZTK
+
+  # ZTK::Ui Error Class
+  #
+  # @author Zachary Patten <zachary@jovelabs.net>
+  class UIError < Error; end
+
+  # @author Zachary Patten <zachary@jovelabs.net>
+  class UI < ZTK::Base
+
+    attr_accessor :stdout, :stderr, :stdin, :logger
+
+    def initialize(configuration={})
+      super({
+        :stdout => $stdout,
+        :stderr => $stderr,
+        :stdin => $stdin,
+        :logger => $logger
+      }.merge(configuration))
+      config.logger.debug { "config=#{config.send(:table).inspect}" }
+    end
+
+  end
+
+end

data/lib/ztk/version.rb

@@ -19,5 +19,8 @@
 ################################################################################
 
 module ZTK
-  VERSION = "0.3.1" unless const_defined?(:VERSION)
+
+  # ZTK Version String
+  VERSION = "1.0.0.rc.0"
+
 end

data/lib/ztk.rb

@@ -18,10 +18,14 @@
 #
 ################################################################################
 
-require 'ztk/version'
+require "ztk/version"
 
 # Main ZTK module
 #
+# ZTK is a general purpose utility library.  It definately has devops activities
+# in mind.  It provides several classes that ease SSH and SFTP, templating,
+# and a myraid of other activities.
+#
 # @author Zachary Patten <zachary@jovelabs.net>
 module ZTK
 
@@ -30,19 +34,21 @@ module ZTK
   # @author Zachary Patten <zachary@jovelabs.net>
   class Error < StandardError; end
 
-  autoload :Base, 'ztk/base'
+  autoload :Base, "ztk/base"
+  autoload :DSL, "ztk/dsl"
 
-  autoload :Background, 'ztk/background'
-  autoload :Benchmark, 'ztk/benchmark'
-  autoload :Command, 'ztk/command'
-  autoload :Config, 'ztk/config'
-  autoload :Logger, 'ztk/logger'
-  autoload :Parallel, 'ztk/parallel'
-  autoload :Report, 'ztk/report'
-  autoload :RescueRetry, 'ztk/rescue_retry'
-  autoload :Spinner, 'ztk/spinner'
-  autoload :SSH, 'ztk/ssh'
-  autoload :TCPSocketCheck, 'ztk/tcp_socket_check'
-  autoload :Template, 'ztk/template'
+  autoload :Background, "ztk/background"
+  autoload :Benchmark, "ztk/benchmark"
+  autoload :Command, "ztk/command"
+  autoload :Config, "ztk/config"
+  autoload :Logger, "ztk/logger"
+  autoload :Parallel, "ztk/parallel"
+  autoload :Report, "ztk/report"
+  autoload :RescueRetry, "ztk/rescue_retry"
+  autoload :Spinner, "ztk/spinner"
+  autoload :SSH, "ztk/ssh"
+  autoload :TCPSocketCheck, "ztk/tcp_socket_check"
+  autoload :Template, "ztk/template"
+  autoload :UI, "ztk/ui"
 
 end

data/spec/ztk/background_spec.rb

@@ -74,7 +74,67 @@ describe ZTK::Background do
         subject.process do
           Process.pid
         end
+
+        subject.wait
+        subject.result.should be_kind_of Integer
+        subject.result.should > 0
+        subject.result.should_not == Process.pid
+      end
+
+    end
+
+    describe "alive?" do
+
+      it "should respond true when the process is still running" do
+        subject.process do
+          sleep(WAIT_SMALL)
+        end
+        subject.alive?.should be true
+
+        subject.wait
+        subject.result.should be_kind_of Integer
+        subject.result.should > 0
+        subject.result.should == WAIT_SMALL
+      end
+
+      it "should respond false when the process is no longer running" do
+        subject.process do
+          Process.pid
+        end
+        subject.wait
+        sleep(WAIT_SMALL)
+
+        subject.alive?.should be false
+
+        subject.result.should be_kind_of Integer
+        subject.result.should > 0
+        subject.result.should_not == Process.pid
+      end
+
+    end
+
+    describe "dead?" do
+
+      it "should respond false when the process is still running" do
+        subject.process do
+          sleep(WAIT_SMALL)
+        end
+        subject.dead?.should be false
+
         subject.wait
+        subject.result.should be_kind_of Integer
+        subject.result.should > 0
+        subject.result.should == WAIT_SMALL
+      end
+
+      it "should respond true when the process is no longer running" do
+        subject.process do
+          Process.pid
+        end
+        subject.wait
+        sleep(WAIT_SMALL)
+
+        subject.dead?.should be true
 
         subject.result.should be_kind_of Integer
         subject.result.should > 0