command_kit 0.2.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d04119403fa9585e0258d2b20bb7c307d124aafb70c88e03749395c7b4eedb97
-  data.tar.gz: 3ec992adf12bbc98313bb6ff8f3038091b50b31abbf8950765a71edd771378fb
+  metadata.gz: 72a3fdeb65d9eb4c4e996aa95ea7e8131e220c2cb24be8b17d56e1742a156d35
+  data.tar.gz: d05b75366f58c219c9680d07571a171239f0ab8f77580cb1c2d47c6322d7e74c
 SHA512:
-  metadata.gz: faeeaa08921ab315a825d4b1ff69f6b254c53b6675dd4278478b77200d6d2afb688d110757685ed33d74b90a6b1e9394c12135c3ab5f08e2ca3ca5834ead248d
-  data.tar.gz: 6b4ba3da0434c9fbd93d92a4c9d91e8eb53f1185df15edb21283c09b2ddf9ec4dc9fcb3708bdf83a1158cef92c988ccb5133ec5664ac9dcb213bdcde45aacf3d
+  metadata.gz: 1cc85835b40fded3170ee21619620dbb988dd3427fa8cb48456f09a7991b6eed72299a81ba19be543c260557504d5636237993f33360d463d72a87600ca14441
+  data.tar.gz: 9d57ec57d540547d2fa664faf8e3bb1e0c0aa06929162d3dac849f858911aa5e7610e8294b2189927d8633de8e9784079df548a3e900fd73c57f76e72c87ad9d

data/.github/workflows/ruby.yml

@@ -10,12 +10,11 @@ jobs:
       fail-fast: false
       matrix:
         ruby:
-          - 2.7
-          - 3.0
+          - '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
@@ -36,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

@@ -7,7 +7,7 @@ AllCops:
 # our rules
 #
 
-Layout/FirstArrayElementIndentation: { EnforcedStyle: consistent }
+Layout/FirstArrayElementIndentation: { Exclude: ['spec/**/*'] }
 Layout/LineLength: { Enabled: false }
 Layout/SpaceAroundEqualsInParameterDefault: { EnforcedStyle: no_space }
 Lint/ConstantDefinitionInBlock: { Exclude: ['spec/**/*'] }
@@ -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,85 @@
+### 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}.
+
+#### CommandKit::FileUtils
+
+* Added {CommandKit::FileUtils#erb #erb}.
+
+#### CommandKit::Colors
+
+* Added {CommandKit::Colors::ANSI::RESET_FG RESET_FG}.
+* Added {CommandKit::Colors::ANSI.bright_black bright_black}.
+* Added {CommandKit::Colors::ANSI.gray gray}.
+* Added {CommandKit::Colors::ANSI.bright_red bright_red}.
+* Added {CommandKit::Colors::ANSI.bright_green bright_green}.
+* Added {CommandKit::Colors::ANSI.bright_yellow bright_yellow}.
+* Added {CommandKit::Colors::ANSI.bright_blue bright_blue}.
+* Added {CommandKit::Colors::ANSI.bright_magenta bright_magenta}.
+* Added {CommandKit::Colors::ANSI.bright_cyan bright_cyan}.
+* Added {CommandKit::Colors::ANSI.bright_white bright_white}.
+* Added {CommandKit::Colors::ANSI.on_bright_black on_bright_black}.
+* Added {CommandKit::Colors::ANSI.on_gray on_gray}.
+* Added {CommandKit::Colors::ANSI.on_bright_red on_bright_red}.
+* Added {CommandKit::Colors::ANSI.on_bright_green on_bright_green}.
+* Added {CommandKit::Colors::ANSI.on_bright_yellow on_bright_yellow}.
+* Added {CommandKit::Colors::ANSI.on_bright_blue on_bright_blue}.
+* Added {CommandKit::Colors::ANSI.on_bright_magenta on_bright_magenta}.
+* Added {CommandKit::Colors::ANSI.on_bright_cyan on_bright_cyan}.
+* Added {CommandKit::Colors::ANSI.on_bright_white on_bright_white}.
+
+#### ComandKit::Options
+
+* Allow grouping options into categories:
+
+      option :opt1, category: 'Foo Options',
+                    desc: 'Option 1'
+
+      option :opt2, category: 'Foo Options',
+                    desc: 'Option 1'
+
+* Allow options to have multi-line descriptions:
+
+      option :opt1, short: '-o',
+                    desc: [
+                            'line1',
+                            'line2',
+                            '...'
+                          ]
+
+#### CommandKit::Arguments
+
+* Allow arguments to have multi-line descriptions:
+
+      argument :arg1, desc: [
+                              'line1',
+                              'line2',
+                              '...'
+                            ]
+
+
+#### CommandKit::ProgramName
+
+* Added {CommandKit::ProgramName#command_name}.
+
 ### 0.2.2 / 2021-12-26
 
 #### CommandKit::Help::Man

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/arguments/argument.rb

@@ -16,7 +16,7 @@ module CommandKit
 
       # The argument's description.
       #
-      # @return [String]
+      # @return [String, Array<String>]
       attr_reader :desc
 
       #
@@ -34,7 +34,7 @@ module CommandKit
       # @param [Boolean] repeats
       #   Specifies whether the argument can be repeated multiple times.
       #
-      # @param [String] desc
+      # @param [String, Array<String>] desc
       #   The description for the argument.
       #
       # @yield [(value)]

data/lib/command_kit/arguments.rb

@@ -46,6 +46,14 @@ module CommandKit
   #     def run(*files)
   #     end
   #
+  # ### Multi-line descriptions
+  #
+  #     argument :arg, desc: [
+  #                            'line1',
+  #                            'line2',
+  #                            '...'
+  #                          ]
+  #
   module Arguments
     include Usage
     include Main
@@ -114,7 +122,7 @@ module CommandKit
       # @option kwargs [Boolean] repeats
       #   Specifies whether the argument can be repeated multiple times.
       #
-      # @option kwargs [String] desc
+      # @option kwargs [String, Array<String>] desc
       #   The description for the argument.
       #
       # @return [Argument]
@@ -123,6 +131,12 @@ module CommandKit
       # @example Define an argument:
       #     argument :bar, desc: "Bar argument"
       #
+      # @example Defines an argument with a multi-line description:
+      #     argument :bar, desc: [
+      #                            "Line 1 ...",
+      #                            "Line 2 ..."
+      #                          ]
+      #
       # @example With a custom usage string:
       #     argument :bar, usage: 'BAR',
       #                    desc: "Bar argument"
@@ -191,7 +205,18 @@ module CommandKit
         puts 'Arguments:'
 
         arguments.each_value do |arg|
-          puts "    #{arg.usage.ljust(33)}#{arg.desc}"
+          case arg.desc
+          when Array
+            arg.desc.each_with_index do |line,index|
+              if index == 0
+                puts "    #{arg.usage.ljust(33)}#{line}"
+              else
+                puts "    #{' '.ljust(33)}#{line}"
+              end
+            end
+          else
+            puts "    #{arg.usage.ljust(33)}#{arg.desc}"
+          end
         end
       end
     end

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