rake-commander 0.1.4 → 0.2.0

data/examples/libs/shell_helpers.rb

@@ -0,0 +1,81 @@
+module Examples
+  module Libs
+    module ShellHelpers
+      SHELL_METHODS = %I[system back_quotes x spawn exec fork_exec pipe].freeze
+
+      # https://stackoverflow.com/a/37329716/4352306
+      def shell(cmd, method: :system)
+        method = method.to_sym
+        case method
+        when :system
+          success = system(cmd)
+          puts "* #{success ? "Succeded in" : "Failed to"} running '#{cmd}'"
+        when :back_quotes, :x
+          result = `#{cmd}`
+          puts result
+          #%x(#{cmd})
+        when :spawn # like Kernel.system but with no wait
+          pid = Process.spawn(cmd)
+          puts "* new child process (pid: #{pid}). Will wait..."
+          Process.wait(pid)
+          puts "* child process finished (pid: #{pid})"
+        when :exec
+          exec cmd
+          # Flow does not reach here
+        when :fork_exec
+          for_exec(cmd)
+        when :pipe # I/O of new process
+          pipe(cmd)
+        else
+          raise "* unknown shell method '#{method}'"
+        end
+      end
+
+      def fork_exec(cmd)
+        pid = fork do
+          shell(cmd, method: :exec)
+        end
+        puts "* new child process (pid: #{pid})"
+      rescue NotImplementedError => e
+        puts e
+        puts "Redirecting to 'spawn'"
+        shell(cmd, method: :spawn)
+      end
+
+      def pipe(cmd)
+        IO.popen(host_shell_command, 'r+') do |pipe|
+          puts "* new child process (pid: #{pipe.pid})"
+          prompt = pipe_prompt(pipe)
+          pipe.puts cmd
+          pipe.close_write # prevent `gets` to get stuck
+          lines = pipe.readlines
+          if index = lines.index {|ln| ln.include?(cmd)}
+            lines = lines[index+1..]
+          end
+          lines.reject! {|ln| ln.start_with?(prompt)}
+          lines = lines.map {|ln| ">> (pid: #{pipe.pid}) #{ln}"}
+          puts lines
+        end
+      end
+
+      # Changes the commandline prompt, so we can discard those.
+      def pipe_prompt(pipe, prompt: ':>$ ')
+        if Gem::Platform.local.os == "mingw32"
+          pipe.puts "function prompt {\"#{prompt}\"}"
+        else
+          pipe.puts "PS1=\"#{prompt}\""
+        end
+        prompt
+      end
+
+      # Command to open a new shell for `pipe`
+      def host_shell_command
+        if Gem::Platform.local.os == "mingw32"
+          "powershell -noprofile -noninteractive"
+        else
+          'sh'
+        end
+      end
+    end
+  end
+end

data/lib/rake-commander/base/class_auto_loader.rb

@@ -25,17 +25,25 @@ class RakeCommander
       end
 
       # To restrict which namespaces it is allowed to load from
+      # @note this deletes from the `:ignore` namespaces
       def autoload_namespace(*namespaces)
         _autoload_namespace(:include, *namespaces)
       end
 
       # To ignore certain namespaces this class should not autoload from
+      # @note this deletes from the `:include` namespaces
       def autoload_namespace_ignore(*namespaces)
         _autoload_namespace(:ignore, *namespaces)
       end
 
+      # Applies a change to the `autoloaded_namespaces`
       def _autoload_namespace(type, *namespaces)
-        autoloaded_namespaces(type).concat(namespaces) unless namespaces.empty?
+        autoloaded_namespaces(type).tap do |target|
+          next if namespaces.empty?
+          other_type = type == :include ? :ignore : :include
+          namespaces.each {|nm_sp| autoloaded_namespace(other_type).delete(nm_sp)}
+          target.concat(namespaces)
+        end
       end
 
       # @param constant [Class, String] a class or namespace we want to check auto-load entitlement thereof.
@@ -61,14 +69,36 @@ class RakeCommander
         @autoloaded_children ||= []
       end
 
+      # Keep track on actual children that have been ignored by `autoload_namespace_ignore`.
+      def ignored_children
+        @ignored_children ||= []
+      end
+
+      # Allows to reload
+      # @note it may be handy some times.
+      def clear_autoloaded_children
+        forget_class!(*autoloaded_children, *ignored_children)
+        @ignored_children    = []
+        @autoloaded_children = []
+      end
+
+      # Prevents already excluded children to enter into the loop again.
+      def excluded_children
+        @excluded_children ||= []
+      end
+
       # Children classes of `autoloader_class` that have not been created an instance of.
       def unloaded_children
         return [] unless autoloaded_class
         new_detected = new_classes
         known_class!(*new_detected)
         descendants(parent_class: autoloaded_class, scope: new_detected).select do |child_class|
-          !autoloaded_children.include?(child_class) && autoload_class?(child_class)
-        end.sort
+          !autoloaded_children.include?(child_class) && \
+            !excluded_children.include?(child_class) && \
+            autoload_class?(child_class).tap do |ignored|
+              ignored_children.push(child_class) if ignored
+            end
+        end
       end
 
       # It loads/creates a new instance of children classes pending to be loaded.
@@ -79,14 +109,15 @@ class RakeCommander
         return false if pending_children.empty?
         @loading_children = true
         pending_children.each do |klass|
-          child = object ? klass.new(object) : klass.new
+          exclude = false
+          child   = object ? klass.new(object) : klass.new
           yield(child) if block_given?
-
         rescue TypeError
           # Can't create from this class (must be the singleton class)
-          # Just ignore
+          exclude = true
+          excluded_children.push(klass)
         ensure
-          autoloaded_children.push(klass)
+          autoloaded_children.push(klass) unless exclude
         end
         @loading_children = false
         true
@@ -101,6 +132,13 @@ class RakeCommander
       # Add to known namespaces
       def known_class!(*classes)
         known_classes.concat(classes)
+        self
+      end
+
+      # Forget namespaces
+      def forget_class!(*classes)
+        @known_classes = known_classes - classes
+        self
       end
 
       # List all new namespaces

data/lib/rake-commander/base/class_helpers.rb

@@ -1,7 +1,7 @@
 class RakeCommander
   module Base
     module ClassHelpers
-      NOT_USED = 'no_used!'.freeze
+      NOT_USED = :not_used!
 
       # Helper to determine if a paramter has been used
       # @note to effectivelly use this helper, you should initialize your target
@@ -65,15 +65,6 @@ class RakeCommander
         end.join("")
       end
 
-      # Helper to create an instance variable `name`
-      # @param [String, Symbol] the name of the variable
-      # @reutrn [String] the name of the created instance variable
-      def instance_variable_name(name)
-        str = name.to_s
-        str = "@#{str}" unless str.start_with?("@")
-        str
-      end
-
       # If the class for `name` exists, it returns it. Otherwise it generates it.
       # @param name [String, Symbol] the name of the new class
       # @param inherits [Class] the parent class to _inherit_ from
@@ -95,6 +86,16 @@ class RakeCommander
         end
       end
 
+      # @param klasses [Arrary<Class>] the classes to sort.
+      # @return [Arrary<Class>] the classes in hierarchy order.
+      def sort_classes(*klasses)
+        klasses.sort do |k_1, k_2|
+          next -1 if k_2 < k_1
+          next  1 if k_1 < k_2
+          0
+        end
+      end
+
       # Finds all child classes of the current class.
       # @param parent_class [Class] the parent class we want to find children of.
       # @param direct [Boolean] it will only include direct child classes.
@@ -103,18 +104,11 @@ class RakeCommander
       def descendants(parent_class: self, direct: false, scope: nil)
         scope ||= ObjectSpace.each_object(::Class)
         return [] if scope.empty?
-        scope.select do |klass|
-          klass < parent_class
-        end.sort do |k_1, k_2|
-          next -1 if k_2 < k_1
-          next  1 if k_1 < k_2
-          0
-        end.tap do |siblings|
-          if direct
-            siblings.reject! do |si|
-              siblings.any? {|s| si < s}
-            end
-          end
+        siblings = scope.select {|klass| klass < parent_class}
+        siblings = sort_classes(*siblings)
+        return siblings unless direct
+        siblings.reject! do |si|
+          siblings.any? {|s| si < s}
         end
       end
 
@@ -124,45 +118,6 @@ class RakeCommander
       def descendants?(parent_class: self, direct: false)
         !descendants(parent_class: parent_class, direct: direct).empty?
       end
-
-      # Keeps track on class instance variables that should be inherited by child classes.
-      # @note
-      #   - subclasses will inherit the value as is at that moment
-      #   - any change afterwards will be only on the specific class (in line with class instance variables)
-      #   - adapted from https://stackoverflow.com/a/10729812/4352306
-      # TODO: this separates the logic of the method to the instance var. Think if would be possible to join them somehow.
-      def inheritable_class_vars(*vars)
-        @inheritable_class_vars ||= [:inheritable_class_vars]
-        @inheritable_class_vars += vars
-      end
-
-      # Builds the attr_reader and attr_writer of `attrs` and registers the associated instance variable as inheritable.
-      def inheritable_attrs(*attrs, add_accessors: false)
-        if add_accessors
-          attrs.each do |attr|
-            class_eval <<-RUBY, __FILE__, __LINE__ + 1
-              class << self; attr_accessor :#{attr} end
-            RUBY
-          end
-        end
-        inheritable_class_vars(*attrs)
-      end
-
-      # This callback method is called whenever a subclass of the current class is created.
-      # @note
-      #   - values of the instance variables are copied as they are (no dups or clones)
-      #   - the above means: avoid methods that change the state of the mutable object on it
-      #   - mutating methods would reflect the changes on other classes as well
-      #   - therefore, `freeze` will be called on the values that are inherited.
-      def inherited(subclass)
-        super.tap do
-          inheritable_class_vars.each do |var|
-            instance_var = instance_variable_name(var)
-            value        = instance_variable_get(instance_var)
-            subclass.instance_variable_set(instance_var, value.freeze)
-          end
-        end
-      end
     end
   end
 end

data/lib/rake-commander/base/class_inheritable.rb

@@ -0,0 +1,122 @@
+class RakeCommander
+  module Base
+    module ClassInheritable
+      include RakeCommander::Base::ObjectHelpers
+
+      # Builds the attr_reader and attr_writer of `attrs` and registers the associated
+      # instance variable as inheritable.
+      # @yield [value]
+      # @yieldparam value [Variant] the value of the parent class
+      # @yieldreturn the value that will be inherited by the child class
+      # @param attrs [Array <Symbol>] the variable names that should be inheritable.
+      # @param add_accessors [Boolean] whether attr_accessor should be invoked
+      # @param deep_dup [Boolean] whether the value of the instance var should be `deep_dup`ed.
+      def attr_inheritable(*attrs, add_accessors: false, deep_dup: true, &block)
+        attrs = attrs.map(&:to_sym)
+        inheritable_class_var(*attrs, deep_dup: deep_dup, &block)
+        return unless add_accessors
+        attrs.each do |attr|
+          class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            class << self; attr_accessor :#{attr} end
+          RUBY
+        end
+        self
+      end
+
+      # @return [Boolean] whether an `var` has been declared as inheritable
+      def inheritable_class_var?(var)
+        inheritable_class_var.any? do |_method, definitions|
+          definitions.key?(var.to_sym)
+        end
+      end
+
+      # Removes from the inheritance some class variables.
+      # @param attrs [Array <Symbol>] the instance variable names of the class
+      #   that should NOT be inheritable.
+      def attr_not_inheritable(*attrs)
+        attrs.each do |attr|
+          next unless method = inheritable_class_var_method(attr)
+          inheritable_class_var[method].delete(attr)
+        end
+        self
+      end
+
+      private
+
+      # This callback method is called whenever a subclass of the current class is created.
+      def inherited(subclass)
+        super.tap do
+          inheritable_class_var.each do |method, definitions|
+            definitions.each do |var, action|
+              instance_var = instance_variable_name(var)
+              value        = instance_variable_get(instance_var)
+              child_value  = inherited_class_value(value, method, action)
+              subclass.instance_variable_set(instance_var, child_value)
+            end
+          end
+        end
+      end
+
+      # @return [Variant] the value that the child class will inherit
+      def inherited_class_value(value, method, action)
+        case method
+        when :mirror
+          value
+        when :deep_dup
+          case action
+          when Proc
+            action.call(value)
+          when :default
+            custom_deep_dup(value)
+          end
+        end
+      end
+
+      # Keeps track on class instance variables that should be inherited by child classes.
+      # @note
+      #   - adapted from https://stackoverflow.com/a/10729812/4352306
+      #   - subclasses will inherit the value depending on `depep_dup` and `block` if enabled or given (respectivelly)
+      #   - any change afterwards will be only on the specific class (in line with class instance variables)
+      # @param see `#attr_inheritable`
+      # @return [Hash] methods and variables to be inherited.
+      def inheritable_class_var(*vars, deep_dup: true, &block)
+        @inheritable_class_var ||= {
+          mirror:   {},
+          deep_dup: {}
+        }.tap do |hash|
+          hash[:deep_dup][:inheritable_class_var] = :default
+        end
+        @inheritable_class_var.tap do |_methods|
+          vars.each {|var| inheritable_class_var_add(var, deep_dup: deep_dup, &block)}
+        end
+      end
+
+      # Adds var to the `inheritable_class_var`
+      # @param var [Symbol] the name of an instance variable of this class that should be inherited.
+      def inheritable_class_var_add(var, deep_dup: true, &block)
+        # Remove previous definition if present
+        attr_not_inheritable(var)
+        method = deep_dup || block ? :deep_dup : :mirror
+        inheritable_class_var[method][var] = block || :default
+        self
+      end
+
+      # @return [Symbol, NilClass]
+      def inheritable_class_var_method(var)
+        inheritable_class_var.each do |method, definitions|
+          return method if definitions.key?(var.to_sym)
+        end
+        nil
+      end
+
+      # Helper to create an instance variable `name`
+      # @param [String, Symbol] the name of the variable
+      # @return [String] the name of the created instance variable
+      def instance_variable_name(name)
+        str = name.to_s
+        str = "@#{str}" unless str.start_with?("@")
+        str
+      end
+    end
+  end
+end

data/lib/rake-commander/base/custom_error.rb

@@ -0,0 +1,52 @@
+class RakeCommander
+  module Base
+    # This class allows to use both method calls to `raise` by using additional parameters.
+    # @note Although not clearly explained, this is somehow captured here https://stackoverflow.com/a/32481520/4352306
+    class CustomError < StandardError
+      def initialize(value = nil)
+        super(@message = to_message(value)) if @value = value
+      end
+
+      # If @value was already set, ignore the latest message and
+      # just return @message
+      def to_s
+        return @message if @message
+        unclassed(super)
+      end
+
+      # If @value was already set, ignore the latest message
+      # just return @message
+      def message
+        return @message if @message
+        to_message(unclassed(super))
+      end
+
+      protected
+
+      # Any **children classes** that want to extend how `value` is transformed
+      # into a `message` **should extend this method**.
+      # @return [String] `message`
+      def to_message(value)
+        case value
+        when StandardError
+          to_message(value.message)
+        when String
+          value
+        when NilClass
+          value
+        else
+          raise ArgumentError, "Expecting String, StandardError or NilClass. Given: #{value.class}"
+        end
+      end
+
+      private
+
+      # When `value` is `nil` **methods** `to_s` and `message` return the error class of `self`.
+      # This helper allows to remove that part to know if the error was raised with `nil`
+      # @return [String]
+      def unclassed(str)
+        str.to_s.gsub(self.class.to_s, '').strip
+      end
+    end
+  end
+end

data/lib/rake-commander/base/object_helpers.rb

@@ -0,0 +1,42 @@
+class RakeCommander
+  module Base
+    module ObjectHelpers
+      private
+
+      # Custom Object#deep_dup for rake commander
+      def custom_deep_dup(value, dup_objects: true, &dup_block)
+        case value
+        when Hash
+          custom_hash_deep_dup(value, dup_objects: dup_objects, &dup_block)
+        when Array
+          value.map {|v| custom_deep_dup(v, dup_objects: dup_objects, &dup_block)}
+        else
+          custom_object_deep_dup(value, dup_objects: true, &dup_block)
+        end
+      end
+
+      # Does the copy of the final object
+      def custom_object_deep_dup(value, dup_objects: true)
+        return yield(value)   if block_given?
+        return value          unless dup_objects
+        return value.deep_dup if value.respond_to?(:deep_dup)
+        value.dup
+      end
+
+      # Custom Hash#deep_dup for rake commander
+      def custom_hash_deep_dup(original, dup_objects: true, &dup_block)
+        raise ArgumentError, "Expecting Hash. Given: #{original.class}" unless original.is_a?(Hash)
+        hash = original.dup
+        original.each_pair do |key, value|
+          unless key.frozen? && key.is_a?(::String)
+            hash.delete(key)
+            key = custom_deep_dup(key, dup_objects: dup_objects, &dup_block) if dup_objects
+          end
+          value     = dup_objects ? custom_deep_dup(value, dup_objects: dup_objects, &dup_block) : value
+          hash[key] = value
+        end
+        hash
+      end
+    end
+  end
+end

data/lib/rake-commander/base.rb

@@ -1,5 +1,8 @@
+require_relative 'base/object_helpers'
 require_relative 'base/class_helpers'
+require_relative 'base/class_inheritable'
 require_relative 'base/class_auto_loader'
+require_relative 'base/custom_error'
 require_relative 'rake_task'
 require_relative 'options'
 
@@ -8,22 +11,33 @@ class RakeCommander
     class << self
       def included(base)
         super(base)
-        base.extend RakeCommander::Base::ClassHelpers
         base.extend RakeCommander::Base::ClassAutoLoader
         base.autoloads_children_of RakeCommander
 
         base.extend ClassMethods
         base.send :include, RakeTask
-
         base.send :include, Options
         #autoload_namespace_ignore "RakeCommander::Samples"
       end
     end
 
     module ClassMethods
+      # Loads children classes by keeping a cache.
       def self_load
         autoload_children
       end
+
+      # Clears track on any auto-loaded children
+      # @note required for reload.
+      def self_load_reset
+        clear_autoloaded_children
+      end
+
+      # Clears the cache of autoloaded children classes and loads them again.
+      def self_reload
+        self_load_reset
+        autoload_children
+      end
     end
   end
 end