command_kit 0.1.0.rc1 → 0.1.0

data/lib/command_kit/commands/auto_require.rb

@@ -27,11 +27,15 @@ module CommandKit
       # The directory to attempt to require command files within.
       #
       # @return [String]
+      #
+      # @api private
       attr_reader :dir
 
       # The namespace to lookup command classes within.
       #
       # @return [String]
+      #
+      # @api private
       attr_reader :namespace
 
       #
@@ -43,6 +47,8 @@ module CommandKit
       # @param [String] namespace
       #   The namespace to search for command classes in.
       #
+      # @api public
+      #
       def initialize(dir: , namespace: )
         @dir       = dir
         @namespace = namespace
@@ -57,6 +63,8 @@ module CommandKit
       # @return [String]
       #   The path to the file that should contain the command.
       #
+      # @api private
+      #
       def join(name)
         File.join(@dir,name)
       end
@@ -70,6 +78,8 @@ module CommandKit
       #
       # @raise [LoadError]
       #
+      # @api private
+      #
       def require(file_name)
         super(join(file_name))
       end
@@ -86,6 +96,8 @@ module CommandKit
       # @raise [NameError]
       #   The command class could not be found within the {#namespace}.
       #
+      # @api private
+      #
       def const_get(constant)
         Object.const_get("::#{@namespace}::#{constant}",false)
       end
@@ -100,6 +112,8 @@ module CommandKit
       #   The command's class, or `nil` if the command cannot be loaded from
       #   {#dir} or found within {#namespace}.
       #
+      # @api private
+      #
       def command(command_name)
         file_name = Inflector.underscore(command_name)
 
@@ -125,6 +139,8 @@ module CommandKit
       # @param [Class] command
       #   The command class including {AutoRequire}.
       #
+      # @api private
+      #
       def included(command)
         command.include Commands
         command.commands.default_proc = ->(hash,key) {

data/lib/command_kit/commands/command.rb

@@ -3,6 +3,9 @@ require 'command_kit/commands/parent_command'
 
 module CommandKit
   module Commands
+    #
+    # @api public
+    #
     class Command < CommandKit::Command
 
       include ParentCommand

data/lib/command_kit/commands/help.rb

@@ -8,6 +8,8 @@ module CommandKit
     #
     # The default help command.
     #
+    # @api semipublic
+    #
     class Help < Command
 
       include ParentCommand

data/lib/command_kit/commands/parent_command.rb

@@ -1,15 +1,22 @@
 module CommandKit
   module Commands
+    #
+    # Allows a command to be aware of it's parent command.
+    #
     module ParentCommand
 
       # The parent command instance.
       #
       # @return [Object<Commands>]
+      #
+      # @api semipublic
       attr_reader :parent_command
 
       #
       # Initializes the command and sets {#parent_command}.
       #
+      # @api public
+      #
       def initialize(parent_command: , **kwargs)
         @parent_command = parent_command
 

data/lib/command_kit/commands/subcommand.rb

@@ -3,6 +3,8 @@ module CommandKit
     #
     # Represents a registered subcommand.
     #
+    # @api private
+    #
     class Subcommand
 
       # The command class.
@@ -40,6 +42,16 @@ module CommandKit
         @aliases = aliases.map(&:to_s)
       end
 
+      #
+      # Derives a summary from the command's description.
+      #
+      # @param [Class] command
+      #   The command class.
+      #
+      # @return [String, nil]
+      #   If the command responds to a `#description` method, the first sentence
+      #   of the description will be returned. Otherwise `nil` is returned.
+      #
       def self.summary(command)
         if command.respond_to?(:description)
           if (desc = command.description)

data/lib/command_kit/description.rb

@@ -13,6 +13,9 @@ module CommandKit
   module Description
     include Help
 
+    #
+    # @api private
+    #
     module ModuleMethods
       #
       # Extends {ClassMethods} or {ModuleMethods}, depending on whether
@@ -50,6 +53,8 @@ module CommandKit
       # @example
       #   description "Does things and stuff"
       #
+      # @api public
+      #
       def description(new_description=nil)
         if new_description
           @description = new_description
@@ -64,6 +69,8 @@ module CommandKit
     #
     # @see ClassMethods#description
     #
+    # @api semipublic
+    #
     def description
       self.class.description
     end
@@ -71,6 +78,8 @@ module CommandKit
     #
     # Prints the {ClassMethods#description description}, if set.
     #
+    # @api semipublic
+    #
     def help_description
       if (description = self.description)
         puts
@@ -82,8 +91,10 @@ module CommandKit
     # Calls the superclass'es `#help` method, if it's defined, then calls
     # {#help_description}.
     #
+    # @api public
+    #
     def help
-      super if defined?(super)
+      super
 
       help_description
     end

data/lib/command_kit/env.rb

@@ -23,6 +23,8 @@ module CommandKit
     # The environment variables hash.
     #
     # @return [Hash{String => String}]
+    #
+    # @api public
     attr_reader :env
 
     #
@@ -34,6 +36,8 @@ module CommandKit
     # @param [Hash{Symbol => Object}] kwargs
     #   Additional keyword arguments.
     #
+    # @api public
+    #
     def initialize(env: ENV, **kwargs)
       @env = env
 

data/lib/command_kit/env/home.rb

@@ -14,6 +14,9 @@ module CommandKit
     module Home
       include Env
 
+      #
+      # @api private
+      #
       module ModuleMethods
         #
         # Extends {ClassMethods} or {ModuleMethods}, depending on whether
@@ -44,6 +47,8 @@ module CommandKit
         #
         # @return [String]
         #
+        # @api semipublic
+        #
         def home_dir
           Gem.user_home
         end
@@ -52,6 +57,8 @@ module CommandKit
       # The home directory.
       #
       # @return [String]
+      #
+      # @api public
       attr_reader :home_dir
 
       #
@@ -61,6 +68,8 @@ module CommandKit
       # @param [Hash{Symbol => Object}] kwargs
       #   Additional keyword arguments.
       #
+      # @api public
+      #
       def initialize(**kwargs)
         super(**kwargs)
 

data/lib/command_kit/env/path.rb

@@ -17,6 +17,8 @@ module CommandKit
       # The home directory.
       #
       # @return [String]
+      #
+      # @api semipublic
       attr_reader :path_dirs
 
       #
@@ -25,6 +27,8 @@ module CommandKit
       # @param [Hash{Symbol => Object}] kwargs
       #   Additional keyword arguments.
       #
+      # @api public
+      #
       def initialize(**kwargs)
         super(**kwargs)
 
@@ -41,6 +45,8 @@ module CommandKit
       #   The absolute path to the executable file, or `nil` if the command
       #   could not be found in any of the {#path_dirs}.
       #
+      # @api public
+      #
       def find_command(name)
         name = name.to_s
 
@@ -63,6 +69,15 @@ module CommandKit
       #   Specifies whether a command with the given name exists in one of the
       #   {#path_dirs}.
       #
+      # @example
+      #   if command_installed?("docker")
+      #     # ...
+      #   else
+      #     abort "Docker is not installed. Aborting"
+      #   end
+      #
+      # @api public
+      #
       def command_installed?(name)
         !find_command(name).nil?
       end

data/lib/command_kit/examples.rb

@@ -17,6 +17,9 @@ module CommandKit
     include Help
     include CommandName
 
+    #
+    # @api private
+    #
     module ModuleMethods
       #
       # Extends {ClassMethods} or {ModuleMethods}, depending on whether
@@ -57,6 +60,8 @@ module CommandKit
       #     "-o output.txt path/to/file"
       #   ]
       #   
+      # @api public
+      #
       def examples(new_examples=nil)
         if new_examples
           @examples = Array(new_examples)
@@ -71,6 +76,8 @@ module CommandKit
     #
     # @see ClassMethods#examples
     #
+    # @api semipublic
+    #
     def examples
       self.class.examples
     end
@@ -78,6 +85,8 @@ module CommandKit
     #
     # Prints the command class'es example commands.
     #
+    # @api semipublic
+    #
     def help_examples
       if (examples = self.examples)
         puts
@@ -92,8 +101,10 @@ module CommandKit
     # Calls the superclass'es `#help` method, if it's defined, then calls
     # {#help_examples}.
     #
+    # @api public
+    #
     def help
-      super if defined?(super)
+      super
 
       help_examples
     end

data/lib/command_kit/exception_handler.rb

@@ -33,6 +33,8 @@ module CommandKit
     # @return [Integer]
     #   The exit status of the command.
     #
+    # @api public
+    #
     def main(argv=[])
       super(argv)
     rescue Interrupt, Errno::EPIPE => error
@@ -47,6 +49,8 @@ module CommandKit
     # @param [Exception] error
     #   The raised exception.
     #
+    # @api semipublic
+    #
     def on_exception(error)
       print_exception(error)
       exit(1)

data/lib/command_kit/help.rb

@@ -15,6 +15,9 @@ module CommandKit
   #     MyCmd.help
   #
   module Help
+    #
+    # @api private
+    #
     module ModuleMethods
       #
       # Extends {ClassMethods} or {ModuleMethods}, depending on whether {Help}
@@ -48,6 +51,8 @@ module CommandKit
       #
       # @see Help#help
       #
+      # @api public
+      #
       def help(**kwargs)
         new(**kwargs).help
       end
@@ -58,8 +63,9 @@ module CommandKit
     #
     # @abstract
     #
+    # @api public
+    #
     def help
-      super if defined?(super)
     end
   end
 end

data/lib/command_kit/help/man.rb

@@ -24,6 +24,9 @@ module CommandKit
       include Help
       include Stdio
 
+      #
+      # @api private
+      #
       module ModuleMethods
         #
         # Extends {ClassMethods} or {ModuleMethods}, depending on whether
@@ -61,6 +64,8 @@ module CommandKit
         # @example
         #   man_dir "#{__dir__}/../../man"
         #
+        # @api public
+        #
         def man_dir(new_man_dir=nil)
           if new_man_dir
             @man_dir = new_man_dir
@@ -80,6 +85,8 @@ module CommandKit
         # @return [String]
         #   The class'es or superclass'es man-page file name.
         #
+        # @api public
+        #
         def man_page(new_man_page=nil)
           if new_man_page
             @man_page = new_man_page
@@ -102,6 +109,8 @@ module CommandKit
       #   Specifies whether the `man` command was successful or not.
       #   Returns `nil` when the `man` command is not installed.
       #
+      # @api public
+      #
       def man(page, section: nil)
         if section
           system('man',section.to_s,page.to_s)
@@ -124,6 +133,8 @@ module CommandKit
       # @raise [NotImplementedError]
       #   {ClassMethods#man_dir .man_dir} does not have a value.
       #
+      # @api semipublic
+      #
       def help_man(man_page=self.class.man_page)
         unless self.class.man_dir
           raise(NotImplementedError,"#{self.class}.man_dir not set")
@@ -145,6 +156,8 @@ module CommandKit
       #   if `TERM` is `dumb` or `$stdout` is not a TTY, fallsback to printing
       #   the usual `--help` output.
       #
+      # @api public
+      #
       def help
         if stdout.tty?
           if help_man.nil?

data/lib/command_kit/inflector.rb

@@ -8,6 +8,8 @@ module CommandKit
   #   If you need something more powerful, checkout
   #   [dry-inflector](https://dry-rb.org/gems/dry-inflector/0.1/)
   #
+  # @api semipublic
+  #
   module Inflector
     #
     # Removes the namespace from a constant name.

data/lib/command_kit/interactive.rb

@@ -1,6 +1,39 @@
+# frozen_string_literal: true
+
 require 'command_kit/stdio'
 
 module CommandKit
+  #
+  # Provides methods for asking the user for input.
+  #
+  # ## Examples
+  #
+  #     first_name = ask("First name")
+  #     last_name = ask("Last name")
+  #
+  # ### Asking for secret input
+  #
+  #     password = ask_secret("Password")
+  #
+  # ### Asking Y/N?
+  #
+  #     if ask_yes_or_no("Proceed anyways?")
+  #       # ...
+  #     else
+  #       stderr.puts "Aborting!"
+  #     end
+  #
+  # ### Asking multi-choice questions
+  #
+  #     ask_multiple_choice("Select a flavor", %w[Apple Orange Lemon Lime])
+  #     #   1) Apple
+  #     #   2) Orange
+  #     #   3) Lemon
+  #     #   4) Lime
+  #     #   Select a flavor: 4
+  #     #
+  #     # => "Lime"
+  #
   module Interactive
     include Stdio
 
@@ -19,6 +52,23 @@ module CommandKit
     # @return [String]
     #   The user input.
     #
+    # @example
+    #   first_name = ask("First name")
+    #   last_name = ask("Last name")
+    #
+    # @example Default value:
+    #   ask("Country", default: "EU")
+    #   # Country [EU]: <enter>
+    #   # => "EU"
+    #
+    # @example Required non-empty input:
+    #   ask("Email", required: true)
+    #   # Email: <enter>
+    #   # Email: bob@example.com<enter>
+    #   # => "bob@example.com"
+    #
+    # @api public
+    #
     def ask(prompt, default: nil, required: false)
       prompt = prompt.chomp
       prompt << " [#{default}]" if default
@@ -56,7 +106,14 @@ module CommandKit
     # @example
     #   ask_yes_or_no("Proceed anyways?")
     #   # Proceed anyways? (Y/N): Y
-    #   # => :yes
+    #   # => true
+    #
+    # @example Default value:
+    #   ask_yes_or_no("Proceed anyways?", default: true)
+    #   # Proceed anyways? (Y/N) [Y]: <enter>
+    #   # => true
+    #
+    # @api public
     #
     def ask_yes_or_no(prompt, default: nil, **kwargs)
       default = case default
@@ -123,6 +180,8 @@ module CommandKit
     #   #
     #   # => "All of the above"
     #
+    # @api public
+    #
     def ask_multiple_choice(prompt,choices,**kwargs)
       choices = case choices
                 when Array
@@ -164,6 +223,8 @@ module CommandKit
     #   # Password: 
     #   # => "s3cr3t"
     #
+    # @api public
+    #
     def ask_secret(prompt, required: true)
       if stdin.respond_to?(:noecho)
         stdin.noecho do