golly-utils 0.0.1

data/lib/golly-utils/callbacks.rb

@@ -0,0 +1,92 @@
+require 'golly-utils/ruby_ext/deep_dup'
+
+module GollyUtils
+  module Callbacks
+
+    def self.included(base)
+      base.send :include, InstanceMethods
+      base.send :include, InstanceAndClassMethods
+      base.extend InstanceAndClassMethods
+      base.extend ClassMethods
+    end
+
+    #-------------------------------------------------------------------------------------------------------------------
+
+    module ClassMethods
+
+      def define_callbacks(*callbacks)
+        callbacks.each do |name|
+          name= _norm_callback_key(name)
+
+          if self.methods.include?(name.to_sym)
+            raise "Can't create callback with name '#{name}'. A method with that name already exists."
+          end
+
+          _callbacks[name] ||= {}
+          class_eval <<-EOB
+            def self.#{name}(&block)
+              v= (_callbacks[#{name.inspect}] ||= {})
+              (v[:procs] ||= [])<< block
+            end
+          EOB
+        end
+      end
+      alias :define_callback :define_callbacks
+
+      private
+
+      def _callbacks
+        @callbacks ||= {}
+      end
+
+      def _get_callback_procs(name)
+        name_verified= false
+        results= []
+
+        # Get local
+        if local= _callbacks[name]
+          name_verified= true
+          results.concat local[:procs] if local[:procs]
+        end
+
+        # Get inherited
+        if superclass.private_methods.include?(:_get_callback_procs)
+          n,r = superclass.send(:_get_callback_procs,name)
+          name_verified ||= n
+          results.concat r
+        end
+
+        [name_verified,results]
+      end
+
+    end
+
+    #-------------------------------------------------------------------------------------------------------------------
+
+    module InstanceAndClassMethods
+
+      private
+      def _norm_callback_key(key)
+        key.to_sym
+      end
+
+    end
+
+    #-------------------------------------------------------------------------------------------------------------------
+
+    module InstanceMethods
+
+      def run_callbacks(*callbacks)
+        callbacks.each do |name|
+          name= _norm_callback_key(name)
+          name_verified,results = self.class.send :_get_callback_procs, name
+          raise "There is no callback defined with name #{name}." unless name_verified
+          results.each{|cb| cb.call }
+        end
+        true
+      end
+      alias :run_callback :run_callbacks
+
+    end
+  end
+end

data/lib/golly-utils/child_process.rb

@@ -0,0 +1,124 @@
+module GollyUtils
+
+  # Start, manage, and stop a child process.
+  class ChildProcess
+    attr_accessor :start_command, :quiet, :spawn_options, :env
+    attr_reader :pid
+    alias :quiet? :quiet
+
+    # @option options [String] :start_command The shell command to start the child process.
+    # @option options [Hash] :env Environment variables to set in the child process.
+    # @option options [Boolean] :quiet (false) Whether to print startup/shutdown info to stdout, and whether or not to
+    #     the stdout and stderr streams of the child process (unless explictly redirected via :spawn_options)
+    # @option options [Hash] :spawn_options Options to pass to Process#spawn.
+    def initialize(options={})
+      options= {env: {}, quiet: false, spawn_options: {}}.merge(options)
+      options[:spawn_options][:in] ||= '/dev/null'
+      options.each {|k,v| send "#{k}=", v}
+    end
+
+    # Starts the child process.
+    #
+    # If it is already running, then this will do nothing.
+    #
+    # @return @self@
+    def startup
+      unless alive?
+        opt= self.spawn_options
+        if quiet?
+          opt= opt.dup
+          mute= [:out,:err] - opt.keys.flatten
+          mute.each {|fd| opt[fd] ||= '/dev/null'}
+        end
+        unless quiet?
+          e= ''
+          env.each{|k,v| e+="#{k}=#{v} "} if env
+          puts "> #{e}#{start_command}"
+        end
+        @pid= spawn env, start_command, opt
+        Process.detach @pid
+        puts "< Spawned process #@pid" unless quiet?
+      end
+      self
+    end
+
+    # Stops the child process.
+    #
+    # If it is already running, then this will do nothing.
+    #
+    # @return [Boolean] Boolean indicating whether shutdown was successful and process is down.
+    def shutdown
+      if alive?
+        t= Thread.new{ attempt_kill }
+        if quiet?
+          t.join
+        else
+          puts "Stopping process #@pid..."
+          t.join
+        end
+      end
+      !alive?
+    end
+
+    # Checks if the process [*previously started by this class*] is still alive.
+    #
+    # If it is determined that the process is no longer alive then the internal {#pid PID} is cleared.
+    #
+    # @return [Boolean]
+    def alive?
+      return false if @pid.nil?
+      alive= begin
+          Process.getpgid(@pid) != -1
+        rescue Errno::ESRCH
+          false
+        end
+      @pid= nil unless alive
+      alive
+    end
+
+    protected
+
+    def kill_signals
+      [
+        ['TERM', 6],
+        ['QUIT', 6],
+        ['INT' , 6],
+        ['KILL', 1],
+      ]
+    end
+
+    private
+
+    def attempt_kill
+      kill_signals.each do |signal, wait_time|
+        Process.kill(signal, @pid)
+        start_time= Time.now
+        sleep 0.1 while alive? and (Time.now - start_time) < wait_time
+        break unless alive?
+      end
+      if alive?
+        STDERR.puts "Failed to kill process, PID #@pid"
+      end
+    end
+
+    # --------------------------------------------------------------------------------------------------------------------
+    class << self
+      OPTION_TRANSLATION= {
+        stdout: :out,
+        stderr: :err,
+        stdin: :in,
+      }.freeze
+
+      def translate_options(prefix='')
+        spawn_opts= {}
+        OPTION_TRANSLATION.each do |from,to|
+          if v= ENV["#{prefix}#{from}"] and !v.empty?
+            spawn_opts[to]= v
+          end
+        end
+        spawn_opts
+      end
+    end
+
+  end
+end

data/lib/golly-utils/colourer.rb

@@ -0,0 +1,50 @@
+module GollyUtils
+
+  # Helps decorate text with ANSI colour codes.
+  class Colourer
+    attr_reader :output
+
+    # @param output The target IO object that text will be written to.
+    def initialize(output)
+      @output= output
+    end
+
+    def color_enabled?
+      @color ||= output_to_tty?
+    end
+
+    def color_enabled=(bool)
+      # Ungracefully ripped out of RSpec.
+      return unless bool
+      @color = true
+      if bool && ::RbConfig::CONFIG['host_os'] =~ /mswin|mingw/
+        unless ENV['ANSICON']
+          warn "You must use ANSICON 1.31 or later (http://adoxa.110mb.com/ansicon/) to use colour on Windows"
+          @color = false
+        end
+      end
+    end
+
+    # Wraps text in a given colour code (with a colour-clear code on the end) if colours are enabled.
+    # @return [String]
+    def add_color(text, color_code)
+      color_enabled? ? "#{color_code}#{text}\e[0m" : text
+    end
+
+    # Calls `puts` on the output stream with optionally coloured text.
+    def puts(text, color_code)
+      output.puts add_color(text, color_code)
+    end
+
+    private
+
+    def output_to_tty?
+      begin
+        output.tty?
+      rescue NoMethodError
+        false
+      end
+    end
+
+  end
+end

data/lib/golly-utils/delegator.rb

@@ -0,0 +1,81 @@
+module GollyUtils
+
+  # An object that delegates method calls to eligible delegate objects.
+  class Delegator
+    attr_reader :delegate_to
+
+    # @overload initialize(*delegates, options={})
+    #   @param [Object] delegates Objects that method calls may be delegated to.
+    #   @param [Hash] options
+    #   @option options [true,false] :cache (true) Whether or not to maintain a cache of which delegate objects can
+    #       respond to each method call.
+    #   @option options [:first,:all] :delegate_to (:first) When multiple delegates can respond to a method call, this
+    #       setting determines which object(s) are delegated to.
+    #   @option options [String, Symbol, Regexp, Array] :method_whitelist Method name matcher(s) that specify which
+    #       methods are allowed to be delegated.
+    #   @option options [String, Symbol, Regexp, Array] :method_blacklist Method name matcher(s) that specify methods
+    #       that are not allowed to be delegated.
+    def initialize(*args)
+      options= args.last.kind_of?(Hash) ? args.pop.clone : {}
+      @original_options= options
+
+      @delegates= args
+      @delegate_to= options[:delegate_to] || :first
+      @cache= {} unless options.has_key?(:cache) && !options[:cache]
+      parse_method_delegation_option options, :method_whitelist
+      parse_method_delegation_option options, :method_blacklist
+    end
+
+    def dup;   Delegator.new @delegates.map(&:dup),   @original_options end
+    def clone; Delegator.new @delegates.map(&:clone), @original_options end
+
+    def method_missing(method, *args)
+      matches= delegates_that_respond_to(method)
+      return super(method,*args) if matches.empty?
+
+      case delegate_to
+      when :first
+        matches[0].public_send(method,*args)
+      when :all
+        matches.map{|m| m.public_send(method,*args)}
+      else
+        raise "Don't know how to respond to :delegate_to value of #{delegate_to.inspect}"
+      end
+    end
+
+    def respond_to?(method)
+      !delegates_that_respond_to(method).empty?
+    end
+
+    private
+
+    def parse_method_delegation_option(options, name)
+      if values= options[name]
+        methods= [values].flatten.compact.map{|m| m.is_a?(String) ? m.to_sym : m}.uniq
+        instance_variable_set :"@#{name}", methods
+      end
+    end
+
+    def delegates_that_respond_to(method)
+      delegation_cache(method){ uncached_delegates_that_respond_to(method) }
+    end
+
+    NO_MATCHES= [].freeze
+    def uncached_delegates_that_respond_to(method)
+      return NO_MATCHES unless @delegates # i.e. not initialised yet, e.g. missing method before super() called in subclass
+      return NO_MATCHES if @method_whitelist && !@method_whitelist.any?{|m| m === method}
+      return NO_MATCHES if @method_blacklist && @method_blacklist.any?{|m| m === method}
+      r= @delegates.select{|d| d.respond_to?(method)}
+      r.empty? ? NO_MATCHES : r
+    end
+
+    # Don't allow nil values
+    def delegation_cache(key)
+      if @cache
+        @cache[key] ||= yield
+      else
+        yield
+      end
+    end
+  end
+end

data/lib/golly-utils/multi_io.rb

@@ -0,0 +1,13 @@
+require 'golly-utils/delegator'
+
+module GollyUtils
+
+  # A fake IO implmentation that writes data to multiple underlying IO objects.
+  class MultiIO < Delegator
+
+    # @param targets Real IO objects.
+    def initialize(*targets)
+      super *targets, delegate_to: :all
+    end
+  end
+end

data/lib/golly-utils/ruby_ext.rb

@@ -0,0 +1,2 @@
+Dir[File.expand_path("../ruby_ext",__FILE__) + '/**/*.rb'].each {|f| require f}
+

data/lib/golly-utils/ruby_ext/array_to_hash.rb

@@ -0,0 +1,29 @@
+class Array
+
+  # Converts the array to a hash where the values are the array elements and the keys are provided by calling a given
+  # block.
+  #
+  # @example
+  #   ['m','abc'].to_hash_keyed_by{ |v| v.length }       # => {1 => 'm', 3 => 'abc}
+  def to_hash_keyed_by(raise_on_duplicate_keys=true, &key_provider)
+    h= {}
+    each {|e|
+      k= key_provider.call(e)
+      raise "Duplicate key: #{k.inspect}" if raise_on_duplicate_keys and h.has_key?(k)
+      h[k]= e
+    }
+    h
+  end
+
+  # Converts the array to a hash where the keys are the array elements and the values are provided by either calling a
+  # given block, or using a fixed, provided argument.
+  #
+  # @example
+  #   [2,5].to_hash_with_values('x')                 # => {2 => 'x', 5 => 'x'}
+  #   [2,5].to_hash_with_values{ |k| 'xo' * k }      # => {2 => 'xoxo', 5 => 'xoxoxoxoxo'}
+  def to_hash_with_values(value=nil)
+    h= {}
+    each {|e| h[e]= block_given? ? yield(e) : value}
+    h
+  end
+end

data/lib/golly-utils/ruby_ext/deep_dup.rb

@@ -0,0 +1,33 @@
+class Object
+  # Creates a deep copy of the object. Where supported (arrays and hashes by default), object state will be duplicated
+  # and used, rather than the original and duplicate objects sharing the same state.
+  def deep_dup
+    dup
+  end
+end
+
+class Array
+  # Creates a copy of the array with deep copies of each element.
+  #
+  # @see Object#deep_dup
+  def deep_dup
+    map(&:deep_dup)
+  end
+end
+
+class Hash
+  # Creates a copy of the hash with deep copies of each key and value.
+  #
+  # @see Object#deep_dup
+  def deep_dup
+    duplicate = {}
+    each_pair do |k,v|
+      duplicate[k.deep_dup]= v.deep_dup
+    end
+    duplicate
+  end
+end
+
+[TrueClass, FalseClass, NilClass, Symbol, Numeric].each do |klass|
+  klass.class_eval "def deep_dup; self end"
+end

data/lib/golly-utils/ruby_ext/env_helpers.rb

@@ -0,0 +1,27 @@
+module GollyUtils
+  module EnvHelpers
+
+    def boolean(key, default=nil)
+      return default unless self.has_key?(key)
+      v= self[key]
+      return true if v =~ /^\s*(?:[1yt]|yes|true|on|enabled?)\s*$/i
+      return false if v =~ /^\s*(?:[0nf]|no|false|off|disabled?)\s*$/i
+      STDERR.puts "Unable to parse boolean value #{v.inspect} for key #{key.inspect}."
+      default
+    end
+
+    alias yes? boolean
+    alias on? boolean
+    alias enabled? boolean
+
+    def no?(key, default=nil)
+      !boolean(key, default)
+    end
+    alias off? no?
+    alias disabled? no?
+
+  end
+end
+
+# Add helpers to ENV
+ENV.send :extend, GollyUtils::EnvHelpers