commander 5.0.0 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c6f343ac9ccafcd3a3815ad19278ea429f189704635616446c92ba2d1551db8
-  data.tar.gz: f759ec220c1c075e42a0b175c01ef55c9aa5a82e3be754db55415bc257ce7120
+  metadata.gz: 2e21aee4b50aee1e76830f9f084a14f31ca37b2b78ce330363ef6811e5af924b
+  data.tar.gz: 29086cb85530a560b2ada64092eb63f2924c7b6b1014b1229ac085630ca38456
 SHA512:
-  metadata.gz: e714a982d479519bba3120f04f5ecb247d95e072f7f9250884649ca3b71288566368a609b4e78706ee5bd02cf6ee8d153c30408d31cfb1732d5f1232eeb8bccf
-  data.tar.gz: f26ca19596dc5099c1203d9a100c2c86072498f2b2e269916f1cdf8b406f11d7585258587eb2da440d63c8a9377f613af49b140b946b1d6b734f8d1c6de11306
+  metadata.gz: 6bfbc2fef5110d982b14b1cba0af293620b52df2a8265e74cc6db8fae48a6d4c1d042ee4bf5f6825402604a4884fe52917faae7031c5ad6e317a4bc8e4475a3c
+  data.tar.gz: beedd12841890d36708b894e1a88c315a453f2cd2805178449f338606b391b8a9e793215bc2f893275b23eca568a26186c1b5e5071e49efe432a5cc7af9748db

data/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Ruby ${{ matrix.ruby }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - '3.1'
+          - '3.2'
+          - '3.3'
+          - '3.4'
+          - '4.0.6'
+          - jruby
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rake spec
+
+  lint:
+    name: RuboCop
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '4.0.6'
+          bundler-cache: true
+
+      - name: Run RuboCop
+        run: bundle exec rubocop
+
+  security:
+    name: Bundler Audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '4.0.6'
+          bundler-cache: true
+
+      - name: Run bundler-audit
+        run: bundle exec bundler-audit check --update

data/.gitignore

@@ -3,5 +3,4 @@
 Gemfile.lock
 pkg/*
 .rvmrc
-.ruby-version
 coverage/*

data/.rubocop.yml

@@ -1,7 +1,7 @@
 inherit_from: .rubocop_todo.yml
 
 AllCops:
-  TargetRubyVersion: 3.0
+  TargetRubyVersion: 3.1
   NewCops: enable
   SuggestExtensions: false
 
@@ -54,9 +54,6 @@ Style/FormatStringToken:
 Style/MixinUsage:
   Enabled: false
 
-Lint/ErbNewArguments:
-  Enabled: false
-
 Style/DocumentDynamicEvalDefinition:
   Enabled: false
 

data/.rubocop_todo.yml

@@ -1,77 +1,81 @@
-# This configuration was generated by `rubocop --auto-gen-config`
-# on 2015-02-16 16:08:54 -0800 using RuboCop version 0.29.0.
+# This configuration was generated by
+# `rubocop --auto-gen-config --no-auto-gen-timestamp`
+# using RuboCop version 1.88.2.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 2
-Security/Eval:
-  Enabled: false
-
-# Offense count: 2
+# Offense count: 1
+# Configuration parameters: AllowComments, AllowNil.
 Lint/SuppressedException:
-  Enabled: false
+  Exclude:
+    - 'lib/commander/user_interaction.rb'
 
-# Offense count: 5
+# Offense count: 6
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
 Metrics/AbcSize:
   Max: 30
 
 # Offense count: 1
-# Configuration parameters: CountComments.
+# Configuration parameters: CountComments, CountAsOne.
 Metrics/ClassLength:
-  Enabled: false
+  Max: 250
 
-# Offense count: 4
+# Offense count: 5
+# Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/CyclomaticComplexity:
   Max: 13
 
-# Offense count: 89
-# Configuration parameters: AllowURI, URISchemes.
-Layout/LineLength:
-  Max: 242
-
-# Offense count: 7
-# Configuration parameters: CountComments.
+# Offense count: 8
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 36
 
-# Offense count: 4
+# Offense count: 5
+# Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/PerceivedComplexity:
   Max: 14
 
-# Offense count: 1
+# Offense count: 2
 Naming/AccessorMethodName:
-  Enabled: false
-
-# Offense count: 18
-Style/Documentation:
-  Enabled: false
-
-# Offense count: 12
-# Configuration parameters: AllowedVariables.
-Style/GlobalVars:
-  Enabled: false
+  Exclude:
+    - 'lib/commander/core_ext/object.rb'
+    - 'lib/commander/help_formatters.rb'
 
 # Offense count: 1
-# Configuration parameters: MaxLineLength.
+Security/Eval:
+  Exclude:
+    - 'lib/commander/delegates.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
 Style/IfUnlessModifier:
-  Enabled: false
+  Exclude:
+    - 'lib/commander/runner.rb'
+    - 'lib/commander/user_interaction.rb'
 
 # Offense count: 1
 Style/MultilineBlockChain:
-  Enabled: false
+  Exclude:
+    - 'lib/commander/user_interaction.rb'
 
 # Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
 Style/MultilineTernaryOperator:
-  Enabled: false
+  Exclude:
+    - 'lib/commander/user_interaction.rb'
 
-# Offense count: 5
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
 Style/RescueModifier:
-  Enabled: false
+  Exclude:
+    - 'lib/commander/runner.rb'
+    - 'lib/commander/user_interaction.rb'
 
-# Offense count: 2
-# Cop supports --auto-correct.
-# Configuration parameters: ExactNameMatch, AllowPredicates, AllowDSLWriters, Whitelist.
-Style/TrivialAccessors:
-  Enabled: false
+# Offense count: 5
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
+# URISchemes: http, https
+Layout/LineLength:
+  Max: 242

data/.ruby-version

@@ -0,0 +1 @@
+4.0.6

data/Gemfile

@@ -3,3 +3,13 @@
 source 'https://rubygems.org'
 
 gemspec
+
+group :development, :test do
+  gem 'bundler-audit', '~> 0.9'
+  gem 'rake', '~> 13.0'
+  gem 'rspec', '~> 3.13'
+  gem 'rubocop', '~> 1.88'
+  # 1.x requires Ruby >= 3.2; allow the last 0.x on Ruby 3.1 while newer
+  # rubies still resolve to 1.x.
+  gem 'simplecov', '>= 0.22', '< 2'
+end

data/History.rdoc

@@ -1,3 +1,10 @@
+=== 6.0.0 / 2026-08-01
+
+* Drop support for Ruby 3.0; require Ruby >= 3.1 (#104). (@dior001)
+* Update highline dependency to ~> 3.1 (#104). (@dior001)
+* Modernize the codebase for the current Ruby ecosystem, including frozen string literals and anonymous block forwarding (#104). (@dior001)
+* Fix `SortedSet` error on Ruby 3.2+, where it was extracted from the `set` library (#104).
+
 === 5.0.0 / 2024-01-15
 
 * Drop support for Ruby < 3.0; update highline dependency to ~3.0 (#102). (@belousovAV)

data/README.md

@@ -1,5 +1,4 @@
-[<img src="https://api.travis-ci.org/commander-rb/commander.svg" alt="Build Status" />](https://travis-ci.org/commander-rb/commander)
-[![Inline docs](https://inch-ci.org/github/commander-rb/commander.svg)](https://inch-ci.org/github/commander-rb/commander)
+[![CI](https://github.com/commander-rb/commander/actions/workflows/ci.yml/badge.svg)](https://github.com/commander-rb/commander/actions/workflows/ci.yml)
 
 # Commander
 
@@ -24,9 +23,12 @@ features, and an elegant API.
 * Sexy paging for long bodies of text
 * Support for MacOS text-to-speech
 * Command aliasing (very powerful, as both switches and arguments can be used)
-* Growl notification support for MacOS
 * Use the `commander` executable to initialize a commander driven program
 
+## Requirements
+
+Ruby >= 3.1 (tested through Ruby 4.0).
+
 ## Installation
 
     $ gem install commander
@@ -50,7 +52,6 @@ as well as an object, specifying a method to call, so view the RDoc for more inf
 ### Classic style
 
 ```ruby
-require 'rubygems'
 require 'commander/import'
 
 # :name is optional, otherwise uses the basename of this executable
@@ -93,7 +94,6 @@ $ foobar bar --suffix '}' --prefix '{'
 **NOTE:** Make sure to use `require 'commander'` rather than `require 'commander/import'`, otherwise Commander methods will still be imported into the global namespace.
 
 ```ruby
-require 'rubygems'
 require 'commander'
 
 class MyApplication
@@ -122,7 +122,6 @@ MyApplication.new.run if $0 == __FILE__
 ### Block style
 
 ```ruby
-require 'rubygems'
 require 'commander'
 
 Commander.configure do
@@ -240,30 +239,6 @@ else
 end
 ```
 
-## Growl Notifications
-
-Commander provides methods for displaying Growl notifications. To use these
-methods you need to install https://github.com/tj/growl which utilizes
-the [growlnotify](https://growl.info/extras.php#growlnotify) executable. Note that
-growl is auto-imported by Commander when available, no need to require.
-
-```ruby
-# Display a generic Growl notification
-notify 'Something happened'
-
-# Display an 'info' status notification
-notify_info 'You have #{emails.length} new email(s)'
-
-# Display an 'ok' status notification
-notify_ok 'Gems updated'
-
-# Display a 'warning' status notification
-notify_warning '1 gem failed installation'
-
-# Display an 'error' status notification
-notify_error "Gem #{name} failed"
-```
-
 ## Commander Goodies
 
 ### Option Defaults
@@ -459,11 +434,11 @@ For feature rich ASCII tables for your terminal app check out the terminal-table
 
 ## Running Specifications
 
-    $ rake spec
+    $ bundle exec rake spec
 
 OR
 
-    $ spec --color spec
+    $ bundle exec rspec
 
 ## Contrib
 

data/commander.gemspec

@@ -18,18 +18,13 @@ Gem::Specification.new do |s|
     'documentation_uri' => "https://www.rubydoc.info/gems/commander/#{s.version}",
     'homepage_uri' => s.homepage,
     'source_code_uri' => "#{s.homepage}/tree/v#{s.version}",
+    'rubygems_mfa_required' => 'true',
   }
-  s.required_ruby_version = '>= 3.0'
+  s.required_ruby_version = '>= 3.1'
 
   s.files         = `git ls-files`.split("\n").reject { |f| f.match(%r{^(test|spec|features)/}) }
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
   s.require_paths = ['lib']
 
-  s.add_runtime_dependency('highline', '~> 3.0.0')
-
-  s.add_development_dependency('rake')
-  s.add_development_dependency('rspec', '~> 3.2')
-  s.add_development_dependency('rubocop', '~> 1.12.1')
-  s.add_development_dependency('simplecov')
+  s.add_dependency('highline', '~> 3.1')
 end

data/lib/commander/blank.rb

@@ -1,6 +1,15 @@
 # frozen_string_literal: true
 
+##
+# Strips a class of (almost) all its instance methods, leaving it as a
+# near-blank slate. Mixed into Commander::Command::Options so that
+# +method_missing+ can treat arbitrary option names as accessors without
+# clashing with methods Ruby defines on every object (e.g. +send+, +type+).
 module Blank
+  ##
+  # Undefines every instance method on +base+ except those beginning with
+  # a double underscore and +object_id+, which are kept so the resulting
+  # object remains minimally usable (e.g. for +__send__+ and identity checks).
   def self.included(base)
     base.class_eval do
       instance_methods.each { |m| undef_method m unless m =~ /^__|object_id/ }

data/lib/commander/command.rb

@@ -3,13 +3,29 @@
 require 'optparse'
 
 module Commander
+  ##
+  # A single named command belonging to a Commander::Runner: its
+  # description, examples, options (parsed via OptionParser), and the
+  # handler invoked with the remaining arguments once options have been
+  # parsed. Built up via the block yielded by Runner#command, e.g.
+  #
+  #   command :foo do |c|
+  #     c.syntax = 'foo [options]'
+  #     c.option '--bar', 'A switch'
+  #     c.action { |args, options| ... }
+  #   end
   class Command
     attr_accessor :name, :examples, :syntax, :description, :summary, :proxy_options, :options
     attr_reader :global_options
 
     ##
     # Options struct.
-
+    #
+    # An open-ended, OpenStruct-like object populated by #option and
+    # #proxy_option_struct. Reading an unset attribute returns +nil+;
+    # writing any attribute (via +some_attr=+) stores it. Almost all of
+    # Object's own instance methods are stripped out (see Blank) so that
+    # option names never collide with built-ins like +send+ or +class+.
     class Options
       include Blank
 
@@ -17,14 +33,22 @@ module Commander
         @table = {}
       end
 
+      ##
+      # The underlying Hash of option name (Symbol) => value pairs.
       def __hash__
         @table
       end
 
+      ##
+      # Reads or writes an arbitrary option. <tt>options.foo</tt> reads
+      # the +:foo+ entry; <tt>options.foo = 1</tt> writes it.
       def method_missing(meth, *args)
         meth.to_s =~ /=$/ ? @table[meth.to_s.chop.to_sym] = args.first : @table[meth]
       end
 
+      ##
+      # Merge _defaults_ into this struct, without overwriting any
+      # options already set.
       def default(defaults = {})
         @table = defaults.merge! @table
       end
@@ -36,7 +60,6 @@ module Commander
 
     ##
     # Initialize new command with specified _name_.
-
     def initialize(name)
       @name, @examples, @when_called = name.to_s, [], []
       @options, @proxy_options = [], []
@@ -55,7 +78,6 @@ module Commander
     #     c.example "Should do something", "my_command something"
     #   end
     #
-
     def example(description, command)
       @examples << [description, command]
     end
@@ -106,7 +128,6 @@ module Commander
     #   c.option '--time TIME', Time
     #   c.option '--date [DATE]', Date
     #
-
     def option(*args, &block)
       switches, description = Runner.separate_switches_from_description(*args)
       proc = block || option_proc(switches)
@@ -138,7 +159,6 @@ module Commander
     #   # Pass an object to handle callback (requires method symbol)
     #   c.when_called SomeObject, :some_method
     #
-
     def when_called(*args, &block)
       fail ArgumentError, 'must pass an object, class, or block.' if args.empty? && !block
 
@@ -152,17 +172,15 @@ module Commander
     # * parses options, call option blocks
     # * invokes when_called proc
     #
-
     def run(*args)
       call parse_options_and_call_procs(*args)
     end
 
-    #:stopdoc:
+    # :stopdoc:
 
     ##
     # Parses options and calls associated procs,
     # returning the arguments remaining.
-
     def parse_options_and_call_procs(*args)
       return args if args.empty?
 
@@ -177,7 +195,6 @@ module Commander
 
     ##
     # Call the commands when_called block with _args_.
-
     def call(args = [])
       object, meth = @when_called[0, 2]
       meth ||= :call
@@ -193,7 +210,6 @@ module Commander
     ##
     # Creates an Options instance populated with the option values
     # collected by the #option_proc.
-
     def proxy_option_struct
       (global_options + proxy_options).each_with_object(Options.new) do |(option, value), options|
         # options that are present will evaluate to true
@@ -207,7 +223,6 @@ module Commander
     # Option proxy proc used when a block is not explicitly passed
     # via the #option method. This allows commander to auto-populate
     # and work with option values.
-
     def option_proc(switches)
       ->(value) { proxy_options << [Runner.switch_to_sym(switches.last), value] }
     end

data/lib/commander/configure.rb

@@ -1,11 +1,39 @@
 # frozen_string_literal: true
 
+##
+# Commander is the top-level namespace for the whole gem: see
+# Commander::Methods for the DSL mixin, Commander::Runner for the engine
+# that drives it, and Commander::Command for individual commands.
 module Commander
-  def configure(*configuration_opts, &configuration_block)
+  ##
+  # Runs a Commander program within an isolated, anonymous module rather
+  # than polluting the including object (as Commander::Methods normally
+  # does when included directly). Useful for embedding a Commander CLI
+  # inside a larger application without leaking its DSL methods. Calls
+  # Runner#run! once the block has finished configuring commands.
+  #
+  # Any _configuration_opts_ are passed through as block arguments.
+  #
+  # === Examples
+  #
+  #   Commander.configure do
+  #     program :name, 'my-tool'
+  #     program :version, '1.0.0'
+  #     program :description, 'Does something useful'
+  #
+  #     command :greet do |c|
+  #       c.action { |args, _options| say "Hello, #{args.first}!" }
+  #     end
+  #   end
+  #
+  #   Commander.configure(default_name) do |name|
+  #     program :name, name
+  #   end
+  def configure(*configuration_opts, &)
     configuration_module = Module.new
     configuration_module.extend Commander::Methods
 
-    configuration_module.class_exec(*configuration_opts, &configuration_block)
+    configuration_module.class_exec(*configuration_opts, &)
 
     configuration_module.class_exec do
       run!

data/lib/commander/core_ext/array.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+##
+# Adds Array.parse, used by HighLine's #ask/#ask_for_array so that
+# +ask '...', Array+ splits a raw response into a Ruby Array.
 class Array
   ##
   # Split _string_ into an array. Used in
@@ -17,7 +20,6 @@ class Array
   #   # or use ask_for_CLASS
   #   list = ask_for_array 'Favorite cookies: '
   #
-
   def self.parse(string)
     # Using reverse + lookahead to work around Ruby 1.8's lack of lookbehind
     # TODO: simplify now that we don't support Ruby 1.8

data/lib/commander/core_ext/object.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
+##
+# Adds Object#get_binding, used by HelpFormatter::Context to capture a
+# target object's binding for evaluation inside an ERB help template.
 class Object
   ##
   # Return the current binding.
-
   def get_binding
     binding
   end

data/lib/commander/delegates.rb

@@ -1,6 +1,13 @@
 # frozen_string_literal: true
 
 module Commander
+  ##
+  # = Delegates
+  #
+  # Mixed into Commander::Methods to expose the singleton
+  # Commander::Runner instance's DSL (+command+, +program+, +run!+, etc.)
+  # as top-level methods, so scripts can call them directly instead of
+  # reaching through <tt>Commander::Runner.instance</tt>.
   module Delegates
     %w(
       add_command
@@ -20,6 +27,9 @@ module Commander
       END
     end
 
+    ##
+    # Delegates to Commander::Runner#commands, returning the hash of
+    # registered command name => Commander::Command pairs.
     def defined_commands(...)
       ::Commander::Runner.instance.commands(...)
     end

data/lib/commander/help_formatters/base.rb

@@ -1,23 +1,27 @@
 # frozen_string_literal: true
 
 module Commander
-  ##
-  # = Help Formatter
-  #
-  # Commander's help formatters control the output when
-  # either the help command, or --help switch are called.
-  # The default formatter is Commander::HelpFormatter::Terminal.
-
   module HelpFormatter
+    ##
+    # Base class for help formatters. Subclasses receive the
+    # Commander::Runner instance being documented and must implement
+    # #render (global help) and #render_command (per-command help). This
+    # base implementation renders placeholder text and exists mainly for
+    # testing and as a minimal example.
     class Base
       def initialize(runner)
         @runner = runner
       end
 
+      ##
+      # Render the global help text shown for <tt>--help</tt> with no
+      # command, or the +help+ command with no arguments.
       def render
         'Implement global help here'
       end
 
+      ##
+      # Render the help text for a single _command_.
       def render_command(command)
         "Implement help for #{command.name} here"
       end

data/lib/commander/help_formatters/terminal.rb

@@ -4,21 +4,29 @@ require 'erb'
 
 module Commander
   module HelpFormatter
+    ##
+    # The default help formatter. Renders full-width, verbosely-labeled
+    # help text (examples, per-option descriptions, etc.) from the ERB
+    # templates in the neighboring +terminal/+ directory. See
+    # HelpFormatter::TerminalCompact for a more condensed alternative.
     class Terminal < Base
+      ##
+      # Render the global help text for the program.
       def render
         template(:help).result(ProgramContext.new(@runner).get_binding)
       end
 
+      ##
+      # Render the help text for a single _command_.
       def render_command(command)
         template(:command_help).result(Context.new(command).get_binding)
       end
 
+      ##
+      # Compile the ERB template named _name_ (+:help+ or
+      # +:command_help+) from this formatter's template directory.
       def template(name)
-        if RUBY_VERSION < '2.6'
-          ERB.new(File.read(File.join(File.dirname(__FILE__), 'terminal', "#{name}.erb")), nil, '-')
-        else
-          ERB.new(File.read(File.join(File.dirname(__FILE__), 'terminal', "#{name}.erb")), trim_mode: '-')
-        end
+        ERB.new(File.read(File.join(File.dirname(__FILE__), 'terminal', "#{name}.erb")), trim_mode: '-')
       end
     end
   end