command_kit 0.1.0.rc1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c8944ddc49470bbe03b23cdf0df4cc9e5f94010208e15b373430453556ff2ed
-  data.tar.gz: bfebe1ddb5ae5a078e5910de55f626ae69dc8716f3d5152690e9002b68878bfe
+  metadata.gz: acf8c9763694ffe7ac298e158863a3165c5d8f1a2209d1cac5b01e9c60d9dd85
+  data.tar.gz: 98669568909de27878be028ae8b0251ddc6e8a4740af23037bd234d06778b2ce
 SHA512:
-  metadata.gz: a8f00bba78443b945ea4c41efeaf4488eb6c65867ac637b4ae368d6a53724802395f0f9d5d464241fbe9d7f22fd1657e50161df4846fcdcce174f4abf206abb7
-  data.tar.gz: 497da95cec49705d426da9dfa27aa5f7ca9e462375dba94375244e5180f9ac9f1735850022fdfd61876cb6661a5988c568eda518dac010859be69589c3780843
+  metadata.gz: b04269a04b5d474f2a17724e04fa015fe5c1eefdbba9f53cf06c49c727c369ae3ba9a77e336c09f69fc3e7c8b6e5f77fa98abe7912c022213489d5b04191f5bb
+  data.tar.gz: 01c43327289df1e30970e618b2d133e26bc5e6cdd3d65cc6fad7cbc369e44085fd164cb0b93a241df6508e3019fbfed658f83191e958457ec6f7ecfed86b88b3

data/ChangeLog.md

@@ -1,4 +1,4 @@
-### 0.1.0 / 2021-07-XX
+### 0.1.0 / 2021-07-16
 
 * Initial release:
   * {CommandKit::Arguments}

data/README.md

@@ -1,9 +1,9 @@
 # command_kit
 
-* [Homepage](https://github.com/postmodern/command_kit#readme)
-* [Issues](https://github.com/postmodern/command_kit/issues)
+* [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)
 * [Documentation](http://rubydoc.info/gems/command_kit/frames)
-* [Email](mailto:postmodern.mod3 at gmail.com)
 
 ## Description
 
@@ -20,9 +20,12 @@ plain-old Ruby classes.
 * 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 optional ANSI coloring.
 * 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`)
 

data/gemspec.yml

@@ -7,7 +7,7 @@ description:
 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
 
 required_ruby_version: ">= 2.7.0"
 

data/lib/command_kit.rb

@@ -1 +1,2 @@
+require 'command_kit/command'
 require 'command_kit/version'

data/lib/command_kit/arguments.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'command_kit/main'
 require 'command_kit/help'
 require 'command_kit/arguments/argument'
@@ -46,6 +48,9 @@ module CommandKit
     include Main
     include Help
 
+    #
+    # @api private
+    #
     module ModuleMethods
       #
       # Extends {ClassMethods} or {ModuleMethods}, depending on whether
@@ -77,6 +82,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 +138,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 +156,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?)
@@ -168,6 +179,8 @@ module CommandKit
     #
     # Prints any defined arguments, along with the usual `--help` information.
     #
+    # @api semipublic
+    #
     def help_arguments
       unless (arguments = self.class.arguments).empty?
         puts
@@ -183,8 +196,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/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/colors.rb

@@ -88,6 +88,8 @@ module CommandKit
       #
       # @see RESET
       #
+      # @api public
+      #
       def reset
         RESET
       end
@@ -95,6 +97,8 @@ module CommandKit
       #
       # @see reset
       #
+      # @api public
+      #
       def clear
         reset
       end
@@ -110,6 +114,8 @@ module CommandKit
       #
       # @see BOLD
       #
+      # @api public
+      #
       def bold(string=nil)
         if string then "#{BOLD}#{string}#{RESET_INTENSITY}"
         else           BOLD
@@ -127,6 +133,8 @@ module CommandKit
       #
       # @see BLACK
       #
+      # @api public
+      #
       def black(string=nil)
         if string then "#{BLACK}#{string}#{RESET_COLOR}"
         else           BLACK
@@ -144,6 +152,8 @@ module CommandKit
       #
       # @see RED
       #
+      # @api public
+      #
       def red(string=nil)
         if string then "#{RED}#{string}#{RESET_COLOR}"
         else           RED
@@ -161,6 +171,8 @@ module CommandKit
       #
       # @see GREEN
       #
+      # @api public
+      #
       def green(string=nil)
         if string then "#{GREEN}#{string}#{RESET_COLOR}"
         else           GREEN
@@ -178,6 +190,8 @@ module CommandKit
       #
       # @see YELLOW
       #
+      # @api public
+      #
       def yellow(string=nil)
         if string then "#{YELLOW}#{string}#{RESET_COLOR}"
         else           YELLOW
@@ -195,6 +209,8 @@ module CommandKit
       #
       # @see BLUE
       #
+      # @api public
+      #
       def blue(string=nil)
         if string then "#{BLUE}#{string}#{RESET_COLOR}"
         else           BLUE
@@ -212,6 +228,8 @@ module CommandKit
       #
       # @see MAGENTA
       #
+      # @api public
+      #
       def magenta(string=nil)
         if string then "#{MAGENTA}#{string}#{RESET_COLOR}"
         else           MAGENTA
@@ -229,6 +247,8 @@ module CommandKit
       #
       # @see CYAN
       #
+      # @api public
+      #
       def cyan(string=nil)
         if string then "#{CYAN}#{string}#{RESET_COLOR}"
         else           CYAN
@@ -246,6 +266,8 @@ module CommandKit
       #
       # @see WHITE
       #
+      # @api public
+      #
       def white(string=nil)
         if string then "#{WHITE}#{string}#{RESET_COLOR}"
         else           WHITE
@@ -331,6 +353,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 +367,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.
@@ -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
 

data/lib/command_kit/commands.rb

@@ -41,6 +41,9 @@ module CommandKit
     include Stdio
     include Env
 
+    #
+    # @api private
+    #
     module ModuleMethods
       #
       # Extends {ClassMethods} or {ModuleMethods}, depending on whether
@@ -73,6 +76,8 @@ module CommandKit
       #
       # @return [Hash{String => Subcommand}]
       #   The Hash of sub-command names and command classes.
+      #
+      # @api semipublic
       # 
       def commands
         @commands ||= if superclass.kind_of?(ClassMethods)
@@ -88,6 +93,8 @@ module CommandKit
       # @return [Hash{String => String}]
       #   The Hash of command aliases to primary command names.
       # 
+      # @api semipublic
+      #
       def command_aliases
         @command_aliases ||= if superclass.kind_of?(ClassMethods)
                                superclass.command_aliases.dup
@@ -125,6 +132,8 @@ module CommandKit
       # @example
       #   command 'foo-bar', FooBar
       #
+      # @api public
+      #
       def command(name=nil, command_class, **kwargs)
         name = if name then name.to_s
                else         command_class.command_name
@@ -145,8 +154,12 @@ module CommandKit
       # Gets the command.
       #
       # @param [String] name
+      #   The command name.
       #
       # @return [Class#main, nil]
+      #   The command class or `nil` if no command could be found.
+      #
+      # @api private
       #
       def get_command(name)
         name = name.to_s
@@ -164,6 +177,8 @@ module CommandKit
     # @note Adds a special rule to the {Options#option_parser #option_parser} to
     # stop parsing options when the first non-option is encountered.
     #
+    # @api public
+    #
     def initialize(**kwargs)
       super(**kwargs)
 
@@ -181,6 +196,8 @@ module CommandKit
     # @return [Object#main, nil]
     #   The initialized subcommand.
     #
+    # @api private
+    #
     def command(name)
       unless (command_class = self.class.get_command(name))
         return
@@ -225,6 +242,8 @@ module CommandKit
     # @return [Integer]
     #   The exit status of the command.
     #
+    # @api semipublic
+    #
     def invoke(name,*argv)
       if (command = command(name))
         command.main(argv)
@@ -237,6 +256,9 @@ module CommandKit
     # Prints an error about an unknown command and exits with an error code.
     #
     # @param [String] name
+    #   The command name.
+    #
+    # @api semipublic
     #
     def command_not_found(name)
       print_error "'#{name}' is not a #{command_name} command. See `#{command_name} help`"
@@ -256,6 +278,8 @@ module CommandKit
     #
     # @see command_not_found
     #
+    # @api semipublic
+    #
     def on_unknown_command(name,argv=[])
       command_not_found(name)
     end
@@ -265,6 +289,8 @@ module CommandKit
     #
     # @note If no subcommand is given, {#help} will be called.
     #
+    # @api public
+    #
     def run(command=nil,*argv)
       if command
         exit invoke(command,*argv)
@@ -276,6 +302,8 @@ module CommandKit
     #
     # Prints the available commands and their summaries.
     #
+    # @api semipublic
+    #
     def help_commands
       unless self.class.commands.empty?
         puts
@@ -296,6 +324,8 @@ module CommandKit
     #
     # Prints help information and available commands.
     #
+    # @api public
+    #
     def help
       super
 

data/lib/command_kit/commands/auto_load.rb

@@ -40,16 +40,22 @@ module CommandKit
       # The auto-load subcommands.
       #
       # @return [Hash{String => Subcommand}]
+      #
+      # @api private
       attr_reader :commands
 
       # The path to the directory containing the command files.
       #
       # @return [String]
+      #
+      # @api private
       attr_reader :dir
 
       # The namespace that the will contain the command classes.
       #
       # @return [String]
+      #
+      # @api private
       attr_reader :namespace
 
       #
@@ -65,6 +71,8 @@ module CommandKit
       #   If a block is given, it will be used to explicitly map the files
       #   within {#dir} as commands.
       #
+      # @api public
+      #
       def initialize(dir: , namespace: )
         @commands  = {}
 
@@ -106,6 +114,8 @@ module CommandKit
       # @option kwargs [Array<String>] aliases
       #   Optional alias names for the subcommand.
       #
+      # @api public
+      #
       def command(name, constant, file, **kwargs)
         @commands[name.to_s] = Subcommand.new(
           "#{@namespace}::#{constant}",
@@ -123,6 +133,8 @@ module CommandKit
       # @return [String]
       #   The joined absolute path.
       #
+      # @api private
+      #
       def join(path)
         File.join(@dir,path)
       end
@@ -133,6 +145,8 @@ module CommandKit
       # @return [Array<String>]
       #   The paths to the `.rb` files in the directory.
       #
+      # @api private
+      #
       def files
         Dir.glob(join('*.rb'))
       end
@@ -144,6 +158,8 @@ module CommandKit
       # @param [Class] command
       #   The command class including {AutoLoad}.
       #
+      # @api private
+      #
       def included(command)
         command.include Commands
         command.commands.merge!(@commands)