command_mapper 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b0bd1d63ca9619bc3d0c0bd3729e1d5a3e0de9d7291f1e92a24f0c4d7fc6e26
-  data.tar.gz: 3f5c08cc90eb514a75ab6333b2e76f7e9a6dd5f3ec33502e5b8c23e8d60c03ed
+  metadata.gz: 7f40de593c4e0124a5c3075b9e89ec08e38fe7451af1ede8fc62030b89b694ec
+  data.tar.gz: '0392b215a5dff4c4b2bffd34ec7df72fece82adbe7d260a975bd909edb9f962d'
 SHA512:
-  metadata.gz: b42311e2b1453ce2c2295ad1cf3e893a205239287dff21566240a721ac45fd9dc16332c34eb8e9beca88053655d88f0d265e8c4a767a58f803f38e318d263e98
-  data.tar.gz: 7981d9e48540297c7282cef7800015933d1fa5820ac0378bc71faa36adec6a4f321160beb8a10d5e7b9a5b860235a6d8407001f9bfc6935ac31d03802bf1f7d1
+  metadata.gz: f5c09b88caea6446ac20238bbba137accd62552c413e5fa67d9dce9a62f2e3f027624c6a951ce59fc6c720f2683e80dcbe5d3e8942d85f472e5d25e12f5e5a85
+  data.tar.gz: a8e1b267f3628fd23d2924f9d6f25534744af6c2af8a80d5cc3b3fa63bbdc1f35853dcda99871db67cbeea6f6824f3ed77a19b33bd8bd1bb1f5ca7750abf8a7b

data/.document

@@ -0,0 +1,3 @@
+-
+ChangeLog.*
+LICENSE.txt

data/.github/workflows/ruby.yml

@@ -11,7 +11,8 @@ jobs:
         ruby:
           - 2.6
           - 2.7
-          - 3.0
+          - '3.0'
+          - 3.1
           - jruby
           - truffleruby
     name: Ruby ${{ matrix.ruby }}

data/ChangeLog.md

@@ -1,3 +1,18 @@
+### 0.2.0 / 2022-04-18
+
+* Added {CommandMapper::Command.spawn} and
+  {CommandMapper::Command#spawn_command}.
+* Added checks to {CommandMapper::Command.option},
+  {CommandMapper::Command.argument}, and {CommandMapper::Command.subcommand} to
+  avoid overwriting an existing option/argument/subcommand with the same name.
+* Added the `value_in_flag:` keyword argument to
+  {CommandMapper::Command.option} which indicates an option's value
+  should be appended to the flag (ex: `-Fvalue`).
+* Added the `range:` keyword argument to {CommandMapper::Types::Num#initialize}
+  for specifying the acceptable range of numbers.
+* Allow options with `equals: true` (aka `--opt=...`) or `value_in_flag: true`
+  (aka `-Fvalue`) to accept values that start with a `-` character.
+
 ### 0.1.2 / 2021-11-29
 
 * Fixed a bug where {CommandMapper::Command.command_name} was not checking the

data/Gemfile

@@ -7,7 +7,9 @@ group :development do
   gem 'rubygems-tasks', '~> 0.2'
   gem 'rspec',          '~> 3.0'
   gem 'simplecov',      '~> 0.20', require: false
+
   gem 'kramdown'
+  gem 'redcarpet',      platform: :mri
   gem 'yard',           '~> 0.9'
   gem 'yard-spellcheck'
 

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2021 Hal Brodigan
+Copyright (c) 2021-2022 Hal Brodigan
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -43,7 +43,10 @@ allow safely and securely executing commands.
 * Allows running commands with additional environment variables.
 * Allows overriding the command name or path to the command.
 * Allows running commands via `sudo`.
-* Prevents command injection and option injection.
+* Prevents [command injection] and [option injection].
+
+[command injection]: https://owasp.org/www-community/attacks/Command_Injection
+[option injection]: https://staaldraad.github.io/post/2019-11-24-argument-injection/
 
 [CommandMapper::Types::Str]: https://rubydoc.info/gems/command_mapper/CommandMapper/Types/Str
 [CommandMapper::Types::Num]: https://rubydoc.info/gems/command_mapper/CommandMapper/Types/Num
@@ -73,7 +76,7 @@ class Grep < CommandMapper::Command
     option "--basic-regexp"
     option "--perl-regexp"
     option "--regexp", equals: true, value: true
-    option "--file", equals: true, value: true
+    option "--file", name: :patterns_file, equals: true, value: true
     option "--ignore-case"
     option "--no-ignore-case"
     option "--word-regexp"
@@ -142,6 +145,18 @@ Defines an option with a required value:
 option "--output", value: {required: true}
 ```
 
+Defines an option that uses an equals sign (ex: `--output=value`):
+
+```ruby
+option "--output", equals: true, value: {required: true}
+```
+
+Defines an option where the value is embedded into the flag (ex: `-Ivalue`):
+
+```ruby
+option "-I", value: {required: true}, value_in_flag: true
+```
+
 Defines an option that can be specified multiple times:
 
 ```ruby
@@ -154,6 +169,12 @@ Defines an option that accepts a numeric value:
 option "--count", value: {type: Num.new}
 ```
 
+Define an option that only accepts a range of acceptable values:
+
+```ruby
+option "--count", value: {type: Num.new(range: 1..100)}
+```
+
 Defines an option that accepts a comma-separated list:
 
 ```ruby
@@ -368,18 +389,18 @@ $ gem install command_mapper
 ### Gemfile
 
 ```ruby
-gem 'command_mapper', '~> 0.1'
+gem 'command_mapper', '~> 0.2'
 ```
 
 ### gemspec
 
 ```ruby
-gemspec.add_dependency 'command_mapper', '~> 0.1'
+gemspec.add_dependency 'command_mapper', '~> 0.2'
 ```
 
 ## License
 
-Copyright (c) 2021 Hal Brodigan
+Copyright (c) 2021-2022 Hal Brodigan
 
 See {file:LICENSE.txt} for license information.
 

data/lib/command_mapper/arg.rb

@@ -6,6 +6,7 @@ module CommandMapper
   # The base class for both {Option options} and {Argument arguments}.
   #
   class Arg
+
     # The argument's arg's type.
     #
     # @return [Types::Type, nil]

data/lib/command_mapper/command.rb

@@ -109,7 +109,33 @@ 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.
+    #
+    # @yield [self]
+    #   The newly initialized command.
+    #
+    # @yieldparam [Command] self
+    #
+    # @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 values.
@@ -128,7 +154,7 @@ 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.
@@ -146,7 +172,7 @@ 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.
@@ -225,6 +251,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.
     #
@@ -234,10 +277,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.
     #
@@ -250,6 +289,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:
@@ -264,6 +311,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
     #
@@ -274,25 +324,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
 
@@ -311,6 +371,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.
     #
@@ -337,7 +414,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
@@ -345,12 +423,15 @@ 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
 
@@ -369,6 +450,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.
     #
@@ -396,25 +494,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
@@ -533,12 +636,28 @@ module CommandMapper
     end
 
     #
-    # Initializes and runs the command.
+    # Runs the command.
     #
     # @return [Boolean, nil]
     #
     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
 
     #
@@ -563,7 +682,7 @@ 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}.

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,29 @@ 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`).
+    #
+    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
 
     #
@@ -90,6 +106,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 +126,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
 
     #
@@ -269,13 +296,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/types/hex.rb

@@ -14,9 +14,11 @@ module CommandMapper
       #   Specifies whether the hex value will start with `0x` or not.
       #
       # @param [Hash{Symbol => Object}] kwargs
-      #   Additional keyword arguments for {Type#initialize}.
+      #   Additional keyword arguments for {Num#initialize}.
       #
-      def initialize(leading_zero: false)
+      def initialize(leading_zero: false, **kwargs)
+        super(**kwargs)
+
         @leading_zero = leading_zero
       end
 
@@ -46,6 +48,12 @@ module CommandMapper
             return [false, "not in hex format (#{value.inspect})"]
           end
 
+          if @range
+            unless @range.include?(value.to_i(16))
+              return [false, "unacceptable value (#{value.inspect})"]
+            end
+          end
+
           return true
         else
           super(value)

data/lib/command_mapper/types/map.rb

@@ -4,6 +4,8 @@ module CommandMapper
   module Types
     class Map < Type
 
+      # The map of values to Strings.
+      #
       # @return [Hash{Object => String}]
       attr_reader :map
 

data/lib/command_mapper/types/num.rb

@@ -7,6 +7,21 @@ module CommandMapper
     #
     class Num < Type
 
+      # The optional range of acceptable numbers.
+      #
+      # @return [Range, nil]
+      attr_reader :range
+
+      #
+      # Initializes the numeric value.
+      #
+      # @param [Range] range
+      #   Specifies the range of acceptable numbers.
+      #
+      def initialize(range: nil)
+        @range = range
+      end
+
       #
       # Validates a value.
       #
@@ -20,7 +35,7 @@ module CommandMapper
       def validate(value)
         case value
         when Integer
-          return true
+          # no-op
         when String
           unless value =~ /\A\d+\z/
             return [false, "contains non-numeric characters (#{value.inspect})"]
@@ -31,6 +46,12 @@ module CommandMapper
           end
         end
 
+        if @range
+          unless @range.include?(value.to_i)
+            return [false, "unacceptable value (#{value.inspect})"]
+          end
+        end
+
         return true
       end
 

data/lib/command_mapper/version.rb

@@ -1,4 +1,4 @@
 module CommandMapper
   # Version of command_mapper
-  VERSION = '0.1.2'
+  VERSION = '0.2.0'
 end