clamp 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f0997bf253dd4d01c04923a7d5f9dcea232a076605a3129e0b1e90d5514ff6f
-  data.tar.gz: af6938afdf7acdc0e513b7549ae5479c276b3457f7ced04bf55ad06dc89747a6
+  metadata.gz: 8f2a9c7d404e87023cc8694e18498df5719974cd11e58663df640c08a0f87c3e
+  data.tar.gz: da2a65496e24eb9abc13eaddc370f31d3e5764a832c3d0a18015dd636e43dbfa
 SHA512:
-  metadata.gz: 8c8a6136a3e4463c2099381a712ffd1625f4aca300d8d43ca28fc1a7b7b380b95477ba7ba7d5ffab6d89181aedf5e47fe234bcdcb29b358c191b9834a35dfaf6
-  data.tar.gz: abdede290dd091cc2d26e79c40e2c65486cefd0c5b29918c44c9fdee1e25bf127cfb4744ddcdbcb2488d75cc46bed5e9b06f6de35c922e5a3491b2d1469d7014
+  metadata.gz: 7318c3498b2e425ecd18395e4ad3d24109e130bac38f9f9406fba97b02b8b78d859374f5e1439a064dff1e4037b2cab2df8210a13a9ea54cac030df8b35e86c8
+  data.tar.gz: 5f46c6724d06d2fa30425369a1867f0e2199e05997d796142af125dad5369a08c444f5a06fb15c2ad206b8e62afcb582fe1442c36fbe7ce994fa7d8400f71993

data/CHANGES.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 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,141 @@
+# 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,
+          "",
+          completion_function,
+          "",
+          "complete -F _#{function_name} #{@executable_name}"
+        ].push("").join("\n")
+      end
+
+      private
+
+      def function_name
+        @executable_name.gsub(/[^a-zA-Z0-9_]/, "_")
+      end
+
+      def completion_function
+        fn = function_name
+        [
+          "_#{fn}() {",
+          "    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",
+          "    subcmd=$(__#{fn}_find_subcmd)",
+          "    if __#{fn}_takes_value \"$prev\" \"$subcmd\"; then",
+          "        return",
+          "    fi",
+          "",
+          completions_case("$subcmd"),
+          "}",
+          "",
+          find_subcmd_function
+        ].join("\n")
+      end
+
+      def find_subcmd_function
+        fn = function_name
+        subcmds = Completion.collect_subcommand_names(@command_class).join("|")
+        [
+          "__#{fn}_find_subcmd() {",
+          "    local i=1 word subcmd",
+          '    while [ "$i" -lt "$COMP_CWORD" ]; do',
+          '        word="${COMP_WORDS[$i]}"',
+          '        case "$word" in',
+          "            -*)",
+          "                if __#{fn}_takes_value \"$word\" \"$subcmd\"; then",
+          "                    ((i++))",
+          "                fi",
+          "                ;;",
+          "            *)",
+          '                case "$word" in',
+          "                    #{subcmds})",
+          '                        if [ -z "$subcmd" ]; then',
+          '                            subcmd="$word"',
+          "                        else",
+          '                            subcmd="${subcmd}::${word}"',
+          "                        fi",
+          "                        ;;",
+          "                esac",
+          "                ;;",
+          "        esac",
+          "        ((i++))",
+          "    done",
+          '    echo "$subcmd"',
+          "}"
+        ].join("\n")
+      end
+
+      def completions_case(var)
+        entries = {}
+        Completion.walk_command_tree(@command_class) do |cmd, path, has_children|
+          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"]
+        entries.each do |path, words|
+          pattern = path.empty? ? '""' : "\"#{path}\""
+          lines << "        #{pattern})"
+          lines << "            COMPREPLY=($(compgen -W \"#{words}\" -- \"$cur\"))"
+          lines << "            ;;"
+        end
+        lines << "    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 = [
+          "__#{function_name}_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,75 @@
+# 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 << ""
+        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
+
+          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
+          lines << ""
+        end
+        "#{lines.join("\n")}\n"
+      end
+
+      private
+
+      def condition_for(path, child_names)
+        if path.empty?
+          "__fish_use_subcommand"
+        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.join("; and ")
+        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
+
+  end
+end

data/lib/clamp/completion/zsh_generator.rb

@@ -0,0 +1,126 @@
+# 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, [function_name], Set.new)
+        lines << "_#{function_name}"
+        lines.push("").join("\n")
+      end
+
+      private
+
+      def function_name
+        @executable_name.gsub(/[^a-zA-Z0-9_]/, "_")
+      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).map { |o| option_spec(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).map { |o| option_spec(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 + [sanitize(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 + [sanitize(sub.names.first)]).join('_')}"
+          pattern = sub.names.join("|")
+          lines << "        #{pattern}) #{sub_fn} ;;"
+        end
+        lines << "      esac"
+        lines << "      ;;"
+        lines << "  esac"
+      end
+
+      def option_spec(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_]/, "_")
+      end
+
+      def escape(str)
+        str.gsub("'", "'\\''")
+      end
+
+    end
+
+  end
+end

data/lib/clamp/completion.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "clamp/command"
+require "clamp/completion/bash_generator"
+require "clamp/completion/fish_generator"
+require "clamp/completion/zsh_generator"
+
+module Clamp
+
+  # Shell completion script generation.
+  #
+  module Completion
+
+    GENERATORS = {
+      bash: Clamp::Completion::BashGenerator,
+      fish: Clamp::Completion::FishGenerator,
+      zsh: Clamp::Completion::ZshGenerator
+    }.freeze
+
+    # Raised when --shell-completions is used; caught by Command.run.
+    #
+    class Wanted < StandardError
+
+      def initialize(command, shell)
+        super("completion requested")
+        @command = command
+        @shell = shell
+      end
+
+      attr_reader :command, :shell
+
+    end
+
+    module_function
+
+    def generate(command_class, shell, executable_name)
+      generator_class = GENERATORS.fetch(shell) do
+        raise ArgumentError, "unsupported shell: #{shell.inspect}"
+      end
+      generator_class.new(command_class, executable_name).generate
+    end
+
+    # Return switches with --[no-]foo expanded to --foo and --no-foo.
+    def expanded_switches(option)
+      option.switches.flat_map do |switch|
+        if switch =~ /^--\[no-\](.*)/
+          ["--#{Regexp.last_match(1)}", "--no-#{Regexp.last_match(1)}"]
+        else
+          switch
+        end
+      end
+    end
+
+    # Options visible in completion (excludes hidden).
+    def visible_options(command_class)
+      command_class.recognised_options.reject(&:hidden?)
+    end
+
+    # Walk the command tree depth-first, yielding (command_class, path, has_children).
+    # Path is an array of Subcommand::Definition objects.
+    # Always yields, even for revisited classes (with has_children=false).
+    def walk_command_tree(command_class, path = [], visited = Set.new, &block)
+      fresh = !visited.include?(command_class)
+      visited |= [command_class]
+      has_children = command_class.has_subcommands? && fresh
+      yield command_class, path, has_children
+      return unless has_children
+
+      command_class.recognised_subcommands.each do |sub|
+        walk_command_tree(sub.subcommand_class, path + [sub], visited, &block)
+      end
+    end
+
+    # Collect all subcommand names across the command tree.
+    def collect_subcommand_names(command_class)
+      names = []
+      walk_command_tree(command_class) do |cmd, _path, has_children|
+        cmd.recognised_subcommands.each { |sub| names.concat(sub.names) } if has_children
+      end
+      names.uniq
+    end
+
+  end
+end
+
+module Clamp
+
+  # Reopened to add completion support.
+  #
+  class Command
+
+    def self.generate_completion(shell, executable_name)
+      Clamp::Completion.generate(self, shell, executable_name)
+    end
+
+    # Adds --shell-completions option and handles the Wanted exception.
+    #
+    module RunWithCompletion
+
+      def run(invocation_path = File.basename($PROGRAM_NAME), arguments = ARGV, context = {})
+        context[:root_command_class] ||= self
+        super
+      rescue Clamp::Completion::Wanted => e
+        shell_name = File.basename(e.shell).to_sym
+        begin
+          puts generate_completion(shell_name, invocation_path)
+        rescue ArgumentError => ex
+          $stderr.puts "ERROR: #{ex.message}"
+          exit(1)
+        end
+      end
+
+    end
+
+    class << self
+
+      prepend RunWithCompletion
+
+    end
+
+  end
+
+end
+
+module Clamp
+  module Option
+
+    # Adds implicit --shell-completions option to all commands.
+    #
+    module Declaration
+
+      # Declares --shell-completions alongside other implicit options.
+      #
+      module WithCompletionOption
+
+        def recognised_options
+          unless @implicit_completion_option_declared
+            @implicit_completion_option_declared = true
+            declare_implicit_completion_option
+          end
+          super
+        end
+
+        private
+
+        def declare_implicit_completion_option
+          return if effective_options.find { |o| o.handles?("--shell-completions") }
+
+          option "--shell-completions", "SHELL",
+                 "generate shell completion script",
+                 hidden: true do |shell|
+            raise Clamp::Completion::Wanted.new(self, shell)
+          end
+        end
+
+      end
+
+      prepend WithCompletionOption
+
+    end
+
+  end
+end

data/lib/clamp/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clamp
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Mike Williams
@@ -17,20 +17,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".autotest"
-- ".editorconfig"
-- ".github/workflows/ci.yml"
-- ".gitignore"
-- ".rspec"
-- ".rubocop.yml"
 - CHANGES.md
-- CODEOWNERS
-- Gemfile
-- Guardfile
 - LICENSE
 - README.md
-- Rakefile
-- clamp.gemspec
 - examples/admin
 - examples/defaulted
 - examples/flipflop
@@ -45,6 +34,10 @@ files:
 - lib/clamp/attribute/definition.rb
 - lib/clamp/attribute/instance.rb
 - lib/clamp/command.rb
+- lib/clamp/completion.rb
+- lib/clamp/completion/bash_generator.rb
+- lib/clamp/completion/fish_generator.rb
+- lib/clamp/completion/zsh_generator.rb
 - lib/clamp/errors.rb
 - lib/clamp/help.rb
 - lib/clamp/messages.rb
@@ -60,15 +53,6 @@ files:
 - lib/clamp/subcommand/parsing.rb
 - lib/clamp/truthy.rb
 - lib/clamp/version.rb
-- spec/clamp/command_group_spec.rb
-- spec/clamp/command_option_module_spec.rb
-- spec/clamp/command_option_reordering_spec.rb
-- spec/clamp/command_spec.rb
-- spec/clamp/help/builder_spec.rb
-- spec/clamp/messages_spec.rb
-- spec/clamp/option/definition_spec.rb
-- spec/clamp/parameter/definition_spec.rb
-- spec/spec_helper.rb
 homepage: https://github.com/mdub/clamp
 licenses:
 - MIT

data/.autotest

@@ -1,11 +0,0 @@
-require "autotest/bundler"
-
-Autotest.add_hook :initialize do |at|
-
-  at.add_exception ".git"
-
-  at.add_mapping(%r{^lib/(.*)\.rb$}, :prepend) do |_, match|
-    ["spec/unit/#{match[1]}_spec.rb"] + Dir['spec/clamp/command*_spec.rb']
-  end
-
-end

data/.editorconfig

@@ -1,10 +0,0 @@
-root = true
-
-[*]
-indent_style = space
-indent_size = 2
-end_of_line = lf
-charset = utf-8
-trim_trailing_whitespace = true
-insert_final_newline = true
-max_line_length = 120