command_kit 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5dc00be598fd9cee093dbfaf32a03118897179587d4dc17c97fdde2b020d3ac7
-  data.tar.gz: 88e498fa844b4db50dc194f6ec474d7c85bbea1619bf1340e6d2abfc4c13c0b3
+  metadata.gz: a218265a42b8b11c95888d07a3dcc3817d534adf830f8e7b1f1790bae73f05d6
+  data.tar.gz: c11cf5b2179d0701d5164b5ffcc07f2040cf8c813ea68caafdd7602e8603b754
 SHA512:
-  metadata.gz: 5fd2683d7d3fb3f4c1258019d209b9f8ca348b0fc71c21c9f292b6799502dcfbc39d8f5ff8e50d54b822aaf229eedd85c3e151bea0f9c92d13dc08bb5b6d947e
-  data.tar.gz: 4276756c0495b2583303c9db090cd0e1221681d7eb357b34d4078a7e59167695f3250552c58ff0be24ee27535fb49ab2ce15d8e0711ee44cebbb93a52f6dfac0
+  metadata.gz: 7bd20d0e6b33b1d84933ea246c51b552c8652e3f59c8ec3fe32bf1944148377799b20b8177f0025114689ff5f73a88d08fe14171bdbd48189ab4123ba9129113
+  data.tar.gz: 617efce051bc51bbb88ada26a83ded0e158b8e0af28ab2bad8af1478aac05a156833aa3bfd95b59e7b07daf1075c08e60f7f6165cc28b76908cb13eb694c4f4b

data/.rubocop.yml

@@ -85,6 +85,7 @@ Style/IfUnlessModifier: { Enabled: false } # Offense count: 13
 Style/MethodCallWithoutArgsParentheses: { Enabled: false } # Offense count: 10
 Style/SpecialGlobalVars: { Enabled: false } # Offense count: 28
 Style/StringLiterals: { Enabled: false } # Offense count: 774
+Lint/ElseLayout: { Enabled: false } # Offense count: 22
 
 # < 10 violations
 Layout/EmptyLinesAroundModuleBody: { Enabled: false } # Offense count: 5
@@ -135,4 +136,6 @@ Style/RegexpLiteral: { Enabled: false } # Offense count: 1
 Style/RescueStandardError: { Enabled: false } # Offense count: 1
 Style/SoleNestedConditional: { Enabled: false } # Offense count: 1
 Style/TrailingCommaInHashLiteral: { Enabled: false } # Offense count: 2
-Style/PercentLiteralDelimiters: { Enabled: false } # Offense count: 2
+
+# rubocop cannot tell that rubygems_mfa_required is enabled in gemspec.yml
+Gemspec/RequireMFA: { Enabled: false }

data/ChangeLog.md

@@ -1,3 +1,67 @@
+### 0.2.1 / 2021-11-16
+
+* Ensure that all error messages end with a period.
+* Documentation fixes.
+* Opt-in to [rubygem.org MFA requirement](https://guides.rubygems.org/mfa-requirement-opt-in/).
+
+#### CommandKit::Printing
+
+* Auto-detect whether {CommandKit::CommandName#command_name #command_name} is
+  available, and if so, prepend the command name to all error messages.
+
+#### CommandKit::Help::Man
+
+* Expand the path given to
+  {CommandKit::Help::Man::ClassMethods#man_dir man_dir}.
+* If {CommandKit::Help::Man::ClassMethods#man_dir man_dir} is not set, fallback
+  to regular `--help` output.
+
+#### CommandKit::Arguments
+
+* Include {CommandKit::Usage} and {CommandKit::Printing} into
+  {CommandKit::Arguments}.
+
+#### CommandKit::Options
+
+* Include {CommandKit::Arguments} into {CommandKit::Options}.
+* Ensure that {CommandKit::Options::Parser#main} runs before
+  {CommandKit::Arguments#main}.
+* Ensure that {CommandKit::Options#help} also calls
+  {CommandKit::Arguments#help_arguments}.
+* Always prepopulate {CommandKit::Options#options #options} with option's
+  default values.
+  * Note: if an option has a default value but the option's value is not
+    required (ex: `value: {required: false, default: "foo"}`), and the option's
+    flag is given but no value is given (ex: `--option-flag --some-other-flag`),
+    the option's value in {CommandKit::Options#options #options} will be `nil`
+    _not_ the option's default value (`"foo"`). This helps indicate that the
+    option's flag was given but no value was given with it.
+
+#### CommandKit::Options::OptionValue
+
+* When a `Class` is passed to {CommandKit::Options::OptionValue.default_usage},
+  demodularize the class name before converting it to underscored/uppercase.
+
+#### CommandKit::Command
+
+* Fixed the inclusion order of {CommandKit::Options} and
+  {CommandKit::Arguments}.
+
+#### CommandKit::Commands
+
+* Define the `COMMAND` and `ARGS` arguments.
+* Correctly duplicate the {CommandKit::Env#env env} (which can be either `ENV`
+  or a `Hash`) to work on ruby-3.1.0-preview1.
+* Print command aliases that were set explicitly
+  (ex: `command_aliases['rm'] = 'remove'`) in {CommandKit::Commands#help}.
+* Print help and exit with status `1` if no command is given. This matches the
+  behavior of the `git` command.
+
+#### CommandKit::Commands::AutoLoad
+
+* Ensure that any explicit command aliases are added to the command's
+  {CommandKit::Commands::ClassMethods#command_aliases command_aliases}.
+
 ### 0.2.0 / 2021-08-31
 
 * Added {CommandKit::Colors::ANSI#on_black}.

data/README.md

@@ -1,6 +1,8 @@
 # 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) |
@@ -153,6 +155,52 @@ Foo::CLI::MyCmd.start
 
     Example command
 
+## 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
+
+    context "when executed with -o OUTPUT" do
+      let(:file)   { ... }
+      let(:output) { ... }
+
+      before { subject.main(["-o", output, file]) }
+
+      it "must create the output file" do
+        ...
+      end
+    end
+  end
+end
+```
+
 ### Reference
 
 * [CommandKit::Arguments](https://rubydoc.info/gems/command_kit/CommandKit/Arguments)

data/gemspec.yml

@@ -14,7 +14,7 @@ metadata:
   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"
 

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
   #
@@ -45,8 +47,10 @@ module CommandKit
   #     end
   #
   module Arguments
+    include Usage
     include Main
     include Help
+    include Printing
 
     #
     # @api private
@@ -168,7 +172,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

data/lib/command_kit/colors.rb

@@ -104,7 +104,7 @@ module CommandKit
       # @since 0.2.0
       ON_BLUE = "\e[44m"
 
-      # ANSI color code for background color megenta
+      # ANSI color code for background color magenta
       #
       # @since 0.2.0
       ON_MAGENTA = "\e[45m"

data/lib/command_kit/commands/auto_load.rb

@@ -162,7 +162,14 @@ module CommandKit
       #
       def included(command)
         command.include Commands
-        command.commands.merge!(@commands)
+
+        @commands.each do |name,subcommand|
+          command.commands[name] = subcommand
+
+          subcommand.aliases.each do |alias_name|
+            command.command_aliases[alias_name] = name
+          end
+        end
       end
     end
   end

data/lib/command_kit/commands/help.rb

@@ -14,7 +14,8 @@ module CommandKit
 
       include ParentCommand
 
-      argument :command, desc: 'Command name to lookup'
+      argument :command, required: false,
+                         desc: 'Command name to lookup'
 
       #
       # Prints the given commands `--help` output or lists registered commands.
@@ -34,7 +35,7 @@ module CommandKit
 
             subcommand.help
           else
-            print_error "#{command_name}: unknown command: #{command}"
+            print_error "unknown command: #{command}"
             exit(1)
           end
         end

data/lib/command_kit/commands/subcommand.rb

@@ -36,7 +36,7 @@ module CommandKit
       #   Optional alias names for the subcommand.
       #
       def initialize(command, summary: self.class.summary(command),
-                                   aliases: [])
+                              aliases: [])
         @command = command
         @summary = summary
         @aliases = aliases.map(&:to_s)

data/lib/command_kit/commands.rb

@@ -59,6 +59,13 @@ module CommandKit
           context.extend ModuleMethods
         else
           context.usage "[options] [COMMAND [ARGS...]]"
+          context.argument :command, required: false,
+                                     desc: 'The command name to run'
+
+          context.argument :args, required: false,
+                                  repeats: true,
+                                  desc: 'Additional arguments for the command'
+
           context.extend ClassMethods
           context.command Help
         end
@@ -140,11 +147,10 @@ module CommandKit
                end
 
         subcommand = Subcommand.new(command_class,**kwargs)
-
         commands[name] = subcommand
 
-        subcommand.aliases.each do |command_alias|
-          command_aliases[command_alias] = name
+        subcommand.aliases.each do |alias_name|
+          command_aliases[alias_name] = name
         end
 
         return subcommand
@@ -220,7 +226,9 @@ module CommandKit
       end
 
       if command_class.include?(Env)
-        kwargs[:env] = env.dup
+        kwargs[:env] = if env.eql?(ENV) then env.to_h
+                       else                  env.dup
+                       end
       end
 
       if command_class.include?(Options)
@@ -296,6 +304,7 @@ module CommandKit
         exit invoke(command,*argv)
       else
         help
+        exit(1)
       end
     end
 
@@ -309,8 +318,14 @@ module CommandKit
         puts
         puts "Commands:"
 
+        command_aliases = Hash.new { |hash,key| hash[key] = [] }
+
+        self.class.command_aliases.each do |alias_name,name|
+          command_aliases[name] << alias_name
+        end
+
         self.class.commands.sort.each do |name,subcommand|
-          names = [name, *subcommand.aliases].join(', ')
+          names = [name, *command_aliases[name]].join(', ')
 
           if subcommand.summary
             puts "    #{names}\t#{subcommand.summary}"

data/lib/command_kit/env/path.rb

@@ -16,7 +16,7 @@ module CommandKit
 
       # The home directory.
       #
-      # @return [String]
+      # @return [Array<String>]
       #
       # @api semipublic
       attr_reader :path_dirs

data/lib/command_kit/help/man.rb

@@ -70,7 +70,7 @@ module CommandKit
         #
         def man_dir(new_man_dir=nil)
           if new_man_dir
-            @man_dir = new_man_dir
+            @man_dir = File.expand_path(new_man_dir)
           else
             @man_dir || if superclass.kind_of?(ClassMethods)
                           superclass.man_dir
@@ -115,10 +115,6 @@ module CommandKit
       # @api semipublic
       #
       def help_man(man_page=self.class.man_page)
-        unless self.class.man_dir
-          raise(NotImplementedError,"#{self.class}.man_dir not set")
-        end
-
         man_path = File.join(self.class.man_dir,man_page)
 
         man(man_path)
@@ -139,11 +135,19 @@ module CommandKit
       #
       def help
         if stdout.tty?
-          if help_man.nil?
-            # the `man` command is not installed
+          if self.class.man_dir
+            status = help_man
+
+            if status.nil?
+              # the `man` command is not installed
+              super
+            end
+          else
+            # man_dir was not set
             super
           end
         else
+          # stdout is not a TTY
           super
         end
       end

data/lib/command_kit/inflector.rb

@@ -44,7 +44,7 @@ module CommandKit
 
       until scanner.eos?
         if (separator = scanner.scan(/[_-]+/))
-          new_string << '_' * separator.length
+          new_string << ('_' * separator.length)
         else
           if (capitalized = scanner.scan(/[A-Z][a-z\d]+/))
             new_string << capitalized
@@ -57,7 +57,7 @@ module CommandKit
           end
 
           if (separator = scanner.scan(/[_-]+/))
-            new_string << '_' * separator.length
+            new_string << ('_' * separator.length)
           elsif !scanner.eos?
             new_string << '_'
           end

data/lib/command_kit/interactive.rb

@@ -218,6 +218,15 @@ module CommandKit
     #
     # Asks the user for secret input.
     #
+    # @param [String] prompt
+    #   The prompt that will be printed before reading input.
+    #
+    # @param [Boolean] required
+    #   Requires non-empty input.
+    #
+    # @return [String]
+    #   The user input.
+    #
     # @example
     #   ask_secret("Password")
     #   # Password: 

data/lib/command_kit/open_app.rb

@@ -9,7 +9,7 @@ module CommandKit
   # ## Examples
   #
   #     open_app_for "movie.avi"
-  #     open_app_for "https://github.com/postmodern/command_kit.rb"
+  #     open_app_for "https://github.com/postmodern/command_kit.rb#readme"
   #
   # @since 0.2.0
   #

data/lib/command_kit/options/option_value.rb

@@ -41,7 +41,7 @@ module CommandKit
 
       # The desired type of the argument value.
       #
-      # @return [Class, Hash, Array, Regexp, nil]
+      # @return [Class, Hash, Array, Regexp]
       attr_reader :type
 
       # The default parsed value for the argument value.
@@ -92,10 +92,11 @@ module CommandKit
       def self.default_usage(type)
         USAGES.fetch(type) do
           case type
-          when Class  then Inflector.underscore(type.name).upcase
           when Hash   then type.keys.join('|')
           when Array  then type.join('|')
           when Regexp then type.source
+          when Class
+            Inflector.underscore(Inflector.demodularize(type.name)).upcase
           else
             raise(TypeError,"unsupported option type: #{type.inspect}")
           end

data/lib/command_kit/options/parser.rb

@@ -144,8 +144,8 @@ module CommandKit
       # @api semipublic
       #
       def on_parse_error(error)
-        print_error("#{command_name}: #{error.message}")
-        print_error("Try '#{command_name} --help' for more information.")
+        print_error(error.message)
+        stderr.puts("Try '#{command_name} --help' for more information.")
         exit(1)
       end
 

data/lib/command_kit/options.rb

@@ -1,3 +1,4 @@
+require 'command_kit/arguments'
 require 'command_kit/options/option'
 require 'command_kit/options/parser'
 
@@ -36,6 +37,7 @@ module CommandKit
   #     end
   #
   module Options
+    include Arguments
     include Parser
 
     #
@@ -211,12 +213,12 @@ module CommandKit
       super(**kwargs)
 
       self.class.options.each_value do |option|
+        default_value = option.default_value
+
+        @options[option.name] = default_value unless default_value.nil?
+
         option_parser.on(*option.usage,option.type,option.desc) do |arg,*captures|
-          @options[option.name] = if arg.nil?
-                                    option.default_value
-                                  else
-                                    arg
-                                  end
+          @options[option.name] = arg
 
           if option.block
             instance_exec(*arg,*captures,&option.block)
@@ -224,5 +226,16 @@ module CommandKit
         end
       end
     end
+
+    #
+    # Overrides the default {Usage#help help} method and calls {#help_options}
+    # and {#help_arguments}.
+    #
+    # @api public
+    #
+    def help
+      help_options
+      help_arguments
+    end
   end
 end

data/lib/command_kit/printing/indent.rb

@@ -65,10 +65,10 @@ module CommandKit
       #
       def indent(n=2)
         if block_given?
+          original_indent = @indent
+
           begin
-            original_indent = @indent
             @indent += n
-
             yield
           ensure
             @indent = original_indent

data/lib/command_kit/printing.rb

@@ -23,12 +23,23 @@ module CommandKit
     #   The error message.
     #
     # @example
-    #   print_error "Error: invalid input"
+    #   print_error "error: invalid input"
+    #   # error: invalid input
+    #
+    # @example When CommandKit::CommandName is included:
+    #   print_error "invalid input"
+    #   # foo: invalid input
     #
     # @api public
     #
     def print_error(message)
-      stderr.puts message
+      if respond_to?(:command_name)
+        # if #command_name is available, prefix all error messages with it
+        stderr.puts "#{command_name}: #{message}"
+      else
+        # if #command_name is not available, just print the error message as-is
+        stderr.puts message
+      end
     end
 
     #

data/lib/command_kit/version.rb

@@ -1,4 +1,4 @@
 module CommandKit
   # command_kit version
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/spec/arguments_spec.rb

@@ -137,6 +137,56 @@ describe CommandKit::Arguments do
 
   subject { command_class.new }
 
+  describe "#main" do
+    module TestArguments
+      class TestCommand
+
+        include CommandKit::Arguments
+
+        argument :argument1, required: true,
+                             usage:    'ARG1',
+                             desc:     "Argument 1"
+
+        argument :argument2, required: false,
+                             usage:    'ARG2',
+                             desc:     "Argument 2"
+
+      end
+    end
+
+    let(:command_class) { TestArguments::TestCommand }
+
+    context "when given the correct number of arguments" do
+      let(:argv) { %w[arg1 arg2] }
+
+      it "must parse options before validating the number of arguments" do
+        expect {
+          expect(subject.main(argv)).to eq(0)
+        }.to_not output.to_stderr
+      end
+    end
+
+    context "when given fewer than the required number of arguments" do
+      let(:argv) { %w[] }
+
+      it "must print an error message and return 1" do
+        expect {
+          expect(subject.main(argv)).to eq(1)
+        }.to output("#{subject.command_name}: insufficient number of arguments.#{$/}").to_stderr
+      end
+    end
+
+    context "when given more than the total number of arguments" do
+      let(:argv) { %w[foo bar baz] }
+
+      it "must print an error message and return 1" do
+        expect {
+          expect(subject.main(argv)).to eq(1)
+        }.to output("#{subject.command_name}: too many arguments given.#{$/}").to_stderr
+      end
+    end
+  end
+
   describe "#help_arguments" do
     context "when #arguments returns {}" do
       module TestArguments