clamp 1.5.0 → 1.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f2a9c7d404e87023cc8694e18498df5719974cd11e58663df640c08a0f87c3e
-  data.tar.gz: da2a65496e24eb9abc13eaddc370f31d3e5764a832c3d0a18015dd636e43dbfa
+  metadata.gz: ceef639e7f7761b30abc7be04ab5384ee2dc238ba472a12c808e2cdffc14e540
+  data.tar.gz: 7f97fc3d84a9fad89123fad6ed35dffeb37efc9e82815a44a6ca76ad134905ec
 SHA512:
-  metadata.gz: 7318c3498b2e425ecd18395e4ad3d24109e130bac38f9f9406fba97b02b8b78d859374f5e1439a064dff1e4037b2cab2df8210a13a9ea54cac030df8b35e86c8
-  data.tar.gz: 5f46c6724d06d2fa30425369a1867f0e2199e05997d796142af125dad5369a08c444f5a06fb15c2ad206b8e62afcb582fe1442c36fbe7ce994fa7d8400f71993
+  metadata.gz: 886c0eb9476e36c0c46e07812a412108f8575799f2a1b5588d0e6ed6feac5d7d8fe25ea27a1b8c4e244e691a62a9c502f0ecdb848eb56022cf48004f353d11ed
+  data.tar.gz: 18cc7167ae022ea13afd50b2367e47f5a9832e67d3754c683077125d4eaa99e75efba69b736fd327173ce9b2662f16be43bdbf53eea33f17b409703579f11b03

data/CHANGES.md

@@ -1,5 +1,9 @@
 # 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.

data/lib/clamp/completion/bash_generator.rb

@@ -19,22 +19,25 @@ module Clamp
           "",
           takes_value_function,
           "",
-          completion_function,
+          param_count_function,
           "",
-          "complete -F _#{function_name} #{@executable_name}"
+          canonical_function,
+          "",
+          main_function,
+          "",
+          "complete -F #{completion_function} #{@executable_name}"
         ].push("").join("\n")
       end
 
       private
 
-      def function_name
-        @executable_name.gsub(/[^a-zA-Z0-9_]/, "_")
+      def completion_function
+        "_clamp_complete_#{Completion.encode_name(@executable_name)}"
       end
 
-      def completion_function
-        fn = function_name
+      def main_function
         [
-          "_#{fn}() {",
+          "#{completion_function}() {",
           "    local cur prev",
           "    if type _init_completion &>/dev/null; then",
           "        _init_completion",
@@ -43,13 +46,21 @@ module Clamp
           '        prev="${COMP_WORDS[COMP_CWORD-1]}"',
           "    fi",
           "",
-          "    local subcmd",
-          "    subcmd=$(__#{fn}_find_subcmd)",
-          "    if __#{fn}_takes_value \"$prev\" \"$subcmd\"; then",
+          "    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",
           "",
-          completions_case("$subcmd"),
+          '    if [[ "$cur" == -* ]]; then',
+          options_case("$subcmd"),
+          "    fi",
+          "",
+          '    if [ "$params_remaining" -eq 0 ]; then',
+          subcommands_case("$subcmd"),
+          "    fi",
           "}",
           "",
           find_subcmd_function
@@ -57,54 +68,111 @@ module Clamp
       end
 
       def find_subcmd_function
-        fn = function_name
-        subcmds = Completion.collect_subcommand_names(@command_class).join("|")
         [
-          "__#{fn}_find_subcmd() {",
-          "    local i=1 word subcmd",
+          "#{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 __#{fn}_takes_value \"$word\" \"$subcmd\"; then",
+          "                if #{completion_function}_takes_value \"$word\" \"$subcmd\"; then",
           "                    ((i++))",
           "                fi",
           "                ;;",
           "            *)",
-          '                case "$word" in',
-          "                    #{subcmds})",
-          '                        if [ -z "$subcmd" ]; then',
-          '                            subcmd="$word"',
-          "                        else",
-          '                            subcmd="${subcmd}::${word}"',
-          "                        fi",
-          "                        ;;",
-          "                esac",
+          find_subcmd_match_word,
           "                ;;",
           "        esac",
           "        ((i++))",
           "    done",
-          '    echo "$subcmd"',
+          '    echo "$subcmd $skip"',
           "}"
         ].join("\n")
       end
 
-      def completions_case(var)
+      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("::")
-          words = Completion.visible_options(cmd).flat_map { |o| Completion.expanded_switches(o) }
-          cmd.recognised_subcommands.each { |sub| words.concat(sub.names) } if has_children
           entries[path_str] = words.join(" ")
         end
-        lines = ["    case \"#{var}\" in"]
+        lines = ["#{indent}case \"#{var}\" in"]
         entries.each do |path, words|
           pattern = path.empty? ? '""' : "\"#{path}\""
-          lines << "        #{pattern})"
-          lines << "            COMPREPLY=($(compgen -W \"#{words}\" -- \"$cur\"))"
-          lines << "            ;;"
+          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 << "    esac"
+        lines.push("        *) #{default} ;;", "    esac", "}")
         lines.join("\n")
       end
 
@@ -116,7 +184,7 @@ module Clamp
                                         .flat_map { |o| Completion.expanded_switches(o) }
         end
         lines = [
-          "__#{function_name}_takes_value() {",
+          "#{completion_function}_takes_value() {",
           '    local option="$1"',
           '    local subcmd="$2"',
           '    case "$subcmd" in'

data/lib/clamp/completion/fish_generator.rb

@@ -16,40 +16,119 @@ module Clamp
         lines << "# Fish completions for #{@executable_name}"
         lines << "# Generated by Clamp"
         lines << ""
+        helpers = [subcmd_args_function]
+
+        # Track visible option switches at each depth, so we can identify
+        # which options are new at each level. Depth-first walk order means
+        # the entry at depth N-1 is always the current node's parent.
+        switches_at_depth = []
+
         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
+          generate_option_completions(lines, cmd, path, switches_at_depth)
+
           next unless has_children
 
-          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
+          # Subcommand names need an exclusive condition (only at this level).
+          child_names = cmd.recognised_subcommands.flat_map(&:names)
+          exclusive_cond = condition_for(path, child_names)
+          subcmd_cond = subcommand_condition(cmd, path, exclusive_cond, helpers)
+          generate_subcommand_completions(lines, cmd, subcmd_cond)
           lines << ""
         end
-        "#{lines.join("\n")}\n"
+        "#{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
+
+      # Emit only options new at this level (not inherited from parent).
+      # Use an inclusive condition so they also apply to child subcommands.
+      def generate_option_completions(lines, cmd, path, switches_at_depth)
+        depth = path.length
+        visible = Completion.visible_options(cmd)
+        parent_switches = depth.positive? ? switches_at_depth[depth - 1] : nil
+        new_options = if parent_switches
+                        visible.reject { |o| parent_switches.include?(o.switches) }
+                      else
+                        visible
+                      end
+        option_cond = depth.positive? ? inclusive_condition_for(path) : nil
+        new_options.each do |option|
+          lines << option_completion(option, option_cond)
+        end
+        switches_at_depth[depth] = Set.new(visible.map(&:switches))
+      end
+
+      # Condition that matches this level AND all child subcommands.
+      def inclusive_condition_for(path)
+        path.map { |sub| "#{completion_function}_seen_subcommand_from #{sub.names.join(' ')}" }.join("; and ")
+      end
+
+      # Condition that matches this level only (excludes child subcommands).
       def condition_for(path, child_names)
         if path.empty?
-          "__fish_use_subcommand"
+          "not #{completion_function}_subcmd_args >/dev/null"
         else
-          parts = path.map { |sub| "__fish_seen_subcommand_from #{sub.names.join(' ')}" }
-          parts << "not __fish_seen_subcommand_from #{child_names.join(' ')}" if child_names.any?
+          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 option_completion(option, condition)
+      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 = nil)
         parts = ["complete -c #{@executable_name} -f"]
-        parts << "-n '#{condition}'"
+        parts << "-n '#{condition}'" if condition
 
         Completion.expanded_switches(option).each do |switch|
           parts << if switch.start_with?("--")
@@ -71,5 +150,57 @@ module Clamp
 
     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

@@ -14,27 +14,27 @@ module Clamp
 
       def generate
         lines = ["#compdef #{@executable_name}", ""]
-        generate_functions(lines, @command_class, [function_name], Set.new)
-        lines << "_#{function_name}"
+        generate_functions(lines, @command_class, [completion_function], Set.new)
+        lines << completion_function
         lines.push("").join("\n")
       end
 
       private
 
-      def function_name
-        @executable_name.gsub(/[^a-zA-Z0-9_]/, "_")
+      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('_')}"
+        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).map { |o| option_spec(o) }
+          specs = Completion.visible_options(command_class).flat_map { |o| option_specs(o) }
           generate_arguments_call(lines, specs) if specs.any?
           lines << "}"
           lines << ""
@@ -46,7 +46,7 @@ module Clamp
         lines << "  local context state state_descr line"
         lines << "  typeset -A opt_args"
         lines << ""
-        specs = Completion.visible_options(command_class).map { |o| option_spec(o) }
+        specs = Completion.visible_options(command_class).flat_map { |o| option_specs(o) }
         specs << "'1:command:->commands'"
         specs << "'*::args:->args'"
         lines << "  _arguments -C \\"
@@ -56,7 +56,7 @@ module Clamp
         lines << "}"
         lines << ""
         command_class.recognised_subcommands.each do |sub|
-          generate_functions(lines, sub.subcommand_class, path + [sanitize(sub.names.first)], visited)
+          generate_functions(lines, sub.subcommand_class, path + [Completion.encode_name(sub.names.first)], visited)
         end
       end
 
@@ -88,7 +88,7 @@ module Clamp
         lines << "    args)"
         lines << "      case $line[1] in"
         command_class.recognised_subcommands.each do |sub|
-          sub_fn = "_#{(path + [sanitize(sub.names.first)]).join('_')}"
+          sub_fn = (path + [Completion.encode_name(sub.names.first)]).join("_")
           pattern = sub.names.join("|")
           lines << "        #{pattern}) #{sub_fn} ;;"
         end
@@ -97,23 +97,20 @@ module Clamp
         lines << "  esac"
       end
 
-      def option_spec(option)
+      def option_specs(option)
         expanded = Completion.expanded_switches(option)
-        desc = "[#{escape(option.description)}]"
-        arg_spec = option.flag? ? "" : ":#{option.type.to_s.downcase}:"
-        exclusion = expanded.length > 1 ? "(#{expanded.join(' ')})" : ""
-
-        "'#{exclusion}#{switch_pattern(option.switches)}#{desc}#{arg_spec}'"
-      end
-
-      def switch_pattern(switches)
-        short = switches.find { |s| s =~ /^-[^-]/ }
-        long = switches.find { |s| s =~ /^--/ }
-        short && long ? "{#{short},#{long}}" : (long || short).to_s
-      end
-
-      def sanitize(name)
-        name.gsub(/[^a-zA-Z0-9_]/, "_")
+        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)

data/lib/clamp/completion.rb

@@ -33,6 +33,12 @@ module Clamp
 
     module_function
 
+    # Encode a name for use as a shell function identifier.
+    # Special characters are replaced with _XX hex codes.
+    def encode_name(name)
+      name.gsub(/[^a-zA-Z0-9_]/) { |c| format("_%02x", c.ord) }
+    end
+
     def generate(command_class, shell, executable_name)
       generator_class = GENERATORS.fetch(shell) do
         raise ArgumentError, "unsupported shell: #{shell.inspect}"
@@ -71,6 +77,24 @@ module Clamp
       end
     end
 
+    # Count required, non-multivalued parameters for a command.
+    def required_parameter_count(command_class)
+      command_class.parameters.count { |p| p.required? && !p.multivalued? }
+    end
+
+    # Return fish argparse optspecs for an option.
+    def argparse_specs_for(option)
+      switches = expanded_switches(option)
+      suffix = option.flag? ? "" : "="
+      short = switches.find { |s| s.match?(/^-[^-]$/) }
+      longs = switches.select { |s| s.start_with?("--") }
+      if short && longs.length == 1
+        ["#{short.delete_prefix('-')}/#{longs.first.delete_prefix('--')}#{suffix}"]
+      else
+        longs.map { |l| "#{l.delete_prefix('--')}#{suffix}" }
+      end
+    end
+
     # Collect all subcommand names across the command tree.
     def collect_subcommand_names(command_class)
       names = []

data/lib/clamp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Clamp
-  VERSION = "1.5.0"
+  VERSION = "1.5.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clamp
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.5.2
 platform: ruby
 authors:
 - Mike Williams