cli_class_tool 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46f243576af73a6b5e4b56a097e4876377f2f4b0b2871ea013955d6eb75addd0
-  data.tar.gz: c44bcb2a54d9f1c3e9d5c19543805ba16f0bd224f5ece98acb02da3be071bf31
+  metadata.gz: 2c2833d3bd929aa6e69df3df0cbadbbc3e92030afdbf8172387869a9ad4f95f3
+  data.tar.gz: 3bac4466f6a3d4e07bc739e36eb0eaaba2929c5a308a980715e4d0c55ef11fd7
 SHA512:
-  metadata.gz: 2d04141ca190c6a98bd4481156708c9fbff7f9550324bee3612c283959ad94b90efaf33484fd77b6425f3320ecf6e2e8996422e307506f837f07785267cf5686
-  data.tar.gz: 761917986fb8e915fc189e2d4cee710bd39ac44c968b421cca4ee65affd0d07ec7de9455a3e46e15beb1ee09110e966c72bc2be01e9746254256e50067308d88
+  metadata.gz: 5f8ab8e7152ade287dc0a8c50598d2069cbbd99ecbcc5d0bb9cc7fd37a8a9e3fa401a889030c3bcea9a387cb2f5ac5a8ab49ef40b78980a982355ecdcba3bd53
+  data.tar.gz: d031b3ca4da59379e5f3079ad091f10fd4934b0d1150df9f846ea2de77e1d439e236ac2070763418083394956cef64ed3f7ec2f7883222c66b14cd24e3ea9854

data/CHANGELOG

@@ -1,3 +1,15 @@
+------------------
+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)
 ------------------

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

@@ -222,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,3 +1,5 @@
+require 'optparse'
+
 module CLIClassTool
     # Generic utilities for CLI class-based actions
     module Utils
@@ -13,7 +15,95 @@ module CLIClassTool
                 raise("Could not find a base error class named #{superclass_name}")
             end
 
-            CLIClassTool.define_run_error(base, Object.const_get(superclass_name))
+            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
@@ -40,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
@@ -62,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
@@ -114,7 +253,7 @@ 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
                     # Use load factory method if defined, else fall back to .new
                     obj = kClass.respond_to?(:load) ? kClass.load() : kClass.new()
@@ -134,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
@@ -193,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")
 
@@ -215,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
@@ -226,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")
@@ -233,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()
 
@@ -255,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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: cli_class_tool
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  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.