command_kit 0.1.0.pre2 → 0.2.1

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

@@ -2,11 +2,19 @@ name: command_kit
 summary: A toolkit for building Ruby CLI commands
 description:
   A Ruby toolkit for building clean, correct, and robust CLI commands as
-  Ruby classes.
+  plain-old Ruby classes.
+
 license: MIT
 authors: Postmodern
 email: postmodern.mod3@gmail.com
-homepage: https://github.com/postmodern/command_kit#readme
+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"
 

data/lib/command_kit/arguments/argument.rb

@@ -5,6 +5,8 @@ module CommandKit
     #
     # Represents a defined argument.
     #
+    # @api private
+    #
     class Argument < ArgumentValue
 
       # The argument's name.

data/lib/command_kit/arguments/argument_value.rb

@@ -3,6 +3,8 @@ module CommandKit
     #
     # Represents an individual argument value.
     #
+    # @api private
+    #
     class ArgumentValue
 
       # Specifies whether the argument value is required or optional.

data/lib/command_kit/arguments.rb

@@ -1,6 +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
   #
@@ -43,9 +47,14 @@ module CommandKit
   #     end
   #
   module Arguments
+    include Usage
     include Main
     include Help
+    include Printing
 
+    #
+    # @api private
+    #
     module ModuleMethods
       #
       # Extends {ClassMethods} or {ModuleMethods}, depending on whether
@@ -77,6 +86,8 @@ module CommandKit
       # @return [Hash{Symbol => Argument}]
       #   The defined argument for the class and it's superclass.
       #
+      # @api semipublic
+      #
       def arguments
         @arguments ||= if superclass.kind_of?(ClassMethods)
                          superclass.arguments.dup
@@ -131,6 +142,8 @@ module CommandKit
       #     argument :bar, repeats: true,
       #                    desc: "Bar argument"
       #
+      # @api public
+      #
       def argument(name,**kwargs)
         arguments[name] = Argument.new(name,**kwargs)
       end
@@ -147,6 +160,8 @@ module CommandKit
     #   The exit status code. If too few or too many arguments are given, then
     #   an error message is printed and `1` is returned.
     #
+    # @api public
+    #
     def main(argv=[])
       required_args   = self.class.arguments.each_value.count(&:required?)
       optional_args   = self.class.arguments.each_value.count(&:optional?)
@@ -157,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
@@ -168,12 +183,14 @@ module CommandKit
     #
     # Prints any defined arguments, along with the usual `--help` information.
     #
+    # @api semipublic
+    #
     def help_arguments
       unless (arguments = self.class.arguments).empty?
         puts
         puts 'Arguments:'
 
-        self.class.arguments.each_value do |arg|
+        arguments.each_value do |arg|
           puts "    #{arg.usage.ljust(33)}#{arg.desc}"
         end
       end
@@ -183,8 +200,10 @@ module CommandKit
     # Calls the superclass'es `#help` method, if it's defined, then calls
     # {#help_arguments}.
     #
+    # @api public
+    #
     def help
-      super if defined?(super)
+      super
 
       help_arguments
     end

data/lib/command_kit/colors.rb

@@ -26,7 +26,7 @@ module CommandKit
   #
   # ## Alternatives
   #
-  # * [ansi](http://rubyworks.github.io/ansi/)
+  # * [ansi](https://rubyworks.github.io/ansi/)
   # * [colorize](https://github.com/fazibear/colorize#readme)
   #
   # @see https://en.wikipedia.org/wiki/ANSI_escape_code
@@ -67,7 +67,7 @@ module CommandKit
       # ANSI color code for blue
       BLUE = "\e[34m"
 
-      # ANSI color code for megenta
+      # ANSI color code for magenta
       MAGENTA = "\e[35m"
 
       # ANSI color code for cyan
@@ -79,6 +79,51 @@ module CommandKit
       # ANSI color for the default foreground color
       RESET_COLOR = "\e[39m"
 
+      # ANSI color code for background color black
+      #
+      # @since 0.2.0
+      ON_BLACK = "\e[40m"
+
+      # ANSI color code for background color red
+      #
+      # @since 0.2.0
+      ON_RED = "\e[41m"
+
+      # ANSI color code for background color green
+      #
+      # @since 0.2.0
+      ON_GREEN = "\e[42m"
+
+      # ANSI color code for background color yellow
+      #
+      # @since 0.2.0
+      ON_YELLOW = "\e[43m"
+
+      # ANSI color code for background color blue
+      #
+      # @since 0.2.0
+      ON_BLUE = "\e[44m"
+
+      # ANSI color code for background color magenta
+      #
+      # @since 0.2.0
+      ON_MAGENTA = "\e[45m"
+
+      # ANSI color code for background color cyan
+      #
+      # @since 0.2.0
+      ON_CYAN = "\e[46m"
+
+      # ANSI color code for background color white
+      #
+      # @since 0.2.0
+      ON_WHITE = "\e[47m"
+
+      # ANSI color for the default background color
+      #
+      # @since 0.2.0
+      RESET_BG = "\e[49m"
+
       module_function
 
       #
@@ -88,6 +133,8 @@ module CommandKit
       #
       # @see RESET
       #
+      # @api public
+      #
       def reset
         RESET
       end
@@ -95,6 +142,8 @@ module CommandKit
       #
       # @see reset
       #
+      # @api public
+      #
       def clear
         reset
       end
@@ -110,6 +159,8 @@ module CommandKit
       #
       # @see BOLD
       #
+      # @api public
+      #
       def bold(string=nil)
         if string then "#{BOLD}#{string}#{RESET_INTENSITY}"
         else           BOLD
@@ -127,6 +178,8 @@ module CommandKit
       #
       # @see BLACK
       #
+      # @api public
+      #
       def black(string=nil)
         if string then "#{BLACK}#{string}#{RESET_COLOR}"
         else           BLACK
@@ -144,6 +197,8 @@ module CommandKit
       #
       # @see RED
       #
+      # @api public
+      #
       def red(string=nil)
         if string then "#{RED}#{string}#{RESET_COLOR}"
         else           RED
@@ -161,6 +216,8 @@ module CommandKit
       #
       # @see GREEN
       #
+      # @api public
+      #
       def green(string=nil)
         if string then "#{GREEN}#{string}#{RESET_COLOR}"
         else           GREEN
@@ -178,6 +235,8 @@ module CommandKit
       #
       # @see YELLOW
       #
+      # @api public
+      #
       def yellow(string=nil)
         if string then "#{YELLOW}#{string}#{RESET_COLOR}"
         else           YELLOW
@@ -195,6 +254,8 @@ module CommandKit
       #
       # @see BLUE
       #
+      # @api public
+      #
       def blue(string=nil)
         if string then "#{BLUE}#{string}#{RESET_COLOR}"
         else           BLUE
@@ -212,6 +273,8 @@ module CommandKit
       #
       # @see MAGENTA
       #
+      # @api public
+      #
       def magenta(string=nil)
         if string then "#{MAGENTA}#{string}#{RESET_COLOR}"
         else           MAGENTA
@@ -229,6 +292,8 @@ module CommandKit
       #
       # @see CYAN
       #
+      # @api public
+      #
       def cyan(string=nil)
         if string then "#{CYAN}#{string}#{RESET_COLOR}"
         else           CYAN
@@ -246,76 +311,209 @@ module CommandKit
       #
       # @see WHITE
       #
+      # @api public
+      #
       def white(string=nil)
         if string then "#{WHITE}#{string}#{RESET_COLOR}"
         else           WHITE
         end
       end
-    end
 
-    #
-    # Dummy module with the same interface as {ANSI}, but for when ANSI is not
-    # supported.
-    #
-    module PlainText
-      RESET = \
-        CLEAR = \
-        BOLD = \
-        RESET_INTENSITY = \
-        BLACK = \
-        RED = \
-        GREEN = \
-        YELLOW = \
-        BLUE = \
-        MAGENTA = \
-        CYAN = \
-        WHITE = \
-        RESET_COLOR = ''
-
-      module_function
+      #
+      # Sets the background color to black.
+      #
+      # @param [String, nil] string
+      #   An optional string.
+      #
+      # @return [String, ON_BLACK]
+      #   The colorized string or just {ON_BLACK} if no arguments were given.
+      #
+      # @see ON_BLACK
+      #
+      # @api public
+      #
+      # @since 0.2.0
+      #
+      def on_black(string=nil)
+        if string then "#{ON_BLACK}#{string}#{RESET_BG}"
+        else           ON_BLACK
+        end
+      end
 
-      def reset
-        RESET
+      #
+      # Sets the background color to red.
+      #
+      # @param [String, nil] string
+      #   An optional string.
+      #
+      # @return [String, ON_RED]
+      #   The colorized string or just {ON_RED} if no arguments were given.
+      #
+      # @see ON_RED
+      #
+      # @api public
+      #
+      # @since 0.2.0
+      #
+      def on_red(string=nil)
+        if string then "#{ON_RED}#{string}#{RESET_BG}"
+        else           ON_RED
+        end
       end
 
-      def clear
-        reset
+      #
+      # Sets the background color to green.
+      #
+      # @param [String, nil] string
+      #   An optional string.
+      #
+      # @return [String, ON_GREEN]
+      #   The colorized string or just {ON_GREEN} if no arguments were given.
+      #
+      # @see ON_GREEN
+      #
+      # @api public
+      #
+      # @since 0.2.0
+      #
+      def on_green(string=nil)
+        if string then "#{ON_GREEN}#{string}#{RESET_BG}"
+        else           ON_GREEN
+        end
       end
 
-      def bold(string=nil)
-        string || ''
+      #
+      # Sets the background color to yellow.
+      #
+      # @param [String, nil] string
+      #   An optional string.
+      #
+      # @return [String, ON_YELLOW]
+      #   The colorized string or just {ON_YELLOW} if no arguments were given.
+      #
+      # @see ON_YELLOW
+      #
+      # @api public
+      #
+      # @since 0.2.0
+      #
+      def on_yellow(string=nil)
+        if string then "#{ON_YELLOW}#{string}#{RESET_BG}"
+        else           ON_YELLOW
+        end
       end
 
-      def black(string=nil)
-        string || ''
+      #
+      # Sets the background color to blue.
+      #
+      # @param [String, nil] string
+      #   An optional string.
+      #
+      # @return [String, ON_BLUE]
+      #   The colorized string or just {ON_BLUE} if no arguments were given.
+      #
+      # @see ON_BLUE
+      #
+      # @api public
+      #
+      # @since 0.2.0
+      #
+      def on_blue(string=nil)
+        if string then "#{ON_BLUE}#{string}#{RESET_BG}"
+        else           ON_BLUE
+        end
       end
 
-      def red(string=nil)
-        string || ''
+      #
+      # Sets the background color to magenta.
+      #
+      # @param [String, nil] string
+      #   An optional string.
+      #
+      # @return [String, ON_MAGENTA]
+      #   The colorized string or just {ON_MAGENTA} if no arguments were given.
+      #
+      # @see ON_MAGENTA
+      #
+      # @api public
+      #
+      # @since 0.2.0
+      #
+      def on_magenta(string=nil)
+        if string then "#{ON_MAGENTA}#{string}#{RESET_BG}"
+        else           ON_MAGENTA
+        end
       end
 
-      def green(string=nil)
-        string || ''
+      #
+      # Sets the background color to cyan.
+      #
+      # @param [String, nil] string
+      #   An optional string.
+      #
+      # @return [String, ON_CYAN]
+      #   The colorized string or just {ON_CYAN} if no arguments were given.
+      #
+      # @see ON_CYAN
+      #
+      # @api public
+      #
+      # @since 0.2.0
+      #
+      def on_cyan(string=nil)
+        if string then "#{ON_CYAN}#{string}#{RESET_BG}"
+        else           ON_CYAN
+        end
       end
 
-      def yellow(string=nil)
-        string || ''
+      #
+      # Sets the background color to white.
+      #
+      # @param [String, nil] string
+      #   An optional string.
+      #
+      # @return [String, ON_WHITE]
+      #   The colorized string or just {ON_WHITE} if no arguments were given.
+      #
+      # @see ON_WHITE
+      #
+      # @api public
+      #
+      # @since 0.2.0
+      #
+      def on_white(string=nil)
+        if string then "#{ON_WHITE}#{string}#{RESET_BG}"
+        else           ON_WHITE
+        end
       end
+    end
 
-      def blue(string=nil)
-        string || ''
+    #
+    # Dummy module with the same interface as {ANSI}, but for when ANSI is not
+    # supported.
+    #
+    module PlainText
+      ANSI.constants(false).each do |name|
+        const_set(name,'')
       end
 
-      def magenta(string=nil)
-        string || ''
+      module_function
+
+      def reset
+        RESET
       end
 
-      def cyan(string=nil)
-        string || ''
+      def clear
+        reset
       end
 
-      def white(string=nil)
-        string || ''
+      [
+        :bold, :black, :red, :green, :yellow, :blue, :magenta, :cyan, :white,
+        :on_black, :on_red, :on_green, :on_yellow, :on_blue, :on_magenta, :on_cyan, :on_white
+      ].each do |name|
+        define_method(name) do |string=nil|
+          string || ''
+        end
       end
     end
 
@@ -331,6 +529,8 @@ module CommandKit
     #   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?
     end
@@ -343,6 +543,14 @@ module CommandKit
     # @return [ANSI, PlainText]
     #   The ANSI module or PlainText dummy module.
     #
+    # @example
+    #   puts colors.green("Hello world")
+    #
+    # @example Using colors with stderr output:
+    #   stderr.puts colors(stderr).green("Hello world")
+    #
+    # @api public
+    #
     def colors(stream=stdout)
       color = if ansi?(stream) then ANSI
               else                  PlainText

data/lib/command_kit/command.rb

@@ -9,6 +9,8 @@ require 'command_kit/examples'
 require 'command_kit/description'
 require 'command_kit/exception_handler'
 
+require 'fileutils'
+
 module CommandKit
   #
   # The command class base-class.
@@ -54,7 +56,7 @@ module CommandKit
   #       end
   #     end
   #
-  # ### initialize and using ivars
+  # ### initialize and using instance variables
   #
   #     option :verbose, short: '-v', desc: "Increase verbose level" do
   #       @verbose += 1
@@ -66,6 +68,8 @@ module CommandKit
   #       @verbose = 0
   #     end
   #
+  # @api public
+  #
   class Command
 
     include Main
@@ -79,6 +83,7 @@ module CommandKit
     include Examples
     include Description
     include ExceptionHandler
+    include FileUtils
 
   end
 end

data/lib/command_kit/command_name.rb

@@ -31,6 +31,9 @@ module CommandKit
   #     # => "foo-cmd"
   #
   module CommandName
+    #
+    # @api private
+    #
     module ModuleMethods
       #
       # Extends {ClassMethods} or {ModuleMethods}, depending on whether
@@ -65,6 +68,8 @@ module CommandKit
       #
       # @return [String]
       #
+      # @api public
+      #
       def command_name(new_command_name=nil)
         if new_command_name
           @command_name = new_command_name.to_s
@@ -77,6 +82,8 @@ module CommandKit
     # The commands name.
     #
     # @return [String]
+    #
+    # @api public
     attr_reader :command_name
 
     #
@@ -86,6 +93,8 @@ module CommandKit
     #   Overrides the command name. Defaults to
     #   {ClassMethods#command_name self.class.command_name}.
     #
+    # @api public
+    #
     def initialize(command_name: self.class.command_name, **kwargs)
       @command_name = command_name