command_mapper 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4db5d03aecac93251d259d3b776a33706bc328208a9fb58c4a96966d87128ed8
-  data.tar.gz: bc67f06449dc8b0b7c5061c55a315112dcf3fab2bf548314e4f20a6b2dbdd67f
+  metadata.gz: abc51ed8c1f7edf0484053eb62854a56b13dce9d5e3ea7b3373799c4b7a1d4fb
+  data.tar.gz: 0e7945e79e57cb99a4448b4eafef1237e9cc5e06d4523e13efd68b2767106a2f
 SHA512:
-  metadata.gz: 9e99f9216620e3847fc8e250d0c05d549f547396eef01a519d332cd3927cd86c71ed26e862fda84f26f28570e180f76eb1fb9117729a737bcf718de33f2d0886
-  data.tar.gz: a3766529ada1866b7736e905d3ba65511eea1b2e9679b9edad99e57089285159a307beb726ee7b1f2f2c02e6eb6d34d569d86babb3f79dc3be54527e834fbacd
+  metadata.gz: ea9449f43ab086e941cc011dffd778cea4d356a2a9171aef5496e9a4593f62ca3ba68356d455cc510046ee926970c290c065b76bf445ba843a317f60c0fbbd31
+  data.tar.gz: 5979c264d481d50be2fed8ca17a19cb59b4c522303ff4d5cdf14164195b9b27fd6589ebe5b8e0b06276494f5298c6898fb297a97a606ca10d5fb916dbe1d568d

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,35 @@
+### 0.2.1 / 2022-04-22
+
+* Properly validate in {CommandMapper::OptionValue#validate} when an option,
+  who's value is not required, is given `true`.
+* Omit `nil` arguments from {CommandMapper::Command#command_argv} if the
+  argument is not required.
+* Improve validation error message for {CommandMapper::Types::Num} when
+  initialized with a `range:` value.
+* Improve validation error message for {CommandMapper::Types::Map} and 
+  {CommandMapper::Types::Enum}.
+
+### 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},

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

@@ -21,9 +21,9 @@ allow safely and securely executing commands.
     * [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).
+    * [Map][CommandMapper::Types::Map]: maps Ruby values to other String values.
+      * `Map::YesNo`: maps `true`/`false` to `yes`/`no`.
+      * `Map::EnabledDisabled`: Maps `true`/`false` to `enabled`/`disabled`.
     * [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
@@ -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
@@ -293,6 +314,18 @@ Grep.run do |grep|
 end
 ```
 
+Overriding the command name:
+
+```ruby
+Grep.run(..., command_name: 'grep2')
+```
+
+Specifying the direct path to the command:
+
+```ruby
+Grep.run(..., command_path: '/path/to/grep')
+```
+
 ### Capturing output
 
 ```ruby
@@ -368,18 +401,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/examples/grep.rb

@@ -0,0 +1,62 @@
+require 'command_mapper/command'
+
+#
+# Represents the `grep` command
+#
+class Grep < CommandMapper::Command
+
+  command "grep" do
+    option "--extended-regexp"
+    option "--fixed-strings"
+    option "--basic-regexp"
+    option "--perl-regexp"
+    option "--regexp", equals: true, value: true
+    option "--file", name: :patterns_file, equals: true, value: true
+    option "--ignore-case"
+    option "--no-ignore-case"
+    option "--word-regexp"
+    option "--line-regexp"
+    option "--null-data"
+    option "--no-messages"
+    option "--invert-match"
+    option "--version"
+    option "--help"
+    option "--max-count", equals: true, value: {type: Num.new}
+    option "--byte-offset"
+    option "--line-number"
+    option "--line-buffered"
+    option "--with-filename"
+    option "--no-filename"
+    option "--label", equals: true, value: true
+    option "--only-matching"
+    option "--quiet"
+    option "--binary-files", equals: true, value: true
+    option "--text"
+    option "-I", name: :binary
+    option "--directories", equals: true, value: true
+    option "--devices", equals: true, value: true
+    option "--recursive"
+    option "--dereference-recursive"
+    option "--include", equals: true, value: true
+    option "--exclude", equals: true, value: true
+    option "--exclude-from", equals: true, value: true
+    option "--exclude-dir", equals: true, value: true
+    option "--files-without-match", value: true
+    option "--files-with-matches"
+    option "--count"
+    option "--initial-tab"
+    option "--null"
+    option "--before-context", equals: true, value: {type: Num.new}
+    option "--after-context", equals: true, value: {type: Num.new}
+    option "--context", equals: true, value: {type: Num.new}
+    option "--group-separator", equals: true, value: true
+    option "--no-group-separator"
+    option "--color", equals: :optional, value: {required: false}
+    option "--colour", equals: :optional, value: {required: false}
+    option "--binary"
+
+    argument :patterns
+    argument :file, required: false, repeats: true
+  end
+
+end

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]
@@ -23,6 +24,8 @@ module CommandMapper
     # @raise [ArgumentError]
     #   The `type` keyword argument was given a `nil` value.
     #
+    # @api private
+    #
     def initialize(required: true, type: Types::Str.new)
       @required = required
 
@@ -61,6 +64,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 value.nil?
         if required?

data/lib/command_mapper/argument.rb

@@ -30,6 +30,8 @@ module CommandMapper
     # @raise [ArgumentError]
     #   The given `type:` must not be `false` or `nil`.
     #
+    # @api private
+    #
     def initialize(name, required: true, type: Types::Str.new, repeats: false)
       super(required: required, type: type)
 
@@ -56,6 +58,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 repeats?
         values = case value
@@ -101,6 +105,8 @@ module CommandMapper
     # @raise [ArgumentError]
     #   The given value was incompatible with the argument.
     #
+    # @api semipublic
+    #
     def argv(argv=[],value)
       valid, message = validate(value)