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

data/lib/ztk/background.rb

@@ -30,6 +30,13 @@ module ZTK
   #
   # This class can be used to easily run a linear process in a background 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,17 +51,53 @@ module ZTK
   #       config.after_fork = a_callback
   #     end
   #
-  #     background.process do
-  #       x
+  #     pid = background.process do
+  #       sleep(1)
   #     end
+  #     puts pid.inspect
   #
   #     background.wait
-  #     background.result
+  #     puts background.result.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:0x00000001368a98@(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:0x00000001060418@(pry):4>
+  #     [4] pry(main)>
+  #     [5] pry(main)> background = ZTK::Background.new
+  #     => #<ZTK::Background:0x00000001379118
+  #      @config=
+  #       #<OpenStruct stdout=#<IO:<STDOUT>>, stderr=#<IO:<STDERR>>, stdin=#<IO:<STDIN>>, logger=#<ZTK::Logger filename="/dev/null">>,
+  #      @result=nil>
+  #     [6] pry(main)> background.config do |config|
+  #     [6] pry(main)*   config.before_fork = b_callback
+  #     [6] pry(main)*   config.after_fork = a_callback
+  #     [6] pry(main)* end
+  #     => #<Proc:0x00000001368a98@(pry):1>
+  #     [7] pry(main)>
+  #     [8] pry(main)> pid = background.process do
+  #     [8] pry(main)*   sleep(1)
+  #     [8] pry(main)* end
+  #     Hello from Before Callback - PID 23564
+  #     Hello from After Callback - PID 23564
+  #     Hello from After Callback - PID 23578
+  #     => 23578
+  #     [9] pry(main)> puts pid.inspect
+  #     23578
+  #     => nil
+  #     [10] pry(main)>
+  #     [11] pry(main)> background.wait
+  #     => [23578, #<Process::Status: pid 23578 exit 0>, 1]
+  #     [12] pry(main)> puts background.result.inspect
+  #     1
+  #     => nil
   #
   # @author Zachary Patten <zachary@jovelabs.net>
   class Background < ZTK::Base
@@ -66,7 +109,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}" }
 
       @result = nil
       GC.respond_to?(:copy_on_write_friendly=) and GC.copy_on_write_friendly = true
@@ -96,7 +139,7 @@ module ZTK
         STDIN.reopen("/dev/null")
 
         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
 
@@ -125,11 +168,11 @@ module ZTK
     #   status and data returned from the process block.  If wait2() fails nil
     #   is returned.
     def wait
-      config.logger.debug { "wait" }
+      config.ui.logger.debug { "wait" }
       pid, status = (Process.wait2(@pid) rescue nil)
       if !pid.nil? && !status.nil?
         data = (Marshal.load(Base64.decode64(@parent_reader.read.to_s)) rescue nil)
-        config.logger.debug { "read(#{data.inspect})" }
+        config.ui.logger.debug { "read(#{data.inspect})" }
         !data.nil? and @result = data
 
         @parent_reader.close

data/lib/ztk/base.rb

@@ -22,6 +22,8 @@ require "ostruct"
 module ZTK
 
   # ZTK::Base Error Class
+  #
+  # @author Zachary Patten <zachary@jovelabs.net>
   class BaseError < Error; end
 
   # ZTK Base Class
@@ -32,34 +34,25 @@ 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>
   class Base
 
     class << self
 
       # @param [Hash] configuration Configuration options hash.
-      # @option config [IO] :stdout Instance of IO to be used for STDOUT.
-      # @option config [IO] :stderr Instance of IO to be used for STDERR.
-      # @option config [IO] :stdin Instance of IO to be used for STDIN.
-      # @option config [Logger] :logger Instance of Logger to be used for logging.
+      # @option config [ZTK::UI] :ui Instance of ZTK:UI to be used for
+      #   console IO and logging.
       def build_config(configuration={})
         if configuration.is_a?(OpenStruct)
           configuration = configuration.send(:table)
         end
 
-        rails_logger = Rails.logger if defined?(Rails)
-
+        # FIXME: this needs to be refactored into the UI class
         config = OpenStruct.new({
-          :stdout => $stdout,
-          :stderr => $stderr,
-          :stdin => $stdin,
-          :logger => ($logger || rails_logger || ZTK::Logger.new("/dev/null"))
+          :ui => ::ZTK::UI.new
         }.merge(configuration))
 
-        (config.stdout && config.stdout.respond_to?(:sync=)) and config.stdout.sync = true
-        (config.stderr && config.stderr.respond_to?(:sync=)) and config.stderr.sync = true
-        (config.stdin  && config.stdin.respond_to?(:sync=))  and config.stdin.sync = true
-        (config.logger && config.logger.respond_to?(:sync=)) and config.logger.sync = true
-
         config
       end
 
@@ -133,7 +126,7 @@ module ZTK
     # @param [Integer] shift (2) How many places to shift the caller stack in
     #   the log statement.
     def log_and_raise(exception, message, shift=2)
-      Base.log_and_raise(config.logger, exception, message, shift)
+      Base.log_and_raise(config.ui.logger, exception, message, shift)
     end
 
     # Direct logging method.
@@ -149,17 +142,17 @@ module ZTK
     # @yield No value is passed to the block.
     # @yieldreturn [String] The message to log.
     def direct_log(log_level, &blocK)
-      @config.logger.nil? and raise BaseError, "You must supply a logger for direct logging support!"
+      @config.ui.logger.nil? and raise BaseError, "You must supply a logger for direct logging support!"
 
       if !block_given?
         log_and_raise(BaseError, "You must supply a block to the log method!")
-      elsif (@config.logger.level <= ZTK::Logger.const_get(log_level.to_s.upcase))
-        if @config.logger.respond_to?(:logdev)
-          @config.logger.logdev.write(yield)
-          @config.logger.logdev.respond_to?(:flush) and @config.logger.logdev.flush
+      elsif (@config.ui.logger.level <= ZTK::Logger.const_get(log_level.to_s.upcase))
+        if @config.ui.logger.respond_to?(:logdev)
+          @config.ui.logger.logdev.write(yield)
+          @config.ui.logger.logdev.respond_to?(:flush) and @config.ui.logger.logdev.flush
         else
-          @config.logger.instance_variable_get(:@logdev).instance_variable_get(:@dev).write(yield)
-          @config.logger.instance_variable_get(:@logdev).instance_variable_get(:@dev).respond_to?(:flush) and @config.logger.instance_variable_get(:@logdev).instance_variable_get(:@dev).flush
+          @config.ui.logger.instance_variable_get(:@logdev).instance_variable_get(:@dev).write(yield)
+          @config.ui.logger.instance_variable_get(:@logdev).instance_variable_get(:@dev).respond_to?(:flush) and @config.ui.logger.instance_variable_get(:@logdev).instance_variable_get(:@dev).flush
         end
       end
     end

data/lib/ztk/benchmark.rb

@@ -35,6 +35,26 @@ module ZTK
   # the appropriate options it will display output to the user while
   # benchmarking the supplied block.
   #
+  # *example code*:
+  #
+  #     message = "I wonder how long this will take?"
+  #     mark = " ...looks like it took %0.4f seconds!"
+  #     ZTK::Benchmark.bench(:message => message, :mark => mark) do
+  #       sleep(1.5)
+  #     end
+  #
+  # *pry output*:
+  #
+  #     [1] pry(main)> message = "I wonder how long this will take?"
+  #     => "I wonder how long this will take?"
+  #     [2] pry(main)> mark = " ...looks like it took %0.4f seconds!"
+  #     => " ...looks like it took %0.4f seconds!"
+  #     [3] pry(main)> ZTK::Benchmark.bench(:message => message, :mark => mark) do
+  #     [3] pry(main)*   sleep(1.5)
+  #     [3] pry(main)* end
+  #     I wonder how long this will take?  ...looks like it took 1.5229 seconds!
+  #     => 1.522871547
+  #
   # @author Zachary Patten <zachary@jovelabs.net>
   class Benchmark
 
@@ -61,23 +81,31 @@ module ZTK
       #   after the block is yielded.  This *String* should have an *sprintf*
       #   floating point macro in it if the benchmark is desired to be embedded
       #   in the given *String*.
+      # @option options [Boolean] :use_spinner (true) Weither or not to use the
+      #   ZTK::Spinner while benchmarking.
       #
       # @yield Block should execute the tasks to be benchmarked.
       # @yieldreturn [Object] The return value of the block is ignored.
       # @return [Float] The benchmark time.
       def bench(options={}, &block)
-        options = Base.build_config(options)
-        options.logger.debug { "options=#{options.send(:table).inspect}" }
+        options = Base.build_config({
+          :use_spinner => true
+        }.merge(options))
+        options.ui.logger.debug { "options=#{options.send(:table).inspect}" }
 
-        !block_given? and Base.log_and_raise(options.logger, BenchmarkError, "You must supply a block!")
+        !block_given? and Base.log_and_raise(options.ui.logger, BenchmarkError, "You must supply a block!")
 
         check = [options.message, options.mark]
-        (check.any?{ |z| !z.nil? } && !check.all?{ |z| !z.nil? }) and Base.log_and_raise(options.logger, BenchmarkError, "You must supply both a message and a mark!")
+        (check.any?{ |z| !z.nil? } && !check.all?{ |z| !z.nil? }) and Base.log_and_raise(options.ui.logger, BenchmarkError, "You must supply both a message and a mark!")
 
-        (options.message && options.mark) and options.stdout.print("#{options.message} ")
+        (options.message && options.mark) and options.ui.stdout.print("#{options.message} ")
         benchmark = ::Benchmark.realtime do
           if (options.message && options.mark)
-            ZTK::Spinner.spin(Base.sanitize_config(options)) do
+            if options.use_spinner
+              ZTK::Spinner.spin(Base.sanitize_config(options)) do
+                yield
+              end
+            else
               yield
             end
           else
@@ -85,8 +113,8 @@ module ZTK
           end
         end
 
-        (options.message && options.mark) and options.stdout.print("#{options.mark}\n" % benchmark)
-        options.logger.info { "#{options.message} #{options.mark}" % benchmark }
+        (options.message && options.mark) and options.ui.stdout.print("#{options.mark}\n" % benchmark)
+        options.ui.logger.info { "#{options.message} #{options.mark}" % benchmark }
 
         benchmark
       end

data/lib/ztk/command.rb

@@ -46,7 +46,7 @@ module ZTK
         :timeout => 600,
         :ignore_exit_status => false
       }.merge(configuration))
-      config.logger.debug { "config=#{config.send(:table).inspect}" }
+      config.ui.logger.debug { "config=#{config.send(:table).inspect}" }
     end
 
     # Executes a local command.
@@ -65,12 +65,12 @@ module ZTK
     def exec(command, options={})
       options = OpenStruct.new({ :exit_code => 0, :silence => false }.merge(options))
 
-      config.logger.debug { "config=#{config.send(:table).inspect}" }
-      config.logger.debug { "options=#{options.send(:table).inspect}" }
-      config.logger.info { "command(#{command.inspect})" }
+      config.ui.logger.debug { "config=#{config.send(:table).inspect}" }
+      config.ui.logger.debug { "options=#{options.send(:table).inspect}" }
+      config.ui.logger.info { "command(#{command.inspect})" }
 
       if config.replace_current_process
-        config.logger.fatal { "REPLACING CURRENT PROCESS - GOODBYE!" }
+        config.ui.logger.fatal { "REPLACING CURRENT PROCESS - GOODBYE!" }
         Kernel.exec(command)
       end
 
@@ -101,7 +101,7 @@ module ZTK
       child_stderr_writer.close
 
       reader_writer_key = {parent_stdout_reader => :stdout, parent_stderr_reader => :stderr}
-      reader_writer_map = {parent_stdout_reader => @config.stdout, parent_stderr_reader => @config.stderr}
+      reader_writer_map = {parent_stdout_reader => @config.ui.stdout, parent_stderr_reader => @config.ui.stderr}
 
       direct_log(:debug) { log_header("COMMAND") }
       direct_log(:debug) { "#{command}\n" }
@@ -152,7 +152,7 @@ module ZTK
       parent_stdout_reader.close
       parent_stderr_reader.close
 
-      config.logger.debug { "exit_code(#{exit_code})" }
+      config.ui.logger.debug { "exit_code(#{exit_code})" }
 
       if !config.ignore_exit_status && (exit_code != options.exit_code)
         log_and_raise(CommandError, "exec(#{command.inspect}, #{options.inspect}) failed! [#{exit_code}]")

data/lib/ztk/dsl.rb

@@ -17,11 +17,14 @@
 #   limitations under the License.
 #
 ################################################################################
-
 require "active_support/inflector"
 
-# @author Zachary Patten <zachary@jovelabs.net>
 module ZTK
+
+  # Generic Domain-specific Language Interface
+  #
+  # @see ZTK::DSL::Base
+  # @author Zachary Patten <zachary@jovelabs.net>
   module DSL
 
     # @author Zachary Patten <zachary@jovelabs.net>

data/lib/ztk/dsl/base.rb

@@ -18,12 +18,141 @@
 #
 ################################################################################
 
-# @author Zachary Patten <zachary@jovelabs.net>
 module ZTK::DSL
 
+  # Generic Domain-specific Language Interface
+  #
+  # This module allows you to easily add attributes and relationships to classes
+  # to create a custom DSL in no time.
+  #
+  # You can then access these classes in manners similar to what *ActiveRecord*
+  # provides for relationships.  You can easily link classes together; load
+  # stored objects from Ruby rb files (think Opscode Chef DSL).
+  #
+  # I intend the interface to act like ActiveRecord for the programmer and a
+  # nice DSL for the end user.  It's not meant to be a database; more like
+  # a soft dataset in memory; extremely fast but highly volitale.  As always
+  # you can never have your cake and eat it too.
+  #
+  # You specify the "schema" in the classes itself; there is no data storage at
+  # this time, but I do plan to add support for loading/saving *datasets* to
+  # disk.  Keep in mind since you do not specify type constrants in Ruby, one
+  # can assign any object to an attribute.
+  #
+  # At this time if you do not specify an ID; one is auto generated.
+  #
+  # If you wish to create objects in a nested fashion the outer most object must
+  # be started using the class name initializer.  Once inside the block you can
+  # start using the relationship names and do not need to call any further
+  # class initializers.
+  #
+  # You can also instantiate classes separately and associate them after the
+  # fact.  That is not shown in this example.
+  #
+  # *example code*:
+  #
+  #     class Network < ZTK::DSL::Base
+  #       has_many :servers
+  #
+  #       attribute :name
+  #       attribute :gw
+  #       attribute :network
+  #       attribute :netmask
+  #     end
+  #
+  #     class Server < ZTK::DSL::Base
+  #       belongs_to :network
+  #
+  #       attribute :name
+  #     end
+  #
+  #     Network.new do
+  #       id :leet_net
+  #       name "leet-net"
+  #       gw "7.3.3.1"
+  #       network "7.3.3.0"
+  #       netmask "255.255.255.0"
+  #
+  #       server do
+  #         name "leet-server"
+  #       end
+  #
+  #       server do
+  #         id :my_server
+  #         name "my-server"
+  #       end
+  #
+  #       server do
+  #         name "dev-server"
+  #       end
+  #     end
+  #
+  #     Network.count
+  #     Network.all
+  #     Network.find(:leet_net)
+  #
+  #     Server.count
+  #     Server.all
+  #     Server.find(:my_server)
+  #
+  # *pry output*:
+  #
+  #     [1] pry(main)> class Network < ZTK::DSL::Base
+  #     [1] pry(main)*   has_many :servers
+  #     [1] pry(main)*
+  #     [1] pry(main)*   attribute :name
+  #     [1] pry(main)*   attribute :gw
+  #     [1] pry(main)*   attribute :network
+  #     [1] pry(main)*   attribute :netmask
+  #     [1] pry(main)* end
+  #     => #<Proc:0x0000000121f498@/home/zpatten/Dropbox/code/chef-repo/vendor/checkouts/ztk/lib/ztk/dsl/core/attributes.rb:45 (lambda)>
+  #     [2] pry(main)> class Server < ZTK::DSL::Base
+  #     [2] pry(main)*   belongs_to :network
+  #     [2] pry(main)*
+  #     [2] pry(main)*   attribute :name
+  #     [2] pry(main)* end
+  #     => #<Proc:0x00000001983108@/home/zpatten/Dropbox/code/chef-repo/vendor/checkouts/ztk/lib/ztk/dsl/core/attributes.rb:45 (lambda)>
+  #     [3] pry(main)> Network.new do
+  #     [3] pry(main)*   id :leet_net
+  #     [3] pry(main)*   name "leet-net"
+  #     [3] pry(main)*   gw "7.3.3.1"
+  #     [3] pry(main)*   network "7.3.3.0"
+  #     [3] pry(main)*   netmask "255.255.255.0"
+  #     [3] pry(main)*
+  #     [3] pry(main)*   server do
+  #     [3] pry(main)*     name "leet-server"
+  #     [3] pry(main)*   end
+  #     [3] pry(main)*
+  #     [3] pry(main)*   server do
+  #     [3] pry(main)*     id :my_server
+  #     [3] pry(main)*     name "my-server"
+  #     [3] pry(main)*   end
+  #     [3] pry(main)*
+  #     [3] pry(main)*   server do
+  #     [3] pry(main)*     name "dev-server"
+  #     [3] pry(main)*   end
+  #     [3] pry(main)* end
+  #     => #<Network id=:leet_net attributes={:id=>:leet_net, :name=>"leet-net", :gw=>"7.3.3.1", :network=>"7.3.3.0", :netmask=>"255.255.255.0"}, has_many_references=1>
+  #     [4] pry(main)> Network.count
+  #     => 1
+  #     [5] pry(main)> Network.all
+  #     => [#<Network id=:leet_net attributes={:id=>:leet_net, :name=>"leet-net", :gw=>"7.3.3.1", :network=>"7.3.3.0", :netmask=>"255.255.255.0"}, has_many_references=1>]
+  #     [6] pry(main)> Network.find(:leet_net)
+  #     => [#<Network id=:leet_net attributes={:id=>:leet_net, :name=>"leet-net", :gw=>"7.3.3.1", :network=>"7.3.3.0", :netmask=>"255.255.255.0"}, has_many_references=1>]
+  #     [7] pry(main)> Server.count
+  #     => 3
+  #     [8] pry(main)> Server.all
+  #     => [#<Server id=2 attributes={:id=>2, :name=>"leet-server", :network_id=>:leet_net}, belongs_to_references=1>,
+  #      #<Server id=:my_server attributes={:id=>:my_server, :name=>"my-server", :network_id=>:leet_net}, belongs_to_references=1>,
+  #      #<Server id=4 attributes={:id=>4, :name=>"dev-server", :network_id=>:leet_net}, belongs_to_references=1>]
+  #     [9] pry(main)> Server.find(:my_server)
+  #     => [#<Server id=:my_server attributes={:id=>:my_server, :name=>"my-server", :network_id=>:leet_net}, belongs_to_references=1>]
+  #
+  # @author Zachary Patten <zachary@jovelabs.net>
   class Base
     include(ZTK::DSL::Core)
 
+    # @api private
     def self.inherited(base)
       puts("inherited(#{base})")
       base.send(:extend, ZTK::DSL::Base::ClassMethods)
@@ -32,10 +161,12 @@ module ZTK::DSL
       end
     end
 
+    # @api private
     def self.included(base)
       puts("included(#{base})")
     end
 
+    # @api private
     def self.extended(base)
       puts("extended(#{base})")
     end
@@ -61,6 +192,7 @@ module ZTK::DSL
       "#<#{self.class.to_s} id=#{self.id.inspect} #{details.join(', ')}>"
     end
 
+    # @author Zachary Patten <zachary@jovelabs.net>
     module ClassMethods
 
       def inspect