command_mapper 0.1.1 → 0.2.1

data/lib/command_mapper/command.rb

@@ -5,6 +5,11 @@ require 'command_mapper/option'
 require 'shellwords'
 
 module CommandMapper
+  #
+  # Base class for all mapped commands.
+  #
+  # @api public
+  #
   class Command
 
     include Types
@@ -24,16 +29,6 @@ module CommandMapper
     # @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]
@@ -51,7 +46,7 @@ module CommandMapper
     # @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
@@ -94,12 +89,16 @@ module CommandMapper
     # 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]
     #
@@ -109,15 +108,49 @@ module CommandMapper
     end
 
     #
-    # Runs the command in a shell and captures all stdout output.
+    # 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]
+    #   The command could not be found.
+    #
+    # @since 0.2.0
+    #
+    def self.spawn(params={},**kwargs,&block)
+      command = new(params,**kwargs,&block)
+      command.spawn_command
+    end
+
+    #
+    # Initializes and runs the command in a shell and captures all stdout
+    # output.
+    #
+    # @param [Hash{Symbol => Object}] params
+    #   The option and argument values.
+    #
+    # @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] command
     #
     # @return [String]
     #   The stdout output of the command.
@@ -128,15 +161,22 @@ module CommandMapper
     end
 
     #
-    # Executes the command and returns an IO object to it.
+    # 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]
     #
@@ -146,18 +186,18 @@ module CommandMapper
     end
 
     #
-    # Initializes and runs the command through sudo.
+    # 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]
     #
@@ -181,7 +221,11 @@ module CommandMapper
     # @api semipublic
     #
     def self.command_name
-      @command_name || raise(NotImplementedError,"#{self} did not call command(...)")
+      @command_name || if superclass < Command
+                         superclass.command_name
+                       else
+                         raise(NotImplementedError,"#{self} did not call command(...)")
+                       end
     end
 
     #
@@ -221,6 +265,23 @@ module CommandMapper
                    end
     end
 
+    #
+    # Determines if an option with the given name has been defined.
+    #
+    # @param [Symbol] name
+    #   The given name.
+    #
+    # @return [Boolean]
+    #   Specifies whether an option with the given name has been defined.
+    #
+    # @api semipublic
+    #
+    # @since 0.2.0
+    #
+    def self.has_option?(name)
+      options.has_key?(name)
+    end
+
     #
     # Defines an option for the command.
     #
@@ -230,10 +291,6 @@ module CommandMapper
     # @param [Symbol, nil] name
     #   The option's name.
     #
-    # @param [Boolean] equals
-    #   Specifies whether the option's flag and value should be separated with a
-    #   `=` character.
-    #
     # @param [Hash, nil] value
     #   The option's value.
     #
@@ -246,6 +303,14 @@ module CommandMapper
     # @param [Boolean] repeats
     #   Specifies whether the option can be given multiple times.
     #
+    # @param [Boolean] equals
+    #   Specifies whether the option's flag and value should be separated with a
+    #   `=` character.
+    #
+    # @param [Boolean] value_in_flag
+    #   Specifies that the value should be appended to the option's flag
+    #   (ex: `-Fvalue`).
+    #
     # @api public
     #
     # @example Defining an option:
@@ -260,6 +325,9 @@ module CommandMapper
     # @example Defining an option who's value is optional:
     #   option '--file', value: {required: false}
     #
+    # @example Defining an `-Fvalue` option:
+    #   option '--foo', value: true, value_in_flag: true
+    #
     # @example Defining an `--opt=value` option:
     #   option '--foo', equals: true, value: true
     #
@@ -270,25 +338,35 @@ module CommandMapper
     #   option '--list', value: List.new
     #
     # @raise [ArgumentError]
-    #   The option flag conflicts with a pre-existing internal method.
-    #
-    def self.option(flag, name: nil, equals: nil, value: nil, repeats: false, &block)
+    #   The option flag conflicts with a pre-existing internal method, or
+    #   another argument or subcommand.
+    #
+    def self.option(flag, name: nil, value: nil, repeats: false,
+                          # formatting options
+                          equals:        nil,
+                          value_in_flag: nil,
+                          &block)
       option = Option.new(flag, name:    name,
-                                equals:  equals,
                                 value:   value,
                                 repeats: repeats,
+                                # formatting options
+                                equals:        equals,
+                                value_in_flag: value_in_flag,
                                 &block)
 
-      self.options[option.name] = option
-
       if is_internal_method?(option.name)
         if name
           raise(ArgumentError,"option #{flag.inspect} with name #{name.inspect} cannot override the internal method with same name: ##{option.name}")
         else
           raise(ArgumentError,"option #{flag.inspect} maps to method name ##{option.name} and cannot override the internal method with same name: ##{option.name}")
         end
+      elsif has_argument?(option.name)
+        raise(ArgumentError,"option #{flag.inspect} with name #{option.name.inspect} conflicts with another argument with the same name")
+      elsif has_subcommand?(option.name)
+        raise(ArgumentError,"option #{flag.inspect} with name #{option.name.inspect} conflicts with another subcommand with the same name")
       end
 
+      self.options[option.name] = option
       attr_accessor option.name
     end
 
@@ -296,6 +374,7 @@ module CommandMapper
     # All defined options.
     #
     # @return [Hash{Symbol => Argument}]
+    #   The mapping of argument names and {Argument} objects.
     #
     # @api semipublic
     #
@@ -307,6 +386,23 @@ module CommandMapper
                      end
     end
 
+    #
+    # Determines if an argument with the given name has been defined.
+    #
+    # @param [Symbol] name
+    #   The given name.
+    #
+    # @return [Boolean]
+    #   Specifies whether an argument with the given name has been defined.
+    #
+    # @api semipublic
+    #
+    # @since 0.2.0
+    #
+    def self.has_argument?(name)
+      arguments.has_key?(name)
+    end
+
     #
     # Defines an option for the command.
     #
@@ -333,7 +429,8 @@ module CommandMapper
     #   argument :file, required: false
     #
     # @raise [ArgumentError]
-    #   The argument name conflicts with a pre-existing internal method.
+    #   The argument name conflicts with a pre-existing internal method, or
+    #   another option or subcommand.
     #
     def self.argument(name, required: true, type: Str.new, repeats: false)
       name     = name.to_sym
@@ -341,19 +438,23 @@ module CommandMapper
                                     type:     type,
                                     repeats:  repeats)
 
-      self.arguments[argument.name] = argument
-
       if is_internal_method?(argument.name)
         raise(ArgumentError,"argument #{name.inspect} cannot override internal method with same name: ##{argument.name}")
+      elsif has_option?(argument.name)
+        raise(ArgumentError,"argument #{name.inspect} conflicts with another option with the same name")
+      elsif has_subcommand?(argument.name)
+        raise(ArgumentError,"argument #{name.inspect} conflicts with another subcommand with the same name")
       end
 
+      self.arguments[argument.name] = argument
       attr_accessor name
     end
 
     #
     # All defined subcommands.
     #
-    # @return [Hash{Symbol => Command}]
+    # @return [Hash{Symbol => Command.class}]
+    #   The mapping of subcommand names and subcommand classes.
     #
     # @api semipublic
     #
@@ -365,6 +466,23 @@ module CommandMapper
                        end
     end
 
+    #
+    # Determines if a subcommand with the given name has been defined.
+    #
+    # @param [Symbol] name
+    #   The given name.
+    #
+    # @return [Boolean]
+    #   Specifies whether a subcommand with the given name has been defined.
+    #
+    # @api semipublic
+    #
+    # @since 0.2.0
+    #
+    def self.has_subcommand?(name)
+      subcommands.has_key?(name)
+    end
+
     #
     # Defines a subcommand.
     #
@@ -392,25 +510,30 @@ module CommandMapper
     #   end
     #
     # @raise [ArgumentError]
-    #   The subcommand name conflicts with a pre-existing internal method.
+    #   The subcommand name conflicts with a pre-existing internal method, or
+    #   another option or argument.
     #
     def self.subcommand(name,&block)
-      name = name.to_s
+      name            = name.to_s
+      method_name     = name.tr('-','_')
+      class_name      = name.split(/[_-]+/).map(&:capitalize).join
+      subcommand_name = method_name.to_sym
+
+      if is_internal_method?(method_name)
+        raise(ArgumentError,"subcommand #{name.inspect} maps to method name ##{method_name} and cannot override the internal method with same name: ##{method_name}")
+      elsif has_option?(subcommand_name)
+        raise(ArgumentError,"subcommand #{name.inspect} conflicts with another option with the same name")
+      elsif has_argument?(subcommand_name)
+        raise(ArgumentError,"subcommand #{name.inspect} conflicts with another argument with the same name")
+      end
 
       subcommand_class = Class.new(Command)
       subcommand_class.command(name)
       subcommand_class.class_eval(&block)
 
-      method_name = name.tr('-','_')
-      class_name  = name.split(/[_-]+/).map(&:capitalize).join
-
-      self.subcommands[method_name.to_sym] = subcommand_class
+      self.subcommands[subcommand_name] = subcommand_class
       const_set(class_name,subcommand_class)
 
-      if is_internal_method?(method_name)
-        raise(ArgumentError,"subcommand #{name.inspect} maps to method name ##{method_name} and cannot override the internal method with same name: ##{method_name}")
-      end
-
       define_method(method_name) do |&block|
         if block then @command_subcommand = subcommand_class.new(&block)
         else          @command_subcommand
@@ -428,8 +551,10 @@ module CommandMapper
     # 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.
@@ -448,10 +573,13 @@ module CommandMapper
     # 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.
@@ -468,6 +596,7 @@ module CommandMapper
     # 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.
@@ -490,8 +619,10 @@ module CommandMapper
         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
@@ -529,12 +660,30 @@ module CommandMapper
     end
 
     #
-    # Initializes and runs the command.
+    # 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
-      system(@command_env,*command_argv)
+      Kernel.system(@command_env,*command_argv)
+    end
+
+    #
+    # Spawns the command as a separate process, returning the PID of the
+    # process.
+    #
+    # @return [Integer]
+    #   The PID of the new command process.
+    #
+    # @raise [Errno::ENOENT]
+    #   The command could not be found.
+    #
+    # @since 0.2.0
+    #
+    def spawn_command
+      Process.spawn(@command_env,*command_argv)
     end
 
     #
@@ -551,6 +700,7 @@ module CommandMapper
     # 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)
@@ -559,12 +709,14 @@ module CommandMapper
     end
 
     #
-    # Initializes and runs the command through sudo.
+    # Runs the command through `sudo`.
     #
     # @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)
@@ -595,6 +747,7 @@ module CommandMapper
     #   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)

data/lib/command_mapper/option.rb

@@ -7,12 +7,18 @@ module CommandMapper
   #
   class Option
 
+    # The option's flag (ex: `-o` or `--output`).
+    #
     # @return [String]
     attr_reader :flag
 
+    # The option's name.
+    #
     # @return [Symbol]
     attr_reader :name
 
+    # Describes the option's value.
+    #
     # @return [OptionValue, nil]
     attr_reader :value
 
@@ -25,10 +31,6 @@ module CommandMapper
     # @param [Symbol, nil] name
     #   The option's name.
     #
-    # @param [Boolean] equals
-    #   Specifies whether the option's flag and value should be separated with a
-    #   `=` character.
-    #
     # @param [Hash, nil] value
     #   The option's value.
     #
@@ -41,15 +43,31 @@ module CommandMapper
     # @param [Boolean] repeats
     #   Specifies whether the option can be given multiple times.
     #
-    def initialize(flag, name: nil, equals: nil, value: nil, repeats: false)
+    # @param [Boolean] equals
+    #   Specifies whether the option's flag and value should be separated with a
+    #   `=` character.
+    #
+    # @param [Boolean] value_in_flag
+    #   Specifies that the value should be appended to the option's flag
+    #   (ex: `-Fvalue`).
+    #
+    # @api private
+    #
+    def initialize(flag, name: nil, value: nil, repeats: false,
+                         # formatting options
+                         equals:        nil,
+                         value_in_flag: nil)
       @flag    = flag
       @name    = name || self.class.infer_name_from_flag(flag)
-      @equals  = equals
       @value   = case value
                  when Hash then OptionValue.new(**value)
                  when true then OptionValue.new
                  end
       @repeats = repeats
+
+      # formatting options
+      @equals        = equals
+      @value_in_flag = value_in_flag
     end
 
     #
@@ -65,6 +83,8 @@ module CommandMapper
     #   Could not infer the name from the given option flag or was not given a
     #   valid option flag.
     #
+    # @api private
+    #
     def self.infer_name_from_flag(flag)
       if flag.start_with?('--')
         name = flag[2..-1]
@@ -90,6 +110,15 @@ module CommandMapper
       !@value.nil?
     end
 
+    #
+    # Determines whether the option can be given multiple times.
+    #
+    # @return [Boolean]
+    #
+    def repeats?
+      @repeats
+    end
+
     #
     # Indicates whether the option flag and value should be separated with a
     # `=` character.
@@ -101,12 +130,14 @@ module CommandMapper
     end
 
     #
-    # Determines whether the option can be given multiple times.
+    # Indicates whether the value will be appended to the option's flag.
     #
     # @return [Boolean]
     #
-    def repeats?
-      @repeats
+    # @since 0.2.0
+    #
+    def value_in_flag?
+      @value_in_flag
     end
 
     #
@@ -119,6 +150,8 @@ module CommandMapper
     #   Returns true if the value is valid, or `false` and a validation error
     #   message if the value is not compatible.
     #
+    # @api semipublic
+    #
     def validate(value)
       if accepts_value?
         if repeats?
@@ -146,6 +179,8 @@ module CommandMapper
     # @raise [ArgumentError]
     #   The given value was incompatible with the option.
     #
+    # @api semipublic
+    #
     def argv(argv=[],value)
       valid, message = validate(value)
 
@@ -269,13 +304,15 @@ module CommandMapper
       else
         string = @value.format(value)
 
-        if string.start_with?('-')
-          raise(ValidationError,"option #{@name} formatted value (#{string.inspect}) cannot start with a '-'")
-        end
-
         if equals?
           argv << "#{@flag}=#{string}"
+        elsif value_in_flag?
+          argv << "#{@flag}#{string}"
         else
+          if string.start_with?('-')
+            raise(ValidationError,"option #{@name} formatted value (#{string.inspect}) cannot start with a '-'")
+          end
+
           argv << @flag << string
         end
       end

data/lib/command_mapper/option_value.rb

@@ -6,6 +6,26 @@ module CommandMapper
   #
   class OptionValue < Arg
 
+    #
+    # Validates whether a given value is compatible with the option {#type}.
+    #
+    # @param [Object] value
+    #   The given value to validate.
+    #
+    # @return [true, (false, String)]
+    #   Returns true if the value is valid, or `false` and a validation error
+    #   message if the value is not compatible.
+    #
+    # @api semipublic
+    #
+    def validate(value)
+      if !required? && value == true
+        return true
+      else
+        super(value)
+      end
+    end
+
     #
     # Formats a value using the options {#type}.
     #
@@ -15,6 +35,8 @@ module CommandMapper
     # @return [String]
     #   The formatted value.
     #
+    # @api semipublic
+    #
     def format(value)
       @type.format(value)
     end

data/lib/command_mapper/types/enum.rb

@@ -2,9 +2,17 @@ require 'command_mapper/types/map'
 
 module CommandMapper
   module Types
+    #
+    # Represents a mapping of Ruby values to their String equivalents.
+    #
     class Enum < Map
 
+      # The values of the enum.
+      #
       # @return [Array<Object>]
+      #
+      # @api semipublic
+      #
       attr_reader :values
 
       #