cli_class_tool 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bad275062a9f72ff201812eb6cd7871b9321b80b57f379f817cab483de42b738
-  data.tar.gz: e3cb70b12fe4831a4fdd194eaa4c67118efcfd9ffc0f1903524d74bdaf805e1a
+  metadata.gz: 2c2833d3bd929aa6e69df3df0cbadbbc3e92030afdbf8172387869a9ad4f95f3
+  data.tar.gz: 3bac4466f6a3d4e07bc739e36eb0eaaba2929c5a308a980715e4d0c55ef11fd7
 SHA512:
-  metadata.gz: 43cc9f0156398b92a5d1c7370c6c8c7dcf61d80e4ad9b18bec8a4a5bedceec7aa9e9af40e5d801554c7369aa746bac98c204ad949d2d27b381c4e14cbec93312
-  data.tar.gz: '0948e6f13057dd174140d84a7845c33a25e758a9ef018e10afb9c75bb734e87dffaf191e81091e01fe8c1dc9ff66437672364343d7ffc054f76cf0d591ebec1d'
+  metadata.gz: 5f8ab8e7152ade287dc0a8c50598d2069cbbd99ecbcc5d0bb9cc7fd37a8a9e3fa401a889030c3bcea9a387cb2f5ac5a8ab49ef40b78980a982355ecdcba3bd53
+  data.tar.gz: d031b3ca4da59379e5f3079ad091f10fd4934b0d1150df9f846ea2de77e1d439e236ac2070763418083394956cef64ed3f7ec2f7883222c66b14cd24e3ea9854

data/CHANGELOG

@@ -1,3 +1,22 @@
+------------------
+0.5.0  (2026-07-22)
+------------------
+
+* Support CLI_HELP_EXPAND on sub-CLIClass modules to recursively list sub-actions in parent help outputs, including support for boolean or custom string headers
+* Support recursive subcommand alias and shortcut resolution within deeply nested sub-CLIClasses
+* Add CLI_COMMAND_ALIASES support to define top-level command shortcuts/aliases to deeply-nested subcommand actions
+* Filter list_actions command output to exclude itself, preserving clean autocomplete query behavior
+* Require optparse explicitly inside utils.rb to prevent NameErrors in production environments
+* Safeguard attribute resolution and _runOnClass to gracefully default when ACTION_HELP/ACTION_LIST is missing
+* Add recursive nested subcommand and namespace auto-discovery support
+
+------------------
+0.4.1  (2026-06-05)
+------------------
+
+* Fix definition on RunError
+* In DEBUG=1 mode, run() call stack depth can be tuned with DEBUG_CALL_STACK=<n>
+
 ------------------
 0.4.0  (2026-06-05)
 ------------------

data/README.md

@@ -294,4 +294,103 @@ MyProject.run_cli(opts) do |parser, phase, action_opts|
   end
 end
 ```
+
+---
+
+## Nested CLI Subcommands (Subcommands & Recursive Routing)
+
+`CLIClassTool` natively supports nested CLI subcommands, enabling hierarchical structures of the form:
+```
+$ mytool <subcommand> <action> [options]
+$ mytool <subcommand> <sub_subcommand> <action> [options]
+```
+
+This allows you to decouple complex tools into self-contained sub-CLI components while executing them seamlessly under a single binary entry point.
+
+### 1. Auto-Discovery & Setup
+
+Any nested module or class defined within your parent CLI module that extends `CLIClassTool::Utils` is **automatically discovered** as a subcommand:
+
+```ruby
+module MyProject
+  extend CLIClassTool::Utils # Parent CLI
+
+  # 1. Nesting a subcommand module
+  module ConfigCLI
+    # Define custom subcommand help description
+    CLI_DESCRIPTION = "Manage application configurations"
+
+    # Optional: Customize the command name (defaults to "config_cli")
+    CLI_COMMAND_NAME = "config"
+
+    class ConfigError < StandardError; end
+
+    class Common < CLIClassTool::Common
+      def parent_module; ConfigCLI; end
+    end
+
+    class ConfigAction < Common
+      ACTION_LIST = [ :set_val ]
+      ACTION_HELP = { :set_val => "Set a config value" }
+
+      def set_val(opts)
+        # business logic...
+        return 0
+      end
+    end
+
+    ACTION_CLASS = [ ConfigAction ]
+    extend CLIClassTool::Utils
+  end
+end
+```
+
+### 2. Help Aggregation & Name Resolution
+
+- **Naming:** By default, subcommand trigger words are derived from the inner module/class name converted to `snake_case` (e.g., `ConfigCLI` becomes `config_cli`). Define `CLI_COMMAND_NAME = "custom_name"` on your submodule to override this behavior.
+- **Help Menus:** Nested subcommands and their descriptions (`CLI_DESCRIPTION` or `HELP` constants) are automatically collected and listed in the parent CLI's usage output under `Possible actions:`.
+- **Option Forwarding:** Global customization blocks and verbosity flags are recursively passed down to the active subcommand.
+- **Help Expansion:** By default, `--help` lists the trigger name and description of subcommands. You can declare `CLI_HELP_EXPAND = true` on a sub-CLI module to recursively list all of its individual actions directly in the parent's help menu. If `CLI_HELP_EXPAND` is a `String` (e.g., `"Config options:"`), that string will be printed as a dedicated help header separator inside the parent help menu.
+
+### 3. Command Aliases (Shortcuts)
+
+You can define command shortcuts/aliases at any CLI level by declaring a `CLI_COMMAND_ALIASES` Hash constant mapping shortcut names (symbols or strings) to subcommand/action pathways:
+
+```ruby
+module MyProject
+  extend CLIClassTool::Utils
+
+  # Map shortcuts to deeply-nested actions
+  CLI_COMMAND_ALIASES = {
+    "myalias"       => ["config", "set_val"],
+    "string_alias"  => "config set_val"
+  }
+end
+```
+
+Running `$ mytool myalias --foo bar` will automatically expand and route arguments exactly as if the user had typed `$ mytool config set_val --foo bar`.
+These shortcuts are also dynamically collected and formatted under a dedicated `Command aliases:` section when printing `--help`.
+
+### 4. Seamless Subcommand Exception Handling
+
+`CLIClassTool` provides dynamic subclass exception matching to solve a common design challenge: *rescuing any exception originating from nested sub-CLIs under a single, central parent rescue block.*
+
+When you extend `CLIClassTool::Utils` on a parent module, `CLIClassTool` overrides the case-equality (`===`) operator on the parent's base error class. This ensures:
+- Any child subcommand exception (such as `MyProject::ConfigCLI::RunError`) is **seamlessly rescued** by the parent base error class.
+- The original exception classes and names remain **completely unchanged**, meaning they can still be rescued by their specific sub-CLI exception class as normal.
+
+This enables infinite sub-CLI nesting while preserving modular reuse across different parent projects or as standalone binaries:
+
+```ruby
+# In bin/mytool
+begin
+  MyProject.run_cli
+rescue MyProjectError => e
+  # Seamlessly catches errors from MyProject::RunError,
+  # MyProject::ConfigCLI::RunError, or any deeper sublevel!
+  STDERR.puts "# ERROR: #{e.message}"
+  exit e.respond_to?(:err_code) ? e.err_code : 1
+end
+```
+
 ```

data/lib/cli_class_tool/common.rb

@@ -25,7 +25,8 @@ module CLIClassTool
         # @param obj [Object,Class] Object or class to get the Module from
         # @raise [StandardError] If command failed
         def obj_to_parent_mod(obj)
-            return obj if obj.is_a?(Module)
+            return obj if obj.class == Module
+
             theClass = obj.is_a?(Class) ? obj : obj.class
             if theClass.name.nil?
                 return Object
@@ -137,7 +138,14 @@ module CLIClassTool
         # @param cmd_type [String] Type of command (e.g., 'git')
         # @param cmd [String] The command string
         def cmd_debug(cmd_type, cmd)
-            log(:DEBUG, "Called from #{caller[1]}")
+            log(:DEBUG, "Called from:")
+            depth=1
+            if ENV["DEBUG_CALL_DEPTH"].to_s() != ""
+                depth = ENV["DEBUG_CALL_DEPTH"].to_i()
+            end
+            [ depth, caller.length].min.downto(1){|x|
+                log(:DEBUG, " #{caller[x]}")
+            }
             log(:DEBUG, "Running #{cmd_type} command '#{cmd}'")
         end
 
@@ -214,7 +222,9 @@ module CLIClassTool
         # @param opts [Hash] Options hash
         # @return [Integer] 0
         def list_actions(opts)
-            puts parent_module.getActionAttr("ACTION_LIST").map(){|x| parent_module.actionToString(x)}.join("\n")
+            actions = parent_module.getActionAttr("ACTION_LIST").map(){|x| parent_module.actionToString(x)}
+            actions.reject! { |x| x == "list_actions" }
+            puts actions.join("\n")
             return 0
         end
     end

data/lib/cli_class_tool/utils.rb

@@ -1,20 +1,109 @@
+require 'optparse'
+
 module CLIClassTool
     # Generic utilities for CLI class-based actions
     module Utils
 
         # Hook called when a module extends CLIClassTool::Utils
         def self.extended(base)
-            possible_name = base.name ? "#{base.name}Error" : nil
+            return if base == nil
 
-            superclass = if possible_name && Object.const_defined?(possible_name)
-                Object.const_get(possible_name)
-            elsif base.const_defined?(:Error)
-                base.const_get(:Error)
-            else
-                CLIClassTool::RunError
+            lower_mod = base.name.split('::')[-1]
+            superclass_name = "#{base.name}::#{lower_mod}Error"
+
+            if ! Object.const_defined?(superclass_name)
+                raise("Could not find a base error class named #{superclass_name}")
             end
 
-            CLIClassTool.define_run_error(base, superclass)
+            error_class = Object.const_get(superclass_name)
+
+            # Override === on the error class to match nested subcommand errors recursively
+            error_class.singleton_class.class_eval do
+                define_method(:_cli_host_module) { base }
+
+                def ===(other)
+                    return true if super
+
+                    if other.is_a?(StandardError) && other.respond_to?(:err_code)
+                        other_class_name = other.class.name
+                        if other_class_name
+                            parts = other_class_name.split('::')
+                            if parts.size > 1
+                                parent_mod_name = parts[0...-1].join('::')
+                                host = _cli_host_module
+                                if host.respond_to?(:cli_sub_actions)
+                                    all_sub_names = _all_sub_module_names(host)
+                                    return all_sub_names.include?(parent_mod_name)
+                                end
+                            end
+                        end
+                    end
+
+                    false
+                end
+
+                define_method(:_all_sub_module_names) do |host_mod|
+                    names = []
+                    if host_mod.respond_to?(:cli_sub_actions)
+                        host_mod.cli_sub_actions.values.each do |sub_cli|
+                            if sub_cli.name
+                                names << sub_cli.name
+                                names.concat(_all_sub_module_names(sub_cli))
+                            end
+                        end
+                    end
+                    names.uniq
+                end
+            end
+
+            CLIClassTool.define_run_error(base, error_class)
+        end
+
+        # Convert CamelCase to snake_case
+        # @param str [String]
+        # @return [String]
+        def _to_snake_case(str)
+            str.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+               .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+               .tr('-', '_')
+               .downcase
+        end
+
+        # Dynamically discover and return a map of sub-CLI tools
+        #
+        # @return [Hash<String, Module>] Map of subcommand string to CLI modules
+        def cli_sub_actions
+            sub_actions = {}
+
+            # First, check if manual CLI_SUB_ACTIONS mapping exists
+            if self.const_defined?(:CLI_SUB_ACTIONS)
+                manual_actions = self::CLI_SUB_ACTIONS
+                if manual_actions.is_a?(Hash)
+                    manual_actions.each do |k, v|
+                        sub_actions[k.to_s] = v
+                    end
+                end
+            end
+
+            # Then, dynamically discover any inner modules/classes extending CLIClassTool::Utils
+            self.constants(false).each do |const_sym|
+                begin
+                    const_val = self.const_get(const_sym)
+                    if const_val.is_a?(Module) && const_val.is_a?(CLIClassTool::Utils)
+                        cmd_name = if const_val.const_defined?(:CLI_COMMAND_NAME)
+                            const_val::CLI_COMMAND_NAME.to_s
+                        else
+                            _to_snake_case(const_sym.to_s)
+                        end
+                        # Only add if not already manually specified
+                        sub_actions[cmd_name] ||= const_val
+                    end
+                rescue NameError, LoadError
+                    # ignore uninitialized autoloads
+                end
+            end
+
+            return sub_actions
         end
 
         # Convert a string to an action symbol, validating it against available actions
@@ -41,19 +130,67 @@ module CLIClassTool
         # @param attr [Symbol] Attribute name (e.g., "ACTION_LIST")
         # @return [Hash, Array] Aggregated attributes
         def getActionAttr(attr)
-            action_classes = self::ACTION_CLASS
-            common_class = self::Common
+            common_class = self.const_defined?(:Common) ? self::Common : CLIClassTool::Common
+            is_hash = if common_class.const_defined?(attr)
+                common_class.const_get(attr).is_a?(Hash)
+            else
+                attr.to_s.include?("HELP")
+            end
+
+            action_classes = self.const_defined?(:ACTION_CLASS) ? self::ACTION_CLASS : []
 
             # Resolve overridden/extended class (addon) if getExtendedClass is defined
             resolved_classes = action_classes.map do |x|
                 self.respond_to?(:getExtendedClass) ? self.getExtendedClass(x) : x
             end
 
-            if common_class.const_get(attr).class == Hash
-                return resolved_classes.inject({}){|h, x| h.merge(x.const_get(attr))}
+            res = if is_hash
+                resolved_classes.inject({}) do |h, x|
+                    x.const_defined?(attr) ? h.merge(x.const_get(attr)) : h
+                end
             else
-                return resolved_classes.map(){|x| x.const_get(attr)}.flatten()
+                resolved_classes.map do |x|
+                    x.const_defined?(attr) ? x.const_get(attr) : []
+                end.flatten()
             end
+
+            # If it's ACTION_LIST, append discovered subcommand names
+            if attr.to_s == "ACTION_LIST"
+                sub_actions = self.cli_sub_actions
+                res += sub_actions.keys.map(&:to_sym)
+                res << :list_actions unless res.include?(:list_actions)
+            # If it's ACTION_HELP, merge subcommand helps
+            elsif attr.to_s == "ACTION_HELP"
+                sub_helps = {}
+                self.cli_sub_actions.each do |cmd_name, sub_cli|
+                    expand_val = sub_cli.const_defined?(:CLI_HELP_EXPAND) ? sub_cli::CLI_HELP_EXPAND : nil
+                    if expand_val
+                        if expand_val.is_a?(String)
+                            sub_helps[expand_val] = ""
+                        end
+                        sub_helps_rec = sub_cli.getActionAttr("ACTION_HELP")
+                        sub_helps_rec.each do |k, desc|
+                            sub_helps["#{cmd_name} #{k}".to_sym] = desc
+                        end
+                    else
+                        desc = ""
+                        if sub_cli.const_defined?(:CLI_DESCRIPTION)
+                            desc = sub_cli::CLI_DESCRIPTION
+                        elsif sub_cli.const_defined?(:HELP)
+                            desc = sub_cli::HELP
+                        end
+                        sub_helps[cmd_name.to_sym] = desc
+                    end
+                end
+                if self.const_defined?(:CLI_SUB_ACTIONS_HELP)
+                    self::CLI_SUB_ACTIONS_HELP.each do |k, desc|
+                        sub_helps[k.to_sym] = desc
+                    end
+                end
+                res = res.merge(sub_helps)
+            end
+
+            return res
         end
 
         # Run a block on the class responsible for a specific action
@@ -63,8 +200,9 @@ module CLIClassTool
         # @yield [Class] The class handling the action
         # @return [Object] Result of the block or error code
         def _runOnClass(action, sym, &block)
+            return -1 unless self.const_defined?(:ACTION_CLASS)
             self::ACTION_CLASS.each(){|x|
-                next if x::ACTION_LIST.index(action) == nil
+                next if !x.const_defined?(:ACTION_LIST) || x::ACTION_LIST.index(action) == nil
 
                 # Resolve overridden/extended class (addon)
                 class_to_use = self.respond_to?(:getExtendedClass) ? self.getExtendedClass(x) : x
@@ -115,16 +253,12 @@ module CLIClassTool
         def execAction(opts, action, error_class = nil)
             caught_error_class = error_class || StandardError
 
-            self._runOnClass(action, nil) {|kClass|
+            ret_code = self._runOnClass(action, nil) {|kClass|
                 begin
-                    # Some class have their own execAction, because object creation might be tricky.
-                    if kClass.respond_to?(:execAction)
-                        ret = kClass.execAction(opts, action)
-                    else
-                        # Use load factory method if defined, else fall back to .new
-                        obj = kClass.respond_to?(:load) ? kClass.load() : kClass.new()
-                        ret = obj.public_send(action, opts)
-                    end
+                    # Use load factory method if defined, else fall back to .new
+                    obj = kClass.respond_to?(:load) ? kClass.load() : kClass.new()
+                    ret = obj.public_send(action, opts)
+
                     return ret.is_a?(Integer) ? ret : 0
                 rescue caught_error_class => e
                     puts("# " + "ERROR".red().to_s() + ": Action '#{action}' failed: #{e.message}")
@@ -139,6 +273,15 @@ module CLIClassTool
                     end
                 end
             }
+
+            if ret_code == -1 && action == :list_actions
+                actions = self.getActionAttr("ACTION_LIST").map(){|x| self.actionToString(x)}
+                actions.reject! { |x| x == "list_actions" }
+                puts actions.join("\n")
+                return 0
+            end
+
+            return ret_code
         end
 
         # Set verbose logging
@@ -198,7 +341,7 @@ module CLIClassTool
         # @param opts [Hash] Initial options hash
         # @param argv [Array<String>] Command line arguments (defaults to ARGV)
         # @yield [parser, phase, action_opts] Custom options setup callback block
-        def run_cli(opts = {}, argv = ARGV)
+        def run_cli(opts = {}, argv = ARGV, &block)
             # Fetch actions and action helps
             action_helps = self.getActionAttr("ACTION_HELP")
 
@@ -220,7 +363,7 @@ module CLIClassTool
             col_width = max_len + 4
             action_helps.each do |k, x|
                 indent = col_width - self.actionToString(k).length
-                action_parser.separator "\t * " + self.actionToString(k) + (" " * indent) + x
+                action_parser.separator "\t * " + self.actionToString(k) + (" " * indent) + x.to_s
             end
 
             # Include any registered custom addon class listings if defined
@@ -231,6 +374,19 @@ module CLIClassTool
                 end
             end
 
+            # Include command aliases if defined
+            if self.const_defined?(:CLI_COMMAND_ALIASES)
+                aliases = self::CLI_COMMAND_ALIASES
+                if aliases.is_a?(Hash) && aliases.length > 0
+                    action_parser.separator ""
+                    action_parser.separator "Command aliases:"
+                    aliases.each do |k, v|
+                        exp_str = v.is_a?(Array) ? v.join(" ") : v.to_s
+                        action_parser.separator "\t * #{k}  -> #{exp_str}"
+                    end
+                end
+            end
+
             rest = action_parser.order!(argv)
             if rest.length <= 0
                 STDERR.puts("Error: No action provided")
@@ -238,7 +394,38 @@ module CLIClassTool
                 exit 1
             end
 
+            # Expand command aliases
+            if self.const_defined?(:CLI_COMMAND_ALIASES)
+                aliases = self::CLI_COMMAND_ALIASES
+                if aliases.is_a?(Hash)
+                    action_s = argv[0]
+                    action_sym = action_s ? action_s.to_sym : nil
+                    if aliases.key?(action_s) || (action_sym && aliases.key?(action_sym))
+                        expansion = aliases[action_s] || aliases[action_sym]
+                        expansion = expansion.split(' ') if expansion.is_a?(String)
+                        argv.shift()
+                        argv.unshift(*expansion)
+                    end
+                end
+            end
+
             action_s = argv[0]
+
+            # Intercept subcommands here!
+            sub_actions = self.cli_sub_actions
+            if sub_actions.key?(action_s)
+                sub_cli = sub_actions[action_s]
+                if sub_cli.respond_to?(:verbose_log=)
+                    sub_cli.verbose_log = self.verbose_log
+                end
+                argv.shift()
+                if block
+                    exit(sub_cli.run_cli(opts, argv, &block))
+                else
+                    exit(sub_cli.run_cli(opts, argv))
+                end
+            end
+
             action = opts[:action] = self.stringToAction(action_s)
             argv.shift()
 
@@ -260,11 +447,11 @@ module CLIClassTool
             self.setOpts(action, opts_parser, opts)
 
             # Order remaining arguments
+            rest = opts_parser.order!(argv)
             if opts[:ignore_opts] != true
-                rest = opts_parser.order!(argv)
                 raise("Extra Unexpected extra arguments provided: " + rest.map(){|x|"'" + x + "'"}.join(", ")) if rest.length != 0
             else
-                opts[:extra_args] = argv
+                opts[:extra_args] = rest
             end
 
             # Validate options and execute action

data/lib/cli_class_tool.rb

@@ -1,31 +1,19 @@
 module CLIClassTool
-  class RunError < StandardError
-    attr_reader :err_code, :output
+    def self.define_run_error(parent_module, superclass)
+        klass = Class.new(superclass)
 
-    def initialize(err_code, output = nil)
-      @err_code = err_code
-      @output = output
-      super("Command failed with exit status #{err_code}#{output ? "\n#{output}" : ''}")
-    end
-  end
-
-  def self.define_run_error(parent_module, superclass = CLIClassTool::RunError)
-    klass = Class.new(superclass)
-
-    if !(superclass <= CLIClassTool::RunError)
-      klass.class_eval do
-        attr_reader :err_code, :output
+        klass.class_eval do
+            attr_reader :err_code, :msg
 
-        def initialize(err_code, output = nil)
-          @err_code = err_code
-          @output = output
-          super("Command failed with exit status #{err_code}#{output ? "\n#{output}" : ''}")
+            def initialize(err_code, output = nil)
+                @err_code = err_code
+                @msg = output
+                super("Command failed with exit status #{err_code}")
+            end
         end
-      end
+        parent_module.const_set(:RunError, klass)
     end
 
-    parent_module.const_set(:RunError, klass)
-  end
 end
 
 require_relative 'cli_class_tool/string'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: cli_class_tool
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Nicolas Morey
 bindir: bin
 cert_chain: []
-date: 2026-06-05 00:00:00.000000000 Z
+date: 2026-07-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -83,7 +83,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: A lightweight object-oriented framework for class-based command-line interface
   (CLI) applications.