command_kit 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 306f055fa898d4d82c14ba8e79b397ae413280bb7144ce69e1787081620827e9
-  data.tar.gz: e79e640f7d4ae566401e7543d3ba98aa42b1e2396657734e29ab3cd3b383b41c
+  metadata.gz: 3a35e836c936c91aa916f33e691260a591d2e363de6a0fd3d9259150b86add15
+  data.tar.gz: fe2e2cc87a8a0fe889cba23b5567b307bb088fdf3ee4eff7d681694a981b5143
 SHA512:
-  metadata.gz: ee4268377db8c2398b5157feda9fa106a0b156537c6085b71fcfd8c7710f898c3bc0ef5d4408d9c6cbcae932e4f4ee4dd49070003e6c5734da06da33fbbace9a
-  data.tar.gz: 03b6a48369bea030002f9432d0d8645d8c0f5cdefba81778922e73a54f267611419bdb63e5033e98b09aa1c6ae97af1e8c3b8135cb7ed4b807fce666c6c379b8
+  metadata.gz: da2676ab635edc9898457b1c532af6ac4c478c6f3a0ab19dfc42f0abc4ddd73ef4f473fe7699f8bed3ac5abec3381a7a9ca9c50736c4cc3697612ef36f3d6fea
+  data.tar.gz: d30a04ab5274f489ef3e534950301669d47112ee56d43b59e51c5e816f7de21fba72197d43f3362331c40f3e75a70e0c316d53fe12bf8960daf79efec270a372

data/.github/workflows/ruby.yml

@@ -10,13 +10,13 @@ jobs:
       fail-fast: false
       matrix:
         ruby:
-          - 2.7
-          - 3.0
-          - 3.1
+          - '3.0'
+          - '3.1'
+          - '3.2'
+          - '3.3'
           # TODO: uncomment when jruby supports ruby >= 2.7
           # - jruby
-          # TODO: uncomment when truffleruby supports splatting empty kwargs
-          # - truffleruby
+          - truffleruby
     name: Ruby ${{ matrix.ruby }}
     steps:
       - uses: actions/checkout@v2
@@ -37,7 +37,7 @@ jobs:
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: 2.7
+          ruby-version: 3.0
       - name: Install dependencies
         run: bundle install --jobs 4 --retry 3
       - name: Run rubocop

data/.rubocop.yml

@@ -22,6 +22,7 @@ Style/PercentLiteralDelimiters:
     '%I': '[]'
     '%w': '[]'
     '%W': '[]'
+Style/UnlessElse: { Enabled: false }
 
 #
 # rules that are in flux
@@ -139,3 +140,18 @@ Style/TrailingCommaInHashLiteral: { Enabled: false } # Offense count: 2
 
 # rubocop cannot tell that rubygems_mfa_required is enabled in gemspec.yml
 Gemspec/RequireMFA: { Enabled: false }
+
+# make an exception for our gemspec code
+Gemspec/DuplicatedAssignment:
+  Exclude:
+    - 'command_kit.gemspec'
+
+Bundler/OrderedGems: { Enabled: false }
+
+# rubocup is not aware of vertical alignment of matrixes (Array of Arrays).
+Layout/SpaceInsideArrayLiteralBrackets: { Enabled: false }
+
+Naming/HeredocDelimiterNaming: { Enabled: false }
+
+# I prefer to use explicit parenthesis for compound logical statements
+Style/RedundantParentheses: { Enabled: false }

data/ChangeLog.md

@@ -1,3 +1,33 @@
+### 0.4.1 / 2024-01-03
+
+* Added more examples of how to define sub-commands and sub-sub-commands.
+
+#### CommandKit::Options::Parser
+
+* Do not override the command's `usage` if it's already been set.
+
+#### CommandKit::Printing::Tables
+
+* Format the table output as UTF-8 to allow UTF-8 data in the formatted table.
+
+### 0.4.0 / 2022-11-11
+
+* Added {CommandKit::BugReport}.
+* Added {CommandKit::Edit}.
+* Added {CommandKit::Printing::Fields}.
+* Added {CommandKit::Printing::Lists}.
+* Added {CommandKit::Printing::Tables}.
+
+#### CommandKit::Colors
+
+* Support disabling ANSI color output if the `NO_COLOR` environment variable is
+  set.
+
+#### CommandKit::Options
+
+* Correct the option usage for long option flags that have optional values
+  (ex: `--longopt[=VALUE]`).
+
 ### 0.3.0 / 2021-12-26
 
 * Added {CommandKit::FileUtils}.

data/Gemfile

@@ -12,6 +12,8 @@ group :development do
   gem 'simplecov', '~> 0.20', require: false
 
   gem 'kramdown'
+  gem 'redcarpet',       platform: :mri
   gem 'yard', '~> 0.9'
   gem 'yard-spellcheck', require: false
+  gem 'dead_end'
 end

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2021 Hal Brodigan
+Copyright (c) 2021-2024 Hal Brodigan
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -11,30 +11,33 @@
 
 ## Description
 
-A Ruby toolkit for building clean, correct, and robust CLI commands as
+A modular Ruby toolkit for building clean, correct, and robust CLI commands as
 plain-old Ruby classes.
 
 ## Features
 
 * **Simple** - Commands are plain-old ruby classes, with options and
-  arguments declared as attributes. All features are ruby modules that can be
+  arguments declared as attributes. All features are Ruby modules that can be
   included into command classes.
 * **Correct** - CommandKit behaves like a standard UNIX command.
   * Safely handles Ctrl^C / SIGINT interrupts and [exits with 130](https://tldp.org/LDP/abs/html/exitcodes.html).
   * Safely handles broken pipes (aka `mycmd | head`).
-  * Respects common environment variables (ex: `TERM=dumb`).
+  * Respects common environment variables (ex: `TERM=dumb` and `NO_COLOR`).
   * Uses [OptionParser][optparse] for POSIX option parsing.
-  * Disables ANSI color when output is redirected to a file.
+  * Disables ANSI color when output is redirected to a file or when `NO_COLOR`
+    is set.
 * **Complete** - Provides many additional CLI features.
   * OS detection.
   * Terminal size detection.
   * ANSI coloring support.
   * Interactive input.
+  * Rich text printing support (fields, lists, and tables).
   * Subcommands (explicit or lazy-loaded) and command aliases.
   * Displaying man pages for `--help`/`help`.
   * Using the pager (aka `less`).
   * [XDG directories](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) (aka `~/.config/`, `~/.local/share/`, `~/.cache/`).
-* **Testable** - Since commands are plain-old ruby classes, it's easy to
+  * Exception handling / Bug reporting.
+* **Testable** - Since commands are plain-old Ruby classes, it's easy to
   initialize them and call `#main` or `#run`.
 
 ## Anti-Features
@@ -45,7 +48,7 @@ plain-old Ruby classes.
 
 ## Requirements
 
-* [ruby] >= 2.7.0
+* [ruby] >= 3.0.0
 
 ## Install
 
@@ -56,13 +59,13 @@ $ gem install command_kit
 ### gemspec
 
 ```ruby
-gem.add_dependency 'command_kit', '~> 0.2'
+gem.add_dependency 'command_kit', '~> 0.3'
 ```
 
 ### Gemfile
 
 ```ruby
-gem 'command_kit', '~> 0.2'
+gem 'command_kit', '~> 0.3'
 ```
 
 ## Examples
@@ -204,6 +207,7 @@ end
 ### Reference
 
 * [CommandKit::Arguments](https://rubydoc.info/gems/command_kit/CommandKit/Arguments)
+* [CommandKit::BugReport](https://rubydoc.info/gems/command_kit/CommandKit/BugReport)
 * [CommandKit::Colors](https://rubydoc.info/gems/command_kit/CommandKit/Colors)
 * [CommandKit::Command](https://rubydoc.info/gems/command_kit/CommandKit/Command)
 * [CommandKit::CommandName](https://rubydoc.info/gems/command_kit/CommandKit/CommandName)
@@ -211,11 +215,13 @@ end
   * [CommandKit::Commands::AutoLoad](https://rubydoc.info/gems/command_kit/CommandKit/Commands/AutoLoad)
   * [CommandKit::Commands::AutoRequire](https://rubydoc.info/gems/command_kit/CommandKit/Commands/AutoRequire)
 * [CommandKit::Description](https://rubydoc.info/gems/command_kit/CommandKit/Description)
+* [CommandKit::Edit](https://rubydoc.info/gems/command_kit/CommandKit/Edit)
 * [CommandKit::Env](https://rubydoc.info/gems/command_kit/CommandKit/Env)
   * [CommandKit::Env::Home](https://rubydoc.info/gems/command_kit/CommandKit/Env/Home)
   * [CommandKit::Env::Path](https://rubydoc.info/gems/command_kit/CommandKit/Env/Path)
 * [CommandKit::Examples](https://rubydoc.info/gems/command_kit/CommandKit/Examples)
 * [CommandKit::ExceptionHandler](https://rubydoc.info/gems/command_kit/CommandKit/ExceptionHandler)
+* [CommandKit::FileUtils](https://rubydoc.info/gems/command_kit/CommandKit/FileUtils)
 * [CommandKit::Help](https://rubydoc.info/gems/command_kit/CommandKit/Help)
   * [CommandKit::Help::Man](https://rubydoc.info/gems/command_kit/CommandKit/Help/Man)
 * [CommandKit::Interactive](https://rubydoc.info/gems/command_kit/CommandKit/Interactive)
@@ -225,7 +231,10 @@ end
   * [CommandKit::Options::Verbose](https://rubydoc.info/gems/command_kit/CommandKit/Options/Verbose)
 * [CommandKit::Pager](https://rubydoc.info/gems/command_kit/CommandKit/Pager)
 * [CommandKit::Printing](https://rubydoc.info/gems/command_kit/CommandKit/Printing)
+  * [CommandKit::Printing::Fields](https://rubydoc.info/gems/command_kit/CommandKit/Printing/Fields)
   * [CommandKit::Printing::Indent](https://rubydoc.info/gems/command_kit/CommandKit/Printing/Indent)
+  * [CommandKit::Printing::Lists](https://rubydoc.info/gems/command_kit/CommandKit/Printing/Lists)
+  * [CommandKit::Printing::Tables](https://rubydoc.info/gems/command_kit/CommandKit/Printing/Tables)
 * [CommandKit::ProgramName](https://rubydoc.info/gems/command_kit/CommandKit/ProgramName)
 * [CommandKit::Stdio](https://rubydoc.info/gems/command_kit/CommandKit/Stdio)
 * [CommandKit::Terminal](https://rubydoc.info/gems/command_kit/CommandKit/Terminal)
@@ -244,7 +253,7 @@ Twitter.
 
 ## Copyright
 
-Copyright (c) 2021 Hal Brodigan
+Copyright (c) 2021-2024 Hal Brodigan
 
 See {file:LICENSE.txt} for details.
 

data/command_kit.gemspec

@@ -32,7 +32,6 @@ Gem::Specification.new do |gem|
   gem.default_executable = gem.executables.first if Gem::VERSION < '1.7.'
 
   gem.extensions       = glob[gemspec['extensions'] || 'ext/**/extconf.rb']
-  gem.test_files       = glob[gemspec['test_files'] || '{test/{**/}*_test.rb']
   gem.extra_rdoc_files = glob[gemspec['extra_doc_files'] || '*.{txt,md}']
 
   gem.require_paths = Array(gemspec.fetch('require_paths') {

data/examples/printing/tables.rb

@@ -0,0 +1,141 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path('../../../lib',__FILE__))
+require 'command_kit/command'
+require 'command_kit/printing/tables'
+
+class TablesCmd < CommandKit::Command
+
+  include CommandKit::Printing::Tables
+
+  def run
+    header = ['A', 'B', 'C']
+    table = [
+      ['AAAA', 'BBBB', 'CCCC'],
+      ['AAAA', 'BBBB', 'CCCC'],
+      ['AAAA', 'BBBB', 'CCCC']
+    ]
+
+    puts
+    puts "Table:"
+    puts
+    print_table table
+
+    puts
+    puts "Table with header:"
+    puts
+    print_table table, header: header
+
+    puts
+    puts "ASCII border:"
+    puts
+
+    print_table table, header: header,
+                       border: :ascii
+
+    puts
+    puts "Border + Separated rows:"
+    puts
+
+    print_table table, header: header,
+                       border: :ascii,
+                       separate_rows: true
+
+    puts
+    puts "Lined border:"
+    puts
+
+    print_table table, header: header,
+                       border: :line
+
+    puts
+    puts "Double line border:"
+    puts
+
+    print_table table, header: header,
+                       border: :double_line
+
+    uneven_table = [
+      ['AAAAAA', 'B',       'CCCCCCC'],
+      ['AAA',    'BBBB',    'CCC'    ],
+      ['A',      'BBBBBBB', 'C'      ]
+    ]
+
+    puts
+    puts "Left-justified:"
+    puts
+
+    print_table uneven_table, header: header,
+                              justify: :left,
+                              justify_header: :left,
+                              border: :line
+
+    puts
+    puts "Right-justified:"
+    puts
+
+    print_table uneven_table, header: header,
+                              justify: :right,
+                              justify_header: :right,
+                              border: :line
+
+    puts
+    puts "Center-justified:"
+    puts
+
+    print_table uneven_table, header: header,
+                              justify: :center,
+                              justify_header: :center,
+                              border: :line
+
+    puts
+    puts "Table with empty cells:"
+    puts
+
+    table_with_empty_cells = [
+      ['AAAA', 'BBBB', 'CCCC'],
+      ['AAAA', nil,    'CCCC'],
+      ['AAAA', 'BBBB']
+    ]
+
+    print_table table_with_empty_cells, header:  header,
+                                        justify: :left,
+                                        border:  :line
+
+    puts
+    puts "Multi-line table:"
+    puts
+
+    multi_line_table = [
+      ['AAAA',        'BBBB',    "CCCC\nCC"],
+      ['AAAA',        "BBBB\nB", 'CCCC'],
+      ["AAAA\nAA\nA", "BBBB",    "CCCC"]
+    ]
+
+    print_table multi_line_table, header:  header,
+                                  justify: :left,
+                                  border:  :line
+
+    puts
+    puts "Indent aware:"
+    puts
+
+    puts "* Item 1"
+    indent do
+      puts "* Item 2"
+      puts
+
+      indent do
+        print_table table, header: header,
+                           border: :line
+      end
+    end
+
+    puts
+  end
+
+end
+
+if __FILE__ == $0
+  TablesCmd.start
+end

data/examples/subcommands/cli/config/get.rb

@@ -0,0 +1,47 @@
+require 'command_kit/command'
+
+module Foo
+  class CLI
+    class Config < CommandKit::Command
+      #
+      # The `config get` sub-command.
+      #
+      class Get < CommandKit::Command
+
+        usage '[options] NAME'
+
+        argument :name, required: false,
+                        desc:     'Configuration variable name'
+
+        description 'Gets a configuration variable'
+
+        CONFIG = {
+          'name'  => 'John Smith',
+          'email' => 'john.smith@example.com'
+        }
+
+        #
+        # Runs the `config get` sub-command.
+        #
+        # @param [String, nil] name
+        #   The optional name argument.
+        #
+        def run(name=nil)
+          if name
+            unless CONFIG.has_key?(name)
+              print_error "unknown config variable: #{name}"
+              exit(1)
+            end
+
+            puts CONFIG.fetch(name)
+          else
+            CONFIG.each do |name,value|
+              puts "#{name}:\t#{value}"
+            end
+          end
+        end
+
+      end
+    end
+  end
+end

data/examples/subcommands/cli/config/set.rb

@@ -0,0 +1,44 @@
+require 'command_kit/command'
+
+module Foo
+  class CLI
+    class Config < CommandKit::Command
+      #
+      # The `config set` sub-command.
+      #
+      class Set < CommandKit::Command
+
+        usage '[options] NAME'
+
+        argument :name, required: true,
+                        desc:     'Configuration variable name to set'
+
+        argument :value, required: true,
+                         desc:     'Configuration variable value to set'
+
+        description 'Sets a configuration variable'
+
+        CONFIG = {
+          'name'  => 'John Smith',
+          'email' => 'john.smith@example.com'
+        }
+
+        #
+        # Runs the `config get` sub-command.
+        #
+        # @param [String] name
+        #   The name argument.
+        #
+        def run(name,value)
+          unless CONFIG.has_key?(name)
+            print_error "unknown config variable: #{name}"
+            exit(1)
+          end
+
+          puts "Configuration variable #{name} was #{CONFIG.fetch(name)}, but is now #{value}"
+        end
+
+      end
+    end
+  end
+end

data/examples/subcommands/cli/config.rb

@@ -0,0 +1,23 @@
+require 'command_kit/command'
+require 'command_kit/commands'
+
+require_relative 'config/get'
+require_relative 'config/set'
+
+module Foo
+  class CLI
+    #
+    # The `config` sub-command.
+    #
+    class Config < CommandKit::Command
+
+      include CommandKit::Commands
+
+      command Get
+      command Set
+
+      description 'Get or set the configuration'
+
+    end
+  end
+end

data/examples/subcommands/cli/list.rb

@@ -0,0 +1,35 @@
+require 'command_kit/command'
+
+module Foo
+  class CLI
+    #
+    # The `list` sub-command.
+    #
+    class List < CommandKit::Command
+
+      usage '[options] [NAME]'
+
+      argument :name, required: false,
+                      desc:     'Optional name to list'
+
+      description 'Lists the contents'
+
+      ITEMS = %w[foo bar baz]
+
+      #
+      # Runs the `list` sub-command.
+      #
+      # @param [String, nil] name
+      #   The optional name argument.
+      #
+      def run(name=nil)
+        if name
+          puts ITEMS.grep(name)
+        else
+          puts ITEMS
+        end
+      end
+
+    end
+  end
+end

data/examples/subcommands/cli/update.rb

@@ -0,0 +1,47 @@
+require 'command_kit/command'
+
+module Foo
+  class CLI
+    #
+    # The `update` sub-command.
+    #
+    class Update < CommandKit::Command
+
+      usage '[options] [NAME]'
+
+      option :quiet, short: '-q',
+                     desc:  'Suppresses logging messages'
+
+      argument :name, required: false,
+                      desc:     'Optional name to update'
+
+      description 'Updates an item or all items'
+
+      ITEMS = %w[foo bar baz]
+
+      #
+      # Runs the `update` sub-command.
+      #
+      # @param [String, nil] name
+      #   The optional name argument.
+      #
+      def run(name=nil)
+        if name
+          unless ITEMS.include?(name)
+            print_error "unknown item: #{name}"
+            exit(1)
+          end
+
+          puts "Updating #{name} ..." unless options[:quiet]
+          sleep 1
+          puts "Item #{name} updated." unless options[:quiet]
+        else
+          puts "Updating ..." unless options[:quiet]
+          sleep 2
+          puts "All items updated." unless options[:quiet]
+        end
+      end
+
+    end
+  end
+end

data/examples/subcommands/cli.rb

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path('../../../lib',__FILE__))
+
+require 'command_kit/commands'
+
+require_relative 'cli/config'
+require_relative 'cli/list'
+require_relative 'cli/update'
+
+module Foo
+  #
+  # The main CLI command.
+  #
+  class CLI
+
+    include CommandKit::Commands
+
+    class << self
+      # The global configuration file setting.
+      #
+      # @return [String, nil]
+      attr_accessor :config_file
+    end
+
+    command_name 'foo'
+
+    # Commands must be explicitly registered, unless
+    # CommandKit::Commands::AutoLoad.new(...) is included.
+    command Config
+    command List
+    command Update
+
+    # Commands may have aliases
+    command_aliases['ls'] = 'list'
+    command_aliases['up'] = 'update'
+
+    # Global options may be defined which are parsed before the sub-command's
+    # options are parsed and the sub-command is executed.
+    option :config_file, short: '-C',
+                         value: {
+                           type: String,
+                           usage: 'FILE'
+                         },
+                         desc: 'Global option to set the config file' do |file|
+                           CLI.config_file = file
+                         end
+
+  end
+end
+
+if $0 == __FILE__
+  # Normally you would invoke Foo::CLI.start from a bin/ script.
+  Foo::CLI.start
+end

data/gemspec.yml

@@ -1,7 +1,7 @@
 name: command_kit
-summary: A toolkit for building Ruby CLI commands
+summary: An all-in-one modular Ruby CLI toolkit
 description:
-  A Ruby toolkit for building clean, correct, and robust CLI commands as
+  A modular Ruby toolkit for building clean, correct, and robust CLI commands as
   plain-old Ruby classes.
 
 license: MIT
@@ -16,7 +16,7 @@ metadata:
   changelog_uri:     https://github.com/postmodern/command_kit.rb/blob/main/ChangeLog.md
   rubygems_mfa_required: 'true'
 
-required_ruby_version: ">= 2.7.0"
+required_ruby_version: ">= 3.0.0"
 
 development_dependencies:
   bundler: ~> 2.0