command_kit 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 306f055fa898d4d82c14ba8e79b397ae413280bb7144ce69e1787081620827e9
-  data.tar.gz: e79e640f7d4ae566401e7543d3ba98aa42b1e2396657734e29ab3cd3b383b41c
+  metadata.gz: 72a3fdeb65d9eb4c4e996aa95ea7e8131e220c2cb24be8b17d56e1742a156d35
+  data.tar.gz: d05b75366f58c219c9680d07571a171239f0ab8f77580cb1c2d47c6322d7e74c
 SHA512:
-  metadata.gz: ee4268377db8c2398b5157feda9fa106a0b156537c6085b71fcfd8c7710f898c3bc0ef5d4408d9c6cbcae932e4f4ee4dd49070003e6c5734da06da33fbbace9a
-  data.tar.gz: 03b6a48369bea030002f9432d0d8645d8c0f5cdefba81778922e73a54f267611419bdb63e5033e98b09aa1c6ae97af1e8c3b8135cb7ed4b807fce666c6c379b8
+  metadata.gz: 1cc85835b40fded3170ee21619620dbb988dd3427fa8cb48456f09a7991b6eed72299a81ba19be543c260557504d5636237993f33360d463d72a87600ca14441
+  data.tar.gz: 9d57ec57d540547d2fa664faf8e3bb1e0c0aa06929162d3dac849f858911aa5e7610e8294b2189927d8633de8e9784079df548a3e900fd73c57f76e72c87ad9d

data/.github/workflows/ruby.yml

@@ -10,13 +10,11 @@ jobs:
       fail-fast: false
       matrix:
         ruby:
-          - 2.7
-          - 3.0
-          - 3.1
+          - '3.0'
+          - '3.1'
           # 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 +35,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,15 @@ 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 }

data/ChangeLog.md

@@ -1,3 +1,21 @@
+### 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-2022 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-2022 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/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

data/lib/command_kit/bug_report.rb

@@ -0,0 +1,105 @@
+require 'command_kit/exception_handler'
+require 'command_kit/printing'
+
+module CommandKit
+  #
+  # Adds an exception handler to print a bug report when an unhandled exception
+  # is raised by `run`.
+  #
+  # @since 0.4.0
+  #
+  module BugReport
+    include ExceptionHandler
+    include Printing
+
+    #
+    # @api private
+    #
+    module ModuleMethods
+      #
+      # Extends {ClassMethods} or {ModuleMethods}, depending on whether
+      # {Options} is being included into a class or a module.
+      #
+      # @param [Class, Module] context
+      #   The class or module which is including {Options}.
+      #
+      def included(context)
+        super(context)
+
+        if context.class == Module
+          context.extend ModuleMethods
+        else
+          context.extend ClassMethods
+        end
+      end
+    end
+
+    extend ModuleMethods
+
+    #
+    # Defines class-level methods.
+    #
+    module ClassMethods
+      #
+      # Gets or sets the bug report URL.
+      #
+      # @param [String, nil] new_url
+      #   The new bug report URL.
+      #
+      # @return [String, nil]
+      #   The bug report URL.
+      #
+      # @example
+      #   bug_report_url 'https://github.com/user/repo/issues/new'
+      #
+      def bug_report_url(new_url=nil)
+        if new_url
+          @bug_report_url = new_url
+        else
+          @bug_report_url || if superclass.kind_of?(ClassMethods)
+                               superclass.bug_report_url
+                             end
+        end
+      end
+    end
+
+    #
+    # The bug report URL.
+    #
+    # @return [String, nil]
+    #
+    def bug_report_url
+      self.class.bug_report_url
+    end
+
+    #
+    # Overrides {#on_exception} to print a bug report for unhandled exceptions
+    # and then exit with `-1`.
+    #
+    # @param [Exception] error
+    #   The unhandled exception.
+    #
+    def on_exception(error)
+      print_bug_report(error)
+      exit(-1)
+    end
+
+    #
+    # Prints a bug report for the unhandled exception.
+    #
+    # @param [Exception] error
+    #   The unhandled exception.
+    #
+    def print_bug_report(error)
+      url = bug_report_url
+
+      stderr.puts
+      stderr.puts "Oops! Looks like you have found a bug. Please report it!"
+      stderr.puts url if url
+      stderr.puts
+      stderr.puts '```'
+      print_exception(error)
+      stderr.puts '```'
+    end
+  end
+end

data/lib/command_kit/colors.rb

@@ -998,14 +998,14 @@ module CommandKit
     # @return [Boolean]
     #
     # @note
-    #   When the env variable `TERM` is set to `dumb`, it will disable color
-    #   output. Color output will also be disabled if the given stream is not
-    #   a TTY.
+    #   When the env variable `TERM` is set to `dumb` or when the `NO_COLOR`
+    #   env variable is set, it will disable color output. Color output will
+    #   also be disabled if the given stream is not a TTY.
     #
     # @api public
     #
     def ansi?(stream=stdout)
-      env['TERM'] != 'dumb' && stream.tty?
+      env['TERM'] != 'dumb' && !env['NO_COLOR'] && stream.tty?
     end
 
     #

data/lib/command_kit/edit.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'command_kit/env'
+
+module CommandKit
+  #
+  # Allows invoking the `EDITOR` environment variable.
+  #
+  # ## Environment Variables
+  #
+  # * `EDITOR` - The preferred editor command.
+  #
+  # ## Example
+  #
+  #     if options[:edit]
+  #       edit CONFIG_FILE
+  #     end
+  #
+  # @since 0.4.0
+  #
+  module Edit
+    include Env
+
+    #
+    # The `EDITOR` environment variable.
+    #
+    # @return [String]
+    #   The `EDITOR` environment variable, or `"nano"` if `EDITOR` was not set.
+    #
+    # @api semipublic
+    #
+    def editor
+      env['EDITOR'] || 'nano'
+    end
+
+    #
+    # Invokes the preferred editor with the additional arguments.
+    #
+    # @param [Array] arguments
+    #   The additional arguments to pass to the editor command.
+    #
+    # @return [Boolean, nil]
+    #   Indicates whether the editor successfully launched and exited.
+    #   If the {#editor} command was not installed, `nil` will be returned.
+    #
+    # @api public
+    #
+    def edit(*arguments)
+      if editor
+        system(editor,*arguments.map(&:to_s))
+      end
+    end
+  end
+end

data/lib/command_kit/env.rb

@@ -7,7 +7,7 @@ module CommandKit
   #     class MyCmd
   #       include CommandKit::Env
   #
-  #       def main
+  #       def run
   #         home = env['HOME']
   #         # ...
   #       end

data/lib/command_kit/options/option.rb

@@ -154,7 +154,11 @@ module CommandKit
       #   The usage strings.
       #
       def usage
-        [*@short, "#{@long}#{separator}#{@value && @value.usage}"]
+        if equals? && (@value && @value.optional?)
+          [*@short, "#{@long}[#{separator}#{@value && @value.usage}]"]
+        else
+          [*@short, "#{@long}#{separator}#{@value && @value.usage}"]
+        end
       end
 
       #

data/lib/command_kit/options/option_value.rb

@@ -19,7 +19,7 @@ module CommandKit
     class OptionValue < Arguments::ArgumentValue
 
       # Maps OptionParser types to USAGE strings.
-      USAGES = {
+      DEFAULT_USAGES = {
         # NOTE: NilClass and Object are intentionally omitted
         Date       => 'DATE',
         DateTime   => 'DATE_TIME',
@@ -90,7 +90,7 @@ module CommandKit
       #   The given type was not a Class, Hash, Array, or Regexp.
       #
       def self.default_usage(type)
-        USAGES.fetch(type) do
+        DEFAULT_USAGES.fetch(type) do
           case type
           when Hash   then type.keys.join('|')
           when Array  then type.join('|')

data/lib/command_kit/options/parser.rb

@@ -22,7 +22,7 @@ module CommandKit
     #       end
     #     end
     #     
-    #     def main(*argv)
+    #     def run(*argv)
     #       if @custom
     #         puts "Custom mode enabled"
     #       end

data/lib/command_kit/options/quiet.rb

@@ -9,7 +9,7 @@ module CommandKit
     #
     #     include CommandKit::Options::Quiet
     #     
-    #     def main(*argv)
+    #     def run(*argv)
     #       # ...
     #       puts "verbose output" unless quiet?
     #       # ...

data/lib/command_kit/options/verbose.rb

@@ -7,9 +7,9 @@ module CommandKit
     #
     # ## Examples
     #
-    #     include Options::Verbose
+    #     include CommandKit::Options::Verbose
     #
-    #     def main(*argv)
+    #     def run(*argv)
     #       # ...
     #       puts "verbose output" if verbose?
     #       # ...

data/lib/command_kit/options/version.rb

@@ -5,6 +5,16 @@ module CommandKit
     #
     # Defines a version option.
     #
+    # ## Examples
+    #
+    #     include CommandKit::Options::Version
+    #     
+    #     version '0.1.0'
+    #     
+    #     def run(*argv)
+    #       # ...
+    #     end
+    #
     module Version
       #
       # Includes {Options}, extends {Version::ClassMethods}, and defines a

data/lib/command_kit/options.rb

@@ -247,7 +247,7 @@ module CommandKit
 
       super(**kwargs)
 
-      define_option_categories
+      define_option_categories()
     end
 
     #

data/lib/command_kit/os.rb

@@ -11,7 +11,7 @@ module CommandKit
   #     
   #       include CommandKit::OS
   #     
-  #       def main(*argv)
+  #       def run(*argv)
   #         if linux?
   #           # ...
   #         elsif macos?