command_kit 0.1.0.pre1 → 0.1.0.pre2

data/lib/command_kit/arguments/argument.rb

@@ -7,82 +7,52 @@ module CommandKit
     #
     class Argument < ArgumentValue
 
+      # The argument's name.
+      #
       # @return [Symbol]
       attr_reader :name
 
-      # @return [Boolean]
-      attr_reader :repeats
-
-      # @return [String, nil]
+      # The argument's description.
+      #
+      # @return [String]
       attr_reader :desc
 
-      # @return [Regexp, nil]
-      attr_reader :pattern
-
-      # @return [Proc, nil]
-      attr_reader :parser
-
-      # @return [Proc, nil]
-      attr_reader :block
-
       #
       # Initializes the argument.
       #
       # @param [Symbol] name
-      #
-      # @param [Class, Hash, Array, Regexp] type
+      #   The name of the argument.
       #
       # @param [String, nil] usage
-      #
-      # @param [Object, Proc, nil] default
+      #   The usage string for the argument. Defaults to the argument's name.
       #
       # @param [Boolean] required
+      #   Specifies whether the argument is required or optional.
       #
       # @param [Boolean] repeats
+      #   Specifies whether the argument can be repeated multiple times.
       #
       # @param [String] desc
-      #
-      # @note `usage` will be assigned a default value based on `type` and
-      # `name`.
+      #   The description for the argument.
       #
       # @yield [(value)]
+      #   If a block is given, it will be used to parse the argument's value.
+      #   Note: not currently used.
       #
       # @yieldparam [Object, nil] value
       #
-      def initialize(name, type:     String,
-                           usage:    name.to_s.upcase,
-                           default:  nil,
+      def initialize(name, usage:    name.to_s.upcase,
                            required: true,
                            repeats:  false,
-                           desc:     ,
-                           &block)
+                           desc:     )
         super(
-          type:     type,
           usage:    usage,
-          default:  default,
           required: required
         )
 
         @name    = name
         @repeats = repeats
         @desc    = desc
-
-        @pattern, @parser = self.class.parser(@type)
-
-        @block = block
-      end
-
-      #
-      # Looks up the option parser for the given `OptionParser` type.
-      #
-      # @param [Class] type
-      #   The `OptionParser` type class.
-      #
-      # @return [(Regexp, Proc), nil]
-      #   The matching pattern and converter proc.
-      #
-      def self.parser(type)
-        OptionParser::DefaultList.search(:atype,type)
       end
 
       #

data/lib/command_kit/arguments/argument_value.rb

@@ -5,16 +5,6 @@ module CommandKit
     #
     class ArgumentValue
 
-      # The desired type of the argument value.
-      #
-      # @return [Class, Hash, Array, Regexp, nil]
-      attr_reader :type
-
-      # The default parsed value for the argument value.
-      #
-      # @return [Object, Proc, nil]
-      attr_reader :default
-
       # Specifies whether the argument value is required or optional.
       #
       # @return [Boolean]
@@ -28,22 +18,14 @@ module CommandKit
       #
       # Initializes the argument value.
       #
-      # @param [Class, Hash, Array, Regexp] type
-      #   The type of the argument value.
-      #
       # @param [Boolean] required
       #   Specifies whether the argument value is required or optional.
       #
       # @param [String] usage
       #   The usage string to represent the argument value.
       #
-      # @param [Object, Proc, nil] default
-      #   The default parsed value for the argument value.
-      #
-      def initialize(type: nil, required: true, default: nil, usage: )
-        @type     = type
+      def initialize(required: true, usage: )
         @required = required
-        @default  = default
         @usage    = usage
       end
 
@@ -65,17 +47,6 @@ module CommandKit
         !@required
       end
 
-      #
-      # Returns a new default value.
-      #
-      # @return [Object]
-      #
-      def default_value
-        if @default.respond_to?(:call) then @default.call
-        else                                @default.dup
-        end
-      end
-
     end
   end
 end

data/lib/command_kit/command.rb

@@ -13,16 +13,58 @@ module CommandKit
   #
   # The command class base-class.
   #
+  # @note
+  #   Command classes are not required to inherit from {Command}. If you do not
+  #   wish to inherit from the {Command} base class, you can instead include
+  #   the individual modules. This class only exists as a convenience.
+  #
   # ## Examples
   #
   #     class MyCmd < CommandKit::Command
   #     
-  #       # ...
+  #       usage '[OPTIONS] [-o OUTPUT] FILE'
+  #     
+  #       option :count, short: '-c',
+  #                      value: {
+  #                        type: Integer,
+  #                        default: 1
+  #                      },
+  #                      desc: "Number of times"
+  #     
+  #       option :output, short: '-o',
+  #                       value: {
+  #                         type: String,
+  #                         usage: 'FILE'
+  #                       },
+  #                       desc: "Optional output file"
+  #     
+  #       argument :file, required: true,
+  #                       usage: 'FILE',
+  #                       desc: "Input file"
+  #     
+  #       examples [
+  #         '-o path/to/output.txt path/to/input.txt',
+  #         '-v -c 2 -o path/to/output.txt path/to/input.txt',
+  #       ]
   #     
+  #       description 'Example command'
+  #     
+  #       def run(*files)
+  #         # ...
+  #       end
   #     end
   #
-  # @note Command classes are not required to inherit from {Command}. This class
-  # only exists as a convenience.
+  # ### initialize and using ivars
+  #
+  #     option :verbose, short: '-v', desc: "Increase verbose level" do
+  #       @verbose += 1
+  #     end
+  # 
+  #     def initialize(**kwargs)
+  #       super(**kwargs)
+  #     
+  #       @verbose = 0
+  #     end
   #
   class Command
 

data/lib/command_kit/commands.rb

@@ -158,6 +158,12 @@ module CommandKit
       end
     end
 
+    #
+    # Initializes the command.
+    #
+    # @note Adds a special rule to the {Options#option_parser #option_parser} to
+    # stop parsing options when the first non-option is encountered.
+    #
     def initialize(**kwargs)
       super(**kwargs)
 

data/lib/command_kit/commands/auto_load/subcommand.rb

@@ -3,6 +3,9 @@ require 'command_kit/commands/subcommand'
 module CommandKit
   module Commands
     class AutoLoad < Module
+      #
+      # Represents a registered subcommand that will be auto-loaded.
+      #
       class Subcommand < Commands::Subcommand
 
         # The fully qualified constant of the command class.

data/lib/command_kit/commands/subcommand.rb

@@ -1,5 +1,8 @@
 module CommandKit
   module Commands
+    #
+    # Represents a registered subcommand.
+    #
     class Subcommand
 
       # The command class.

data/lib/command_kit/description.rb

@@ -54,7 +54,9 @@ module CommandKit
         if new_description
           @description = new_description
         else
-          @description || (superclass.description if superclass.kind_of?(ClassMethods))
+          @description || if superclass.kind_of?(ClassMethods)
+                            superclass.description
+                          end
         end
       end
     end

data/lib/command_kit/examples.rb

@@ -61,7 +61,9 @@ module CommandKit
         if new_examples
           @examples = Array(new_examples)
         else
-          @examples || (superclass.examples if superclass.kind_of?(ClassMethods))
+          @examples || if superclass.kind_of?(ClassMethods)
+                         superclass.examples
+                       end
         end
       end
     end

data/lib/command_kit/help.rb

@@ -36,6 +36,9 @@ module CommandKit
 
     extend ModuleMethods
 
+    #
+    # Class-level methods.
+    #
     module ClassMethods
       #
       # Prints `--help` information.

data/lib/command_kit/help/man.rb

@@ -1,16 +1,29 @@
 # frozen_string_literal: true
 
+require 'command_kit/command_name'
+require 'command_kit/help'
+require 'command_kit/stdio'
+
 module CommandKit
   module Help
     #
     # Allows displaying a man-page instead of the usual `--help` output.
     #
-    # ## Environment Variables
+    # ## Examples
+    #
+    #     class Foo < CommandKit::Command
+    #
+    #       include CommandKit::Help::Man
     #
-    # * `TERM` - Specifies the type of terminal. When set to `DUMB`, it will
-    #   disable man-page help output.
+    #       man_dir "#{__dir__}/../../man"
+    #
+    #     end
     #
     module Man
+      include CommandName
+      include Help
+      include Stdio
+
       module ModuleMethods
         #
         # Extends {ClassMethods} or {ModuleMethods}, depending on whether
@@ -33,7 +46,7 @@ module CommandKit
       extend ModuleMethods
 
       #
-      # Defines class-level methods.
+      # Class-level methods.
       #
       module ClassMethods
         #
@@ -46,74 +59,96 @@ module CommandKit
         #   The class'es or superclass'es man-page directory.
         #
         # @example
-        #   man_dir File.expand_path('../../../man',__FILE__)
+        #   man_dir "#{__dir__}/../../man"
         #
         def man_dir(new_man_dir=nil)
           if new_man_dir
-            @man_dir = File.expand_path(new_man_dir)
+            @man_dir = new_man_dir
           else
-            @man_dir || (superclass.man_dir if superclass.kind_of?(ClassMethods))
+            @man_dir || if superclass.kind_of?(ClassMethods)
+                          superclass.man_dir
+                        end
           end
         end
-      end
 
-      #
-      # Determines if displaying man pages is supported.
-      #
-      # @return [Boolean]
-      #   Indicates whether the `TERM` environment variable is not `dumb`
-      #   and `$stdout` is a TTY.
-      #
-      def self.supported?
-        ENV['TERM'] != 'dumb' && $stdout.tty?
+        #
+        # Gets or sets the class'es man-page file name.
+        #
+        # @param [String, nil] new_man_page
+        #   If a String is given, the class'es man-page file name will be set.
+        #
+        # @return [String]
+        #   The class'es or superclass'es man-page file name.
+        #
+        def man_page(new_man_page=nil)
+          if new_man_page
+            @man_page = new_man_page
+          else
+            @man_page || "#{command_name}.1"
+          end
+        end
       end
 
       #
-      # Returns the man-page file name for the given command name.
+      # Displays the given man page.
+      #
+      # @param [String] page
+      #   The man page file name.
       #
-      # @param [String] command
-      #   The given command name.
+      # @param [Integer, String, nil] section
+      #   The optional section number to specify.
       #
-      # @return [String]
-      #   The man-page file name.
+      # @return [Boolean, nil]
+      #   Specifies whether the `man` command was successful or not.
+      #   Returns `nil` when the `man` command is not installed.
       #
-      def man_page(command=command_name)
-        "#{command}.1"
+      def man(page, section: nil)
+        if section
+          system('man',section.to_s,page.to_s)
+        else
+          system('man',page.to_s)
+        end
       end
 
       #
-      # Displays the given man page.
+      # Provides help information by showing one of the man pages within
+      # {ClassMethods#man_dir .man_dir}.
       #
-      # @param [String] page
-      #   The man page file name.
+      # @param [String] man_page
+      #   The file name of the man page to display.
       #
       # @return [Boolean, nil]
       #   Specifies whether the `man` command was successful or not.
       #   Returns `nil` when the `man` command is not installed.
       #
-      def man(page=man_page)
-        system('man',page)
+      # @raise [NotImplementedError]
+      #   {ClassMethods#man_dir .man_dir} does not have a value.
+      #
+      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)
       end
 
       #
-      # Displays the {#man_page} instead of the usual `--help` output.
+      # Displays the {ClassMethods#man_page .man_page} in
+      # {ClassMethods#man_dir .man_dir} instead of the usual `--help` output.
       #
       # @raise [NotImplementedError]
-      #   {ClassMethods#man_dir man_dir} does not have a value.
+      #   {ClassMethods#man_dir .man_dir} does not have a value.
       #
       # @note
       #   if `TERM` is `dumb` or `$stdout` is not a TTY, fallsback to printing
       #   the usual `--help` output.
       #
       def help
-        if Man.supported?
-          unless self.class.man_dir
-            raise(NotImplementedError,"#{self.class}.man_dir not set")
-          end
-
-          man_path = File.join(self.class.man_dir,man_page)
-
-          if man(man_path).nil?
+        if stdout.tty?
+          if help_man.nil?
+            # the `man` command is not installed
             super
           end
         else