command_mapper 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d3986821a50009055f2fe58c4f69e7eb530b5463114f73f838997743c8227fe
-  data.tar.gz: dc0ca8143917f12ef8cb72601f5a2ff44cccd6c76c0fdbc23fc75bafff571ff5
+  metadata.gz: 7f40de593c4e0124a5c3075b9e89ec08e38fe7451af1ede8fc62030b89b694ec
+  data.tar.gz: '0392b215a5dff4c4b2bffd34ec7df72fece82adbe7d260a975bd909edb9f962d'
 SHA512:
-  metadata.gz: dfaccdfb0892218f9e3b8661d2c80227d492c292407989d3bb2b2ffabe45806898549d463a9bb0aa54fe05092753b0751e797460a94c19849552675b75309ec2
-  data.tar.gz: 4bc76e0cd50aaaf790331ce2aab5acac98562c7ed63cd3979a90429cad836ee4e095ab765aa22b57c17eff9bc89fb92f9ed1b09f97d98fe4ab47cfa38dbcc99a
+  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,33 @@
+### 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
+  superclass for the {CommandMapper::Command.command_name command_name}, if no
+  `command "..."` was defined in the subclass.
+
+### 0.1.1 / 2021-11-29
+
+* Fixed a bug where {CommandMapper::Types::Num}, {CommandMapper::Types::Hex},
+  {CommandMapper::Types::Enum}, {CommandMapper::Types::InputPath},
+  {CommandMapper::Types::InputFile}, and {CommandMapper::Types::InputDir} were
+  not being required by default.
+* Allow {CommandMapper::Types::Map} to accept values that have already been
+  mapped to a String.
+
 ### 0.1.0 / 2021-11-25
 
 * Initial release:

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

@@ -18,27 +18,47 @@ allow safely and securely executing commands.
 * Supports defining commands as Ruby classes.
 * Supports mapping in options and additional arguments.
   * Supports common option types:
-    * `Str`: string values
-    * `Num`: numeric values
-    * `Hex`: hexadecimal values
-    * `Map`: maps `true`/`false` to `yes`/`no`, or `enabled`/`disabled`
-      (aka `--opt=yes|no` or `--opt=enabled|disabled` values).
-    * `Enum`: maps a finite set of Symbols to a finite set of Strings
-      (aka `--opt={foo|bar|baz}` values).
-    * `List`: comma-separated list (aka `--opt VALUE,...`).
-    * `KeyValue`: maps a Hash or Array to key:value Strings
-      (aka `--opt KEY:VALUE` or `--opt KEY=VALUE` values).
-    * `KeyValueList`: a key-value list
+    * [Str][CommandMapper::Types::Str]: string values
+    * [Num][CommandMapper::Types::Num]: numeric values
+    * [Hex][CommandMapper::Types::Hex]: hexadecimal values
+    * [Map][CommandMapper::Types::Map]: maps `true`/`false` to `yes`/`no`, or
+      `enabled`/`disabled` (aka `--opt=yes|no` or
+      `--opt=enabled|disabled` values).
+    * [Enum][CommandMapper::Types::Enum]: maps a finite set of Symbols to a
+      finite set of Strings (aka `--opt={foo|bar|baz}` values).
+    * [List][CommandMapper::Types::List]: comma-separated list
+      (aka `--opt VALUE,...`).
+    * [KeyValue][CommandMapper::Types::KeyValue]: maps a Hash or Array to
+      key:value Strings (aka `--opt KEY:VALUE` or `--opt KEY=VALUE` values).
+    * [KeyValueList][CommandMapper::Types::KeyValueList]: a key-value list
       (aka `--opt KEY:VALUE,...` or  `--opt KEY=VALUE;...` values).
-    * `InputPath`: a path to a pre-existing file or directory
-    * `InputFile`: a path to a pre-existing file
-    * `InputDir`: a path to a pre-existing directory
+    * [InputPath][CommandMapper::Types::InputPath]: a path to a pre-existing
+      file or directory
+    * [InputFile][CommandMapper::Types::InputFile]: a path to a pre-existing
+      file
+    * [InputDir][CommandMapper::Types::InputDir]: a path to a pre-existing
+      directory
 * Supports mapping in sub-commands.
 * Allows running the command via `IO.popen` to read the command's output.
 * 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
+[CommandMapper::Types::Hex]: https://rubydoc.info/gems/command_mapper/CommandMapper/Types/Hex
+[CommandMapper::Types::Map]: https://rubydoc.info/gems/command_mapper/CommandMapper/Types/Map
+[CommandMapper::Types::Enum]: https://rubydoc.info/gems/command_mapper/CommandMapper/Types/Enum
+[CommandMapper::Types::List]: https://rubydoc.info/gems/command_mapper/CommandMapper/Types/List
+[CommandMapper::Types::KeyValue]: https://rubydoc.info/gems/command_mapper/CommandMapper/Types/KeyValue
+[CommandMapper::Types::KeyValueList]: https://rubydoc.info/gems/command_mapper/CommandMapper/Types/KeyValueList
+[CommandMapper::Types::InputPath]: https://rubydoc.info/gems/command_mapper/CommandMapper/Types/InputPath
+[CommandMapper::Types::InputFile]: https://rubydoc.info/gems/command_mapper/CommandMapper/Types/InputFile
+[CommandMapper::Types::InputDir]: https://rubydoc.info/gems/command_mapper/CommandMapper/Types/InputDir
 
 ## Examples
 
@@ -56,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"
@@ -125,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
@@ -137,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
@@ -351,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]
@@ -18,6 +19,7 @@ module CommandMapper
     #   Specifies whether the argument is required or can be omitted.
     #
     # @param [Types::Type, Hash, nil] type
+    #   The type of the arg's value.
     #
     # @raise [ArgumentError]
     #   The `type` keyword argument was given a `nil` value.
@@ -54,6 +56,7 @@ module CommandMapper
     # Validates whether a given value is compatible with the arg.
     #
     # @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

data/lib/command_mapper/argument.rb

@@ -50,6 +50,7 @@ module CommandMapper
     # Validates whether a given value is compatible with the arg.
     #
     # @param [Array<Object>, Object] value
+    #   The given value to validate.
     #
     # @return [true, (false, String)]
     #   Returns true if the value is valid, or `false` and a validation error

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.
@@ -181,7 +207,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 +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.
     #
@@ -230,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.
     #
@@ -246,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:
@@ -260,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
     #
@@ -270,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
 
@@ -307,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.
     #
@@ -333,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
@@ -341,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
 
@@ -365,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.
     #
@@ -392,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
@@ -529,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
 
     #
@@ -559,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}.