command_kit 0.1.0.rc1 → 0.1.0

data/lib/command_kit/main.rb

@@ -12,6 +12,9 @@ module CommandKit
   #     end
   #
   module Main
+    #
+    # @api private
+    #
     module ModuleMethods
       #
       # Extends {ClassMethods} or {ModuleMethods}, depending on whether {Main}
@@ -43,6 +46,8 @@ module CommandKit
       # @param [Array<String>] argv
       #   The Array of command-line arguments.
       #
+      # @api public
+      #
       def start(argv=ARGV, **kwargs)
         begin
           exit main(argv, **kwargs)
@@ -68,6 +73,8 @@ module CommandKit
       # @return [Integer]
       #   The exit status of the command.
       #
+      # @api public
+      #
       def main(argv=[], **kwargs)
         new(**kwargs).main(argv)
       end
@@ -84,6 +91,8 @@ module CommandKit
     #
     # @note `argv` is splatted into {#run}.
     #
+    # @api public
+    #
     def main(argv=[])
       run(*argv)
       return 0
@@ -99,6 +108,8 @@ module CommandKit
     #   
     # @abstract
     #
+    # @api public
+    #
     def run(*args)
     end
   end

data/lib/command_kit/options.rb

@@ -38,6 +38,9 @@ module CommandKit
   module Options
     include Parser
 
+    #
+    # @api private
+    #
     module ModuleMethods
       #
       # Extends {ClassMethods} or {ModuleMethods}, depending on whether
@@ -68,6 +71,8 @@ module CommandKit
       #
       # @return [Hash{Symbol => Option}]
       #
+      # @api semipublic
+      #
       def options
         @options ||= if superclass.kind_of?(ClassMethods)
                        superclass.options.dup
@@ -172,6 +177,8 @@ module CommandKit
       #       # ...
       #     end
       #
+      # @api public
+      #
       def option(name,**kwargs,&block)
         options[name] = Option.new(name,**kwargs,&block)
       end
@@ -180,6 +187,9 @@ module CommandKit
     # Hash of parsed option values.
     #
     # @return [Hash{Symbol => Object}]
+    #
+    # @api semipublic
+    #
     attr_reader :options
 
     #
@@ -193,6 +203,8 @@ module CommandKit
     #   The {#option_parser} will populate {#options} and also call any
     #   {ClassMethods#option option} blocks with the parsed option values.
     #
+    # @api public
+    #
     def initialize(options: {}, **kwargs)
       @options = options
 

data/lib/command_kit/options/option.rb

@@ -11,6 +11,8 @@ module CommandKit
     #
     # Represents a defined option.
     #
+    # @api private
+    #
     class Option
 
       # The option's name.

data/lib/command_kit/options/option_value.rb

@@ -14,6 +14,8 @@ module CommandKit
     #
     # Represents an additional argument associated with an option flag.
     #
+    # @api private
+    #
     class OptionValue < Arguments::ArgumentValue
 
       # Maps OptionParser types to USAGE strings.

data/lib/command_kit/options/parser.rb

@@ -33,6 +33,9 @@ module CommandKit
       include Main
       include Printing
 
+      #
+      # @api private
+      #
       module ModuleMethods
         #
         # Sets {CommandKit::Usage::ClassMethods#usage .usage} or extends
@@ -58,6 +61,8 @@ module CommandKit
       # The option parser.
       #
       # @return [OptionParser]
+      #
+      # @api semipublic
       attr_reader :option_parser
 
       #
@@ -65,6 +70,8 @@ module CommandKit
       #
       # @return [OptionParser]
       #
+      # @api public
+      #
       def initialize(**kwargs)
         super(**kwargs)
 
@@ -91,6 +98,8 @@ module CommandKit
       # @return [Integer]
       #   The exit status code.
       #
+      # @api public
+      #
       def main(argv=[])
         super(parse_options(argv))
       rescue SystemExit => system_exit
@@ -106,6 +115,8 @@ module CommandKit
       # @return [Array<String>]
       #   The remaining non-option arguments.
       #
+      # @api semipublic
+      #
       def parse_options(argv)
         begin
           option_parser.parse(argv)
@@ -132,6 +143,8 @@ module CommandKit
       # @param [OptionParser::ParseError] error
       #   The error from `OptionParser`.
       #
+      # @api semipublic
+      #
       def on_parse_error(error)
         print_error("#{command_name}: #{error.message}")
         print_error("Try '#{command_name} --help' for more information.")
@@ -145,6 +158,8 @@ module CommandKit
       #
       # @see on_parse_error
       #
+      # @api semipublic
+      #
       def on_invalid_option(error)
         on_parse_error(error)
       end
@@ -157,6 +172,8 @@ module CommandKit
       #
       # @see on_parse_error
       #
+      # @api semipublic
+      #
       def on_ambiguous_option(error)
         on_parse_error(error)
       end
@@ -169,6 +186,8 @@ module CommandKit
       #
       # @see on_parse_error
       #
+      # @api semipublic
+      #
       def on_invalid_argument(error)
         on_parse_error(error)
       end
@@ -181,6 +200,8 @@ module CommandKit
       #
       # @see on_parse_error
       #
+      # @api semipublic
+      #
       def on_missing_argument(error)
         on_parse_error(error)
       end
@@ -193,6 +214,8 @@ module CommandKit
       #
       # @see on_parse_error
       #
+      # @api semipublic
+      #
       def on_needless_argument(error)
         on_parse_error(error)
       end
@@ -205,6 +228,8 @@ module CommandKit
       #
       # @see on_parse_error
       #
+      # @api semipublic
+      #
       def on_ambiguous_argument(error)
         on_parse_error(error)
       end
@@ -212,6 +237,8 @@ module CommandKit
       #
       # Prints the `--help` output.
       #
+      # @api semipublic
+      #
       def help_options
         puts option_parser
       end
@@ -219,6 +246,8 @@ module CommandKit
       #
       # @see #help_options
       #
+      # @api public
+      #
       def help
         help_options
       end

data/lib/command_kit/options/quiet.rb

@@ -18,6 +18,9 @@ module CommandKit
     module Quiet
       include Options
 
+      #
+      # @api private
+      #
       module ModuleMethods
         #
         # Defines a `-q, --quiet` option.

data/lib/command_kit/options/verbose.rb

@@ -18,6 +18,9 @@ module CommandKit
     module Verbose
       include Options
 
+      #
+      # @api private
+      #
       module ModuleMethods
         #
         # Defines a `-v, --verbose` option or extends {ModuleMethods}, depending
@@ -47,6 +50,8 @@ module CommandKit
       #
       # @return [Boolean]
       #
+      # @api public
+      #
       def verbose?
         @verbose
       end

data/lib/command_kit/options/version.rb

@@ -35,6 +35,8 @@ module CommandKit
         # @return [String, nil]
         #   The classes version string.
         #
+        # @api public
+        #
         def version(new_version=nil)
           if new_version
             @version = new_version
@@ -47,6 +49,8 @@ module CommandKit
       #
       # @see ClassMethods#version
       #
+      # @api public
+      #
       def version
         self.class.version
       end
@@ -54,6 +58,8 @@ module CommandKit
       #
       # Prints the version.
       #
+      # @api public
+      #
       def print_version
         puts "#{command_name} #{version}"
       end

data/lib/command_kit/os.rb

@@ -22,6 +22,8 @@ module CommandKit
     #
     # @return [Boolean]
     #
+    # @api public
+    #
     def linux?
       RUBY_PLATFORM.include?('linux')
     end
@@ -31,6 +33,8 @@ module CommandKit
     #
     # @return [Boolean]
     #
+    # @api public
+    #
     def macos?
       RUBY_PLATFORM.include?('darwin')
     end
@@ -40,6 +44,8 @@ module CommandKit
     #
     # @return [Boolean]
     #
+    # @api public
+    #
     def windows?
       Gem.win_platform?
     end

data/lib/command_kit/pager.rb

@@ -53,6 +53,8 @@ module CommandKit
     #   Respects the `PAGER` env variable, or attemps to find `less` or
     #   `more` by searching the `PATH` env variable.
     #
+    # @api public
+    #
     def initialize(**kwargs)
       super(**kwargs)
 
@@ -74,6 +76,23 @@ module CommandKit
     # @yieldparam [IO]
     #   The IO pipe to the pager.
     #
+    # @example
+    #   pager do |io|
+    #     io.puts "Hello world"
+    #     # ...
+    #   end
+    #
+    # @example Piping a command into the pager:
+    #   IO.peopn(["ping", ip]) do |ping|
+    #     pager do |io|
+    #       ping.each_line do |line|
+    #         io.write line
+    #       end
+    #     end
+    #   end
+    #
+    # @api public
+    #
     def pager
       if !stdout.tty? || @pager.nil?
         # fallback to stdout if the process does not have a terminal or we could
@@ -105,6 +124,14 @@ module CommandKit
     # @param [Array<String>, #to_s] data
     #   The data to print.
     #
+    # @example
+    #   print_or_page(data)
+    #
+    # @example Print or pages the contents of a file:
+    #   print_or_page(File.read(file))
+    #
+    # @api public
+    #
     def print_or_page(data)
       line_count = case data
                    when Array  then data.length

data/lib/command_kit/printing.rb

@@ -9,12 +9,24 @@ module CommandKit
   module Printing
     include Stdio
 
+    # Platform independency new-line constant
+    #
+    # @return [String]
+    #
+    # @api public
+    EOL = $/
+
     #
     # Prints the error message to {Stdio#stderr stderr}.
     #
     # @param [String] message
     #   The error message.
     #
+    # @example
+    #   print_error "Error: invalid input"
+    #
+    # @api public
+    #
     def print_error(message)
       stderr.puts message
     end
@@ -25,6 +37,17 @@ module CommandKit
     # @param [Exception] error
     #   The error to print.
     #
+    # @example
+    #   begin
+    #     # ...
+    #   rescue => error
+    #     print_error "Error encountered"
+    #     print_exception(error)
+    #     exit(1)
+    #   end
+    #
+    # @api public
+    #
     def print_exception(error)
       print_error error.full_message(highlight: stderr.tty?)
     end

data/lib/command_kit/printing/indent.rb

@@ -42,6 +42,27 @@ module CommandKit
       # @return [Integer]
       #   If no block is given, the indententation level will be returned.
       #
+      # @example
+      #   puts "values:"
+      #   indent do
+      #     values.each do |key,value|
+      #       puts "#{key}: #{value}"
+      #     end
+      #   end
+      #
+      # @example
+      #   puts "Code:"
+      #   puts
+      #   puts "```"
+      #   indent(4) do
+      #     code.each_line do |line|
+      #       puts line
+      #     end
+      #   end
+      #   puts "```"
+      #
+      # @api public
+      #
       def indent(n=2)
         if block_given?
           begin
@@ -63,6 +84,8 @@ module CommandKit
       # @param [Array<String>] lines
       #   The lines to indent and print.
       #
+      # @api public
+      #
       def puts(*lines)
         if (@indent > 0 && !lines.empty?)
           padding = " " * @indent

data/lib/command_kit/program_name.rb

@@ -3,6 +3,9 @@ module CommandKit
   # Retrieves the current program name (`$PROGRAM_NAME`).
   #
   module ProgramName
+    #
+    # @api private
+    #
     module ModuleMethods
       #
       # Extends {ClassMethods} or {ModuleMethods}, depending on whether
@@ -42,6 +45,8 @@ module CommandKit
       #   The `$PROGRAM_NAME` or `nil` if the `$PROGRAM_NAME` is `-e`, `irb`,
       #   or `rspec`.
       #
+      # @api semipublic
+      #
       def program_name
         $PROGRAM_NAME unless IGNORED_PROGRAM_NAMES.include?($PROGRAM_NAME)
       end
@@ -50,6 +55,8 @@ module CommandKit
     #
     # @see ClassMethods#program_name
     #
+    # @api public
+    #
     def program_name
       self.class.program_name
     end