command_mapper 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f40de593c4e0124a5c3075b9e89ec08e38fe7451af1ede8fc62030b89b694ec
-  data.tar.gz: '0392b215a5dff4c4b2bffd34ec7df72fece82adbe7d260a975bd909edb9f962d'
+  metadata.gz: 254468c58bbee95ac037609a4ddefc34c026240b4933a37038df1bade5b7487e
+  data.tar.gz: 1fe51a7d6ad09b0b51c753bee28632e70292bfa9e9938896e22183c0327f48ae
 SHA512:
-  metadata.gz: f5c09b88caea6446ac20238bbba137accd62552c413e5fa67d9dce9a62f2e3f027624c6a951ce59fc6c720f2683e80dcbe5d3e8942d85f472e5d25e12f5e5a85
-  data.tar.gz: a8e1b267f3628fd23d2924f9d6f25534744af6c2af8a80d5cc3b3fa63bbdc1f35853dcda99871db67cbeea6f6824f3ed77a19b33bd8bd1bb1f5ca7750abf8a7b
+  metadata.gz: c1fc9b041fafa2d92300bcbf312e8b1d848450bd4691b6b0eea57fb401a8d20b8a73613328c69cc5d323e9b42313ecc2f3e66b8bcfff14454a8cdb5bd5db5467
+  data.tar.gz: 62fd74bd469bff9620c94a8c0710f6d309bb0611af7e58664fa7d04808ee40b14d3b076fb8143a6fdbd409a0fd35fb12682e535c30b41ed616200dc7be982bd2

data/ChangeLog.md

@@ -1,3 +1,18 @@
+### 0.3.0 / 2022-11-11
+
+* Added {CommandMapper::Types::Dec}.
+
+### 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

data/README.md

@@ -10,8 +10,8 @@
 
 ## Description
   
-Command Mapper maps a command's options and arguments to Class attributes to
-allow safely and securely executing commands.
+Command Mapper maps an external command's options and arguments to Class
+attributes to allow safely and securely executing commands.
 
 ## Features
 
@@ -20,10 +20,11 @@ allow safely and securely executing commands.
   * Supports common option types:
     * [Str][CommandMapper::Types::Str]: string values
     * [Num][CommandMapper::Types::Num]: numeric values
+    * [Dec][CommandMapper::Types::Dec]: decimal 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
@@ -50,6 +51,7 @@ allow safely and securely executing commands.
 
 [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::Dec]: https://rubydoc.info/gems/command_mapper/CommandMapper/Types/Dec
 [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
@@ -314,6 +316,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

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/gemspec.yml

@@ -1,8 +1,8 @@
 name: command_mapper
 summary: Safe and secure execution of commands.
 description:
-  Command Mapper maps a command's arguments to Class attributes to allow safely
-  and securely executing commands.
+  Command Mapper maps an external command's arguments to Class attributes to
+  allow safely and securely executing commands.
 
 license: MIT
 authors: Postmodern

data/lib/command_mapper/arg.rb

@@ -24,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
 
@@ -62,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)
 

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]
     #
@@ -113,12 +112,16 @@ module CommandMapper
     # 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.
@@ -138,12 +141,16 @@ module CommandMapper
     # 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.
@@ -157,12 +164,19 @@ module CommandMapper
     # 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]
     #
@@ -175,15 +189,15 @@ module CommandMapper
     # 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]
     #
@@ -360,6 +374,7 @@ module CommandMapper
     # All defined options.
     #
     # @return [Hash{Symbol => Argument}]
+    #   The mapping of argument names and {Argument} objects.
     #
     # @api semipublic
     #
@@ -438,7 +453,8 @@ module CommandMapper
     #
     # All defined subcommands.
     #
-    # @return [Hash{Symbol => Command}]
+    # @return [Hash{Symbol => Command.class}]
+    #   The mapping of subcommand names and subcommand classes.
     #
     # @api semipublic
     #
@@ -535,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.
@@ -555,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.
@@ -575,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.
@@ -597,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
@@ -639,6 +663,8 @@ module CommandMapper
     # 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)
@@ -674,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)
@@ -688,6 +715,8 @@ module CommandMapper
     #   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)
@@ -718,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

@@ -51,6 +51,8 @@ module CommandMapper
     #   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,
@@ -81,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]
@@ -146,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?
@@ -173,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)
 

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/dec.rb

@@ -0,0 +1,84 @@
+require 'command_mapper/types/type'
+
+module CommandMapper
+  module Types
+    #
+    # Represents a decimal value (ex: `1.5`).
+    #
+    # @since 0.3.0
+    #
+    class Dec < Type
+
+      # The optional range of acceptable decimal numbers.
+      #
+      # @return [Range<Float,Float>, nil]
+      #
+      # @api semipublic
+      attr_reader :range
+
+      #
+      # Initializes the decimal type.
+      #
+      # @param [Range<Float,Float>] range
+      #   Specifies the range of acceptable numbers.
+      #
+      def initialize(range: nil)
+        @range = range
+      end
+
+      #
+      # Validates a value.
+      #
+      # @param [String, Numeric] 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)
+        case value
+        when Float
+          # no-op
+        when String
+          unless value =~ /\A\d+(?:\.\d+)?\z/
+            return [false, "contains non-decimal characters (#{value.inspect})"]
+          end
+        else
+          unless value.respond_to?(:to_f)
+            return [false, "cannot be converted into a Float (#{value.inspect})"]
+          end
+        end
+
+        if @range
+          unless @range.include?(value.to_f)
+            return [false, "(#{value.inspect}) not within the range of acceptable values (#{range.inspect})"]
+          end
+        end
+
+        return true
+      end
+
+      #
+      # Formats a decimal value.
+      #
+      # @param [String, Float, #to_f] value
+      #   The given value to format.
+      #
+      # @return [String]
+      #   The formatted decimal value.
+      #
+      # @api semipublic
+      #
+      def format(value)
+        case value
+        when Float, String then value.to_s
+        else                    value.to_f.to_s
+        end
+      end
+
+    end
+  end
+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
 
       #

data/lib/command_mapper/types/hex.rb

@@ -27,6 +27,8 @@ module CommandMapper
       #
       # @return [Boolean]
       #
+      # @api semipublic
+      #
       def leading_zero?
         @leading_zero
       end
@@ -41,6 +43,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)
         case value
         when String
@@ -69,6 +73,8 @@ module CommandMapper
       # @return [String]
       #   The formatted numeric value.
       #
+      # @api semipublic
+      #
       def format(value)
         case value
         when String

data/lib/command_mapper/types/input_dir.rb

@@ -17,6 +17,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)
         valid, message = super(value)
 

data/lib/command_mapper/types/input_file.rb

@@ -17,6 +17,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)
         valid, message = super(value)
 

data/lib/command_mapper/types/input_path.rb

@@ -17,6 +17,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)
         unless value.empty?
           unless File.exists?(value)