command_kit 0.1.0.pre1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: aa6096447b8ddf59149147d020c3fe6f5fcf6de1c167f749692fc1b50dec1b8a
+  data.tar.gz: c4c0a58596e92563f9f69a7fd151a7b7dd9121c8083ca104a21dd3ce53ef2fc5
+SHA512:
+  metadata.gz: a777422cddc17a986940b7cd902ac43c01765b6ef98efe717307f545a29dfe975579bb8eacdce9647cd2ccbd0f210b7a8b0ab3ffac026d8341f2c9669ef56a18
+  data.tar.gz: 7b768f74911ac136b24f755534d31844febb92b5b034e672b4b93c3a45083b4731d9658830b6f700bc8b70106b772f253291ed15fcd36f5f709351808910c93b

data/.document

@@ -0,0 +1,3 @@
+- 
+ChangeLog.md
+LICENSE.txt

data/.github/workflows/ruby.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on: [ push, pull_request ]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          # - 2.4
+          # - 2.5
+          # - 2.6
+          - 2.7
+          - 3.0
+          # TODO: uncomment when jruby supports ruby >= 2.7
+          # - jruby
+    name: Ruby ${{ matrix.ruby }}
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: Install dependencies
+        run: bundle install --jobs 4 --retry 3
+      - name: Run tests
+        run: bundle exec rake test

data/.gitignore

@@ -0,0 +1,7 @@
+/.bundle
+/.yardoc/
+/Gemfile.lock
+/coverage/
+/doc/
+/pkg/
+/vendor/cache/*.gem

data/.rspec

@@ -0,0 +1 @@
+--colour --format documentation

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --title "CommandKit Documentation" --protected

data/ChangeLog.md

@@ -0,0 +1,29 @@
+### 0.1.0 / 2021-05-XX
+
+* Initial release:
+  * {CommandKit::Arguments}
+  * {CommandKit::Colors}
+  * {CommandKit::CommandName}
+  * {CommandKit::Commands}
+    * {CommandKit::Commands::AutoLoad}
+    * {CommandKit::Commands::AutoRequire}
+  * {CommandKit::Console}
+  * {CommandKit::Description}
+  * {CommandKit::Env}
+    * {CommandKit::Env::Home}
+    * {CommandKit::Env::Path}
+  * {CommandKit::Examples}
+  * {CommandKit::ExceptionHandler}
+  * {CommandKit::Help}
+    * {CommandKit::Help::Man}
+  * {CommandKit::Main}
+  * {CommandKit::Options}
+    * {CommandKit::Options::Quiet}
+    * {CommandKit::Options::Verbose}
+  * {CommandKit::Pager}
+  * {CommandKit::Printing}
+  * {CommandKit::ProgramName}
+  * {CommandKit::Stdio}
+  * {CommandKit::Usage}
+  * {CommandKit::XDG}
+

data/Gemfile

@@ -0,0 +1,14 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'rake'
+  gem 'rubygems-tasks', '~> 0.2'
+
+  gem 'rspec', '~> 3.0'
+  gem 'simplecov', '~> 0.20', require: false
+
+  gem 'kramdown'
+  gem 'yard', '~> 0.9'
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2021 Hal Brodigan
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,283 @@
+# command_kit
+
+* [Homepage](https://github.com/postmodern/command_kit#readme)
+* [Issues](https://github.com/postmodern/command_kit/issues)
+* [Documentation](http://rubydoc.info/gems/command_kit/frames)
+* [Email](mailto:postmodern.mod3 at gmail.com)
+
+## Description
+
+A Ruby toolkit for building clean, correct, and robust CLI commands as Ruby
+classes.
+
+## Features
+
+* Supports defining commands as Classes.
+* Supports defining options and arguments as attributes.
+* 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`).
+* Uses [OptionParser][optparse] for option parsing.
+* Provides ANSI coloring support.
+* Supports optionally displaying a man-page instead of `--help`
+  (see {CommandKit::Help::Man}).
+* Supports XDG directories (`~/.config/`, `~/.local/share/`, `~/.cache/`).
+* Easy to test:
+  * `MyCmd.main(arg1, arg2, options: {foo: foo}) # => 0`
+
+### Modules
+
+* {CommandKit::Arguments}
+* {CommandKit::Colors}
+* {CommandKit::CommandName}
+* {CommandKit::Commands}
+  * {CommandKit::Commands::AutoLoad}
+  * {CommandKit::Commands::AutoRequire}
+* {CommandKit::Console}
+* {CommandKit::Description}
+* {CommandKit::Env}
+  * {CommandKit::Env::Home}
+  * {CommandKit::Env::Path}
+* {CommandKit::Examples}
+* {CommandKit::ExceptionHandler}
+* {CommandKit::Help}
+  * {CommandKit::Help::Man}
+* {CommandKit::Main}
+* {CommandKit::Options}
+  * {CommandKit::Options::Quiet}
+  * {CommandKit::Options::Verbose}
+* {CommandKit::Pager}
+* {CommandKit::Printing}
+* {CommandKit::ProgramName}
+* {CommandKit::Stdio}
+* {CommandKit::Usage}
+* {CommandKit::XDG}
+
+## Anti-Features
+
+* No additional runtime dependencies.
+* Does not implement it's own option parser.
+* Not named after a comic-book Superhero.
+
+## Examples
+
+### Command
+
+#### 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, type: String,
+                          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
+
+#### --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
+
+### Options
+
+Define an option:
+
+    option :foo, desc: "Foo option"
+
+With a custom short option:
+
+    option :foo, short: '-f',
+                 desc: "Foo option"
+
+With a custom long option:
+
+    option :foo, short: '--foo-opt',
+                 desc: "Foo option"
+
+With a custom usage string:
+
+    option :foo, value: {usage: 'FOO'},
+                 desc: "Foo option"
+
+With a custom block:
+
+    option :foo, desc: "Foo option" do |value|
+      @foo = Foo.new(value)
+    end
+
+With a custom type:
+
+    option :foo, value: {type: Integer},
+                 desc: "Foo option"
+
+With a default value:
+
+    option :foo, value: {type: Integer, default: 1},
+                 desc: "Foo option"
+
+With a required value:
+
+    option :foo, value: {type: String, required: true},
+                 desc: "Foo option"
+
+With a custom option value Hash map:
+
+    option :flag, value: {
+                    type: {
+                      'enabled'  => :enabled,
+                      'yes'      => :enabled,
+                      'disabled' => :disabled,
+                      'no'       => :disabled
+                    }
+                  },
+                  desc: "Flag option"
+
+With a custom option value Array enum:
+
+    option :enum, value: {type: %w[yes no]},
+                  desc: "Enum option"
+
+With a custom option value Regexp:
+
+    option :date, value: {type: /(\d+)-(\d+)-(\d{2,4})/},
+                  desc: "Regexp optin" do |date,d,m,y|
+      # ...
+    end
+
+### Arguments
+
+Define an argument:
+
+    argument :bar, desc: "Bar argument"
+
+With a custom usage string:
+
+    option :bar, usage: 'BAR',
+                 desc: "Bar argument"
+
+With a custom block:
+
+    argument :bar, desc: "Bar argument" do |bar|
+      # ...
+    end
+
+With a custom type:
+
+    argument :bar, type: Integer,
+                   desc: "Bar argument"
+
+With a default value:
+
+    argument :bar, default: "bar.txt",
+                   desc: "Bar argument"
+
+An optional argument:
+
+    argument :bar, required: true,
+                   desc: "Bar argument"
+
+A repeating argument:
+
+    argument :bar, repeats: true,
+                   desc: "Bar argument"
+
+## Requirements
+
+* [ruby] >= 2.7.0
+
+## Install
+
+    $ gem install command_kit
+
+### Gemfile
+
+    gem 'command_kit', '~> 0.1'
+
+## Alternatives
+
+* [dry-cli](https://dry-rb.org/gems/dry-cli/0.6/)
+* [cmdparse](https://cmdparse.gettalong.org/)
+
+## Special Thanks
+
+Special thanks to everyone who answered my questions and gave feedback on
+Twitter.
+
+## Copyright
+
+Copyright (c) 2021 Hal Brodigan
+
+See {file:LICENSE.txt} for details.
+
+[ruby]: https://www.ruby-lang.org/
+[optparse]: https://rubydoc.info/stdlib/optparse/OptionParser

data/Rakefile

@@ -0,0 +1,23 @@
+# encoding: utf-8
+
+require 'rubygems'
+
+begin
+  require 'bundler/setup'
+rescue LoadError => e
+  abort e.message
+end
+
+require 'rake'
+require 'rubygems/tasks'
+Gem::Tasks.new
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+
+task :test    => :spec
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new
+task :doc => :yard

data/command_kit.gemspec

@@ -0,0 +1,60 @@
+# encoding: utf-8
+
+require 'yaml'
+
+Gem::Specification.new do |gem|
+  gemspec = YAML.load_file('gemspec.yml')
+
+  gem.name    = gemspec.fetch('name')
+  gem.version = gemspec.fetch('version') do
+                  lib_dir = File.join(File.dirname(__FILE__),'lib')
+                  $LOAD_PATH << lib_dir unless $LOAD_PATH.include?(lib_dir)
+
+                  require 'command_kit/version'
+                  CommandKit::VERSION
+                end
+
+  gem.summary     = gemspec['summary']
+  gem.description = gemspec['description']
+  gem.licenses    = Array(gemspec['license'])
+  gem.authors     = Array(gemspec['authors'])
+  gem.email       = gemspec['email']
+  gem.homepage    = gemspec['homepage']
+
+  glob = lambda { |patterns| gem.files & Dir[*patterns] }
+
+  gem.files = `git ls-files`.split($/)
+  gem.files = glob[gemspec['files']] if gemspec['files']
+
+  gem.executables = gemspec.fetch('executables') do
+    glob['bin/*'].map { |path| File.basename(path) }
+  end
+  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') {
+    %w[ext lib].select { |dir| File.directory?(dir) }
+  })
+
+  gem.requirements              = Array(gemspec['requirements'])
+  gem.required_ruby_version     = gemspec['required_ruby_version']
+  gem.required_rubygems_version = gemspec['required_rubygems_version']
+  gem.post_install_message      = gemspec['post_install_message']
+
+  split = lambda { |string| string.split(/,\s*/) }
+
+  if gemspec['dependencies']
+    gemspec['dependencies'].each do |name,versions|
+      gem.add_dependency(name,split[versions])
+    end
+  end
+
+  if gemspec['development_dependencies']
+    gemspec['development_dependencies'].each do |name,versions|
+      gem.add_development_dependency(name,split[versions])
+    end
+  end
+end