cli_class_tool 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 641f72caf2c39cac1c5a222756c481f0de86b5fd7db14893001a64773400d894
-  data.tar.gz: 612b9cca3cbd1b157780c490093657e77ba021bb973ca38e76e63f19de1e730e
+  metadata.gz: bad275062a9f72ff201812eb6cd7871b9321b80b57f379f817cab483de42b738
+  data.tar.gz: e3cb70b12fe4831a4fdd194eaa4c67118efcfd9ffc0f1903524d74bdaf805e1a
 SHA512:
-  metadata.gz: f2ceb59e563ebe911176786f1e4ffdd3762c2ef0b9a62acad6323896c68741228468f3b21e53331f4b22774b4bd0ac8746048330408d84366b6fa4426a546ff6
-  data.tar.gz: 3d848b3725fd1e80e061d04e358bbb71821708fc2ed490612ad4fe66b2ffc038396605cda7dfa28f89d7bdaaf703f6b038a0b66a68f18d18c12a2a12742667ab
+  metadata.gz: 43cc9f0156398b92a5d1c7370c6c8c7dcf61d80e4ad9b18bec8a4a5bedceec7aa9e9af40e5d801554c7369aa746bac98c204ad949d2d27b381c4e14cbec93312
+  data.tar.gz: '0948e6f13057dd174140d84a7845c33a25e758a9ef018e10afb9c75bb734e87dffaf191e81091e01fe8c1dc9ff66437672364343d7ffc054f76cf0d591ebec1d'

data/CHANGELOG

@@ -1,7 +1,24 @@
+------------------
+0.4.0  (2026-06-05)
+------------------
+
+* Add basic initializer for Common
+* Add Common::run() that will auto spawn a Common object and run the command with it.
+* log function can now be used in alternate object or class by including/extending CLIClassTool::Logger
+
+------------------
+0.3.0  (2026-06-02)
+------------------
+
+* Enforce module/class namespaces for all action classes (potentially breaking change)
+* Support automatic project-specific `RunError` generation with customized base error inheritance
+
 ------------------
 0.2.1  (2026-06-01)
 ------------------
 
+* Fix issue with conflicting addon files
+
 ------------------
 0.2.0  (2026-06-01)
 ------------------

data/README.md

@@ -112,6 +112,61 @@ exit MyProject.execAction(opts, opts[:action])
 
 ---
 
+## Namespace Requirement & Error Handling
+
+### 1. Module Namespace Requirement
+
+To ensure clean encapsulation and safe error resolution, all action classes and standard subclasses inheriting from `CLIClassTool::Common` **must** be defined within a named module/class namespace (such as `MyProject`):
+
+```ruby
+# Correct: Action class is scoped under MyProject namespace
+module MyProject
+  class Suse < CLIClassTool::Common
+    # ...
+  end
+end
+
+# Incorrect: Defining action classes directly in the global namespace is forbidden
+# and will raise an error at load-time:
+class Suse < CLIClassTool::Common; end
+# => "CLIClassTool action classes must be defined within a named module/class namespace"
+```
+
+### 2. Automated `RunError` Generation & Customized Inheritance
+
+When your project's parent module extends `CLIClassTool::Utils`, `CLIClassTool` automatically generates a nested `RunError` class (i.e. `MyProject::RunError`) specifically for your project on load.
+
+By default, this generated error inherits from `CLIClassTool::RunError`. However, if you have a binary-specific or project-wide base error class defined, `CLIClassTool` will **automatically detect it** and make `RunError` inherit from it instead!
+
+It looks for existing error classes in this order:
+1. `#{base_name}Error` (e.g., `MyProjectError` in the global scope)
+2. `#{base_name}::Error` (e.g., `MyProject::Error` within your namespace)
+3. Falls back to `CLIClassTool::RunError`
+
+#### Why is this useful?
+This allows you to catch all potential CLI errors (including system command failures from `run`, `runGit`, etc.) in a single rescue block at the entry point of your binary:
+
+```ruby
+# Define your binary-specific error class
+class MyProjectError < StandardError; end
+
+module MyProject
+  extend CLIClassTool::Utils
+  # CLIClassTool automatically defines MyProject::RunError inheriting from MyProjectError!
+end
+
+# In your executable (bin/mytool)
+begin
+  MyProject.run_cli
+rescue MyProjectError => e
+  # This cleanly catches MyProject::RunError, as well as any other custom MyProjectError!
+  STDERR.puts "# ERROR: #{e.message}"
+  exit e.respond_to?(:err_code) ? e.err_code : 1
+end
+```
+
+---
+
 ## Logging Levels
 By inheriting from `CLIClassTool::Common`, your action classes have access to a rich `log` helper supporting several standard output and color levels:
 

data/lib/cli_class_tool/common.rb

@@ -1,22 +1,9 @@
 # Main module for generic CLI class-based tools and utilities
 module CLIClassTool
 
-    # Common utility class providing logging, configuration, and shell execution methods
-    class Common
-        # List of available actions for this class
-        ACTION_LIST = [ :list_actions ]
-        # Help text for actions
-        ACTION_HELP = {}
-
+    # Logger for CLIClassTool::Common
+    module Logger
         private
-        # Get the parent module of this class (e.g. KernelWork or XXX)
-        def parent_module
-            @parent_module ||= begin
-                parts = self.class.name.split('::')
-                parts.size > 1 ? Object.const_get(parts[0...-1].join('::')) : Object
-            end
-        end
-
         # Internal log method
         # @param lvl [String] Log level string (colored)
         # @param str [String] Message
@@ -33,26 +20,33 @@ module CLIClassTool
             out.print("# " + lvl.to_s() + ": " + str + "\r")
         end
 
-        # Raise error if system command failed
-        # @param check_err [Boolean] Whether to check for errors
-        # @param sysret [Process::Status] System return status
-        # @param ret [String, nil] Optional return message
+        # Compute the parent module of an object or a class
+        #
+        # @param obj [Object,Class] Object or class to get the Module from
         # @raise [StandardError] If command failed
-        def abort_if_err(check_err, sysret, ret = nil)
-            if sysret.exitstatus != 0 && check_err == true
-                run_error_class = parent_module.const_defined?(:RunError) ? parent_module::RunError : RuntimeError
-                raise(run_error_class.new(sysret.exitstatus, ret))
+        def obj_to_parent_mod(obj)
+            return obj if obj.is_a?(Module)
+            theClass = obj.is_a?(Class) ? obj : obj.class
+            if theClass.name.nil?
+                return Object
+            else
+                parts = theClass.name.split('::')
+                if parts.size <= 1
+                    raise "CLIClassTool action classes must be defined within a named module/class namespace"
+                end
+                return Object.const_get(parts[0...-1].join('::'))
             end
         end
 
-        # Debug command execution
-        # @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, "Running #{cmd_type} command '#{cmd}'")
+        # Get the parent module of this class (e.g. KernelWork or XXX)
+        def parent_module
+            return @parent_module if @parent_module != nil
+
+            @parent_module = obj_to_parent_mod(self)
+            return @parent_module
         end
-        protected
+
+        public
         # Log a message with a specific level
         #
         # @param lvl [Symbol] Log level (:DEBUG, :INFO, :WARNING, :ERROR, etc.)
@@ -102,8 +96,61 @@ module CLIClassTool
             end
             return rep
         end
+    end
+
+    # Common utility class providing logging, configuration, and shell execution methods
+    class Common
+        # Hook to enforce namespace loading at load time
+        def self.inherited(subclass)
+            if subclass.name
+                parts = subclass.name.to_s.split('::')
+                if parts.size <= 1
+                    raise "CLIClassTool action classes must be defined within a named module/class namespace"
+                end
+            end
+        end
+
+        # List of available actions for this class
+        ACTION_LIST = [ :list_actions ]
+        # Help text for actions
+        ACTION_HELP = {}
+
+        # Give the Logger mathods to Common
+        include CLIClassTool::Logger
+
+        private
+        # Raise error if system command failed
+        # @param check_err [Boolean] Whether to check for errors
+        # @param sysret [Process::Status] System return status
+        # @param ret [String, nil] Optional return message
+        # @raise [StandardError] If command failed
+        def abort_if_err(check_err, sysret, ret = nil)
+            if sysret.exitstatus != 0 && check_err == true
+                unless parent_module.const_defined?(:RunError)
+                    raise "CLIClassTool parent module #{parent_module} must extend CLIClassTool::Utils to define RunError"
+                end
+                raise(parent_module::RunError.new(sysret.exitstatus, ret))
+            end
+        end
+
+        # Debug command execution
+        # @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, "Running #{cmd_type} command '#{cmd}'")
+        end
+
 
         public
+        # Simple initializer for a Common object
+        #
+        # @param path [String] Path to run commands from
+        def initialize(path=".", caller_obj=self)
+            @path = path
+            @parent_module = obj_to_parent_mod(caller_obj)
+        end
+
         # Run a shell command
         #
         # @param cmd [String] Command to run
@@ -117,6 +164,10 @@ module CLIClassTool
             return ret
         end
 
+        def self.run(path, cmd, check_err = true)
+            obj = Common.new(path, self)
+            return obj.run(cmd, check_err)
+        end
         # Run a shell command using system() (interactive)
         #
         # @param cmd [String] Command to run

data/lib/cli_class_tool/utils.rb

@@ -2,6 +2,21 @@ 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
+
+            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
+            end
+
+            CLIClassTool.define_run_error(base, superclass)
+        end
+
         # Convert a string to an action symbol, validating it against available actions
         #
         # @param str [String] Action name
@@ -186,7 +201,6 @@ module CLIClassTool
         def run_cli(opts = {}, argv = ARGV)
             # Fetch actions and action helps
             action_helps = self.getActionAttr("ACTION_HELP")
-            action_list = self.getActionAttr("ACTION_LIST")
 
             # 1. Action Parser Setup
             action_parser = OptionParser.new(nil, 60)

data/lib/cli_class_tool.rb

@@ -1,3 +1,33 @@
+module CLIClassTool
+  class RunError < StandardError
+    attr_reader :err_code, :output
+
+    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
+
+        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
+    end
+
+    parent_module.const_set(:RunError, klass)
+  end
+end
+
 require_relative 'cli_class_tool/string'
 require_relative 'cli_class_tool/common'
 require_relative 'cli_class_tool/utils'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: cli_class_tool
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Nicolas Morey
 bindir: bin
 cert_chain: []
-date: 2026-06-01 00:00:00.000000000 Z
+date: 2026-06-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake