command_kit 0.1.0 → 0.3.0

data/README.md

@@ -1,8 +1,12 @@
 # command_kit
 
+[![Build Status](https://github.com/postmodern/command_kit.rb/workflows/CI/badge.svg?branch=main)](https://github.com/postmodern/command_kit.rb/actions)
+[![Code Climate](https://codeclimate.com/github/postmodern/command_kit.rb.svg)](https://codeclimate.com/github/postmodern/command_kit.rb)
+[![Gem Version](https://badge.fury.io/rb/command_kit.svg)](https://badge.fury.io/rb/command_kit)
+
 * [Homepage](https://github.com/postmodern/command_kit.rb#readme)
-* [Forum](https://github.com/postmodern/command_kit.rb/discussions)
-* [Issues](https://github.com/postmodern/command_kit.rb/issues)
+* [Forum](https://github.com/postmodern/command_kit.rb/discussions) |
+  [Issues](https://github.com/postmodern/command_kit.rb/issues)
 * [Documentation](http://rubydoc.info/gems/command_kit/frames)
 
 ## Description
@@ -12,53 +16,26 @@ plain-old Ruby classes.
 
 ## Features
 
-* Supports defining commands as Classes.
-* Supports defining options and arguments as attributes.
-* Supports extending commands via inheritance.
-* Supports subcommands (explicit or lazy-loaded) and command aliases.
-* Correctly handles Ctrl^C and SIGINT interrupts (aka exit 130).
-* Correctly handles broken pipes (aka `mycmd | head`).
-* Correctly handles when stdout or stdin is redirected to a file.
-* Uses [OptionParser][optparse] for POSIX option parsing.
-* Supports optionally displaying a man-page instead of `--help`
-  (see {CommandKit::Help::Man}).
-* Supports optional ANSI coloring.
-* Supports interactively prompting for user input.
-* Supports easily detecting the terminal size.
-* Supports paging output with `less` or `more`.
-* Supports XDG directories (`~/.config/`, `~/.local/share/`, `~/.cache/`).
-* Easy to test (ex: `MyCmd.main(arg1, arg2, options: {foo: foo}) # => 0`)
-
-### API
-
-* [CommandKit::Arguments](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Arguments)
-* [CommandKit::Colors](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Colors)
-* [CommandKit::Command](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Command)
-* [CommandKit::CommandName](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/CommandName)
-* [CommandKit::Commands](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Commands)
-  * [CommandKit::Commands::AutoLoad](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Commands/AutoLoad)
-  * [CommandKit::Commands::AutoRequire](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Commands/AutoRequire)
-* [CommandKit::Description](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Description)
-* [CommandKit::Env](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Env)
-  * [CommandKit::Env::Home](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Env/Home)
-  * [CommandKit::Env::Path](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Env/Path)
-* [CommandKit::Examples](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Examples)
-* [CommandKit::ExceptionHandler](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/ExceptionHandler)
-* [CommandKit::Help](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Help)
-  * [CommandKit::Help::Man](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Help/Man)
-* [CommandKit::Interactive](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Interactive)
-* [CommandKit::Main](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Main)
-* [CommandKit::Options](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Options)
-  * [CommandKit::Options::Quiet](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Options/Quiet)
-  * [CommandKit::Options::Verbose](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Options/Verbose)
-* [CommandKit::Pager](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Pager)
-* [CommandKit::Printing](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Printing)
-  * [CommandKit::Printing::Indent](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Printing/Indent)
-* [CommandKit::ProgramName](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/ProgramName)
-* [CommandKit::Stdio](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Stdio)
-* [CommandKit::Terminal](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Terminal)
-* [CommandKit::Usage](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/Usage)
-* [CommandKit::XDG](https://rubydoc.info/github/postmodern/command_kit/main/CommandKit/XDG)
+* **Simple** - Commands are plain-old ruby classes, with options and
+  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`).
+  * Uses [OptionParser][optparse] for POSIX option parsing.
+  * Disables ANSI color when output is redirected to a file.
+* **Complete** - Provides many additional CLI features.
+  * OS detection.
+  * Terminal size detection.
+  * ANSI coloring support.
+  * Interactive input.
+  * 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
+  initialize them and call `#main` or `#run`.
 
 ## Anti-Features
 
@@ -66,103 +43,194 @@ plain-old Ruby classes.
 * Does not implement it's own option parser.
 * Not named after a comic-book Superhero.
 
+## Requirements
+
+* [ruby] >= 2.7.0
+
+## Install
+
+```sh
+$ gem install command_kit
+```
+
+### gemspec
+
+```ruby
+gem.add_dependency 'command_kit', '~> 0.2'
+```
+
+### Gemfile
+
+```ruby
+gem 'command_kit', '~> 0.2'
+```
+
 ## Examples
 
 ### lib/foo/cli/my_cmd.rb
 
-    require 'command_kit'
-
-    module Foo
-      module CLI
-        class MyCmd < CommandKit::Command
-    
-          usage '[OPTIONS] [-o OUTPUT] FILE'
-    
-          option :count, short: '-c',
-                         value: {
-                           type: Integer,
-                           default: 1
-                         },
-                         desc: "Number of times"
-    
-          option :output, short: '-o',
-                          value: {
-                            type: String,
-                            usage: 'FILE'
-                          },
-                          desc: "Optional output file"
-    
-          option :verbose, short: '-v', desc: "Increase verbose level" do
-            @verbose += 1
-          end
-    
-          argument :file, required: true,
-                          usage: 'FILE',
-                          desc: "Input file"
-
-          examples [
-            '-o path/to/output.txt path/to/input.txt',
-            '-v -c 2 -o path/to/output.txt path/to/input.txt',
-          ]
-
-          description 'Example command'
-    
-          def initialize(**kwargs)
-            super(**kwargs)
-    
-            @verbose = 0
-          end
-    
-          def run(file)
-            puts "count=#{options[:count].inspect}"
-            puts "output=#{options[:output].inspect}"
-            puts "file=#{file.inspect}"
-            puts "verbose=#{@verbose.inspect}"
-          end
-    
-        end
+```ruby
+require 'command_kit'
+
+module Foo
+  module CLI
+    class MyCmd < CommandKit::Command
+
+      usage '[OPTIONS] [-o OUTPUT] FILE'
+
+      option :count, short: '-c',
+                     value: {
+                       type: Integer,
+                       default: 1
+                     },
+                     desc: "Number of times"
+
+      option :output, short: '-o',
+                      value: {
+                        type: String,
+                        usage: 'FILE'
+                      },
+                      desc: "Optional output file"
+
+      option :verbose, short: '-v', desc: "Increase verbose level" do
+        @verbose += 1
       end
+
+      argument :file, required: true,
+                      usage: 'FILE',
+                      desc: "Input file"
+
+      examples [
+        '-o path/to/output.txt path/to/input.txt',
+        '-v -c 2 -o path/to/output.txt path/to/input.txt',
+      ]
+
+      description 'Example command'
+
+      def initialize(**kwargs)
+        super(**kwargs)
+
+        @verbose = 0
+      end
+
+      def run(file)
+        puts "count=#{options[:count].inspect}"
+        puts "output=#{options[:output].inspect}"
+        puts "file=#{file.inspect}"
+        puts "verbose=#{@verbose.inspect}"
+      end
+
     end
+  end
+end
+```
 
 ### bin/my_cmd
 
-    #!/usr/bin/env ruby
-    
-    $LOAD_PATH.unshift(File.expand_path('../../lib',__FILE__))
-    require 'foo/cli/my_cmd'
-    
-    Foo::CLI::MyCmd.start
+```ruby
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path('../../lib',__FILE__))
+require 'foo/cli/my_cmd'
+
+Foo::CLI::MyCmd.start
+```
 
 ### --help
 
     Usage: my_cmd [OPTIONS] [-o OUTPUT] FILE
-    
+
     Options:
         -c, --count INT                  Number of times (Default: 1)
         -o, --output FILE                Optional output file
         -v, --verbose                    Increase verbose level
         -h, --help                       Print help information
-    
+
     Arguments:
         FILE                             Input file
-    
+
     Examples:
         my_cmd -o path/to/output.txt path/to/input.txt
         my_cmd -v -c 2 -o path/to/output.txt path/to/input.txt
-    
-    Example command
 
-## Requirements
-
-* [ruby] >= 2.7.0
+    Example command
 
-## Install
+## Testing
+
+### RSpec
+
+```ruby
+require 'spec_helper'
+require 'stringio'
+require 'foo/cli/my_cmd'
+
+describe Foo::CLI::MyCmd do
+  let(:stdin)  { StringIO.new }
+  let(:stdout) { StringIO.new }
+  let(:stderr) { StringIO.new }
+  let(:env)    { ENV }
+
+  subject do
+    described_class.new(
+      stdin:   stdin,
+      stdout:  stdout,
+      stderr:  stderr,
+      env:     env
+    )
+  end
+
+  # testing with raw options/arguments
+  describe "#main" do
+    context "when executed with no arguments" do
+      it "must exit with -1" do
+        expect(subject.main([])).to eq(-1)
+      end
+    end
 
-    $ gem install command_kit
+    context "when executed with -o OUTPUT" do
+      let(:file)   { ... }
+      let(:output) { ... }
 
-### Gemfile
+      before { subject.main(["-o", output, file]) }
 
-    gem 'command_kit', '~> 0.1'
+      it "must create the output file" do
+        ...
+      end
+    end
+  end
+end
+```
+
+### Reference
+
+* [CommandKit::Arguments](https://rubydoc.info/gems/command_kit/CommandKit/Arguments)
+* [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)
+* [CommandKit::Commands](https://rubydoc.info/gems/command_kit/CommandKit/Commands)
+  * [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::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::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)
+* [CommandKit::Main](https://rubydoc.info/gems/command_kit/CommandKit/Main)
+* [CommandKit::Options](https://rubydoc.info/gems/command_kit/CommandKit/Options)
+  * [CommandKit::Options::Quiet](https://rubydoc.info/gems/command_kit/CommandKit/Options/Quiet)
+  * [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::Indent](https://rubydoc.info/gems/command_kit/CommandKit/Printing/Indent)
+* [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)
+* [CommandKit::Usage](https://rubydoc.info/gems/command_kit/CommandKit/Usage)
+* [CommandKit::XDG](https://rubydoc.info/gems/command_kit/CommandKit/XDG)
 
 ## Alternatives
 

data/Rakefile

@@ -1,5 +1,3 @@
-# encoding: utf-8
-
 require 'rubygems'
 
 begin
@@ -21,3 +19,6 @@ task :default => :spec
 require 'yard'
 YARD::Rake::YardocTask.new
 task :doc => :yard
+
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new

data/command_kit.gemspec

@@ -1,5 +1,3 @@
-# encoding: utf-8
-
 require 'yaml'
 
 Gem::Specification.new do |gem|
@@ -20,11 +18,13 @@ Gem::Specification.new do |gem|
   gem.authors     = Array(gemspec['authors'])
   gem.email       = gemspec['email']
   gem.homepage    = gemspec['homepage']
+  gem.metadata    = gemspec['metadata'] if gemspec['metadata']
 
   glob = lambda { |patterns| gem.files & Dir[*patterns] }
 
-  gem.files = `git ls-files`.split($/)
-  gem.files = glob[gemspec['files']] if gemspec['files']
+  gem.files = if gemspec['files'] then glob[gemspec['files']]
+              else                     `git ls-files`.split($/)
+              end
 
   gem.executables = gemspec.fetch('executables') do
     glob['bin/*'].map { |path| File.basename(path) }

data/examples/command.rb

@@ -16,7 +16,7 @@ class Command < CommandKit::Command
 
   option :output, value: {
                     type: String,
-                    usage: 'FILE',
+                    usage: 'FILE'
                   },
                   short: '-o',
                   desc: "Optional output file"

data/gemspec.yml

@@ -9,6 +9,13 @@ authors: Postmodern
 email: postmodern.mod3@gmail.com
 homepage: https://github.com/postmodern/command_kit.rb#readme
 
+metadata:
+  documentation_uri: https://rubydoc.info/gems/command_kit
+  source_code_uri:   https://github.com/postmodern/command_kit.rb
+  bug_tracker_uri:   https://github.com/postmodern/command_kit.rb/issues
+  changelog_uri:     https://github.com/postmodern/command_kit.rb/blob/main/ChangeLog.md
+  rubygems_mfa_required: 'true'
+
 required_ruby_version: ">= 2.7.0"
 
 development_dependencies:

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

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+require 'command_kit/arguments/argument'
+require 'command_kit/usage'
 require 'command_kit/main'
 require 'command_kit/help'
-require 'command_kit/arguments/argument'
+require 'command_kit/printing'
 
 module CommandKit
   #
@@ -44,9 +46,19 @@ module CommandKit
   #     def run(*files)
   #     end
   #
+  # ### Multi-line descriptions
+  #
+  #     argument :arg, desc: [
+  #                            'line1',
+  #                            'line2',
+  #                            '...'
+  #                          ]
+  #
   module Arguments
+    include Usage
     include Main
     include Help
+    include Printing
 
     #
     # @api private
@@ -110,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]
@@ -119,9 +131,15 @@ 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:
-      #     option :bar, usage: 'BAR',
-      #                  desc: "Bar argument"
+      #     argument :bar, usage: 'BAR',
+      #                    desc: "Bar argument"
       #
       # @example With a custom type:
       #     argument :bar, desc: "Bar argument"
@@ -168,7 +186,7 @@ module CommandKit
         help_usage
         return 1
       elsif argv.length > (required_args + optional_args) && !has_repeats_arg
-        print_error("too many arguments given")
+        print_error("too many arguments given.")
         help_usage
         return 1
       end
@@ -186,8 +204,19 @@ module CommandKit
         puts
         puts 'Arguments:'
 
-        self.class.arguments.each_value do |arg|
-          puts "    #{arg.usage.ljust(33)}#{arg.desc}"
+        arguments.each_value do |arg|
+          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