golly-utils 0.0.1 → 0.6.0

data/lib/golly-utils/callbacks.rb

@@ -1,22 +1,158 @@
 require 'golly-utils/ruby_ext/deep_dup'
+require 'golly-utils/delegator'
 
 module GollyUtils
+  # A very simple callback mechanism for use within a single class heirarchy.
+  #
+  # It is primiarily meant to be used as a replacement for method overriding in external subclasses; the problem with
+  # that approach being a) it's unclear with methods are required/overrides, and b) if the wrong method name is used
+  # there is no early feedback - the erronously named method will simply never be invoked and the super-method will not
+  # receive the intended modification.
+  #
+  # It allows:
+  #
+  # 1. A class to define named callback point.
+  # 2. Subclasses to supply callbacks to specific points by name.
+  # 3. Ability to run all callbacks for a given callback point.
+  #
+  # Unlike Rails' callbacks implementation, this deliberately doesn't provide before/after/around functionality, nor a
+  # chain-like structure where the return value of one callback can affect the determinism of other callbacks being
+  # invoked.
+  #
+  # ## Usage
+  #
+  # * In your superclass:
+  #   1. Include {Callbacks}.
+  #   2. Use {ClassMethods#define_callbacks} in the class definition.
+  #   3. Call {InstanceMethods#run_callbacks} in your code.
+  # * In subclasses:
+  #   1. Supply a callback by declaring the callback name in the class definition, followed by a block of code.
+  #
+  # @example
+  #   class Engine
+  #     include GollyUtils::Callbacks
+  #
+  #     define_callback :start
+  #
+  #     def start
+  #       puts "About to start..."
+  #       run_callbacks :start
+  #       puts "Running."
+  #     end
+  #   end
+  #
+  #   class CustomEngine < Engine
+  #     start do
+  #       puts "---> STARTING!!!"
+  #     end
+  #   end
+  #
+  #   CustomEngine.new.start    # => About to start...
+  #                             # => ---> STARTING!!!
+  #                             # => Running.
+  #
+  # @example Also works in modules
+  #   module SupportsStuff
+  #     include GollyUtils::Callbacks
+  #     define_callback :stuff
+  #   end
+  #
+  #   class DoerOfStuff
+  #     include SupportsStuff
+  #     stuff{ puts 'Doing stuff!!' }
+  #   end
+  #
+  #   def stuff_machine(anything_that_supports_stuff)
+  #     puts "I'll take anything that SupportsStuff."
+  #     anything_that_supports_stuff.run_callbacks :stuff
+  #     puts "See!"
+  #   end
+  #
+  #   stuff_machine DoerOfStuff.new  # => I'll take anything that SupportsStuff.
+  #                                  # => Doing stuff!!
+  #                                  # => See!
   module Callbacks
 
+    # @!visibility private
     def self.included(base)
-      base.send :include, InstanceMethods
-      base.send :include, InstanceAndClassMethods
-      base.extend InstanceAndClassMethods
-      base.extend ClassMethods
+      if base.is_a?(Class)
+        base.send :include, InstanceMethods
+        base.extend ClassMethods
+      else
+        base.extend ModuleMethods
+        base.class_eval <<-EOB
+        class << self
+          alias :included_without_gu_callbacks :included
+          def included(base)
+            included_without_gu_callbacks(base)
+            __add_callbacks_when_included(base)
+          end
+        end
+        EOB
+      end
+    end
+
+    # @!visibility private
+    def self.__norm_callback_key(key)
+      key.to_sym
+    end
+
+    #-------------------------------------------------------------------------------------------------------------------
+
+    # Provides methods that can be run within definitions of modules that include {Callbacks}.
+    module ModuleMethods
+
+      # Create one or more callback points that will be added to classes that include the enclosing module.
+      #
+      # @param (see GollyUtils::Callbacks::ClassMethods#define_callbacks)
+      # @return [true]
+      def define_callbacks(*callbacks)
+        __module_callback_names.concat callbacks
+        __module_callback_names.uniq!
+        true
+      end
+      alias :define_callback :define_callbacks
+
+      # Returns a list of all callbacks available to this module. (i.e. defined, inherited, and included.)
+      #
+      # @return [Array<Symbol>] Callback names.
+      def callbacks
+        c= __module_callback_names
+        included_modules.each {|m|
+          c.concat m.callbacks if m.respond_to? :callbacks
+        }
+        c.uniq.sort_by(&:to_s)
+      end
+
+      private
+      def __add_callbacks_when_included(base)
+        base.send :include, Callbacks
+        names= __module_callback_names
+        unless names.empty?
+          base.class_eval "define_callbacks *#{names.inspect}"
+        end
+      end
+
+      def __module_callback_names
+        @__module_callbacks ||= []
+      end
     end
 
     #-------------------------------------------------------------------------------------------------------------------
 
+    # Provides methods that can be run within definitions of classes that include {Callbacks}.
     module ClassMethods
 
+      # Create one or more callback points for this class and its children.
+      #
+      # @param [Array<String|Symbol>] callbacks The callback name(s).
+      # @return [true]
+      # @raise If the callback has already been defined, or a method with that name already exists.
+      # @see Callbacks
+      # @see InstanceMethods#run_callbacks
       def define_callbacks(*callbacks)
         callbacks.each do |name|
-          name= _norm_callback_key(name)
+          name= ::GollyUtils::Callbacks.__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."
@@ -30,9 +166,19 @@ module GollyUtils
             end
           EOB
         end
+        true
       end
       alias :define_callback :define_callbacks
 
+      # Returns a list of all callbacks available to this class. (i.e. defined, inherited, and included.)
+      #
+      # @return [Array<Symbol>] Callback names.
+      def callbacks
+        c= superclass.respond_to?(:callbacks) ? superclass.callbacks : []
+        c.concat _callbacks.keys
+        c.uniq.sort_by(&:to_s)
+      end
+
       private
 
       def _callbacks
@@ -63,29 +209,75 @@ module GollyUtils
 
     #-------------------------------------------------------------------------------------------------------------------
 
-    module InstanceAndClassMethods
+    # Provides methods that are available to instances of classes that include {Callbacks}.
+    module InstanceMethods
 
-      private
-      def _norm_callback_key(key)
-        key.to_sym
-      end
+      # Run all callbacks provided for a single callback point.
+      #
+      # @param [String, Symbol] callback The callback name.
+      # @param [Hash] options
+      # @option options [Array] args ([]) Arguments to pass to the callbacks.
+      # @option options [nil|Object] context (nil) If provided, code within callbacks will have access to methods
+      #   available from the provided object.
+      # @return [true]
+      # @raise If the provided callback name hasn't been declared for this class.
+      # @raise If unrecognised or invalid options are provided.
+      # @see Callbacks
+      # @see ClassMethods#define_callbacks
+      def run_callback(callback, options={})
 
-    end
+        # Validate callback name
+        name= ::GollyUtils::Callbacks.__norm_callback_key(callback)
+        name_verified,callback_procs = self.class.send :_get_callback_procs, name
+        raise "There is no callback defined with name #{name}." unless name_verified
 
-    #-------------------------------------------------------------------------------------------------------------------
+        # Validate options
+        invalid_options= options.keys - RUN_CALLBACKS_OPTIONS
+        unless invalid_options.empty?
+          raise "Unable to recognise options: #{invalid_options.map(&:inspect).sort}"
+        end
+        args= options[:args] || []
+        raise "The :args option must provide an array. Invalid: #{args}" unless args.is_a?(Array)
 
-    module InstanceMethods
+        # Run callback
+        callback_procs.each{|cb|
+          if ctx= options[:context]
+            dlg= GollyUtils::Delegator.new self, ctx, delegate_to: :first, allow_protected: true
+            dlg.instance_eval &cb
+          else
+            cb.call *args
+          end
+        }
+
+        true
+      end
 
+      # Run all callbacks provided for one or more callback points.
+      #
+      # @overload run_callbacks(*callbacks, options = {})
+      #   @param [Array<String, Symbol>] callbacks The callback name(s).
+      #   @param [Hash] options
+      #   @option options [Array] args ([]) Arguments to pass to the callbacks.
+      #   @option options [nil|Object] context (nil) If provided, code within callbacks will have access to methods
+      #     available from the provided object.
+      # @return [true]
+      # @raise If one of the provided callback names hasn't been declared for this class.
+      # @raise If unrecognised or invalid options are provided.
+      # @see Callbacks
+      # @see ClassMethods#define_callbacks
       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 }
+        options= callbacks.last.is_a?(Hash) ? callbacks.pop : {}
+
+        # Run callbacks
+        callbacks.each do |callback|
+          run_callback callback, options
         end
+
         true
       end
-      alias :run_callback :run_callbacks
+
+      # @!visibility private
+      RUN_CALLBACKS_OPTIONS= [:args, :context].freeze
 
     end
   end

data/lib/golly-utils/child_process.rb

@@ -2,15 +2,33 @@ module GollyUtils
 
   # Start, manage, and stop a child process.
   class ChildProcess
-    attr_accessor :start_command, :quiet, :spawn_options, :env
-    attr_reader :pid
+
+    # The shell command to start the child process.
+    # @return [String]
+    attr_accessor :start_command
+
+    # 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)
+    # @return [Boolean]
+    attr_accessor :quiet
     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.
+    # Options to pass to `Process#spawn`.
+    # @return [Hash]
+    attr_accessor :spawn_options
+
+    # Environment variables to set in the child process.
+    # @return [Hash]
+    attr_accessor :env
+
+    # The PID of the child process if running.
+    # @return [Fixnum, nil]
+    attr_reader :pid
+
+    # @option options [String] :start_command See {#start_command}.
+    # @option options [Hash] :env See {#env}.
+    # @option options [Boolean] :quiet (false) See {#quiet}.
+    # @option options [Hash] :spawn_options See {#spawn_options}.
     def initialize(options={})
       options= {env: {}, quiet: false, spawn_options: {}}.merge(options)
       options[:spawn_options][:in] ||= '/dev/null'
@@ -21,7 +39,7 @@ module GollyUtils
     #
     # If it is already running, then this will do nothing.
     #
-    # @return @self@
+    # @return [self]
     def startup
       unless alive?
         opt= self.spawn_options
@@ -103,12 +121,14 @@ module GollyUtils
 
     # --------------------------------------------------------------------------------------------------------------------
     class << self
+      # @!visibility private
       OPTION_TRANSLATION= {
         stdout: :out,
         stderr: :err,
         stdin: :in,
       }.freeze
 
+      # @!visibility private
       def translate_options(prefix='')
         spawn_opts= {}
         OPTION_TRANSLATION.each do |from,to|

data/lib/golly-utils/delegator.rb

@@ -7,6 +7,8 @@ module GollyUtils
     # @overload initialize(*delegates, options={})
     #   @param [Object] delegates Objects that method calls may be delegated to.
     #   @param [Hash] options
+    #   @option options [true,false] :allow_protected (false) Whether or not to allow calls to protected methods in
+    #       delegates.
     #   @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
@@ -22,6 +24,7 @@ module GollyUtils
       @delegates= args
       @delegate_to= options[:delegate_to] || :first
       @cache= {} unless options.has_key?(:cache) && !options[:cache]
+      @allow_protected= options[:allow_protected]
       parse_method_delegation_option options, :method_whitelist
       parse_method_delegation_option options, :method_blacklist
     end
@@ -35,20 +38,28 @@ module GollyUtils
 
       case delegate_to
       when :first
-        matches[0].public_send(method,*args)
+        delegate_call matches[0], method, args
       when :all
-        matches.map{|m| m.public_send(method,*args)}
+        matches.map{|m| delegate_call m, 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?
+      super(method) or !delegates_that_respond_to(method).empty?
     end
 
     private
 
+    def delegate_call(target, method, args)
+      if @allow_protected and target.protected_methods.include?(method)
+        target.send method, *args
+      else
+        target.public_send method, *args
+      end
+    end
+
     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

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

@@ -0,0 +1,120 @@
+class Class
+
+  # @!visibility private
+  def inherited other
+    super if defined? super
+  ensure
+    ( @subclasses ||= [] ).push(other).uniq!
+  end
+
+  # Returns a list of classes that extend this class, directly or indirectly (as in subclasses of subclasses).
+  #
+  # @example
+  #   # Given the following class heirarchy:
+  #   #   A
+  #   #   |
+  #   #   +--B
+  #   #   |  +--B1
+  #   #   |  +--B2
+  #   #   |
+  #   #   +--C
+  #
+  #   A.subclasses         # => [B1, B2, C]
+  #   A.subclasses(false)  # => [B1, B2, C]
+  #   A.subclasses(true)   # => [B, B1, B2, C]
+  #
+  # @param include_subclassed_nodes If `true` then classes extended by other classes are returned. If `false` then you
+  #     only get the end nodes.
+  # @return [Array<Class>] An array of all subclasses.
+  def subclasses(include_subclassed_nodes = false)
+    @subclasses ||= []
+    classes= @subclasses.inject( [] ) {|list, subclass| list.push subclass, *subclass.subclasses }
+    classes.reject! {|c| classes.any?{|i| c != i and c.subclasses.include?(i) }} unless include_subclassed_nodes
+    classes
+  end
+end
+
+class Object
+  # Returns the class hierarchy of a given instance or class.
+  #
+  # @example
+  #   Fixnum.superclasses  # <= [Fixnum, Integer, Numeric, Object, BasicObject]
+  #   100.superclasses     # <= [Fixnum, Integer, Numeric, Object, BasicObject]
+  #
+  # @return [Array<Class>] An array of classes starting with the current class, descending to `BasicObject`.
+  def superclasses
+    if self == BasicObject
+      [self]
+    elsif self.is_a? Class
+      [self] + self.superclass.superclasses
+    else
+      self.class.superclasses
+    end
+  end
+
+  # Indicates that a type validation check has failed.
+  class TypeValidationError < RuntimeError
+  end
+
+  # Validates the type of the current object.
+  #
+  # @example
+  #     3     .validate_type nil, Numeric
+  #     nil   .validate_type nil, Numeric
+  #     'What'.validate_type nil, Numeric   # <= raises TypeValidationError
+  #
+  #     # Ensures that f_debug is boolean
+  #     f_debug.validate_type! 'the debug flag', true, false
+  #
+  # @overload validate_type!(name = nil, *valid_classes)
+  #   @param [nil|Symbol|String] name The name of the object being checked (i.e. `self`).
+  #     This only used in the error message and has no functional impact.
+  #   @param [Array<Class>] valid_classes One or more classes that this object is allowed to be. Ruby primatives will
+  #     automatically be translated to the corresponding class.
+  # @return [self] If validation passes.
+  # @raise [TypeValidationError] If validation fails.
+  # @see Symbol#validate_lvar_type!
+  def validate_type!(*args)
+    name= args.first.is_a?(String) || args.first.is_a?(Symbol) ? args.shift : nil
+    classes= args.map{|a| RUBY_PRIMATIVE_CLASSES[a] || a }
+    raise "You must specify at least one valid class." if classes.empty?
+
+    unless classes.any?{|c| self.is_a? c }
+      for_name= name ? " for #{name}" : ''
+      raise TypeValidationError, "Invalid type#{for_name}: #{self.class}\nValid types are: #{classes.map(&:to_s).sort.join ', '}."
+    end
+    self
+  end
+
+
+  # @!visibility private
+  RUBY_PRIMATIVE_CLASSES= Hash[ [nil,true,false].map{|p|[p,p.class]} ].freeze
+end
+
+class Symbol
+  # Validates the type of a local variable.
+  #
+  # @example
+  #   def save_person(name, eyes)
+  #     # Validate args
+  #     :name.validate_lvar_type!{ String }
+  #     :eyes.validate_lvar_type!{ [nil,Fixnum] }
+  #
+  #     # Do other stuff
+  #     # ...
+  #   end
+  #
+  # @yield Calls a given block once to get the list of valid classes. The block must have access to the local variable.
+  # @yieldreturn [Class|Array<Class>] The given block should return one or more classes.
+  # @return [true] If validation passes.
+  # @raise [TypeValidationError] If validation fails.
+  # @see Object#validate_type!
+  def validate_lvar_type!(&block)
+    name= self
+    raise "You must provide a block that returns one or more valid classes for #{name}." unless block
+    classes= [block.()].flatten
+    v= block.send(:binding).eval(name.to_s)
+    v.validate_type! name, *classes
+    true
+  end
+end