ztk 0.3.1 → 1.0.0.rc.0

data/.travis.yml

@@ -4,10 +4,12 @@ rvm:
   - 1.9.2
   - 1.9.3
 
-branches:
-  only:
-    - master
+before_install:
+  - sudo apt-get -qq update
+
+bundler_args: --binstubs
+
+script: "rake spec"
 
 notifications:
-  irc:
-    - "irc.freenode.org#jovelabs"
+  irc: "irc.freenode.net#jovelabs"

data/.yardopts

@@ -0,0 +1,2 @@
+--markup-provider=redcarpet
+--markup=markdown

data/README.md

@@ -2,7 +2,7 @@
 
 # ZTK
 
-Zachary's Tool Kit is a general purpose utility gem, featuring a collection of classes meant to simplify development of complex systems in Ruby.
+Zachary's (DevOp) Tool Kit is a general purpose utility gem, featuring a collection of classes meant to simplify development of complex systems in Ruby.
 
 # RESOURCES
 
@@ -16,7 +16,7 @@ Issues:
 
 Documentation:
 
-* http://rubydoc.info/gems/ztk
+* http://jovelabs.github.com/ztk/
 
 Wiki:
 
@@ -24,7 +24,7 @@ Wiki:
 
 # LICENSE
 
-ZTK - Zachary's Tool Kit
+ZTK - Zachary's (DevOp) Tool Kit
 
 * Author: Zachary Patten <zachary@jovelabs.net>
 * Copyright: Copyright (c) Jove Labs

data/Rakefile

@@ -41,3 +41,42 @@ task :coverage do
 end
 
 ################################################################################
+
+require 'yard'
+require 'yard/rake/yardoc_task'
+
+GEM_NAME = File.basename(Dir.pwd)
+DOC_PATH = File.expand_path(File.join("..", "/", "#{GEM_NAME}.doc"))
+
+namespace :doc do
+  YARD::Rake::YardocTask.new(:pages) do |t|
+
+    # t.files = ['lib/**/*.rb']
+    t.options = ['--verbose', '-o', DOC_PATH]
+  end
+
+  namespace :pages do
+
+    desc 'Generate and publish YARD Documentation to GitHub pages'
+    task :publish => ['doc:pages'] do
+      describe = %x(git describe).chomp
+      stats = %x(bundle exec yard stats).chomp
+
+      commit_message = Array.new
+      commit_message << "Generated YARD Documentation for #{GEM_NAME.upcase} #{describe}\n\n"
+      commit_message << stats
+
+      Dir.chdir(DOC_PATH) do
+        puts(%x{git add -Av})
+        puts(%x{git commit -m"#{commit_message.join}"})
+        puts(%x{git push origin gh-pages})
+      end
+    end
+
+  end
+
+end
+desc 'Alias to doc:yard'
+task 'doc' => 'doc:yard'
+
+################################################################################

data/lib/ztk/background.rb

@@ -17,7 +17,6 @@
 #   limitatIOns under the License.
 #
 ################################################################################
-
 require "base64"
 
 module ZTK
@@ -63,10 +62,7 @@ module ZTK
     # Result Set
     attr_accessor :pid, :result
 
-    # @param [Hash] config 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.
+    # @param [Hash] configuration Configuration options hash.
     def initialize(configuration={})
       super({
       }.merge(configuration))
@@ -80,7 +76,7 @@ module ZTK
     #
     # @yield Block should execute tasks to be performed in background.
     # @yieldreturn [Object] Block can return any object to be marshalled back to
-    #   the parent processes result set.
+    #   the parent processes.
     # @return [Integer] Returns the pid of the child process forked.
     def process(&block)
       !block_given? and log_and_raise(BackgroundError, "You must supply a block to the process method!")
@@ -121,6 +117,10 @@ module ZTK
     # If a process successfully finished, it's return value from the *process*
     # block is stored into the result set.
     #
+    # It's advisable to use something like the *at_exit* hook to ensure you don't
+    # leave orphaned processes.  For example, in the *at_exit* hook you could
+    # call *wait* to block until the child process finishes up.
+    #
     # @return [Array<pid, status, data>] An array containing the pid,
     #   status and data returned from the process block.  If wait2() fails nil
     #   is returned.
@@ -140,6 +140,14 @@ module ZTK
       nil
     end
 
+    def alive?
+      (Process.getpgid(@pid).is_a?(Integer) rescue false)
+    end
+
+    def dead?
+      !alive?
+    end
+
   end
 
 end

data/lib/ztk/base.rb

@@ -17,7 +17,6 @@
 #   limitations under the License.
 #
 ################################################################################
-
 require "ostruct"
 
 module ZTK
@@ -37,7 +36,7 @@ module ZTK
 
     class << self
 
-      # @param [Hash] config Configuration options hash.
+      # @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.
@@ -81,6 +80,14 @@ module ZTK
         config
       end
 
+      # Logs an exception and then raises it.
+      #
+      # @param [Logger] logger An instance of a class based off the Ruby
+      #   *Logger* class.
+      # @param [Exception] exception The exception class to raise.
+      # @param [String] message The message to display with the exception.
+      # @param [Integer] shift (1) How many places to shift the caller stack in
+      #   the log statement.
       def log_and_raise(logger, exception, message, shift=1)
         if logger.is_a?(ZTK::Logger)
           logger.shift(:fatal, shift) { "EXCEPTION: #{exception.inspect} - #{message.inspect}" }
@@ -117,8 +124,16 @@ module ZTK
       end
     end
 
-    def log_and_raise(exception, message)
-      Base.log_and_raise(config.logger, exception, message, 2)
+    # Logs an exception and then raises it.
+    #
+    # @see Base.log_and_raise
+    #
+    # @param [Exception] exception The exception class to raise.
+    # @param [String] message The message to display with the exception.
+    # @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)
     end
 
     # Direct logging method.
@@ -130,7 +145,7 @@ module ZTK
     # The value returned in the block is passed down to the logger specified in
     # the classes configuration.
     #
-    # @param [Symbol] method_name This should be any one of [:debug, :info, :warn, :error, :fatal].
+    # @param [Symbol] log_level This should be any one of [:debug, :info, :warn, :error, :fatal].
     # @yield No value is passed to the block.
     # @yieldreturn [String] The message to log.
     def direct_log(log_level, &blocK)

data/lib/ztk/benchmark.rb

@@ -26,13 +26,45 @@ module ZTK
   # @author Zachary Patten <zachary@jovelabs.net>
   class BenchmarkError < Error; end
 
-  # Benchmark Class
+  # ZTK Benchmark Class
+  #
+  # This class contains a benchmarking tool which doubles to supply indications
+  # of activity to the console user during long running tasks.
+  #
+  # It can be run strictly for benchmarking (the default) or if supplied with
+  # the appropriate options it will display output to the user while
+  # benchmarking the supplied block.
   #
   # @author Zachary Patten <zachary@jovelabs.net>
   class Benchmark
 
     class << self
 
+      # Benchmark the supplied block.
+      #
+      # If *message* and *mark* options are used, then the *message* text will
+      # be displayed to the user.  The the supplied *block* is yielded inside
+      # a *ZTK::Spinner.spin* call.  This will provide the spinning cursor while
+      # the block executes.  It is advisable to not have output sent to the
+      # console during this period.
+      #
+      # Once the block finishes executing, the *mark* text is displayed with
+      # the benchmark supplied to it as a sprintf option.  One could use "%0.4f"
+      # in a *String* for example to get the benchmark time embedded in it
+      #
+      # @see Kernel#sprintf
+      #
+      # @param [Hash] options Configuration options hash.
+      # @option options [String] :message The *String* to be displayed to the
+      #   user before the block is yielded.
+      # @option options [String] :mark The *String* to be displayed to the user
+      #   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*.
+      #
+      # @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}" }

data/lib/ztk/command.rb

@@ -17,7 +17,6 @@
 #   limitations under the License.
 #
 ################################################################################
-
 require "ostruct"
 require "timeout"
 
@@ -50,11 +49,6 @@ module ZTK
       config.logger.debug { "config=#{config.send(:table).inspect}" }
     end
 
-    def inspect
-      @hostname ||= %x(hostname -f).chomp
-      "#{ENV['USER']}@#{@hostname}"
-    end
-
     # Executes a local command.
     #
     # @param [String] command The command to execute.
@@ -69,20 +63,17 @@ module ZTK
     #   cmd = ZTK::Command.new
     #   puts cmd.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}" }
       config.logger.debug { "options=#{options.send(:table).inspect}" }
       config.logger.info { "command(#{command.inspect})" }
 
+      if config.replace_current_process
+        config.logger.fatal { "REPLACING CURRENT PROCESS - GOODBYE!" }
+        Kernel.exec(command)
+      end
+
       output = ""
       exit_code = -1
       stdout_header = false
@@ -169,14 +160,33 @@ module ZTK
       OpenStruct.new(:output => output, :exit_code => exit_code)
     end
 
+    # Not Supported
+    # @raise [CommandError] Not Supported
     def upload(*args)
       log_and_raise(CommandError, "Not Supported")
     end
 
+    # Not Supported
+    # @raise [CommandError] Not Supported
     def download(*args)
       log_and_raise(CommandError, "Not Supported")
     end
 
+
+  private
+
+    def tag
+      @hostname ||= %x(hostname -f).chomp
+      "#{ENV['USER']}@#{@hostname}"
+    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/config.rb

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

data/lib/ztk/dsl/base.rb

@@ -0,0 +1,76 @@
+################################################################################
+#
+#      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.
+#
+################################################################################
+
+# @author Zachary Patten <zachary@jovelabs.net>
+module ZTK::DSL
+
+  class Base
+    include(ZTK::DSL::Core)
+
+    def self.inherited(base)
+      puts("inherited(#{base})")
+      base.send(:extend, ZTK::DSL::Base::ClassMethods)
+      base.instance_eval do
+        attribute :id
+      end
+    end
+
+    def self.included(base)
+      puts("included(#{base})")
+    end
+
+    def self.extended(base)
+      puts("extended(#{base})")
+    end
+
+    def initialize(&block)
+      self.id = self.class.id
+      self.class.dataset << self
+      block_given? and ((block.arity < 1) ? instance_eval(&block) : block.call(self))
+
+      primary_key_count = self.class.dataset.count do |d|
+        puts("d.id == #{d.id.inspect} / self.id == #{self.id.inspect}")
+        d.id == self.id
+      end
+      puts("primary_key_count == #{primary_key_count}")
+      raise StandardError, "Primary key '#{self.id}' already exists!" if (primary_key_count > 1)
+    end
+
+    def inspect
+      details = Array.new
+      details << "attributes=#{attributes.inspect}" if attributes.count > 0
+      details << "has_many_references=#{@has_many_references.count}" if @has_many_references
+      details << "belongs_to_references=#{@belongs_to_references.count}" if @belongs_to_references
+      "#<#{self.class.to_s} id=#{self.id.inspect} #{details.join(', ')}>"
+    end
+
+    module ClassMethods
+
+      def inspect
+        details = Array.new
+        details << "count=#{self.all.count}" if self.all.count > 0
+        "#<#{self.class.to_s}:#{self.id} #{details.join(', ')}>"
+      end
+
+    end
+
+  end
+
+end

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

@@ -0,0 +1,49 @@
+################################################################################
+#
+#      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::Actions
+  module Find
+
+    def self.included(base)
+      base.class_eval do
+        base.send(:extend, ZTK::DSL::Core::Actions::Find::ClassMethods)
+      end
+    end
+
+    module ClassMethods
+
+      def all
+        dataset
+      end
+
+      def find(*args)
+        logger.debug { "*args(#{args.inspect})" }
+        ids = [args].flatten
+        all.select{ |data| ids.include?(data.id) }
+      end
+
+      def count
+        all.count
+      end
+
+    end
+
+  end
+end

data/lib/ztk/dsl/core/actions/timestamps.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.
+#
+################################################################################
+
+module ZTK::DSL::Core::Actions
+  module Timestamps
+
+    def self.included(base)
+      base.class_eval do
+        base.send(:extend, ZTK::DSL::Core::Actions::Timestamps::ClassMethods)
+      end
+      base.instance_eval do
+        attribute :created_at
+        attribute :updated_at
+      end
+    end
+
+    module ClassMethods
+
+      def updated_at_timestamp
+        self.updated_at = Time.now
+      end
+
+      def created_at_timestamp
+        self.created_at ||= Time.now
+      end
+
+    end
+
+  end
+end

data/lib/ztk/dsl/core/actions.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.
+#
+################################################################################
+
+module ZTK::DSL::Core
+  module Actions
+    autoload :Find, "ztk/dsl/core/actions/find"
+    autoload :Timestamps, "ztk/dsl/core/actions/timestamps"
+
+    def self.included(base)
+      base.class_eval do
+        base.send(:include, ZTK::DSL::Core::Actions::Find)
+        base.send(:include, ZTK::DSL::Core::Actions::Timestamps)
+      end
+    end
+
+  end
+end

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

@@ -0,0 +1,53 @@
+################################################################################
+#
+#      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 Attributes
+
+    def self.included(base)
+      base.class_eval do
+        base.send(:extend, ZTK::DSL::Core::Attributes::ClassMethods)
+      end
+    end
+
+    def attributes
+      @attributes ||= {}
+    end
+
+    module ClassMethods
+
+      def attribute(key, options={})
+        send(:define_method, key) do |*args|
+          if args.count == 0
+            attributes[key]
+          else
+            send("#{key}=", *args)
+          end
+        end
+
+        send(:define_method, "#{key}=") do |value|
+          attributes[key] = value
+        end
+      end
+
+    end
+
+  end
+end

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

@@ -0,0 +1,66 @@
+################################################################################
+#
+#      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 Dataset
+
+    def self.included(base)
+      base.class_eval do
+        base.send(:extend, ZTK::DSL::Core::Dataset::ClassMethods)
+      end
+    end
+
+    module ClassMethods
+
+      def dataset
+        klass = self.to_s.underscore.to_sym
+        @@dataset ||= {}
+        if @@dataset.key?(klass)
+          @@dataset[klass]
+        else
+          @@dataset[klass] ||= []
+        end
+      end
+
+      def purge
+        @@dataset = nil
+      end
+
+      def id
+        @@id ||= 0
+        (@@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
+end