command_kit 0.1.0.pre1 → 0.2.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,16 +46,16 @@ module CommandKit
       # @param [Array<String>] argv
       #   The Array of command-line arguments.
       #
+      # @api public
+      #
       def start(argv=ARGV, **kwargs)
-        begin
-          exit main(argv, **kwargs)
-        rescue Interrupt
-          # https://tldp.org/LDP/abs/html/exitcodes.html
-          exit 130
-        rescue Errno::EPIPE
-          # STDOUT pipe broken
-          exit 0
-        end
+        exit main(argv, **kwargs)
+      rescue Interrupt
+        # https://tldp.org/LDP/abs/html/exitcodes.html
+        exit 130
+      rescue Errno::EPIPE
+        # STDOUT pipe broken
+        exit 0
       end
 
       #
@@ -68,6 +71,8 @@ module CommandKit
       # @return [Integer]
       #   The exit status of the command.
       #
+      # @api public
+      #
       def main(argv=[], **kwargs)
         new(**kwargs).main(argv)
       end
@@ -82,6 +87,10 @@ module CommandKit
     # @return [Integer]
     #   The exit status code.
     #
+    # @note `argv` is splatted into {#run}.
+    #
+    # @api public
+    #
     def main(argv=[])
       run(*argv)
       return 0
@@ -97,6 +106,8 @@ module CommandKit
     #   
     # @abstract
     #
+    # @api public
+    #
     def run(*args)
     end
   end

data/lib/command_kit/man.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module CommandKit
+  #
+  # Allows displaying man pages.
+  #
+  # ## Examples
+  #
+  #     man "passwd"
+  #     man "passwd", section: 5
+  #
+  # @since 0.2.0
+  #
+  module Man
+    #
+    # Displays the given man page.
+    #
+    # @param [String] page
+    #   The man page file name.
+    #
+    # @param [Integer, String, nil] section
+    #   The optional section number to specify.
+    #
+    # @return [Boolean, nil]
+    #   Specifies whether the `man` command was successful or not.
+    #   Returns `nil` when the `man` command is not installed.
+    #
+    # @example
+    #   man "passwd"
+    #
+    # @example Display a man-page from a specific section:
+    #   man "passwd", section: 5
+    #
+    # @api public
+    #
+    def man(page, section: nil)
+      if section
+        system('man',section.to_s,page.to_s)
+      else
+        system('man',page.to_s)
+      end
+    end
+  end
+end

data/lib/command_kit/open_app.rb

@@ -0,0 +1,69 @@
+require 'command_kit/os'
+require 'command_kit/env/path'
+
+module CommandKit
+  #
+  # Allows opening a file or a URI with the system's preferred application for
+  # that file type or URI scheme.
+  #
+  # ## Examples
+  #
+  #     open_app_for "movie.avi"
+  #     open_app_for "https://github.com/postmodern/command_kit.rb"
+  #
+  # @since 0.2.0
+  #
+  module OpenApp
+    include OS
+    include Env::Path
+
+    #
+    # Initializes the command and determines which open command to use.
+    #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keyword arguments.
+    #
+    # @api public
+    #
+    def initialize(**kwargs)
+      super(**kwargs)
+
+      @open_command = if macos?
+                        'open'
+                      elsif linux? || bsd?
+                        if command_installed?('xdg-open')
+                          'xdg-open'
+                        end
+                      elsif windows?
+                        if command_installed?('invoke-item')
+                          'invoke-item'
+                        else
+                          'start'
+                        end
+                      end
+    end
+
+    #
+    # Opens a file or URI using the system's preferred application for that
+    # file type or URI scheme.
+    #
+    # @param [String, URI] file_or_uri
+    #   The file path or URI to open.
+    #
+    # @return [Boolean, nil]
+    #   Specifies whether the file or URI was successfully opened or not.
+    #   If the open command could not be determined, `nil` is returned.
+    #
+    # @example Open a file:
+    #   open_app_for "movie.avi"
+    #
+    # @example Open a URI:
+    #   open_app_for "https://github.com/postmodern/command_kit.rb"
+    #
+    def open_app_for(file_or_uri)
+      if @open_command
+        system(@open_command,file_or_uri.to_s)
+      end
+    end
+  end
+end

data/lib/command_kit/options/option.rb

@@ -11,26 +11,32 @@ module CommandKit
     #
     # Represents a defined option.
     #
+    # @api private
+    #
     class Option
 
+      # The option's name.
+      #
       # @return [Symbol]
       attr_reader :name
 
+      # The option's optional short-flag.
+      #
       # @return [String, nil]
       attr_reader :short
 
+      # The option's long-flag.
+      #
       # @return [String]
       attr_reader :long
 
-      # @return [Boolean]
-      attr_reader :equals
-
+      # The option value's type.
+      #
       # @return [OptionValue, nil]
       attr_reader :value
 
-      # @return [String]
-      attr_reader :desc
-
+      # The optional block that will receive the parsed option value.
+      #
       # @return [Proc, nil]
       attr_reader :block
 
@@ -38,26 +44,39 @@ module CommandKit
       # Initializes the option.
       #
       # @param [Symbol] name
+      #   The name of the option.
       #
       # @param [String, nil] short
+      #   Optional short-flag for the option.
       #
       # @param [String, nil] long
+      #   Optional explicit long-flag for the option.
       #
       # @param [Boolean] equals
+      #   Specifies whether the option is of the form (`--opt=value`).
       #
-      # @param [Hash{Symbol => Object}, nil] value
+      # @param [Hash{Symbol => Object}, true, false, nil] value
       #   Keyword arguments for {OptionValue#initialize}, or `nil` if the option
       #   has no additional value.
       #
       # @option value [Class, Hash, Array, Regexp] type
+      #   The type of the option's value.
       #
       # @option value [String, nil] usage
+      #   The usage string for the option's value.
       #
       # @param [String] desc
+      #   The description for the option.
       #
       # @yield [(value)]
+      #   If a block is given, it will be called when the option is parsed.
       #
       # @yieldparam [Object, nil] value
+      #   The given block will be passed the parsed option's value.
+      #
+      # @raise [TypeError]
+      #   The `value` keyword argument was not a `Hash`, `true`, `false`, or
+      #   `nil`.
       #
       def initialize(name, short:   nil,
                            long:    self.class.default_long_opt(name),
@@ -69,7 +88,13 @@ module CommandKit
         @short   = short
         @long    = long
         @equals  = equals
-        @value   = OptionValue.new(**value) if value
+        @value   = case value
+                   when Hash       then OptionValue.new(**value)
+                   when true       then OptionValue.new()
+                   when false, nil then nil
+                   else
+                     raise(TypeError,"value: keyword must be Hash, true, false, or nil")
+                   end
         @desc    = desc
         @block   = block
       end
@@ -79,8 +104,10 @@ module CommandKit
       # (ex: `:long_opt`).
       #
       # @param [Symbol] name
+      #   The option name.
       #
       # @return [String]
+      #   The long-flag for the option.
       #
       def self.default_long_opt(name)
         "--#{Inflector.dasherize(name)}"
@@ -96,7 +123,7 @@ module CommandKit
       end
 
       #
-      # The separator characer between the option and option value.
+      # The separator character between the option and option value.
       #
       # @return ['=', ' ', nil]
       #

data/lib/command_kit/options/option_value.rb

@@ -14,8 +14,11 @@ module CommandKit
     #
     # Represents an additional argument associated with an option flag.
     #
+    # @api private
+    #
     class OptionValue < Arguments::ArgumentValue
 
+      # Maps OptionParser types to USAGE strings.
       USAGES = {
         # NOTE: NilClass and Object are intentionally omitted
         Date       => 'DATE',
@@ -36,27 +39,52 @@ module CommandKit
         Regexp     => '/REGEXP/'
       }
 
+      # 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
+
       #
       # Initializes the option value.
       #
       # @param [Class, Hash, Array, Regexp] type
+      #   The type of the option value.
+      #
+      # @param [Object, Proc, nil] default
+      #   The default parsed value for the option value.
       #
       # @param [String, nil] usage
+      #   The optional usage string for the option value.
       #
       # @param [Hash{Symbol => Object}] kwargs
+      #   Additional keyword arguments.
+      #
+      # @option kwargs [Boolean] required
+      #   Specifies whether the option value is required or optional.
       #
-      def initialize(type: String,
-                     usage: self.class.default_usage(type),
+      def initialize(type:    String,
+                     default: nil,
+                     usage:   self.class.default_usage(type),
                      **kwargs)
-        super(type: type, usage: usage, **kwargs)
+        super(usage: usage, **kwargs)
+
+        @type    = type
+        @default = default
       end
 
       #
       # Returns the default option value usage for the given type.
       #
       # @param [Class, Hash, Array, Regexp] type
+      #   The option value type.
       #
       # @return [String, nil]
+      #   A default usage string based on the option value type.
       #
       # @raise [TypeError]
       #   The given type was not a Class, Hash, Array, or Regexp.
@@ -85,6 +113,17 @@ module CommandKit
         string
       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/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,24 +115,24 @@ module CommandKit
       # @return [Array<String>]
       #   The remaining non-option arguments.
       #
+      # @api semipublic
+      #
       def parse_options(argv)
-        begin
-          option_parser.parse(argv)
-        rescue OptionParser::InvalidOption => error
-          on_invalid_option(error)
-        rescue OptionParser::AmbiguousOption => error
-          on_ambiguous_option(error)
-        rescue OptionParser::InvalidArgument => error
-          on_invalid_argument(error)
-        rescue OptionParser::MissingArgument => error
-          on_missing_argument(error)
-        rescue OptionParser::NeedlessArgument => error
-          on_needless_argument(error)
-        rescue OptionParser::AmbiguousArgument => error
-          on_ambiguous_argument(error)
-        rescue OptionParser::ParseError => error
-          on_parse_error(error)
-        end
+        option_parser.parse(argv)
+      rescue OptionParser::InvalidOption => error
+        on_invalid_option(error)
+      rescue OptionParser::AmbiguousOption => error
+        on_ambiguous_option(error)
+      rescue OptionParser::InvalidArgument => error
+        on_invalid_argument(error)
+      rescue OptionParser::MissingArgument => error
+        on_missing_argument(error)
+      rescue OptionParser::NeedlessArgument => error
+        on_needless_argument(error)
+      rescue OptionParser::AmbiguousArgument => error
+        on_ambiguous_argument(error)
+      rescue OptionParser::ParseError => error
+        on_parse_error(error)
       end
 
       #
@@ -132,6 +141,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 +156,8 @@ module CommandKit
       #
       # @see on_parse_error
       #
+      # @api semipublic
+      #
       def on_invalid_option(error)
         on_parse_error(error)
       end
@@ -157,6 +170,8 @@ module CommandKit
       #
       # @see on_parse_error
       #
+      # @api semipublic
+      #
       def on_ambiguous_option(error)
         on_parse_error(error)
       end
@@ -169,6 +184,8 @@ module CommandKit
       #
       # @see on_parse_error
       #
+      # @api semipublic
+      #
       def on_invalid_argument(error)
         on_parse_error(error)
       end
@@ -181,6 +198,8 @@ module CommandKit
       #
       # @see on_parse_error
       #
+      # @api semipublic
+      #
       def on_missing_argument(error)
         on_parse_error(error)
       end
@@ -193,6 +212,8 @@ module CommandKit
       #
       # @see on_parse_error
       #
+      # @api semipublic
+      #
       def on_needless_argument(error)
         on_parse_error(error)
       end
@@ -205,6 +226,8 @@ module CommandKit
       #
       # @see on_parse_error
       #
+      # @api semipublic
+      #
       def on_ambiguous_argument(error)
         on_parse_error(error)
       end
@@ -212,6 +235,8 @@ module CommandKit
       #
       # Prints the `--help` output.
       #
+      # @api semipublic
+      #
       def help_options
         puts option_parser
       end
@@ -219,6 +244,8 @@ module CommandKit
       #
       # @see #help_options
       #
+      # @api public
+      #
       def help
         help_options
       end