lib/command_mapper/command.rb in command_mapper-0.2.0 vs lib/command_mapper/command.rb in command_mapper-0.2.1

@@ -3,10 +3,15 @@
 require 'command_mapper/option'
 
 require 'shellwords'
 
 module CommandMapper
+  #
+  # Base class for all mapped commands.
+  #
+  # @api public
+  #
   class Command
 
     include Types
 
     # The command name.
@@ -22,20 +27,10 @@
     # The environment variables to execute the command with.
     #
     # @return [Hash{String => String}]
     attr_reader :command_env
 
-    # The option values to execute the command with.
-    #
-    # @return [Hash{String => Object}]
-    attr_reader :command_options
-
-    # The argument values to execute the command with.
-    #
-    # @return [Hash{String => Object}]
-    attr_reader :command_arguments
-
     # The subcommand's options and arguments.
     #
     # @return [Command, nil]
     attr_reader :command_subcommand
 
@@ -49,11 +44,11 @@
     #   Overrides the command with a custom command name.
     #
     # @param [String, nil] command_path
     #   Overrides the command with a custom path to the command.
     #
-    # @param [Hash{String => String}] env
+    # @param [Hash{String => String}] command_env
     #   Custom environment variables to pass to the command.
     #
     # @param [Hash{Symbol => Object}] kwargs
     #   Additional keywords arguments. These will be used to populate
     #   {#options} and {#arguments}, along with `params`.
@@ -92,16 +87,20 @@
 
     #
     # Initializes and runs the command.
     #
     # @param [Hash{Symbol => Object}] params
-    #   The option values.
+    #   The option and argument values.
     #
-    # @yield [self]
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keywords arguments. These will be used to populate
+    #   {#options} and {#arguments}, along with `params`.
+    #
+    # @yield [command]
     #   The newly initialized command.
     #
-    # @yieldparam [Command] self
+    # @yieldparam [Command] command
     #
     # @return [Boolean, nil]
     #
     def self.run(params={},**kwargs,&block)
       command = new(params,**kwargs,&block)
@@ -111,16 +110,20 @@
     #
     # Initializes and spawns the command as a separate process, returning the
     # PID of the process.
     #
     # @param [Hash{Symbol => Object}] params
-    #   The option values.
+    #   The option and argument values.
     #
-    # @yield [self]
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keywords arguments. These will be used to populate
+    #   {#options} and {#arguments}, along with `params`.
+    #
+    # @yield [command]
     #   The newly initialized command.
     #
-    # @yieldparam [Command] self
+    # @yieldparam [Command] command
     #
     # @return [Integer]
     #   The PID of the new command process.
     #
     # @raise [Errno::ENOENT]
@@ -136,16 +139,20 @@
     #
     # Initializes and runs the command in a shell and captures all stdout
     # output.
     #
     # @param [Hash{Symbol => Object}] params
-    #   The option values.
+    #   The option and argument values.
     #
-    # @yield [self]
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keywords arguments. These will be used to populate
+    #   {#options} and {#arguments}, along with `params`.
+    #
+    # @yield [command]
     #   The newly initialized command.
     #
-    # @yieldparam [Command] self
+    # @yieldparam [Command] command
     #
     # @return [String]
     #   The stdout output of the command.
     #
     def self.capture(params={},**kwargs,&block)
@@ -155,16 +162,23 @@
 
     #
     # Initializes and executes the command and returns an IO object to it.
     #
     # @param [Hash{Symbol => Object}] params
-    #   The option values.
+    #   The option and argument values.
     #
-    # @yield [self]
+    # @param [String] mode
+    #   The IO "mode" to open the IO pipe in.
+    #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keywords arguments. These will be used to populate
+    #   {#options} and {#arguments}, along with `params`.
+    #
+    # @yield [command]
     #   The newly initialized command.
     #
-    # @yieldparam [Command] self
+    # @yieldparam [Command] command
     #
     # @return [IO]
     #
     def self.popen(params={}, mode: 'r', **kwargs,&block)
       command = new(params,**kwargs,&block)
@@ -173,19 +187,19 @@
 
     #
     # Initializes and runs the command through `sudo`.
     #
     # @param [Hash{Symbol => Object}] params
-    #   The option values.
+    #   The option and argument values.
     #
     # @param [Hash{Symbol => Object}] kwargs
     #   Additional keyword arguments for {#initialize}.
     #
-    # @yield [self]
+    # @yield [command]
     #   The newly initialized command.
     #
-    # @yieldparam [Command] self
+    # @yieldparam [Command] command
     #
     # @return [Boolean, nil]
     #
     def self.sudo(params={}, sudo: {}, **kwargs,&block)
       command = new(params,**kwargs,&block)
@@ -358,10 +372,11 @@
 
     #
     # All defined options.
     #
     # @return [Hash{Symbol => Argument}]
+    #   The mapping of argument names and {Argument} objects.
     #
     # @api semipublic
     #
     def self.arguments
       @arguments ||= if superclass < Command
@@ -436,11 +451,12 @@
     end
 
     #
     # All defined subcommands.
     #
-    # @return [Hash{Symbol => Command}]
+    # @return [Hash{Symbol => Command.class}]
+    #   The mapping of subcommand names and subcommand classes.
     #
     # @api semipublic
     #
     def self.subcommands
       @subcommands ||= if superclass < Command
@@ -533,12 +549,14 @@
 
     #
     # Gets the value of an option or an argument.
     #
     # @param [Symbol] name
+    #   The name of the option, argument, or subcommand.
     #
     # @return [Object]
+    #   The value of the option, argument, or subcommand.
     #
     # @raise [ArgumentError]
     #   The given name was not match any option or argument.
     #
     def [](name)
@@ -553,14 +571,17 @@
 
     #
     # Sets an option or an argument with the given name.
     #
     # @param [Symbol] name
+    #   The name of the option, argument, or subcommand.
     #
     # @param [Object] value
+    #   The new value for the option, argument, or subcommand.
     #
     # @return [Object]
+    #   The new value for the option, argument, or subcommand.
     #
     # @raise [ArgumentError]
     #   The given name was not match any option or argument.
     #
     def []=(name,value)
@@ -573,10 +594,11 @@
 
     #
     # Returns an Array of command-line arguments for the command.
     #
     # @return [Array<String>]
+    #   The formatted command-line arguments.
     #
     # @raise [ArgumentReqired]
     #   A required argument was not set.
     #
     def command_argv
@@ -595,12 +617,14 @@
         additional_args = []
 
         self.class.arguments.each do |name,argument|
           value = self[name]
 
-          if value.nil? && argument.required?
-            raise(ArgumentRequired,"argument #{name} is required")
+          if value.nil?
+            if argument.required?
+              raise(ArgumentRequired,"argument #{name} is required")
+            end
           else
             argument.argv(additional_args,value)
           end
         end
 
@@ -637,10 +661,12 @@
 
     #
     # Runs the command.
     #
     # @return [Boolean, nil]
+    #   Indicates whether the command exited successfully or not.
+    #   `nil` indicates the command could not be found.
     #
     def run_command
       Kernel.system(@command_env,*command_argv)
     end
 
@@ -672,10 +698,11 @@
 
     #
     # Executes the command and returns an IO object to it.
     #
     # @return [IO]
+    #   The IO object for the command's `STDIN`.
     #
     def popen_command(mode=nil)
       if mode then IO.popen(@command_env,command_argv,mode)
       else         IO.popen(@command_env,command_argv)
       end
@@ -686,10 +713,12 @@
     #
     # @param [Hash{Symbol => Object}] sudo_params
     #   Additional keyword arguments for {Sudo#initialize}.
     #
     # @return [Boolean, nil]
+    #   Indicates whether the command exited successfully or not.
+    #   `nil` indicates the command could not be found.
     #
     def sudo_command(**sudo_kwargs,&block)
       sudo_params = sudo_kwargs.merge(command: command_argv)
 
       Sudo.run(sudo_params, command_env: @command_env, &block)
@@ -716,9 +745,10 @@
     #
     # @param [#to_sym] name
     #   The method name.
     #
     # @return [Boolean]
+    #   Indicates that the method name is also an intenral method name.
     #
     def self.is_internal_method?(name)
       Command.instance_methods(false).include?(name.to_sym)
     end