ztk 0.0.6 → 0.0.7

data/lib/ztk.rb

@@ -20,7 +20,14 @@
 
 require "ztk/version"
 
+# Main ZTK module
+#
+# @author Zachary Patten <zachary@jovelabs.com>
 module ZTK
+
+  # ZTK error class
+  #
+  # @author Zachary Patten <zachary@jovelabs.com>
   class Error < StandardError; end
 
   autoload :Base, "ztk/base"
@@ -31,4 +38,5 @@ module ZTK
   autoload :SSH, "ztk/ssh"
   autoload :TCPSocketCheck, "ztk/tcp_socket_check"
   autoload :Template, "ztk/template"
+
 end

data/lib/ztk/command.rb

@@ -20,12 +20,10 @@
 
 require "ostruct"
 
-################################################################################
-
 module ZTK
 
-################################################################################
-
+  # ZTK::Command error class
+  # @author Zachary Patten <zachary@jovelabs.com>
   class CommandError < Error; end
 
 ################################################################################

data/lib/ztk/logger.rb

@@ -20,27 +20,24 @@
 
 require "logger"
 
-################################################################################
-
 module ZTK
 
-################################################################################
-
+  # @author Zachary Patten <zachary@jovelabs.com>
   class Logger < ::Logger
 
-################################################################################
-
     SEVERITIES = Severity.constants.inject([]) {|arr,c| arr[Severity.const_get(c)] = c; arr}
 
-################################################################################
-
     def initialize(*args)
       super(*args)
       set_log_level
     end
 
-################################################################################
 
+  private
+
+    # Parses caller entries, extracting the file, line number and method.
+    #
+    # @param [String] at Entry from the caller Array.
     def parse_caller(at)
       if /^(.+?):(\d+)(?::in `(.*)')?/ =~ at
         file = Regexp.last_match[1]
@@ -52,15 +49,21 @@ module ZTK
       end
     end
 
-################################################################################
-
+    # Writes a log message if the current log level is at or below the supplied
+    # severity.
+    #
+    # @param [Constant] severity Log level severity.
+    # @param [String] message Optional message to prefix the log entry with.
+    # @param [String] progname Optional name of the program to prefix the log
+    #   entry with.
+    # @yieldreturn [String] The block should return the desired log message.
     def add(severity, message = nil, progname = nil, &block)
       return if (@level > severity)
 
       called_by = parse_caller(caller[1])
       msg = (block && block.call)
       (msg.nil? || msg.strip.empty?) and return
-      message = [message, progname, msg].delete_if{ |i| i.nil? }.join(": ")
+      message = [message, progname, msg].flatten.compact.join(": ")
       message = "%19s.%06d|%05d|%5s|%s%s\n" % [Time.now.utc.strftime("%Y-%m-%d|%H:%M:%S"), Time.now.utc.usec, Process.pid, SEVERITIES[severity], called_by, message]
 
       @logdev.write(message)
@@ -68,20 +71,15 @@ module ZTK
       true
     end
 
-################################################################################
-
+    # Sets the log level.
+    #
+    # @param [String] level Log level to use.
     def set_log_level(level=nil)
       defined?(Rails) and (default = (Rails.env.production? ? "INFO" : "DEBUG")) or (default = "INFO")
       log_level = (ENV['LOG_LEVEL'] || level || default)
       self.level = ZTK::Logger.const_get(log_level.to_s.upcase)
     end
 
-################################################################################
-
   end
 
-################################################################################
-
 end
-
-################################################################################

data/lib/ztk/spinner.rb

@@ -20,24 +20,18 @@
 
 require "ostruct"
 
-################################################################################
-
 module ZTK
 
-################################################################################
-
+  # ZTK::Spinner error class
+  #
+  # @author Zachary Patten <zachary@jovelabs.com>
   class SpinnerError < Error; end
 
-################################################################################
-
+  # @author Zachary Patten <zachary@jovelabs.com>
   class Spinner
 
-################################################################################
-
     class << self
 
-################################################################################
-
       def spin(stdout=$stdout)
         charset = %w( | / - \\ )
         count = 0
@@ -56,16 +50,8 @@ module ZTK
         end
       end
 
-################################################################################
-
     end
 
-################################################################################
-
   end
 
-################################################################################
-
 end
-
-################################################################################

data/lib/ztk/ssh.rb

@@ -26,6 +26,8 @@ require "net/sftp"
 module ZTK
 
   # ZTK::SSH error class
+  #
+  # @author Zachary Patten <zachary@jovelabs.com>
   class SSHError < Error; end
 
   # We can get a new instance of SSH like so:
@@ -69,24 +71,36 @@ module ZTK
   #     ssh.config do |config|
   #       config.host_key_verify = true
   #     end
+  #
+  # @author Zachary Patten <zachary@jovelabs.com>
   class SSH < ZTK::Base
 
     # @param [Hash] config 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 identity files to use for authentication.
+    # @option config [String, Array<String>] :keys A single or series of
+    #   identity files to use for authentication.
     # @option config [String] :password Password to use for authentication.
     # @option config [Integer] :timeout SSH connection timeout to use.
-    # @option config [Boolean] :compression Weither or not to use compression for this session.
-    # @option config [Integer] :compression_level What level of compression  to use.
+    # @option config [Boolean] :compression Weither or not to use compression
+    #   for this session.
+    # @option config [Integer] :compression_level What level of compression to
+    #   use.
     # @option config [String] :proxy_host_name Server hostname to proxy through.
-    # @option config [String] :proxy_user Username to use for proxy authentication.
-    # @option config [String, Array<String>] :proxy_keys A single or series of identity files to use for authentication with the proxy.
+    # @option config [String] :proxy_user Username to use for proxy
+    #   authentication.
+    # @option config [String, Array<String>] :proxy_keys A single or series of
+    #   identity files to use for authentication with the proxy.
     def initialize(config={})
-      super(config)
+      super({
+        :forward_agent => true,
+        :compression => false,
+        :user_known_hosts_file => '/dev/null'
+      }.merge(config))
     end
 
-    # Launches an SSH console, replacing the current process with the console process.
+    # Launches an SSH console, replacing the current process with the console
+    # process.
     #
     # @example Launch a console:
     #   $logger = ZTK::Logger.new(STDOUT)
@@ -107,9 +121,13 @@ module ZTK
     #
     # @param [String] command The command to execute.
     # @param [Hash] options The options hash for executing the command.
-    # @option options [Boolean] :silence Squelch output to STDOUT and STDERR.  If the log level is :debug, STDOUT and STDERR will go to the log file regardless of this setting.  STDOUT and STDERR are always returned in the output return value regardless of this setting.
+    # @option options [Boolean] :silence Squelch output to STDOUT and STDERR.
+    #   If the log level is :debug, STDOUT and STDERR will go to the log file
+    #   regardless of this setting.  STDOUT and STDERR are always returned in
+    #   the output return value regardless of this setting.
     #
-    # @return [OpenStruct#output] The output of the command, both STDOUT and STDERR.
+    # @return [OpenStruct#output] The output of the command, both STDOUT and
+    #   STDERR.
     # @return [OpenStruct#exit] The exit status (i.e. $?).
     #
     # @example Execute a command:
@@ -296,11 +314,7 @@ module ZTK
       log(:debug) { "ssh_options" }
       log(:debug) { "config(#{@config.inspect})" }
 
-      options = {
-        :forward_agent => true,
-        :compression => false,
-        :user_known_hosts_file => '/dev/null'
-      }
+      options = {}
 
       # These are plainly documented on the Net::SSH config class.
       options.merge!(:encryption => @config.encryption) if @config.encryption

data/lib/ztk/tcp_socket_check.rb

@@ -18,34 +18,63 @@
 #
 ################################################################################
 
-require "socket"
-
-################################################################################
+require 'socket'
+require 'timeout'
 
 module ZTK
 
-################################################################################
-
+  # ZTK::TCPSocketCheck error class
+  #
+  # @author Zachary Patten <zachary@jovelabs.com>
   class TCPSocketCheckError < Error; end
 
-################################################################################
-
+  # TCP Socket Checking Class
+  #
+  # Given a host and port we want to check, we can do something like this:
+  #     sc = ZTK::TCPSocketCheck.new(:host => "www.github.com", :port => 22)
+  #
+  # Then if we want to check if this host is responding on the specified port:
+  #     sc.ready? and puts("They are there!")
+  #
+  # This works well for protocols that spew forth some data right away for use
+  # to read.  However, with certain protocols, such as HTTP, we need to send
+  # some data first before we get a response.
+  #
+  # Given we want to check a host and port that requires some giving before we
+  # can take:
+  #     sc = ZTK::TCPSocketCheck.new(:host => "www.google.com", :port => 80, :data => "GET")
+  #
+  # Then if we want to check if this host is responding on the specified port:
+  #     sc.ready? and puts("They are there!")
+  # The ready? methods timeout is bound to the configuration option *timeout*.
+  #
+  # If we are waiting for a service to come online, we can do this:
+  #     sc.wait and puts("They are there!")
+  # The wait methods timeout is bound to the configuration option *wait*.
+  #
+  # @author Zachary Patten <zachary@jovelabs.com>
   class TCPSocketCheck < ZTK::Base
 
-################################################################################
-
+    # @param [Hash] config 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.
+    # @option config [Integer] :timeout (5) Set the IO select timeout.
+    # @option config [Integer] :wait (60) Set the amount of time before the wait
+    #   method call will timeout.
     def initialize(config={})
       super({
-        :host => nil,
-        :port => nil,
-        :data => nil,
         :timeout => 5,
         :wait => 60
       }.merge(config))
     end
 
-################################################################################
-
+    # Check to see if socket on the host and port specified is ready.  This
+    # method will timeout and return false after the amount of seconds specified
+    # in *config.timeout* has passed if the socket has not become ready.
+    #
+    # @return [Boolean] Returns true or false depending on weither the socket
+    #   is ready or not.
     def ready?
       if @config.host.nil?
         message = "You must supply a host!"
@@ -76,8 +105,12 @@ module ZTK
       (socket && socket.close)
     end
 
-################################################################################
-
+    # Wait for the socket on the host and port specified to become ready.  This
+    # method will timeout and return false after the amount of seconds specified
+    # in *config.wait* has passed if the socket has not become ready.
+    #
+    # @return [Boolean] Returns true or false depending on weither the socket
+    #   became ready or not.
     def wait
       log(:debug) { "waiting for socket to become available; timeout after #{@config.wait} seconds" }
       Timeout.timeout(@config.wait) do
@@ -92,12 +125,6 @@ module ZTK
       false
     end
 
-################################################################################
-
   end
 
-################################################################################
-
 end
-
-################################################################################

data/lib/ztk/template.rb

@@ -20,52 +20,56 @@
 
 require "erubis"
 
-################################################################################
-
 module ZTK
 
-################################################################################
-
+  # ZTK::Template error class
+  #
+  # @author Zachary Patten <zachary@jovelabs.com>
   class TemplateError < Error; end
 
-################################################################################
-
+  # Erubis Templating Class
+  #
+  # Given a template like this (i.e. "template.erb"):
+  #     This is a test template!
+  #     <%= @variable %>
+  #
+  # We can do this:
+  #   ZTK::Template.render("template.erb", { :variable => "Hello World" })
+  #
+  # And get:
+  #     This is a test template!
+  #     Hello World
+  #
+  # @author Zachary Patten <zachary@jovelabs.com>
   class Template
 
-################################################################################
-
     class << self
 
-################################################################################
-
+      # Renders a template to a string.
+      #
+      # @param [String] template The ERB template to process.
+      # @param [Hash] context A hash containing key-pairs, for which the keys are turned into global variables with their respective values.
+      #
+      # @return [String] The evaulated template content.
       def render(template, context=nil)
         render_template(load_template(template), context)
       end
 
-################################################################################
+
     private
-################################################################################
 
+      # Loads the template files contents.
       def load_template(template)
         IO.read(template).chomp
       end
 
-################################################################################
-
+      # Renders the template through Erubis.
       def render_template(template, context={})
         Erubis::Eruby.new(template).evaluate(context)
       end
 
-################################################################################
-
     end
 
-################################################################################
-
   end
 
-################################################################################
-
 end
-
-################################################################################

data/lib/ztk/version.rb

@@ -19,5 +19,5 @@
 ################################################################################
 
 module ZTK
-  VERSION = "0.0.6" unless const_defined?(:VERSION)
+  VERSION = "0.0.7" unless const_defined?(:VERSION)
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ztk
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.7
   prerelease: 
 platform: ruby
 authors:
@@ -205,7 +205,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3329543031620665477
+      hash: -971283166384197742
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -214,7 +214,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3329543031620665477
+      hash: -971283166384197742
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24