ztk 0.3.1 → 1.0.0.rc.0

data/lib/ztk/dsl/core/io.rb

@@ -0,0 +1,41 @@
+################################################################################
+#
+#      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.
+#
+################################################################################
+
+module ZTK::DSL::Core
+  module IO
+
+    def self.included(base)
+      base.class_eval do
+        base.send(:extend, ZTK::DSL::Core::IO::ClassMethods)
+      end
+    end
+
+    module ClassMethods
+
+      def load(rb_file)
+        new do
+          instance_eval(::IO.read(rb_file))
+        end
+      end
+
+    end
+
+  end
+end

data/lib/ztk/dsl/core/relations/belongs_to.rb

@@ -0,0 +1,135 @@
+################################################################################
+#
+#      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.
+#
+################################################################################
+
+module ZTK::DSL::Core::Relations
+  module BelongsTo
+
+    def self.included(base)
+      base.class_eval do
+        base.add_relation(:belongs_to)
+        base.send(:extend, ZTK::DSL::Core::Relations::BelongsTo::ClassMethods)
+      end
+    end
+
+    def belongs_to_references
+      @belongs_to_references ||= {}
+    end
+
+    def get_belongs_to_reference(key)
+      logger.debug { "key(#{key})" }
+
+      if belongs_to_references.key?(key)
+        logger.debug { "found key -> (#{key})" }
+
+        belongs_to_references[key]
+      else
+        logger.debug { "looking up key -> (#{key})" }
+
+        key_id = send("#{key}_id")
+        item = key.to_s.classify.constantize.find(key_id).first
+        belongs_to_references[key] = item
+      end
+    end
+
+    def set_belongs_to_reference(key, value)
+      logger.debug { "key(#{key}), value(#{value})" }
+
+      belongs_to_references[key] = value
+      attributes.merge!("#{key}_id".to_sym => value.id)
+
+      klass = self.class.to_s.demodulize.downcase.pluralize
+      logger.debug { "send(#{klass})" }
+      many = value.send(klass)
+      many << self
+      many.uniq!
+    end
+
+    def save_belongs_to_references
+      belongs_to_references.each do |key, dataset|
+        dataset.each do |data|
+          # do something to store the data somewhere
+        end
+      end
+    end
+
+    module ClassMethods
+
+      def belongs_to(key, options={})
+        belongs_to_relations[key] = {
+          :class_name => key.to_s.classify,
+          :key => key
+        }.merge(options)
+        logger.debug { "key(#{key.inspect}), options(#{belongs_to_relations[key].inspect})" }
+
+        define_method(key) do |*args|
+          logger.debug { "*args(#{args.inspect})" }
+
+          if args.count == 0
+            get_belongs_to_reference(key)
+          else
+            send("#{key}=", *args)
+          end
+        end
+
+        define_method("#{key}=") do |value|
+          logger.debug { "#{key}= value(#{value.inspect})" }
+
+          set_belongs_to_reference(key, value)
+        end
+
+        define_method("#{key}_id") do |*args|
+          logger.debug { "#{key}_id *args(#{args.inspect})" }
+
+          if args.count == 0
+            attributes["#{key}_id".to_sym]
+          else
+            send("#{key}_id=".to_sym, args.first)
+          end
+
+        end
+
+        define_method("#{key}_id=") do |value|
+          options = self.class.belongs_to_relations[key]
+          logger.debug { "#{key}_id= value(#{value.inspect}), options(#{options.inspect})" }
+
+          if value != attributes["#{key}_id".to_sym]
+            item = options[:class_name].constantize.find(value).first
+            set_belongs_to_reference(key, item)
+          else
+            value
+          end
+        end
+
+        # define_method(singularize(key)) do |value|
+        #   set_belongs_to_reference(key, value)
+        # end
+
+        # define_method(singularize(key)) do |&block|
+        #   puts get_belongs_to_reference(key).inspect
+        #   data = constantize(classify(key.to_s)).new(&block)
+        #   get_belongs_to_reference(key) << data
+        #   data
+        # end
+      end
+
+    end
+
+  end
+end

data/lib/ztk/dsl/core/relations/has_many.rb

@@ -0,0 +1,105 @@
+################################################################################
+#
+#      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.
+#
+################################################################################
+
+module ZTK::DSL::Core::Relations
+  module HasMany
+
+    def self.included(base)
+      base.class_eval do
+        base.add_relation(:has_many)
+        base.send(:extend, ZTK::DSL::Core::Relations::HasMany::ClassMethods)
+      end
+    end
+
+    def has_many_references
+      @has_many_references ||= {}
+    end
+
+    def get_has_many_reference(key)
+      logger.debug { "key(#{key})" }
+
+      if has_many_references.key?(key)
+        logger.debug { "found key -> (#{key})" }
+
+        has_many_references[key]
+      else
+        logger.debug { "looking up key -> (#{key})" }
+
+        has_many_references[key] ||= []
+      end
+    end
+
+    def set_has_many_reference(key, value)
+      logger.debug { "key(#{key}), value(#{value})" }
+
+      dataset = get_has_many_reference(key)
+      dataset.clear
+      dataset.concat(value)
+    end
+
+    def save_has_many_references
+      has_many_references.each do |key, dataset|
+        dataset.each do |data|
+          # do something to store the data somewhere
+        end
+      end
+    end
+
+    module ClassMethods
+
+      def has_many(key, options={})
+        has_many_relations[key] = {
+          :class_name => key.to_s.classify,
+          :key => key
+        }.merge(options)
+        logger.debug { "key(#{key.inspect}), options(#{has_many_relations[key].inspect})" }
+
+        define_method(key) do |*args|
+          logger.debug { "#{key} *args(#{args.inspect})" }
+
+          if args.count == 0
+            get_has_many_reference(key)
+          else
+            send("#{key}=", *args)
+          end
+        end
+
+        define_method("#{key}=") do |value|
+          logger.debug { "#{key}= value(#{value.inspect})" }
+
+          set_has_many_reference(key, value)
+        end
+
+        define_method(key.to_s.singularize) do |&block|
+          options = self.class.has_many_relations[key]
+          logger.debug { "#{key.to_s.singularize} block(#{block.inspect}), options(#{options.inspect})" }
+          data = options[:class_name].constantize.new(&block)
+          get_has_many_reference(key) << data
+          klass = self.class.to_s.demodulize.singularize.downcase
+          logger.debug { "send(#{klass})" }
+          data.send("#{klass}=", self)
+          data
+        end
+      end
+
+    end
+
+  end
+end

data/lib/ztk/dsl/core/relations.rb

@@ -0,0 +1,45 @@
+################################################################################
+#
+#      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.
+#
+################################################################################
+
+module ZTK::DSL::Core
+  module Relations
+    autoload :BelongsTo, "ztk/dsl/core/relations/belongs_to"
+    autoload :HasMany, "ztk/dsl/core/relations/has_many"
+
+    def self.included(base)
+      base.class_eval do
+        base.send(:extend, ZTK::DSL::Core::Relations::ClassMethods)
+        base.send(:include, ZTK::DSL::Core::Relations::BelongsTo)
+        base.send(:include, ZTK::DSL::Core::Relations::HasMany)
+      end
+    end
+
+    module ClassMethods
+
+      def add_relation(key)
+        relation_key = "#{key}_relations"
+        cattr_accessor relation_key
+        send(relation_key) || send("#{relation_key}=", {})
+      end
+
+    end
+
+  end
+end

data/lib/ztk/dsl/core.rb

@@ -0,0 +1,77 @@
+module ZTK::DSL
+  module Core
+    autoload :Attributes, "ztk/dsl/core/attributes"
+    autoload :Actions, "ztk/dsl/core/actions"
+    autoload :Dataset, "ztk/dsl/core/dataset"
+    autoload :IO, "ztk/dsl/core/io"
+    autoload :Relations, "ztk/dsl/core/relations"
+
+    def self.included(base)
+      base.class_eval do
+        base.send(:extend, ZTK::DSL::Core::ClassMethods)
+
+        base.send(:extend, ZTK::DSL::Core::DualMethods)
+        base.send(:include, ZTK::DSL::Core::DualMethods)
+
+        base.send(:include, ZTK::DSL::Core::Attributes)
+        base.send(:include, ZTK::DSL::Core::Actions)
+        base.send(:include, ZTK::DSL::Core::Dataset)
+        base.send(:include, ZTK::DSL::Core::IO)
+        base.send(:include, ZTK::DSL::Core::Relations)
+      end
+    end
+
+    module DualMethods
+
+      def logger
+        unless defined?($logger)
+          $logger = ::ZTK::Logger.new("dsl.log")
+          $logger.info {"=" * 80}
+          $logger.info {"=" * 80}
+          $logger.info {"=" * 80}
+        end
+        $logger
+      end
+
+    end
+
+    module ClassMethods
+
+      def cattr_accessor(*args)
+        cattr_reader(*args)
+        cattr_writer(*args)
+      end
+
+      def cattr_reader(*args)
+        args.flatten.each do |arg|
+          next if arg.is_a?(Hash)
+          instance_eval %Q{
+            unless defined?(@@#{arg})
+              @@#{arg} = nil
+            end
+
+            def #{arg}
+              @@#{arg}
+            end
+          }
+        end
+      end
+
+      def cattr_writer(*args)
+        args.flatten.each do |arg|
+          next if arg.is_a?(Hash)
+          instance_eval %Q{
+            unless defined?(@@#{arg})
+              @@#{arg} = nil
+            end
+
+            def #{arg}=(value)
+              @@#{arg} = value
+            end
+          }
+        end
+      end
+    end
+
+  end
+end

data/lib/ztk/dsl.rb

@@ -0,0 +1,34 @@
+################################################################################
+#
+#      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 "active_support/inflector"
+
+# @author Zachary Patten <zachary@jovelabs.net>
+module ZTK
+  module DSL
+
+    # @author Zachary Patten <zachary@jovelabs.net>
+    class DSLError < Error; end
+
+    autoload :Base, "ztk/dsl/base"
+    autoload :Core, "ztk/dsl/core"
+
+  end
+end

data/lib/ztk/logger.rb

@@ -17,7 +17,6 @@
 #   limitations under the License.
 #
 ################################################################################
-
 require "logger"
 
 module ZTK
@@ -45,6 +44,7 @@ module ZTK
   # @author Zachary Patten <zachary@jovelabs.net>
   class Logger < ::Logger
 
+    # Log Levels
     SEVERITIES = Severity.constants.inject([]) {|arr,c| arr[Severity.const_get(c)] = c; arr}
 
     def initialize(*args)
@@ -52,15 +52,28 @@ module ZTK
       set_log_level
     end
 
+    # Provides access to the raw log device.
     def logdev
       self.instance_variable_get(:@logdev).instance_variable_get(:@dev)
     end
 
+    # Specialized logging.  Logs messages in the same format, except has the
+    # option to shift the caller_at position to exposed the proper calling
+    # method.
+    #
+    # Very useful in situations of class inheritence, for example, where you
+    # might have logging statements in a base class, which are inherited by
+    # another class.  When calling the base class method via the inherited class
+    # the log messages will indicate the base class as the caller.  While this
+    # is technically true it is not always what we want to see in the logs
+    # because it is ambigious and does not show us where the call truly
+    # originated from.
     def shift(severity, shift=0, &block)
       severity = ZTK::Logger.const_get(severity.to_s.upcase)
       add(severity, nil, nil, shift, &block)
     end
 
+    # Generates a human-readable string about the logger.
     def inspect
       "#<#{self.class} filename=#{@logdev.filename.inspect}>"
     end

data/lib/ztk/parallel.rb

@@ -17,7 +17,6 @@
 #   limitatIOns under the License.
 #
 ################################################################################
-
 require "base64"
 
 module ZTK
@@ -62,6 +61,7 @@ module ZTK
   # @author Zachary Patten <zachary@jovelabs.net>
   class Parallel < ZTK::Base
 
+    # Default Maximum Number of Forks
     MAX_FORKS = case RUBY_PLATFORM
     when /darwin/ then
       %x( sysctl hw.ncpu ).chomp.split(':').last.strip.to_i
@@ -72,7 +72,7 @@ module ZTK
     # Result Set
     attr_accessor :results
 
-    # @param [Hash] config Configuration options hash.
+    # @param [Hash] configuration Configuration options hash.
     # @option config [Integer] :max_forks Maximum number of forks to use.
     # @option config [Proc] :before_fork (nil) Proc to call before forking.
     # @option config [Proc] :after_fork (nil) Proc to call after forking.

data/lib/ztk/report.rb

@@ -17,7 +17,6 @@
 #   limitations under the License.
 #
 ################################################################################
-
 require 'socket'
 require 'timeout'
 
@@ -28,6 +27,15 @@ module ZTK
   # @author Zachary Patten <zachary@jovelabs.net>
   class ReportError < Error; end
 
+  # ZTK Report Class
+  #
+  # This class contains tools for generating spreadsheet or key-value list
+  # styled output.  Report methods are currently meant to be interchangeable;
+  # that is one should be able to just switch which method they are calling
+  # to change the output type.
+  #
+  # The idea here is that everything is auto-sized and simply displayed.
+  #
   # @author Zachary Patten <zachary@jovelabs.net>
   class Report < ZTK::Base
 
@@ -38,6 +46,21 @@ module ZTK
       config.logger.debug { "config=#{config.send(:table).inspect}" }
     end
 
+    # Displays data in a spreadsheet style.
+    #
+    #     +-------------+-------+-------+--------+----------------+-------------------+--------------+---------+
+    #     | NAME        | ALIVE | ARCH  | DISTRO | IP             | MAC               | CHEF VERSION | PERSIST |
+    #     +-------------+-------+-------+--------+----------------+-------------------+--------------+---------+
+    #     | sudo        | false | amd64 | ubuntu | 192.168.99.110 | 00:00:5e:34:d6:aa | N/A          | true    |
+    #     | timezone    | false | amd64 | ubuntu | 192.168.122.47 | 00:00:5e:92:d7:f6 | N/A          | true    |
+    #     | chef-client | false | amd64 | ubuntu | 192.168.159.98 | 00:00:5e:c7:ce:26 | N/A          | true    |
+    #     | users       | false | amd64 | ubuntu | 192.168.7.78   | 00:00:5e:89:f9:50 | N/A          | true    |
+    #     +-------------+-------+-------+--------+----------------+-------------------+--------------+---------+
+    #
+    # @param [Array] dataset An array of items for which we want to generate a
+    #   report
+    # @param [Array] headers An array of headers used for ordering the output.
+    # @return [OpenStruct]
     def spreadsheet(dataset, headers, &block)
       !block_given? and log_and_raise(ReportError, "You must supply a block!")
       headers.nil? and log_and_raise(ReportError, "Headers can not be nil!")
@@ -80,6 +103,25 @@ module ZTK
       OpenStruct.new(:rows => rows, :max_lengths => max_lengths, :width => width)
     end
 
+    # Displays data in a key-value list style.
+    #
+    #     +-------------------------------------------------------------------+
+    #     |                      PROVIDER: Cucumber::Chef::Provider::Vagrant  |
+    #     |                            ID: default                            |
+    #     |                         STATE: aborted                            |
+    #     |                      USERNAME: vagrant                            |
+    #     |                    IP ADDRESS: 127.0.0.1                          |
+    #     |                          PORT: 2222                               |
+    #     |               CHEF-SERVER API: http://127.0.0.1:4000              |
+    #     |             CHEF-SERVER WEBUI: http://127.0.0.1:4040              |
+    #     |      CHEF-SERVER DEFAULT USER: admin                              |
+    #     |  CHEF-SERVER DEFAULT PASSWORD: p@ssw0rd1                          |
+    #     +-------------------------------------------------------------------+
+    #
+    # @param [Array] dataset An array of items for which we want to generate a
+    #   report
+    # @param [Array] headers An array of headers used for ordering the output.
+    # @return [OpenStruct]
     def list(dataset, headers, &block)
       !block_given? and log_and_raise(ReportError, "You must supply a block!")
       headers.nil? and log_and_raise(ReportError, "Headers can not be nil!")

data/lib/ztk/rescue_retry.rb

@@ -17,6 +17,7 @@
 #   limitations under the License.
 #
 ################################################################################
+
 module ZTK
 
   # ZTK::RescueRetry Error Class
@@ -24,13 +25,50 @@ module ZTK
   # @author Zachary Patten <zachary@jovelabs.net>
   class RescueRetryError < Error; end
 
-  # RescueRetry Class
+  # ZTK RescueRetry Class
+  #
+  # This class contains an exception handling tool, which will allowing retry
+  # of all or specific *Exceptions* based on a set number of attempts to make.
+  #
+  # The block is yielded and if a valid exception occurs the block will be
+  # re-executed for the set number of attempts.
+  #
+  # For example, from the ZTK SSH class:
+  #
+  #     ZTK::RescueRetry.try(:tries => 3, :on => EOFError) do
+  #       @ssh = Net::SSH.start(config.host_name, config.user, ssh_options)
+  #       ...
+  #     end
+  #
+  # If an SSH connection drops on the other side and we go to write to it, we
+  # will get this error.  Wrapping the SSH code in *RescueRetry* allows us to
+  # retry the connection in the event this happens.  If we have no luck after
+  # 3 attempts at executing the block, *RescueRetry* surfaces the exception.
   #
   # @author Zachary Patten <zachary@jovelabs.net>
   class RescueRetry
 
     class << self
 
+      # Rescue and Retry the supplied block.
+      #
+      # When no options are supplied, if an *Exception* is encounter it is
+      # surfaced immediately and no retry is performed.
+      #
+      # It is advisable to at least leave the *delay* option at 1.  You could
+      # optionally set this to 0, but this is generally a bad idea.
+      #
+      # @param [Hash] options Configuration options hash.
+      # @option options [String] :tries (1) How many attempts at executing the
+      #   block before we give up and surface the *Exception*.
+      # @option options [String] :on (Exception) Watch for a specific exception
+      #   instead of performing retry on all exceptions.
+      # @option options [Float,Integer] :delay (1) How long to sleep for between
+      #   each retry.
+      #
+      # @yield Block should execute the tasks to be rescued and retried if
+      #   needed.
+      # @return [Object] The return value of the block.
       def try(options={}, &block)
         options = Base.build_config({
           :tries => 1,