clamp 1.4.0 → 1.5.1

data/lib/clamp/completion.rb

@@ -0,0 +1,187 @@
+# 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
+
+    # 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}"
+      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
+
+    # 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 = []
+      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.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clamp
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.1
 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

data/.github/workflows/ci.yml

@@ -1,31 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [master]
-  pull_request:
-    branches: [master]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-
-    strategy:
-      fail-fast: false
-      matrix:
-        ruby-version:
-          - "3.1"
-          - "3.4"
-          - "4.0"
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Set up Ruby ${{ matrix.ruby-version }}
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: ${{ matrix.ruby-version }}
-          bundler-cache: true
-
-      - name: Run tests and linter
-        run: bundle exec rake

data/.gitignore

@@ -1,9 +0,0 @@
-*.gem
-.bundle
-.markdownlint*
-.rvmrc
-.ruby-version
-.yardoc
-doc
-pkg/*
-Gemfile.lock

data/.rspec

@@ -1,2 +0,0 @@
---color
---warnings

data/.rubocop.yml

@@ -1,74 +0,0 @@
-plugins:
-  - rubocop-rake
-  - rubocop-rspec
-
-AllCops:
-  TargetRubyVersion: 2.5
-  NewCops: enable
-
-Layout/LineLength:
-  Max: 120
-
-Layout/EmptyLinesAroundBlockBody:
-  Enabled: false
-
-Layout/EmptyLinesAroundClassBody:
-  EnforcedStyle: empty_lines
-
-Layout/EmptyLinesAroundModuleBody:
-  Enabled: false
-
-Metrics/AbcSize:
-  Enabled: false
-
-Metrics/BlockLength:
-  Exclude:
-    - "spec/**/*"
-
-Metrics/MethodLength:
-  Max: 30
-
-Naming/AccessorMethodName:
-  Enabled: false
-
-Naming/FileName:
-  Exclude:
-    - "bin/*"
-
-Naming/PredicatePrefix:
-  Enabled: false
-
-Style/ClassAndModuleChildren:
-  EnforcedStyle: nested
-  Exclude:
-    - "spec/**/*"
-
-Style/Documentation:
-  Exclude:
-    - "lib/**/version.rb"
-    - "examples/*"
-    - "spec/**/*"
-
-Style/Encoding:
-  Enabled: true
-
-Style/Lambda:
-  Enabled: false
-
-Style/NumericLiterals:
-  Enabled: false
-
-Style/StderrPuts:
-  Enabled: false
-
-Style/StringLiterals:
-  EnforcedStyle: double_quotes
-
-Style/WordArray:
-  Enabled: false
-
-RSpec/NestedGroups:
-  Enabled: false
-
-RSpec/Output:
-  Enabled: false

data/CODEOWNERS

@@ -1 +0,0 @@
-*	@mdub

data/Gemfile

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-source "https://rubygems.org"
-
-gemspec
-
-group :development do
-  gem "guard-rspec", "~> 4.7", require: false
-  gem "highline"
-  gem "listen", "~> 3.9"
-  gem "pry-byebug", "~> 3.11"
-  gem "rake", "~> 13.3"
-  gem "rubocop", "~> 1.84.1", require: false
-  gem "rubocop-rake", "~> 0.7.1", require: false
-  gem "rubocop-rspec", "~> 3.9.0", require: false
-end
-
-group :test do
-  gem "rspec", "~> 3.13"
-end

data/Guardfile

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-# A sample Guardfile
-# More info at https://github.com/guard/guard#readme
-
-## Uncomment and set this to only include directories you want to watch
-# directories %w(app lib config test spec features) \
-#  .select{|d| Dir.exists?(d) ? d : UI.warning("Directory #{d} does not exist")}
-
-## NOTE: if you are using the `directories` clause above and you are not
-## watching the project directory ('.'), then you will want to move
-## the Guardfile to a watched dir and symlink it back, e.g.
-#
-#  $ mkdir config
-#  $ mv Guardfile config/
-#  $ ln -s config/Guardfile .
-#
-# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
-
-# NOTE: The cmd option is now required due to the increasing number of ways
-#       rspec may be run, below are examples of the most common uses.
-#  * bundler: 'bundle exec rspec'
-#  * bundler binstubs: 'bin/rspec'
-#  * spring: 'bin/rspec' (This will use spring if running and you have
-#                          installed the spring binstubs per the docs)
-#  * zeus: 'zeus rspec' (requires the server to be started separately)
-#  * 'just' rspec: 'rspec'
-
-guard :rspec, cmd: "bundle exec rspec" do
-  require "guard/rspec/dsl"
-  dsl = Guard::RSpec::Dsl.new(self)
-
-  # Feel free to open issues for suggestions and improvements
-
-  # RSpec files
-  rspec = dsl.rspec
-  watch(rspec.spec_helper) { rspec.spec_dir }
-  watch(rspec.spec_support) { rspec.spec_dir }
-  watch(rspec.spec_files)
-
-  # Ruby files
-  ruby = dsl.ruby
-  dsl.watch_spec_files_for(ruby.lib_files)
-
-end

data/Rakefile

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler"
-
-Bundler::GemHelper.install_tasks
-
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new do |t|
-  t.pattern = "spec/**/*_spec.rb"
-  t.rspec_opts = ["--colour", "--format", "documentation"]
-end
-
-require "rubocop/rake_task"
-
-RuboCop::RakeTask.new
-
-task "default" => ["spec", "rubocop"]

data/clamp.gemspec

@@ -1,28 +0,0 @@
-# frozen_string_literal: true
-
-$LOAD_PATH.push File.expand_path("lib", __dir__)
-require "clamp/version"
-
-Gem::Specification.new do |s|
-
-  s.name          = "clamp"
-  s.version       = Clamp::VERSION.dup
-  s.platform      = Gem::Platform::RUBY
-  s.authors       = ["Mike Williams"]
-  s.email         = "mdub@dogbiscuit.org"
-  s.homepage      = "https://github.com/mdub/clamp"
-
-  s.license       = "MIT"
-
-  s.summary       = "a minimal framework for command-line utilities"
-  s.description   = <<-TEXT.gsub(/^\s+/, "")
-    Clamp provides an object-model for command-line utilities.
-    It handles parsing of command-line options, and generation of usage help.
-  TEXT
-
-  s.files         = `git ls-files`.split("\n")
-  s.require_paths = ["lib"]
-
-  s.required_ruby_version = ">= 2.5", "< 5"
-  s.metadata["rubygems_mfa_required"] = "true"
-end