command_mapper 0.1.0.pre1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a8f5edcef133633cddd3398cb7314514661a48f2803800f43410b1ccd2195679
+  data.tar.gz: 57dcbb7895fa2dff5ef8528439ae128fe9b86072674fb32da93f13e03c5d2572
+SHA512:
+  metadata.gz: 5675fc6957f545350b54cb9a46003c9c059496366c1198b4bf2a1656dc7484d009d6e9bd896f56c14fdce222354fb788cedaf6b54b0f88c4835c28893124fc13
+  data.tar.gz: d3fbefad0bc588d75a4dfdf0e0f009d2162ed15562d2ee6ae44f08b9e1efc0815547f5d5fe5276548c921bad0b727e72a139b8ffbb8a09838ece1e19688676e7

data/.github/workflows/ruby.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on: [ push, pull_request ]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - 2.6
+          - 2.7
+          - 3.0
+          - jruby
+          - truffleruby
+    name: Ruby ${{ matrix.ruby }}
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: Install dependencies
+        run: bundle install --jobs 4 --retry 3
+      - name: Run tests
+        run: bundle exec rake test

data/.gitignore

@@ -0,0 +1,10 @@
+/Gemfile.lock
+/coverage
+/doc/
+/pkg/
+/vendor/bundle/
+.DS_Store
+.yardoc
+*.log
+*.swp
+*~

data/.rspec

@@ -0,0 +1 @@
+--colour --format documentation

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --title "CommandMapper Documentation" --protected --quiet

data/ChangeLog.md

@@ -0,0 +1,25 @@
+### 0.1.0 / 2021-11-22
+
+* Initial release:
+  * Added {CommandMapper::Error}.
+  * Added {CommandMapper::ValidationError}.
+  * Added {CommandMapper::ArgumentRequired}.
+  * Added {CommandMapper::Types::Type}.
+  * Added {CommandMapper::Types::Str}.
+  * Added {CommandMapper::Types::Num}.
+  * Added {CommandMapper::Types::Hex}.
+  * Added {CommandMapper::Types::Map}.
+  * Added {CommandMapper::Types::Enum}.
+  * Added {CommandMapper::Types::InputPath}.
+  * Added {CommandMapper::Types::InputFile}.
+  * Added {CommandMapper::Types::InputDir}.
+  * Added {CommandMapper::Types::List}.
+  * Added {CommandMapper::Types::KeyValue}.
+  * Added {CommandMapper::Types::KeyValueList}.
+  * Added {CommandMapper::Arg}.
+  * Added {CommandMapper::Argument}.
+  * Added {CommandMapper::OptionValue}.
+  * Added {CommandMapper::Option}.
+  * Added {CommandMapper::Command}.
+  * Added {CommandMapper::Sudo}.
+

data/Gemfile

@@ -0,0 +1,15 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'rake'
+  gem 'rubygems-tasks', '~> 0.2'
+  gem 'rspec',          '~> 3.0'
+  gem 'simplecov',      '~> 0.20', require: false
+  gem 'kramdown'
+  gem 'yard',           '~> 0.9'
+  gem 'yard-spellcheck'
+
+  gem 'dead_end'
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2021 Hal Brodigan
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,369 @@
+# command_mapper
+
+[![CI](https://github.com/postmodern/command_mapper.rb/actions/workflows/ruby.yml/badge.svg)](https://github.com/postmodern/command_mapper.rb/actions/workflows/ruby.yml)
+[![Code Climate](https://codeclimate.com/github/postmodern/command_mapper.rb.svg)](https://codeclimate.com/github/postmodern/command_mapper.rb)
+
+* [Source](https://github.com/postmodern/command_mapper)
+* [Issues](https://github.com/postmodern/command_mapper/issues)
+* [Documentation](http://rubydoc.info/gems/command_mapper/frames)
+
+## Description
+  
+Command Mapper maps a command's options and arguments to Class attributes to
+allow safely and securely executing commands.
+
+## Features
+
+* 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
+      (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
+* 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.
+
+## Examples
+
+```ruby
+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", 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: 	# FIXME: name
+    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
+```
+
+### Defining Options
+
+```ruby
+option "--opt"
+```
+
+Define a short option:
+
+```ruby
+option "-o", name: :opt
+```
+
+Defines an option with a required value:
+
+```ruby
+option "--output", value: {required: true}
+```
+
+Defines an option that can be specified multiple times:
+
+```ruby
+option "--include-dir", repeats: true
+```
+
+Defines an option that accepts a numeric value:
+
+```ruby
+option "--count", value: {type: Num.new}
+```
+
+Defines an option that accepts a comma-separated list:
+
+```ruby
+option "--list", value: {type: List.new}
+```
+
+Defines an option that accepts a `key=value` pair:
+
+```ruby
+option "--param", value: {type: KeyValue.new}
+```
+
+Defines an option that accepts a `key:value` pair:
+
+```ruby
+option "--param", value: {type: KeyValue.new(separator: ':')}
+```
+
+Defines an option that accepts a finite number of values:
+
+```ruby
+option "--type", value: {type: Enum[:foo, :bar, :baz]}
+```
+
+Custom methods:
+
+```ruby
+def foo
+  @foo || @bar
+end
+
+def foo=(value)
+  @foo = case value
+         when Hash  then ...
+         when Array then ...
+         else            value.to_s
+         end
+end
+```
+
+### Defining Arguments
+
+```ruby
+argument :host
+```
+
+Define an optional argument:
+
+```ruby
+argument :optional_output, required: false
+```
+
+Define an argument that can be repeated:
+
+```ruby
+argument :files, repeats: true
+```
+
+Define an argument that accepts an existing file:
+
+```ruby
+argument :file, type: InputFile.new
+```
+
+Define an argument that accepts an existing directory:
+
+```ruby
+argument :dir, type: InputDir.new
+```
+
+Custom methods:
+
+```ruby
+def foo
+  @foo || @bar
+end
+
+def foo=(value)
+  @foo = case value
+         when Hash  then ...
+         when Array then ...
+         else            value.to_s
+         end
+end
+```
+
+### Custom Types
+
+```ruby
+class PortRange < CommandMapper::Types::Type
+
+  def validate(value)
+    case value
+    when Integer
+      true
+    when Range
+      if value.begin.kind_of?(Integer)
+        true
+      else
+        [false, "port range can only contain Integers"]
+      end
+    else
+      [false, "port range must be an Integer or a Range of Integers"]
+    end
+  end
+
+  def format(value)
+    case value
+    when Integer
+      "#{value}"
+    when Range
+      "#{value.begin}-#{value.end}"
+    end
+  end
+
+end
+
+option :ports, value: {required: true, type: PortRange.new}
+```
+
+### Running
+
+Keyword arguments:
+
+```ruby
+Grep.run(ignore_case: true, patterns: "foo", file: "file.txt")
+# ...
+```
+
+With a block:
+
+```ruby
+Grep.run do |grep|
+  grep.ignore_case = true
+  grep.patterns    = "foo"
+  grep.file        = "file.txt"
+end
+```
+
+### Capturing output
+
+```ruby
+Grep.capture(ignore_case: true, patterns: "foo", file: "file.txt")
+# => "..."
+```
+
+### popen
+
+```ruby
+io = Grep.popen(ignore_case: true, patterns: "foo", file: "file.txt")
+
+io.each_line do |line|
+  # ...
+end
+```
+
+### sudo
+
+```ruby
+Grep.sudo(patterns: "Error", file: "/var/log/syslog")
+# Password: 
+# ...
+```
+
+### Code Gen
+
+[command_mapper-gen] can automatically generate command classes from a command's
+`--help` output and/or man page.
+
+[command_mapper-gen]: https://github.com/postmodern/command_mapper-gen.rb#readme
+
+```
+$ gem install command_mapper-gen
+$ command_mapper-gen cat
+require 'command_mapper/command'
+
+#
+# Represents the `cat` command
+#
+class Cat < CommandMapper::Command
+
+  command "cat" do
+    option "--show-all"
+    option "--number-nonblank"
+    option "-e", name: 	# FIXME: name
+    option "--show-ends"
+    option "--number"
+    option "--squeeze-blank"
+    option "-t", name: 	# FIXME: name
+    option "--show-tabs"
+    option "-u", name: 	# FIXME: name
+    option "--show-nonprinting"
+    option "--help"
+    option "--version"
+
+    argument :file, required: false, repeats: true
+  end
+
+end
+```
+
+## Requirements
+
+* [ruby] >= 2.0.0
+
+## Install
+
+```shell
+$ gem install command_mapper
+```
+
+### Gemfile
+
+```ruby
+gem 'command_mapper', '~> 0.1'
+```
+
+### gemspec
+
+```ruby
+gemspec.add_dependency 'command_mapper', '~> 0.1'
+```
+
+## License
+
+Copyright (c) 2021 Hal Brodigan
+
+See {file:LICENSE.txt} for license information.
+
+[command_mapper]: https://github.com/postmodern/command_mapper.rb#readme
+[ruby]: https://www.ruby-lang.org/

data/Rakefile

@@ -0,0 +1,12 @@
+require 'rubygems'
+
+require 'rubygems/tasks'
+Gem::Tasks.new
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+task :test    => :spec
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/commnad_mapper.gemspec

@@ -0,0 +1,61 @@
+# encoding: utf-8
+
+require 'yaml'
+
+Gem::Specification.new do |gem|
+  gemspec = YAML.load_file('gemspec.yml')
+
+  gem.name    = gemspec.fetch('name')
+  gem.version = gemspec.fetch('version') do
+                  lib_dir = File.join(File.dirname(__FILE__),'lib')
+                  $LOAD_PATH << lib_dir unless $LOAD_PATH.include?(lib_dir)
+
+                  require 'command_mapper/version'
+                  CommandMapper::VERSION
+                end
+
+  gem.summary     = gemspec['summary']
+  gem.description = gemspec['description']
+  gem.licenses    = Array(gemspec['license'])
+  gem.authors     = Array(gemspec['authors'])
+  gem.email       = gemspec['email']
+  gem.homepage    = gemspec['homepage']
+  gem.metadata    = gemspec['metadata'] if gemspec['metadata']
+
+  glob = lambda { |patterns| gem.files & Dir[*patterns] }
+
+  gem.files = `git ls-files`.split($/)
+  gem.files = glob[gemspec['files']] if gemspec['files']
+
+  gem.executables = gemspec.fetch('executables') do
+    glob['bin/*'].map { |path| File.basename(path) }
+  end
+  gem.default_executable = gem.executables.first if Gem::VERSION < '1.7.'
+
+  gem.extensions       = glob[gemspec['extensions'] || 'ext/**/extconf.rb']
+  gem.test_files       = glob[gemspec['test_files'] || '{test/{**/}*_test.rb']
+  gem.extra_rdoc_files = glob[gemspec['extra_doc_files'] || '*.{txt,md}']
+
+  gem.require_paths = Array(gemspec.fetch('require_paths') {
+    %w[ext lib].select { |dir| File.directory?(dir) }
+  })
+
+  gem.requirements              = gemspec['requirements']
+  gem.required_ruby_version     = gemspec['required_ruby_version']
+  gem.required_rubygems_version = gemspec['required_rubygems_version']
+  gem.post_install_message      = gemspec['post_install_message']
+
+  split = lambda { |string| string.split(/,\s*/) }
+
+  if gemspec['dependencies']
+    gemspec['dependencies'].each do |name,versions|
+      gem.add_dependency(name,split[versions])
+    end
+  end
+
+  if gemspec['development_dependencies']
+    gemspec['development_dependencies'].each do |name,versions|
+      gem.add_development_dependency(name,split[versions])
+    end
+  end
+end

data/gemspec.yml

@@ -0,0 +1,23 @@
+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.
+
+license: MIT
+authors: Postmodern
+email: postmodern.mod3@gmail.com
+homepage: https://github.com/postmodern/command_mapper.rb#readme
+has_yard: true
+
+metadata:
+  documentation_uri: https://rubydoc.info/gems/command_mapper
+  source_code_uri:   https://github.com/postmodern/command_mapper.rb
+  bug_tracker_uri:   https://github.com/postmodern/command_mapper.rb/issues
+  changelog_uri:     https://github.com/postmodern/command_mapper.rb/blob/master/ChangeLog.md
+  rubygems_mfa_required: 'true'
+
+required_ruby_version: ">= 2.0.0"
+
+development_dependencies:
+  bundler: ~> 2.0

data/lib/command_mapper/arg.rb

@@ -0,0 +1,75 @@
+require 'command_mapper/types/type'
+require 'command_mapper/types/str'
+
+module CommandMapper
+  #
+  # The base class for both {Option options} and {Argument arguments}.
+  #
+  class Arg
+    # The argument's arg's type.
+    #
+    # @return [Types::Type, nil]
+    attr_reader :type
+
+    #
+    # Initializes the argument.
+    #
+    # @param [Boolean] required
+    #   Specifies whether the argument is required or can be omitted.
+    #
+    # @param [Types::Type, Hash, nil] type
+    #
+    # @raise [ArgumentError]
+    #   The `type` keyword argument was given a `nil` value.
+    #
+    def initialize(required: true, type: Types::Str.new)
+      @required = required
+
+      if type.nil?
+        raise(ArgumentError,"type: keyword cannot be nil")
+      end
+
+      @type = Types::Type(type)
+    end
+
+    #
+    # Specifies whether the argument value is required.
+    #
+    # @return [Boolean]
+    #
+    def required?
+      @required
+    end
+
+    #
+    # Specifies whether the argument value can be omitted.
+    #
+    # @return [Boolean]
+    #
+    def optional?
+      !@required
+    end
+
+    #
+    # Validates whether a given value is compatible with the arg.
+    #
+    # @param [Object] value
+    #
+    # @return [true, (false, String)]
+    #   Returns true if the value is valid, or `false` and a validation error
+    #   message if the value is not compatible.
+    #
+    def validate(value)
+      if value.nil?
+        if required?
+          return [false, "does not accept a nil value"]
+        else
+          return true
+        end
+      else
+        return @type.validate(value)
+      end
+    end
+
+  end
+end