ztk 1.0.0.rc.0 → 1.0.0.rc.1

data/lib/ztk/dsl/core.rb

@@ -1,4 +1,29 @@
+################################################################################
+#
+#      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
+
+  # ZTK::DSL Core
+  #
+  # @author Zachary Patten <zachary@jovelabs.net>
+  # @api private
   module Core
     autoload :Attributes, "ztk/dsl/core/attributes"
     autoload :Actions, "ztk/dsl/core/actions"
@@ -21,6 +46,7 @@ module ZTK::DSL
       end
     end
 
+    # @author Zachary Patten <zachary@jovelabs.net>
     module DualMethods
 
       def logger
@@ -35,6 +61,7 @@ module ZTK::DSL
 
     end
 
+    # @author Zachary Patten <zachary@jovelabs.net>
     module ClassMethods
 
       def cattr_accessor(*args)

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

@@ -19,6 +19,9 @@
 ################################################################################
 
 module ZTK::DSL::Core
+
+  # @author Zachary Patten <zachary@jovelabs.net>
+  # @api private
   module Actions
     autoload :Find, "ztk/dsl/core/actions/find"
     autoload :Timestamps, "ztk/dsl/core/actions/timestamps"

data/lib/ztk/dsl/core/actions/find.rb

@@ -19,6 +19,9 @@
 ################################################################################
 
 module ZTK::DSL::Core::Actions
+
+  # @author Zachary Patten <zachary@jovelabs.net>
+  # @api private
   module Find
 
     def self.included(base)
@@ -27,6 +30,7 @@ module ZTK::DSL::Core::Actions
       end
     end
 
+    # @author Zachary Patten <zachary@jovelabs.net>
     module ClassMethods
 
       def all

data/lib/ztk/dsl/core/actions/timestamps.rb

@@ -19,6 +19,9 @@
 ################################################################################
 
 module ZTK::DSL::Core::Actions
+
+  # @author Zachary Patten <zachary@jovelabs.net>
+  # @api private
   module Timestamps
 
     def self.included(base)
@@ -31,6 +34,7 @@ module ZTK::DSL::Core::Actions
       end
     end
 
+    # @author Zachary Patten <zachary@jovelabs.net>
     module ClassMethods
 
       def updated_at_timestamp

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

@@ -19,6 +19,9 @@
 ################################################################################
 
 module ZTK::DSL::Core
+
+  # @author Zachary Patten <zachary@jovelabs.net>
+  # @api private
   module Attributes
 
     def self.included(base)
@@ -31,6 +34,7 @@ module ZTK::DSL::Core
       @attributes ||= {}
     end
 
+    # @author Zachary Patten <zachary@jovelabs.net>
     module ClassMethods
 
       def attribute(key, options={})

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

@@ -19,6 +19,9 @@
 ################################################################################
 
 module ZTK::DSL::Core
+
+  # @author Zachary Patten <zachary@jovelabs.net>
+  # @api private
   module Dataset
 
     def self.included(base)
@@ -27,6 +30,7 @@ module ZTK::DSL::Core
       end
     end
 
+    # @author Zachary Patten <zachary@jovelabs.net>
     module ClassMethods
 
       def dataset
@@ -48,18 +52,6 @@ module ZTK::DSL::Core
         (@@id += 1)
       end
 
-      # def foreign_keys(target)
-      #   puts("==> foreign_keys(#{target.inspect})")
-
-      #   target = singularize(underscore(target).to_sym)
-      #   source = singularize(underscore(self).to_sym)
-
-      #   splat = [source, target].sort
-
-      #   key = [ splat[0], "references", splat[1] ].join(":")
-      #   puts("key=#{key}")
-      # end
-
     end
 
   end

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

@@ -19,6 +19,9 @@
 ################################################################################
 
 module ZTK::DSL::Core
+
+  # @author Zachary Patten <zachary@jovelabs.net>
+  # @api private
   module IO
 
     def self.included(base)
@@ -27,6 +30,7 @@ module ZTK::DSL::Core
       end
     end
 
+    # @author Zachary Patten <zachary@jovelabs.net>
     module ClassMethods
 
       def load(rb_file)

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

@@ -19,6 +19,9 @@
 ################################################################################
 
 module ZTK::DSL::Core
+
+  # @author Zachary Patten <zachary@jovelabs.net>
+  # @api private
   module Relations
     autoload :BelongsTo, "ztk/dsl/core/relations/belongs_to"
     autoload :HasMany, "ztk/dsl/core/relations/has_many"
@@ -31,6 +34,7 @@ module ZTK::DSL::Core
       end
     end
 
+    # @author Zachary Patten <zachary@jovelabs.net>
     module ClassMethods
 
       def add_relation(key)

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

@@ -19,6 +19,9 @@
 ################################################################################
 
 module ZTK::DSL::Core::Relations
+
+  # @author Zachary Patten <zachary@jovelabs.net>
+  # @api private
   module BelongsTo
 
     def self.included(base)
@@ -69,6 +72,7 @@ module ZTK::DSL::Core::Relations
       end
     end
 
+    # @author Zachary Patten <zachary@jovelabs.net>
     module ClassMethods
 
       def belongs_to(key, options={})

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

@@ -19,6 +19,9 @@
 ################################################################################
 
 module ZTK::DSL::Core::Relations
+
+  # @author Zachary Patten <zachary@jovelabs.net>
+  # @api private
   module HasMany
 
     def self.included(base)
@@ -62,6 +65,7 @@ module ZTK::DSL::Core::Relations
       end
     end
 
+    # @author Zachary Patten <zachary@jovelabs.net>
     module ClassMethods
 
       def has_many(key, options={})

data/lib/ztk/parallel.rb

@@ -30,6 +30,13 @@ module ZTK
   #
   # This class can be used to easily run iterative and linear processes in a parallel manner.
   #
+  # The before fork callback is called once in the parent process.
+  #
+  # The after fork callback is called twice, once in the parent process and once
+  # in the child process.
+  #
+  # *example code*:
+  #
   #     a_callback = Proc.new do |pid|
   #       puts "Hello from After Callback - PID #{pid}"
   #     end
@@ -44,6 +51,8 @@ module ZTK
   #       config.after_fork = a_callback
   #     end
   #
+  #     puts Process.pid.inspect
+  #
   #     3.times do |x|
   #       parallel.process do
   #         x
@@ -51,12 +60,57 @@ module ZTK
   #     end
   #
   #     parallel.waitall
-  #     parallel.results
+  #     puts parallel.results.inspect
   #
-  # The before fork callback is called once in the parent process.
+  # *pry output*:
   #
-  # The after fork callback is called twice, once in the parent process and once
-  # in the child process.
+  #     [1] pry(main)> a_callback = Proc.new do |pid|
+  #     [1] pry(main)*   puts "Hello from After Callback - PID #{pid}"
+  #     [1] pry(main)* end
+  #     => #<Proc:0x000000015a8768@(pry):1>
+  #     [2] pry(main)>
+  #     [3] pry(main)> b_callback = Proc.new do |pid|
+  #     [3] pry(main)*   puts "Hello from Before Callback - PID #{pid}"
+  #     [3] pry(main)* end
+  #     => #<Proc:0x000000012910e8@(pry):4>
+  #     [4] pry(main)>
+  #     [5] pry(main)> parallel = ZTK::Parallel.new
+  #     => #<ZTK::Parallel:0x000000015a9d48
+  #      @config=
+  #       #<OpenStruct stdout=#<IO:<STDOUT>>, stderr=#<IO:<STDERR>>, stdin=#<IO:<STDIN>>, logger=#<ZTK::Logger filename="/dev/null">, max_forks=12>,
+  #      @forks=[],
+  #      @results=[]>
+  #     [6] pry(main)> parallel.config do |config|
+  #     [6] pry(main)*   config.before_fork = b_callback
+  #     [6] pry(main)*   config.after_fork = a_callback
+  #     [6] pry(main)* end
+  #     => #<Proc:0x000000015a8768@(pry):1>
+  #     [7] pry(main)>
+  #     [8] pry(main)> puts Process.pid.inspect
+  #     24761
+  #     => nil
+  #     [9] pry(main)>
+  #     [10] pry(main)> 3.times do |x|
+  #     [10] pry(main)*   parallel.process do
+  #     [10] pry(main)*     x
+  #     [10] pry(main)*   end
+  #     [10] pry(main)* end
+  #     Hello from Before Callback - PID 24761
+  #     Hello from After Callback - PID 24761
+  #     Hello from Before Callback - PID 24761
+  #     Hello from After Callback - PID 24776
+  #     Hello from After Callback - PID 24761
+  #     Hello from Before Callback - PID 24761
+  #     Hello from After Callback - PID 24779
+  #     Hello from After Callback - PID 24761
+  #     Hello from After Callback - PID 24782
+  #     => 3
+  #     [11] pry(main)>
+  #     [12] pry(main)> parallel.waitall
+  #     => [0, 1, 2]
+  #     [13] pry(main)> puts parallel.results.inspect
+  #     [0, 1, 2]
+  #     => nil
   #
   # @author Zachary Patten <zachary@jovelabs.net>
   class Parallel < ZTK::Base
@@ -80,7 +134,7 @@ module ZTK
       super({
         :max_forks => MAX_FORKS
       }.merge(configuration))
-      config.logger.debug { "config=#{config.send(:table).inspect}" }
+      config.ui.logger.debug { "config=#{config.send(:table).inspect}" }
 
       (config.max_forks < 1) and log_and_raise(ParallelError, "max_forks must be equal to or greater than one!")
 
@@ -98,7 +152,7 @@ module ZTK
     def process(&block)
       !block_given? and log_and_raise(ParallelError, "You must supply a block to the process method!")
 
-      config.logger.debug { "forks(#{@forks.inspect})" }
+      config.ui.logger.debug { "forks(#{@forks.inspect})" }
 
       while (@forks.count >= config.max_forks) do
         wait
@@ -115,7 +169,7 @@ module ZTK
         parent_reader.close
 
         if !(data = block.call).nil?
-          config.logger.debug { "write(#{data.inspect})" }
+          config.ui.logger.debug { "write(#{data.inspect})" }
           child_writer.write(Base64.encode64(Marshal.dump(data)))
         end
 
@@ -143,12 +197,12 @@ module ZTK
     #   status and data returned from the process block.  If wait2() fails nil
     #   is returned.
     def wait
-      config.logger.debug { "wait" }
-      config.logger.debug { "forks(#{@forks.inspect})" }
+      config.ui.logger.debug { "wait" }
+      config.ui.logger.debug { "forks(#{@forks.inspect})" }
       pid, status = (Process.wait2(-1) rescue nil)
       if !pid.nil? && !status.nil? && !(fork = @forks.select{ |f| f[:pid] == pid }.first).nil?
         data = (Marshal.load(Base64.decode64(fork[:reader].read.to_s)) rescue nil)
-        config.logger.debug { "read(#{data.inspect})" }
+        config.ui.logger.debug { "read(#{data.inspect})" }
         !data.nil? and @results.push(data)
         fork[:reader].close
         fork[:writer].close
@@ -163,7 +217,7 @@ module ZTK
     #
     # @return [Array<Object>] The results from all of the *process* blocks.
     def waitall
-      config.logger.debug { "waitall" }
+      config.ui.logger.debug { "waitall" }
       while @forks.count > 0
         self.wait
       end
@@ -174,7 +228,7 @@ module ZTK
     #
     # @return [Integer] Current number of active forks.
     def count
-      config.logger.debug { "count(#{@forks.count})" }
+      config.ui.logger.debug { "count(#{@forks.count})" }
       @forks.count
     end
 

data/lib/ztk/report.rb

@@ -43,7 +43,7 @@ module ZTK
     def initialize(configuration={})
       super({
       }.merge(configuration))
-      config.logger.debug { "config=#{config.send(:table).inspect}" }
+      config.ui.logger.debug { "config=#{config.send(:table).inspect}" }
     end
 
     # Displays data in a spreadsheet style.
@@ -84,19 +84,19 @@ module ZTK
       end
       header_line = format_row(header_line)
 
-      config.stdout.puts(format_header(headers, max_lengths))
-      config.stdout.puts(header_line)
-      config.stdout.puts(format_header(headers, max_lengths))
+      config.ui.stdout.puts(format_header(headers, max_lengths))
+      config.ui.stdout.puts(header_line)
+      config.ui.stdout.puts(format_header(headers, max_lengths))
 
       rows.each do |row|
         row_line = headers.collect do |header|
           "%-#{max_lengths.send(header)}s" % row.send(header)
         end
         row_line = format_row(row_line)
-        config.stdout.puts(row_line)
+        config.ui.stdout.puts(row_line)
       end
 
-      config.stdout.puts(format_header(headers, max_lengths))
+      config.ui.stdout.puts(format_header(headers, max_lengths))
 
       width = (2 + max_lengths.send(:table).values.reduce(:+) + ((headers.count * 3) - 3) + 2)
 
@@ -141,13 +141,13 @@ module ZTK
       width = (max_key_length + max_value_length + 2 + 2 + 2)
 
       rows.each do |row|
-        config.stdout.puts("+#{"-" * width}+")
+        config.ui.stdout.puts("+#{"-" * width}+")
         headers.each do |header|
           entry_line = format_entry(header, max_key_length, row.send(header), max_value_length)
-          config.stdout.puts(entry_line)
+          config.ui.stdout.puts(entry_line)
         end
       end
-      config.stdout.puts("+#{"-" * width}+")
+      config.ui.stdout.puts("+#{"-" * width}+")
 
       OpenStruct.new(:rows => rows, :max_key_length => max_key_length, :max_value_length => max_value_length, :width => width)
     end

data/lib/ztk/rescue_retry.rb

@@ -33,17 +33,66 @@ module ZTK
   # 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:
+  # *example code*:
   #
+  #     counter = 0
   #     ZTK::RescueRetry.try(:tries => 3, :on => EOFError) do
-  #       @ssh = Net::SSH.start(config.host_name, config.user, ssh_options)
-  #       ...
+  #       counter += 1
+  #       raise EOFError
   #     end
+  #     puts counter.inspect
   #
-  # 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.
+  #     counter = 0
+  #     ZTK::RescueRetry.try(:tries => 3) do
+  #       counter += 1
+  #       raise "OMGWTFBBQ"
+  #     end
+  #     puts counter.inspect
+  #
+  #     counter = 0
+  #     ZTK::RescueRetry.try(:tries => 3, :on => EOFError) do
+  #       counter += 1
+  #       raise "OMGWTFBBQ"
+  #     end
+  #     puts counter.inspect
+  #
+  # *pry output*:
+  #
+  #     [1] pry(main)> counter = 0
+  #     => 0
+  #     [2] pry(main)> ZTK::RescueRetry.try(:tries => 3, :on => EOFError) do
+  #     [2] pry(main)*   counter += 1
+  #     [2] pry(main)*   raise EOFError
+  #     [2] pry(main)* end
+  #     EOFError: EOFError
+  #     from (pry):4:in `block in <main>'
+  #     [3] pry(main)> puts counter.inspect
+  #     3
+  #     => nil
+  #     [4] pry(main)>
+  #     [5] pry(main)> counter = 0
+  #     => 0
+  #     [6] pry(main)> ZTK::RescueRetry.try(:tries => 3) do
+  #     [6] pry(main)*   counter += 1
+  #     [6] pry(main)*   raise "OMGWTFBBQ"
+  #     [6] pry(main)* end
+  #     RuntimeError: OMGWTFBBQ
+  #     from (pry):10:in `block in <main>'
+  #     [7] pry(main)> puts counter.inspect
+  #     3
+  #     => nil
+  #     [8] pry(main)>
+  #     [9] pry(main)> counter = 0
+  #     => 0
+  #     [10] pry(main)> ZTK::RescueRetry.try(:tries => 3, :on => EOFError) do
+  #     [10] pry(main)*   counter += 1
+  #     [10] pry(main)*   raise "OMGWTFBBQ"
+  #     [10] pry(main)* end
+  #     RuntimeError: OMGWTFBBQ
+  #     from (pry):16:in `block in <main>'
+  #     [11] pry(main)> puts counter.inspect
+  #     1
+  #     => nil
   #
   # @author Zachary Patten <zachary@jovelabs.net>
   class RescueRetry
@@ -75,19 +124,19 @@ module ZTK
           :on => Exception,
           :delay => 1
         }.merge(options))
-        options.logger.debug { "options=#{options.send(:table).inspect}" }
+        options.ui.logger.debug { "options=#{options.send(:table).inspect}" }
 
-        !block_given? and Base.log_and_raise(options.logger, RescueRetryError, "You must supply a block!")
+        !block_given? and Base.log_and_raise(options.ui.logger, RescueRetryError, "You must supply a block!")
 
         begin
           return block.call
         rescue options.on => e
           if ((options.tries -= 1) > 0)
-            options.logger.warn { "Caught #{e.inspect}, we will give it #{options.tries} more tr#{options.tries > 1 ? 'ies' : 'y'}." }
+            options.ui.logger.warn { "Caught #{e.inspect}, we will give it #{options.tries} more tr#{options.tries > 1 ? 'ies' : 'y'}." }
             sleep(options.delay)
             retry
           else
-            options.logger.fatal { "Caught #{e.inspect} and we have no more tries left, sorry, we have to give up now." }
+            options.ui.logger.fatal { "Caught #{e.inspect} and we have no more tries left, sorry, we have to give up now." }
             raise e
           end
         end