cli_class_tool 1.1.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 645eabaadb2f9f7b6497f524dc2e847bbe6fa2b3bd0085449e7a5c6e49e6d943
-  data.tar.gz: 94cb2bfe852dce7a0f1a55a7888a813e4beea307f0a41c056c69d26f0914e4e7
+  metadata.gz: 89e584d14bafdaf918d35406f8bf1dd1b548147cf65ff7e8a51f0f687add515c
+  data.tar.gz: 4dc4ed8c9a27d01fdf8b3cc408532b42e0c7ab2c80b6e75d92b35c1a200be4bb
 SHA512:
-  metadata.gz: 576fc426eedf2ed6578dce762fae533432cee75c1dce31d31ebf1c44b2b6c82b0a6418d74670fb5b6a6812b278c0444cc8295adb79d5fa2be4507cbbc9136d16
-  data.tar.gz: 4c6544ef6d4eecb54d5f2e7de75106e33936523d3e2bcea82ad729e0a388d9e33b193727b67637ef9901f29c23fccfa5ee9caed484043c4b2e7e8f60da7ca7db
+  metadata.gz: 52e76102055a0d40a7ef754232f30619a882b906200d29e7a31eafe87e24304225bc022877c3a504957389064874046ee522aba7d7e96d3dee46697d6e7afdaf
+  data.tar.gz: be038285b90077978d9b4f72150d66aee2d994f9dffa6b709b59c49b1be8a645a0fcfe1b9f6ca2e1cf9ffe372c1ad9832be7aa7ea026353c33084797e1bd1f3e

data/CHANGELOG

@@ -1,3 +1,19 @@
+------------------
+2.1.0  (2026-09-25)
+------------------
+
+* Add `String#hyperlink` method for OSC 8 terminal hyperlinks
+* Add `String#visible_length` method to compute visible string length stripped of ANSI escapes, control characters, and hyperlinks
+
+------------------
+2.0.0  (2026-09-18)
+------------------
+
+* Refactor Common.run, runSystem, runGit, and runGitInteractive to accept optional named arguments (env:, catch_err:, silent_err:)
+* Replace check_err positional boolean with catch_err: keyword argument (default: false) across all run methods
+* Replace opts[:env] with env: keyword argument across all run methods
+* Add silent_err: keyword argument to redirect stderr to /dev/null
+
 ------------------
 1.1.0  (2026-09-09)
 ------------------

data/README.md

@@ -207,6 +207,48 @@ confirm(opts, "format the disk", ignored_default: true)
 
 ---
 
+## Command Execution (`run`, `runSystem`, `runGit`, `runGitInteractive`)
+
+`CLIClassTool::Common` provides shell and git execution methods that run within the context of the instance's target `@path`.
+
+### Available Methods
+
+- `run(cmd, env: nil, catch_err: false, silent_err: false)`: Executes a command in a subshell, returning the stripped stdout (`String`).
+- `CLIClassTool::Common.run(path, cmd, env: nil, catch_err: false, silent_err: false)`: Class method convenience helper that instantiates a `Common` object for `path` and runs `cmd`.
+- `runSystem(cmd, env: nil, catch_err: false, silent_err: false)`: Executes a command interactively using `system()`, returning `true` on success and `false` on failure.
+- `runGit(cmd, env: nil, catch_err: false, silent_err: false)`: Runs `git #{cmd}` in a subshell, returning the stripped stdout (`String`).
+- `runGitInteractive(cmd, env: nil, catch_err: false, silent_err: false)`: Runs `git #{cmd}` interactively using `system()`, returning `true` on success and `false` on failure.
+
+### Optional Named Arguments
+
+- `env` (`String`, default: `nil`): Optional environment variable prefix prepended to the command (e.g. `env: "FOO=bar"` or `env: "GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=user.name GIT_CONFIG_VALUE_0=TestRunner"`).
+- `catch_err` (`Boolean`, default: `false`): Controls error handling on non-zero exit codes:
+  - `catch_err: false` (default): Command failures abort and raise a project-specific `RunError`.
+  - `catch_err: true`: Suppresses raising `RunError`, returning the command output (or `false` for `system` methods).
+- `silent_err` (`Boolean`, default: `false`): When `true`, redirects stderr output to `/dev/null` (`2>/dev/null`).
+
+### Examples
+
+```ruby
+# Basic execution (raises RunError if command exits non-zero)
+branch = run("git rev-parse --abbrev-ref HEAD")
+
+# Running with environment variables
+run("make", env: "CC=clang CFLAGS='-O2'")
+
+# Suppressing errors on expected failures
+output = run("grep -r 'pattern' .", catch_err: true)
+
+# Suppressing error output (stderr redirected to /dev/null)
+runGit("rev-parse --verify non_existing_ref", catch_err: true, silent_err: true)
+
+# Interactive execution via system()
+runSystem("make menuconfig")
+runGitInteractive("rebase -i origin/main")
+```
+
+---
+
 ## Dynamic Class Overrides (Addons)
 
 `CLIClassTool` natively supports dynamic class overrides (addons). This allows projects to load repository-specific or custom subclasses that extend or override base action behaviors without modifying the core codebase.
@@ -446,3 +488,22 @@ puts "System Message".bold       # Bold text using default terminal color
 ```
 
 These methods automatically check if `$stdout` is a TTY and safely fall back to standard, unformatted strings if output is piped or redirected (non-TTY mode).
+
+### Terminal Hyperlinks (`hyperlink`)
+
+You can create clickable OSC 8 terminal hyperlinks using the `.hyperlink(url)` method. When `$stdout` is a TTY and a target URL is provided, it formats the string with OSC 8 escape sequences; otherwise, it returns the original string:
+
+```ruby
+puts "Visit Website".hyperlink("https://example.com")
+puts "Source Code".blue.hyperlink("https://github.com")
+```
+
+### Visible String Length (`visible_length`)
+
+To compute the display length of a string without ANSI color escape codes, embedded hyperlinks, or residual control characters, use `.visible_length`:
+
+```ruby
+str = "Click here".bold.red.hyperlink("https://example.com")
+str.length         # Raw string length including escape sequences
+str.visible_length # 10 (visible characters count)
+```

data/lib/cli_class_tool/common.rb

@@ -136,12 +136,12 @@ module CLIClassTool
 
         private
         # Raise error if system command failed
-        # @param check_err [Boolean] Whether to check for errors
+        # @param catch_err [Boolean] Whether to catch (suppress raising) 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
+        # @raise [StandardError] If command failed and catch_err is false
+        def abort_if_err(catch_err, sysret, ret = nil)
+            if sysret.exitstatus != 0 && !catch_err
                 unless parent_module.const_defined?(:RunError)
                     raise "CLIClassTool parent module #{parent_module} must extend CLIClassTool::Utils to define RunError"
                 end
@@ -177,58 +177,73 @@ module CLIClassTool
         # Run a shell command
         #
         # @param cmd [String] Command to run
-        # @param check_err [Boolean] Raise error on failure
+        # @param env [String, nil] Environment variable prefix (e.g., "FOO=bar")
+        # @param catch_err [Boolean] If true, do not raise error on failure
+        # @param silent_err [Boolean] If true, redirect stderr to /dev/null
         # @return [String] Command output
-        # @raise [StandardError] If command fails and check_err is true
-        def run(cmd, check_err = true)
+        # @raise [StandardError] If command fails and catch_err is false
+        def run(cmd, env: nil, catch_err: false, silent_err: false)
             cmd_debug('', cmd)
-            ret = `cd #{@path} && #{cmd}`.chomp()
-            abort_if_err(check_err, $?, ret)
+            env_prefix = env ? "#{env} " : ""
+            redirect = silent_err ? " 2>/dev/null" : ""
+            ret = `cd #{@path} && #{env_prefix}#{cmd}#{redirect}`.chomp()
+            abort_if_err(catch_err, $?, ret)
             return ret
         end
 
-        def self.run(path, cmd, check_err = true)
+        def self.run(path, cmd, env: nil, catch_err: false, silent_err: false)
             obj = Common.new(path, self)
-            return obj.run(cmd, check_err)
+            return obj.run(cmd, env: env, catch_err: catch_err, silent_err: silent_err)
         end
+
         # Run a shell command using system() (interactive)
         #
         # @param cmd [String] Command to run
-        # @param check_err [Boolean] Raise error on failure
+        # @param env [String, nil] Environment variable prefix (e.g., "FOO=bar")
+        # @param catch_err [Boolean] If true, do not raise error on failure
+        # @param silent_err [Boolean] If true, redirect stderr to /dev/null
         # @return [Boolean] Command success status
-        # @raise [StandardError] If command fails and check_err is true
-        def runSystem(cmd, check_err = true)
+        # @raise [StandardError] If command fails and catch_err is false
+        def runSystem(cmd, env: nil, catch_err: false, silent_err: false)
             cmd_debug('interactive', cmd)
-            ret = system("cd #{@path} && #{cmd}")
-            abort_if_err(check_err, $?)
+            env_prefix = env ? "#{env} " : ""
+            redirect = silent_err ? " 2>/dev/null" : ""
+            ret = system("cd #{@path} && #{env_prefix}#{cmd}#{redirect}")
+            abort_if_err(catch_err, $?)
             return ret
         end
 
         # Run a git command
         #
         # @param cmd [String] Git command arguments
-        # @param opts [Hash] Options (e.g., :env)
-        # @param check_err [Boolean] Raise error on failure
+        # @param env [String, nil] Environment variable prefix (e.g., "FOO=bar")
+        # @param catch_err [Boolean] If true, do not raise error on failure
+        # @param silent_err [Boolean] If true, redirect stderr to /dev/null
         # @return [String] Command output
-        # @raise [StandardError] If command fails and check_err is true
-        def runGit(cmd, opts={}, check_err = true)
+        # @raise [StandardError] If command fails and catch_err is false
+        def runGit(cmd, env: nil, catch_err: false, silent_err: false)
             cmd_debug('git', cmd)
-            ret = `cd #{@path} && #{opts[:env]} git #{cmd}`.chomp()
-            abort_if_err(check_err, $?, ret)
+            env_prefix = env ? "#{env} " : ""
+            redirect = silent_err ? " 2>/dev/null" : ""
+            ret = `cd #{@path} && #{env_prefix}git #{cmd}#{redirect}`.chomp()
+            abort_if_err(catch_err, $?, ret)
             return ret
         end
 
         # Run a git command interactively
         #
         # @param cmd [String] Git command arguments
-        # @param opts [Hash] Options (e.g., :env)
-        # @param check_err [Boolean] Raise error on failure
+        # @param env [String, nil] Environment variable prefix (e.g., "FOO=bar")
+        # @param catch_err [Boolean] If true, do not raise error on failure
+        # @param silent_err [Boolean] If true, redirect stderr to /dev/null
         # @return [Boolean] Command success status
-        # @raise [StandardError] If command fails and check_err is true
-        def runGitInteractive(cmd, opts={}, check_err = true)
+        # @raise [StandardError] If command fails and catch_err is false
+        def runGitInteractive(cmd, env: nil, catch_err: false, silent_err: false)
             cmd_debug('git interactive', cmd)
-            ret = system("cd #{@path} && #{opts[:env]} git #{cmd}")
-            abort_if_err(check_err, $?)
+            env_prefix = env ? "#{env} " : ""
+            redirect = silent_err ? " 2>/dev/null" : ""
+            ret = system("cd #{@path} && #{env_prefix}git #{cmd}#{redirect}")
+            abort_if_err(catch_err, $?)
             return ret
         end
 

data/lib/cli_class_tool/string.rb

@@ -139,4 +139,28 @@ class String
     def light_white
         colorize(97)
     end
+
+    # Wrap the string in an OSC 8 terminal hyperlink if stdout is a TTY.
+    #
+    # @param url [String, #to_s, nil] Target URL for the hyperlink.
+    # @return [String] The formatted terminal hyperlink, or original string if not a TTY or URL is nil/empty.
+    def hyperlink(url)
+        @@is_a_tty = $stdout.isatty() if @@is_a_tty == nil
+        if @@is_a_tty && url && !url.to_s.empty?
+            "\e]8;;#{url}\e\\#{self}\e]8;;\e\\"
+        else
+            self
+        end
+    end
+
+    # Compute the visible length of the string
+    # Without any of ANSI/ASCII control characters nor embedded hyperlinks
+    #
+    # @return [Integer] Visible string length
+    def visible_length()
+        return self.gsub(/\e\]8;.*?(?:\e\\|\a)/, "") # Removes opening and closing hyperlink tags
+                   .gsub(/\e\[[0-9;?]*[a-zA-Z]/, "") # Removes ANSI escape codes (colors, cursor control)
+                   .gsub(/[[:cntrl:]]/, "")          # Removes any residual control characters
+                   .length
+    end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: cli_class_tool
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Nicolas Morey
 bindir: bin
 cert_chain: []
-date: 2026-09-09 00:00:00.000000000 Z
+date: 2026-09-25 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.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: A lightweight object-oriented framework for class-based command-line interface
   (CLI) applications.