clamp 1.4.0 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f0997bf253dd4d01c04923a7d5f9dcea232a076605a3129e0b1e90d5514ff6f
-  data.tar.gz: af6938afdf7acdc0e513b7549ae5479c276b3457f7ced04bf55ad06dc89747a6
+  metadata.gz: d0987845ae98be0a62e6501a780e42f4e73826df831d5d3809e17c8f8d335db2
+  data.tar.gz: 07665f169706158283c5e3d5fa9e231d668fa7105b8f4726e46f801679173071
 SHA512:
-  metadata.gz: 8c8a6136a3e4463c2099381a712ffd1625f4aca300d8d43ca28fc1a7b7b380b95477ba7ba7d5ffab6d89181aedf5e47fe234bcdcb29b358c191b9834a35dfaf6
-  data.tar.gz: abdede290dd091cc2d26e79c40e2c65486cefd0c5b29918c44c9fdee1e25bf127cfb4744ddcdbcb2488d75cc46bed5e9b06f6de35c922e5a3491b2d1469d7014
+  metadata.gz: 1a2b310ce3f8a1e2cd0bb100abf9a1fec7b8dc36ad639f4b2007824136dd77409d460a2305d36fba0c11999c5e8620406fef5326ab749e31505809631671ee0e
+  data.tar.gz: 3fbc558438ae5dd809e60562a9b799c034a3bbbf620eeb77a7cec2ca0c8eb4dd35a86330214a94bde6c22a449974527dc480c9d4278774af0dacb0212a6556fe

data/CHANGES.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.5.1 (2026-03-11)
+
+* Fix shell completion scripts: required parameters, subcommand aliases, and option value handling.
+
+## 1.5.0 (2026-03-03)
+
+* Add `--shell-completions` support.
+
 ## 1.4.0 (2026-02-09)
 
 * Add support for Ruby 4.0.

data/README.md

@@ -413,6 +413,50 @@ Options:
     -h, --help                    print help
 ```
 
+## Shell completion
+
+Clamp can generate shell completion scripts for bash, zsh, and fish. This is an opt-in feature:
+
+```ruby
+require 'clamp/completion'
+```
+
+This adds a hidden `--shell-completions` option to all commands. Use it to generate a completion script:
+
+```sh
+$ myapp --shell-completions bash   # or: zsh, fish
+```
+
+### Activating completions
+
+For **bash**, add to your `~/.bashrc`:
+
+```sh
+eval "$(myapp --shell-completions bash)"
+```
+
+For **zsh**, add to your `~/.zshrc`:
+
+```sh
+eval "$(myapp --shell-completions zsh)"
+```
+
+For **fish**, add to your `~/.config/fish/config.fish`:
+
+```sh
+myapp --shell-completions fish | source
+```
+
+### Programmatic API
+
+You can also generate completion scripts programmatically:
+
+```ruby
+script = MyCommand.generate_completion(:fish, "myapp")
+```
+
+This returns the completion script as a string, which you can write to a file or use however you like.
+
 ## Localization
 
 Clamp comes with support for overriding strings with custom translations. You can use localization library of your choice and override the strings at startup.

data/examples/gitdown

@@ -4,6 +4,7 @@
 # Demonstrate how subcommands can be declared as classes
 
 require "clamp"
+require "clamp/completion"
 
 module GitDown
 

data/lib/clamp/completion/bash_generator.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module Clamp
+  module Completion
+
+    # Generates bash shell completion scripts.
+    #
+    class BashGenerator
+
+      def initialize(command_class, executable_name)
+        @command_class = command_class
+        @executable_name = executable_name
+      end
+
+      def generate
+        [
+          "# Bash completions for #{@executable_name}",
+          "# Generated by Clamp",
+          "",
+          takes_value_function,
+          "",
+          param_count_function,
+          "",
+          canonical_function,
+          "",
+          main_function,
+          "",
+          "complete -F #{completion_function} #{@executable_name}"
+        ].push("").join("\n")
+      end
+
+      private
+
+      def completion_function
+        "_clamp_complete_#{Completion.encode_name(@executable_name)}"
+      end
+
+      def main_function
+        [
+          "#{completion_function}() {",
+          "    local cur prev",
+          "    if type _init_completion &>/dev/null; then",
+          "        _init_completion",
+          "    else",
+          '        cur="${COMP_WORDS[COMP_CWORD]}"',
+          '        prev="${COMP_WORDS[COMP_CWORD-1]}"',
+          "    fi",
+          "",
+          "    local subcmd_info subcmd params_remaining",
+          "    subcmd_info=$(#{completion_function}_find_subcmd)",
+          '    subcmd="${subcmd_info%% *}"',
+          '    params_remaining="${subcmd_info##* }"',
+          "    if #{completion_function}_takes_value \"$prev\" \"$subcmd\"; then",
+          "        return",
+          "    fi",
+          "",
+          options_case("$subcmd"),
+          "",
+          '    if [ "$params_remaining" -eq 0 ]; then',
+          subcommands_case("$subcmd"),
+          "    fi",
+          "}",
+          "",
+          find_subcmd_function
+        ].join("\n")
+      end
+
+      def find_subcmd_function
+        [
+          "#{completion_function}_find_subcmd() {",
+          "    local i=1 word subcmd skip",
+          "    skip=$(#{completion_function}_param_count \"\")",
+          '    while [ "$i" -lt "$COMP_CWORD" ]; do',
+          '        word="${COMP_WORDS[$i]}"',
+          '        case "$word" in',
+          "            -*)",
+          "                if #{completion_function}_takes_value \"$word\" \"$subcmd\"; then",
+          "                    ((i++))",
+          "                fi",
+          "                ;;",
+          "            *)",
+          find_subcmd_match_word,
+          "                ;;",
+          "        esac",
+          "        ((i++))",
+          "    done",
+          '    echo "$subcmd $skip"',
+          "}"
+        ].join("\n")
+      end
+
+      def find_subcmd_match_word
+        subcmds = Completion.collect_subcommand_names(@command_class).join("|")
+        [
+          '                if [ "$skip" -gt 0 ]; then',
+          "                    ((skip--))",
+          "                else",
+          '                    case "$word" in',
+          "                        #{subcmds})",
+          "                            local canonical=$(#{completion_function}_canonical \"$word\")",
+          '                            if [ -z "$subcmd" ]; then',
+          '                                subcmd="$canonical"',
+          "                            else",
+          '                                subcmd="${subcmd}::${canonical}"',
+          "                            fi",
+          "                            skip=$(#{completion_function}_param_count \"$subcmd\")",
+          "                            ;;",
+          "                    esac",
+          "                fi"
+        ].join("\n")
+      end
+
+      def options_case(var)
+        build_case(var, "    ", "COMPREPLY=") do |cmd, _has_children|
+          Completion.visible_options(cmd).flat_map { |o| Completion.expanded_switches(o) }
+        end
+      end
+
+      def subcommands_case(var)
+        build_case(var, "        ", "COMPREPLY+=") do |cmd, has_children|
+          cmd.recognised_subcommands.flat_map(&:names) if has_children
+        end
+      end
+
+      def build_case(var, indent, assign)
+        entries = {}
+        Completion.walk_command_tree(@command_class) do |cmd, path, has_children|
+          words = yield(cmd, has_children)
+          next if words.nil? || words.empty?
+
+          path_str = path.map { |sub| sub.names.first }.join("::")
+          entries[path_str] = words.join(" ")
+        end
+        lines = ["#{indent}case \"#{var}\" in"]
+        entries.each do |path, words|
+          pattern = path.empty? ? '""' : "\"#{path}\""
+          lines << "#{indent}    #{pattern})"
+          lines << "#{indent}        #{assign}($(compgen -W \"#{words}\" -- \"$cur\"))"
+          lines << "#{indent}        ;;"
+        end
+        lines << "#{indent}esac"
+        lines.join("\n")
+      end
+
+      def param_count_function
+        entries = {}
+        Completion.walk_command_tree(@command_class) do |cmd, path, has_children|
+          next unless has_children
+
+          entries[path.map { |s| s.names.first }.join("::")] = Completion.required_parameter_count(cmd)
+        end
+        build_lookup_function("param_count", entries, "echo", default: "echo 0")
+      end
+
+      def canonical_function
+        aliases = {}
+        Completion.walk_command_tree(@command_class) do |cmd, _path, has_children|
+          next unless has_children
+
+          cmd.recognised_subcommands.each do |sub|
+            sub.names.drop(1).each { |name| aliases[name] = sub.names.first }
+          end
+        end
+        build_lookup_function("canonical", aliases, "echo", default: 'echo "$1"')
+      end
+
+      def build_lookup_function(suffix, entries, verb, default:)
+        lines = ["#{completion_function}_#{suffix}() {", '    case "$1" in']
+        entries.each do |key, value|
+          pattern = key.empty? ? '""' : key
+          lines << "        #{pattern}) #{verb} #{value.is_a?(String) ? "\"#{value}\"" : value} ;;"
+        end
+        lines.push("        *) #{default} ;;", "    esac", "}")
+        lines.join("\n")
+      end
+
+      def takes_value_function
+        entries = {}
+        Completion.walk_command_tree(@command_class) do |cmd, path, _has_children|
+          path_str = path.map { |sub| sub.names.first }.join("::")
+          entries[path_str] = Completion.visible_options(cmd).reject(&:flag?)
+                                        .flat_map { |o| Completion.expanded_switches(o) }
+        end
+        lines = [
+          "#{completion_function}_takes_value() {",
+          '    local option="$1"',
+          '    local subcmd="$2"',
+          '    case "$subcmd" in'
+        ]
+        entries.each do |path, switches|
+          next if switches.empty?
+
+          pattern = path.empty? ? '""' : "\"#{path}\""
+          lines << "        #{pattern})"
+          lines << '            case "$option" in'
+          lines << "                #{switches.join('|')}) return 0 ;;"
+          lines << "            esac"
+          lines << "            ;;"
+        end
+        lines.push("    esac", "    return 1", "}")
+        lines.join("\n")
+      end
+
+    end
+
+  end
+end

data/lib/clamp/completion/fish_generator.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Clamp
+  module Completion
+
+    # Generates fish shell completion scripts.
+    class FishGenerator
+
+      def initialize(command_class, executable_name)
+        @command_class = command_class
+        @executable_name = executable_name
+      end
+
+      def generate
+        lines = []
+        lines << "# Fish completions for #{@executable_name}"
+        lines << "# Generated by Clamp"
+        lines << ""
+        helpers = [subcmd_args_function]
+        Completion.walk_command_tree(@command_class) do |cmd, path, has_children|
+          child_names = has_children ? cmd.recognised_subcommands.flat_map(&:names) : []
+          condition = condition_for(path, child_names)
+          Completion.visible_options(cmd).each do |option|
+            lines << option_completion(option, condition)
+          end
+          next unless has_children
+
+          subcmd_condition = subcommand_condition(cmd, path, condition, helpers)
+          generate_subcommand_completions(lines, cmd, subcmd_condition)
+          lines << ""
+        end
+        "#{helpers.join("\n\n")}\n\n#{lines.join("\n")}\n"
+      end
+
+      private
+
+      def subcommand_condition(cmd, path, condition, helpers)
+        param_count = Completion.required_parameter_count(cmd)
+        return condition unless param_count.positive?
+
+        helper = ParamsSatisfiedHelper.new(@executable_name, path, param_count)
+        helpers << helper.to_s
+        "#{condition}; and #{helper.function_name}"
+      end
+
+      def generate_subcommand_completions(lines, cmd, condition)
+        cmd.recognised_subcommands.each do |sub|
+          sub.names.each do |name|
+            lines << "complete -c #{@executable_name} -f -n '#{condition}' -a #{name} " \
+                     "-d '#{escape(sub.description)}'"
+          end
+        end
+      end
+
+      def condition_for(path, child_names)
+        if path.empty?
+          "not #{completion_function}_subcmd_args >/dev/null"
+        else
+          parts = path.map { |sub| "#{completion_function}_seen_subcommand_from #{sub.names.join(' ')}" }
+          parts << "not #{completion_function}_seen_subcommand_from #{child_names.join(' ')}" if child_names.any?
+          parts.join("; and ")
+        end
+      end
+
+      def completion_function
+        "_clamp_complete_#{@executable_name}"
+      end
+
+      def subcmd_args_function
+        optspecs = argparse_optspecs(@command_class)
+        lines = [
+          "function #{completion_function}_subcmd_args",
+          "    set -l tokens (commandline -opc)",
+          "    set -e tokens[1]",
+          "    argparse -si #{optspecs.map { |s| "'#{s}'" }.join(' ')} -- $tokens 2>/dev/null",
+          "    or return 1",
+          "    test (count $argv) -gt 0",
+          "    and printf '%s\\n' $argv",
+          "end",
+          "",
+          "function #{completion_function}_seen_subcommand_from",
+          "    for p in (#{completion_function}_subcmd_args)",
+          "        if contains -- $p $argv",
+          "            return 0",
+          "        end",
+          "    end",
+          "    return 1",
+          "end"
+        ]
+        lines.join("\n")
+      end
+
+      def argparse_optspecs(command_class)
+        command_class.recognised_options.flat_map do |option|
+          Completion.argparse_specs_for(option)
+        end
+      end
+
+      def option_completion(option, condition)
+        parts = ["complete -c #{@executable_name} -f"]
+        parts << "-n '#{condition}'"
+
+        Completion.expanded_switches(option).each do |switch|
+          parts << if switch.start_with?("--")
+                     "-l #{switch.sub(/^--/, '')}"
+                   else
+                     "-s #{switch.sub(/^-/, '')}"
+                   end
+        end
+
+        parts << "-r" unless option.flag?
+        parts << "-d '#{escape(option.description)}'"
+
+        parts.join(" ")
+      end
+
+      def escape(str)
+        str.gsub("'", "\\\\'")
+      end
+
+    end
+
+    # Generates a fish function that checks whether required parameters
+    # have been provided before offering subcommand completions.
+    class ParamsSatisfiedHelper
+
+      def initialize(executable_name, path, required_count)
+        @executable_name = executable_name
+        @path = path
+        @required_count = required_count
+      end
+
+      def function_name
+        parts = [@executable_name]
+        @path.each { |sub| parts << sub.names.first }
+        "_clamp_complete_#{parts.join('_')}_params_satisfied"
+      end
+
+      def to_s
+        lines = ["function #{function_name}", "    set -l tokens (commandline -opc)", "    set -l positional 0"]
+        if @path.empty?
+          count_positional_root(lines)
+        else
+          count_positional_nested(lines)
+        end
+        lines.push("    test $positional -ge #{@required_count}", "end")
+        lines.join("\n")
+      end
+
+      private
+
+      def count_positional_root(lines)
+        lines.push("    for token in $tokens[2..]",
+                   "        if not string match -q -- '-*' $token",
+                   "            set positional (math $positional + 1)",
+                   "        end", "    end")
+      end
+
+      def count_positional_nested(lines)
+        lines.push("    set -l depth 0", "    for token in $tokens[2..]", "        switch $depth")
+        @path.each_with_index do |sub, i|
+          all_names = sub.names.join(" ")
+          lines.push("            case #{i}",
+                     "                if contains -- $token #{all_names}",
+                     "                    set depth #{i + 1}", "                end")
+        end
+        lines.push("            case #{@path.length}",
+                   "                if not string match -q -- '-*' $token",
+                   "                    set positional (math $positional + 1)",
+                   "                end", "        end", "    end")
+      end
+
+    end
+
+  end
+end

data/lib/clamp/completion/zsh_generator.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Clamp
+  module Completion
+
+    # Generates zsh shell completion scripts.
+    #
+    class ZshGenerator
+
+      def initialize(command_class, executable_name)
+        @command_class = command_class
+        @executable_name = executable_name
+      end
+
+      def generate
+        lines = ["#compdef #{@executable_name}", ""]
+        generate_functions(lines, @command_class, [completion_function], Set.new)
+        lines << completion_function
+        lines.push("").join("\n")
+      end
+
+      private
+
+      def completion_function
+        "_clamp_complete_#{Completion.encode_name(@executable_name)}"
+      end
+
+      def generate_functions(lines, command_class, path, visited)
+        has_children = command_class.has_subcommands? && !visited.include?(command_class)
+        visited |= [command_class]
+        func_name = path.join("_")
+
+        if has_children
+          generate_subcommand_node(lines, command_class, path, func_name, visited)
+        else
+          lines << "#{func_name}() {"
+          specs = Completion.visible_options(command_class).flat_map { |o| option_specs(o) }
+          generate_arguments_call(lines, specs) if specs.any?
+          lines << "}"
+          lines << ""
+        end
+      end
+
+      def generate_subcommand_node(lines, command_class, path, func_name, visited)
+        lines << "#{func_name}() {"
+        lines << "  local context state state_descr line"
+        lines << "  typeset -A opt_args"
+        lines << ""
+        specs = Completion.visible_options(command_class).flat_map { |o| option_specs(o) }
+        specs << "'1:command:->commands'"
+        specs << "'*::args:->args'"
+        lines << "  _arguments -C \\"
+        generate_spec_lines(lines, specs)
+        lines << ""
+        generate_state_dispatch(lines, command_class, path)
+        lines << "}"
+        lines << ""
+        command_class.recognised_subcommands.each do |sub|
+          generate_functions(lines, sub.subcommand_class, path + [Completion.encode_name(sub.names.first)], visited)
+        end
+      end
+
+      def generate_arguments_call(lines, specs)
+        lines << "  _arguments \\"
+        generate_spec_lines(lines, specs)
+      end
+
+      def generate_spec_lines(lines, specs)
+        specs.each_with_index do |spec, i|
+          suffix = i < specs.length - 1 ? " \\" : ""
+          lines << "    #{spec}#{suffix}"
+        end
+      end
+
+      def generate_state_dispatch(lines, command_class, path)
+        lines << "  case $state in"
+        lines << "    commands)"
+        lines << "      local -a cmds"
+        lines << "      cmds=("
+        command_class.recognised_subcommands.each do |sub|
+          sub.names.each do |name|
+            lines << "        '#{escape(name)}:#{escape(sub.description)}'"
+          end
+        end
+        lines << "      )"
+        lines << "      _describe 'command' cmds"
+        lines << "      ;;"
+        lines << "    args)"
+        lines << "      case $line[1] in"
+        command_class.recognised_subcommands.each do |sub|
+          sub_fn = (path + [Completion.encode_name(sub.names.first)]).join("_")
+          pattern = sub.names.join("|")
+          lines << "        #{pattern}) #{sub_fn} ;;"
+        end
+        lines << "      esac"
+        lines << "      ;;"
+        lines << "  esac"
+      end
+
+      def option_specs(option)
+        expanded = Completion.expanded_switches(option)
+        suffix = "[#{escape(option.description)}]"
+        suffix += ":#{option.type.to_s.downcase}:" unless option.flag?
+        exclusion = expanded.length > 1 ? "'(#{expanded.join(' ')})'" : ""
+        short = expanded.find { |s| s.match?(/^-[^-]/) }
+        longs = expanded.grep(/^--/)
+
+        if short && longs.length == 1
+          # Braces outside quotes for zsh brace expansion
+          ["#{exclusion}{#{short},#{longs.first}}'#{suffix}'"]
+        else
+          expanded.map { |sw| "#{exclusion}'#{sw}#{suffix}'" }
+        end
+      end
+
+      def escape(str)
+        str.gsub("'", "'\\''")
+      end
+
+    end
+
+  end
+end