mini-cli 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3f71b96747e645a7e4ab1131c3e52840f63f22af4035d06b98f2d21172716d9b
+  data.tar.gz: a8ec28b1326a313f16ec8986f85a56b60f1b8c9832583324b79fd6a55c6a6228
+SHA512:
+  metadata.gz: 72575dc73beedd924a2080b8cb436dcb11b78d9897e4f9eb87836dff6af028845d077c069540b06a5b7b93c6a2719c2de3a53a4e19996476a8c5871332fe97bb
+  data.tar.gz: 6848f5981ef7ce5bb4545a015b309f549450796a5d6530f4fd0f56fd3c315e7347da2afa318048facdb077db0eeee21676cd305b5cd17a863cb2037f5323cf32

data/.gitignore

@@ -0,0 +1,4 @@
+idea/
+tmp/
+pkg/
+gems.locked

data/README.md

@@ -0,0 +1,64 @@
+# Mini Cli
+
+This gem is a minimalistic, easy to use CLI framework with a very small footprint. I provides an easy to use argument parsing, help displaying, minimalistic error handling and some tools like executing external programs and gather their output.
+
+## Installation
+
+To use Mini CLI just install the gem with
+
+```shell
+gem install mini-cli
+```
+
+or include it to you project's gemspec:
+
+```ruby
+gem 'mini-cli'
+```
+
+## Sample
+
+A very minimalistic program may look like this sample program:
+
+```ruby
+require 'mini-cli'
+
+include MiniCli
+
+help <<~HELP, %w[TARGET [SOURCE]]
+  -n, --name NAME  option requires NAME argument, has shortcut
+      --url URL    option requires URL argument
+  -s, --switch     option without any argument, has shortcut
+      --opt        option without any argument
+
+  This is a sample application only.
+HELP
+
+main do |args|
+  puts "TARGET: #{args['TARGET']}"
+  puts "SOURCE: #{args['SOURCE']}" if args.key?('SOURCE')
+  puts "NAME: #{args['NAME']}" if args.key?('NAME')
+  puts "URL: #{args['URL']}" if args.key?('URL')
+  puts "FILES: #{args['FILES']}" unless args['FILES'].empty?
+  puts '--switch was given' if args.key?('switch')
+  puts '--opt was given' if args.key?('opt')
+end
+```
+
+The sample uses the powerful `#help` method to generate an argument parser which handles the command line for you. You only need to handle the given `Hash` parameter (named `args` in the sample) in the body of your `#main` block.
+
+Executing the sample with `--help` or `-h` will provide following help screen:
+
+```
+Usage: sample [OPTIONS] TARGET [SOURCE]
+
+Valid Options:
+-n, --name NAME  option requires NAME argument, has shortcut
+    --url URL    option requires URL argument
+-s, --switch     option without any argument, has shortcut
+    --opt        option without any argument
+
+This is a sample application only.
+```
+
+See the `./samples` directory for more sample programs…

data/gems.rb

@@ -0,0 +1 @@
+gemspec

data/lib/mini-cli.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module MiniCli
+  def self.included(_)
+    return if const_defined?(:SRC)
+    const_set(:SRC, caller_locations(1, 1).first.absolute_path)
+  end
+
+  def name(name = nil)
+    return name ? @__name = name : @__name if defined?(@__name)
+    @__name = name || File.basename(MiniCli::SRC, '.*')
+  end
+
+  def help(helptext, *args)
+    @__argv_parser = ArgvParser.new(helptext, args)
+  end
+
+  def show_help
+    __argv_parser.show_help(name)
+    true
+  end
+
+  def error(code, message)
+    $stderr.puts("#{name}: #{message}")
+    exit(code)
+  end
+
+  def parse_argv(argv = nil, &block)
+    return @__argv_converter = block if block
+    argv ||= ARGV.dup
+    exit(show_help) if argv.index('--help') || argv.index('-h')
+    args = __argv_parser.parse(argv, method(:error).to_proc)
+    defined?(@__argv_converter) ? @__argv_converter.call(args) || args : args
+  end
+
+  def main(args = nil)
+    at_exit do
+      yield(args || parse_argv)
+    rescue Interrupt
+      error(130, 'aborted')
+    end
+  end
+
+  private
+
+  def __argv_parser
+    @__argv_parser ||= ArgvParser.new(nil, [])
+  end
+
+  class ArgvParser
+    def initialize(helptext, args)
+      @helptext = helptext.to_s
+      @args = args.flatten.map!(&:to_s).uniq
+      @options = nil
+    end
+
+    def show_help(name)
+      parse_help! unless @options
+      print("Usage: #{name}")
+      print(' [OPTIONS]') unless @options.empty?
+      print(' ', @args.join(' ')) unless @args.empty?
+      puts
+      puts(nil, 'Valid Options:') unless @options.empty?
+      puts(@helptext) unless @helptext.empty?
+    end
+
+    def parse(argv, error)
+      @error = error
+      parse_help! unless @options
+      @result, arguments = {}, []
+      loop do
+        case arg = argv.shift
+        when nil
+          break
+        when '--'
+          arguments += argv
+          break
+        when /\A--([[[:alnum:]]-]+)\z/
+          handle_option(Regexp.last_match[1], argv)
+        when /\A-([[:alnum:]]+)\z/
+          parse_options(Regexp.last_match[1], argv)
+        else
+          arguments << arg
+        end
+      end
+      process(arguments)
+    end
+
+    private
+
+    def error(msg)
+      @error.call(1, msg)
+    end
+
+    def process(arguments)
+      @args.each do |arg|
+        next if arg.index('..')
+        value = arguments.shift
+        if arg.start_with?('[')
+          @result[arg[1..-2]] = value if value
+        else
+          @result[arg] = value || error("parameter expected - #{arg}")
+        end
+      end
+      arguments.unshift(@result['FILES']) if @result.key?('FILES')
+      @result['FILES'] = arguments
+      @result
+    end
+
+    def handle_option(option, argv)
+      key = @options[option] || error("unknown option - #{option}")
+      return @result[key] = true if option == key
+      @result[key] = value = argv.shift
+      return unless value.nil? || value.start_with?('-')
+      error("parameter #{key} expected - --#{option}")
+    end
+
+    def parse_options(options, argv)
+      options.each_char do |opt|
+        key = @options[opt] || error("unknown option - #{opt}")
+        next @result[key] = true if key == key.downcase
+        @result[key] = value = argv.shift
+        next unless value.nil? || value.start_with?('-')
+        error("parameter #{key} expected - -#{opt}")
+      end
+    end
+
+    def parse_help!
+      @options = {}
+      @helptext.each_line do |line|
+        case line
+        when /-([[:alnum:]]), --([[[:alnum:]]-]+) ([[:upper:]]+)\s+\S+/
+          named_option(Regexp.last_match)
+        when /--([[[:alnum:]]-]+) ([[:upper:]]+)\s+\S+/
+          named_option_short(Regexp.last_match)
+        when /-([[:alnum:]]), --([[[:alnum:]]-]+)\s+\S+/
+          option(Regexp.last_match)
+        when /--([[[:alnum:]]-]+)\s+\S+/
+          option_short(Regexp.last_match)
+        end
+      end
+    end
+
+    def named_option(match)
+      @options[match[1]] = @options[match[2]] = match[3]
+    end
+
+    def named_option_short(match)
+      @options[match[1]] = match[2]
+    end
+
+    def option(match)
+      @options[match[1]] = @options[match[2]] = match[2]
+    end
+
+    def option_short(match)
+      @options[match[1]] = match[1]
+    end
+  end
+
+  private_constant(:ArgvParser)
+end

data/lib/mini-cli/run.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module MiniCli
+  def run(*cmd)
+    opts = Hash === cmd.last ? __run_opt(cmd.last) : [:stdout]
+    opts.delete(:stderr) ? __run3(opts, cmd) : __run2(opts, cmd)
+  rescue SystemCallError
+    nil
+  end
+
+  private
+
+  def __run3(opts, cmd)
+    result = Open3.capture3(*cmd)
+    result.shift unless opts.first == :stdout
+    result.pop unless opts.last == :status
+    result.size == 1 ? result.first : result
+  end
+
+  def __run2(opts, cmd)
+    result = Open3.capture2e(*cmd)
+    return result.last.success? if opts.empty?
+    return result if opts.size == 2
+    opts.first == :status ? result.last : result.first
+  end
+
+  def __run_opt(opts)
+    %i[stdout stderr status].keep_if{ |s| opts.delete(s) }
+  end
+end

data/lib/mini-cli/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MiniCli
+  VERSION = '0.1.0'
+end

data/mini-cli.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative './lib/mini-cli/version'
+
+GemSpec = Gem::Specification.new do |gem|
+  gem.name = 'mini-cli'
+  gem.version = MiniCli::VERSION
+  gem.summary = 'The minimalistic CLI framework for Ruby'
+  gem.description = <<~DESC
+    This gem is a minimalistic, easy to use CLI framework with a very small
+    footprint. I provides an easy to use argument parsing, help displaying and
+    minimalistic error handling.
+  DESC
+  gem.author = 'Mike Blumtritt'
+  gem.homepage = 'https://github.com/mblumtritt/mini-cli'
+  gem.metadata = {
+    'source_code_uri' => 'https://github.com/mblumtritt/mini-cli',
+    'bug_tracker_uri' => 'https://github.com/mblumtritt/mini-cli/issues'
+  }
+
+  gem.required_ruby_version = '>= 2.5.0'
+
+  gem.add_development_dependency 'bundler'
+  gem.add_development_dependency 'minitest'
+  gem.add_development_dependency 'rake'
+
+  all_files = %x(git ls-files -z).split(0.chr)
+  gem.test_files = all_files.grep(%r{^(spec|test)/})
+  gem.files = all_files - gem.test_files
+  # gem.extra_rdoc_files = %w[README.MD]
+end

data/rakefile.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'rake/testtask'
+require 'bundler/gem_tasks'
+
+STDOUT.sync = STDERR.sync = true
+
+CLOBBER << 'prj'
+
+task :default do
+  exec "#{$PROGRAM_NAME} --tasks"
+end
+
+Rake::TestTask.new(:test) do |t|
+  t.ruby_opts = %w[-w]
+  t.verbose = true
+  t.test_files = FileList['test/**/*_test.rb']
+end

data/samples/custom_args.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative '../lib/mini-cli'
+
+include MiniCli
+
+help <<~HELP, %w[TARGET [SOURCE]]
+  -n, --name NAME  option requires NAME argument, has shortcut
+      --url URL    option requires URL argument
+  -s, --switch     option without any argument, has shortcut
+      --opt        option without any argument
+HELP
+
+main do |cfg|
+  cfg.each_pair{ |key, value| puts("#{key}: #{value}") }
+end
+
+parse_argv do |args|
+  Struct.new(:target, :sources, :name, :url, :switch, :opt).new.tap do |cfg|
+    cfg.target = args['TARGET']
+    # args['FILES'] is an array containing all surplus arguments
+    cfg.sources = args['FILES']
+    source = args['SOURCE'] || ENV['SOURCE']
+    cfg.sources.unshift(source) if source
+    cfg.sources << 'STDIN' if cfg.sources.empty?
+    cfg.name = args['NAME'] || 'default_name'
+    cfg.url = args['URL'] || 'www.url.test'
+    cfg.switch = args.key?('switch')
+    cfg.opt = args.key?('opt')
+  end
+end

data/samples/demo.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative '../lib/mini-cli'
+
+include MiniCli
+
+help <<~HELP, %w[TARGET [SOURCE]]
+  -n, --name NAME  option requires NAME argument, has shortcut
+      --url URL    option requires URL argument
+  -s, --switch     option without any argument, has shortcut
+      --opt        option without any argument
+HELP
+
+main do |args|
+  puts("TARGET: #{args['TARGET']}")
+  puts("SOURCE: #{args['SOURCE']}") if args.key?('SOURCE')
+  puts("NAME: #{args['NAME']}") if args.key?('NAME')
+  puts("URL: #{args['URL']}") if args.key?('URL')
+  puts("FILES: #{args['FILES']}") unless args['FILES'].empty?
+  puts('--switch was given') if args.key?('switch')
+  puts('--opt was given') if args.key?('opt')
+end

data/samples/simple.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative '../lib/mini-cli'
+
+include MiniCli
+
+help <<~HELP
+
+  This is a very simple sample without any required parameter.
+HELP
+
+main do |args|
+  puts("given files: #{args['FILES']}")
+end

data/test/helper.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+require 'minitest/parallel'
+
+require_relative '../lib/mini-cli'
+require_relative '../lib/mini-cli/run'
+
+class Test < Minitest::Test
+  parallelize_me!
+  attr_reader :subject
+
+  def setup
+    @subject = Class.new do
+      include MiniCli
+      attr_reader :exit_args
+
+      def exit(*args)
+        @exit_args = args
+      end
+    end.new
+  end
+
+  def assert_stop_with_error(code, text, &block)
+    assert_output(nil, "helper: #{text}\n", &block)
+    assert_equal([code], subject.exit_args)
+  end
+
+  def as_argv(str)
+    str.split(' ')
+  end
+end

data/test/mini-cli/main_test.rb

@@ -0,0 +1,178 @@
+require_relative '../helper'
+
+class MainTest < Test
+  def test_defaults
+    assert_equal('helper', subject.name)
+    assert_output("Usage: helper\n"){ subject.show_help }
+  end
+
+  def test_methods
+    subject = Class.new{ include MiniCli }.new
+
+    expected_methods = %i[
+      error
+      help
+      main
+      name
+      parse_argv
+      run
+      show_help
+    ].sort!
+    methods = (subject.methods - Object.new.methods).sort!
+    assert_equal(expected_methods, methods)
+  end
+
+  def test_error
+    assert_stop_with_error(42, 'some error text') do
+      subject.error(42, 'some error text')
+    end
+
+    assert_stop_with_error(21, 'error') do
+      subject.error(21, :error)
+    end
+  end
+
+  def test_help_simple
+    subject.help 'Some helptext'
+    expected_text = <<~EXPECTED
+      Usage: helper
+      Some helptext
+    EXPECTED
+
+    assert_output(expected_text){ subject.show_help }
+  end
+
+  def test_help_with_args
+    subject.help <<~HELP, 'ARG1', :ARG2
+      Some helptext comes
+      here
+    HELP
+
+    expected_text = <<~EXPECTED
+      Usage: helper ARG1 ARG2
+      Some helptext comes
+      here
+    EXPECTED
+
+    assert_output(expected_text){ subject.show_help }
+  end
+
+  def test_argument_required
+    subject.help :text, :ARG
+
+    assert_stop_with_error(1, 'parameter expected - ARG') do
+      subject.parse_argv(as_argv(''))
+    end
+
+    expected = {'ARG' => 'arg', 'FILES' => []}
+    assert_equal(expected, subject.parse_argv(as_argv('arg')))
+
+    expected = {'ARG' => 'arg1', 'FILES' => %w[arg2 arg3]}
+    assert_equal(expected, subject.parse_argv(as_argv('arg1 arg2 arg3')))
+  end
+
+  def test_name
+    subject.name 'test-42'
+    assert_equal('test-42', subject.name)
+  end
+
+  def test_argument_optional
+    subject.help :text, 'ARG1', '[ARG2]'
+
+    assert_stop_with_error(1, 'parameter expected - ARG1') do
+      subject.parse_argv(as_argv(''))
+    end
+
+    expected = {'ARG1' => 'arg1', 'ARG2' => 'arg2', 'FILES' => []}
+    assert_equal(expected, subject.parse_argv(as_argv('arg1 arg2')))
+
+    expected = {'ARG1' => 'arg', 'FILES' => []}
+    assert_equal(expected, subject.parse_argv(as_argv('arg')))
+  end
+
+  def test_options
+    subject.help <<~HELP
+      -n, --named NAME     option NAME with shortcut
+      --named-long LNAME   option LNAME without shortcut
+      -u, --unnamed        option unnamed with shortcut
+      --un-named           option un-named without shortcut
+
+      Some additional explaination can be here
+    HELP
+
+    expected = {'FILES' => []}
+    assert_equal(expected, subject.parse_argv(as_argv('')))
+
+    expected = {'NAME' => 'name', 'FILES' => []}
+    assert_equal(expected, subject.parse_argv(as_argv('--named name')))
+    assert_equal(expected, subject.parse_argv(as_argv('-n name')))
+
+    expected = {'LNAME' => 'long', 'FILES' => []}
+    assert_equal(expected, subject.parse_argv(as_argv('--named-long long')))
+
+    expected = {'unnamed' => true, 'FILES' => []}
+    assert_equal(expected, subject.parse_argv(as_argv('--unnamed')))
+    assert_equal(expected, subject.parse_argv(as_argv('-u')))
+
+    expected = {'un-named' => true, 'FILES' => []}
+    assert_equal(expected, subject.parse_argv(as_argv('--un-named')))
+
+    expected = {
+      'NAME' => 'name',
+      'LNAME' => 'long',
+      'unnamed' => true,
+      'un-named' => true,
+      'FILES' => %w[FILE1 FILE2]
+    }
+
+    result = subject.parse_argv(%w[
+      --named name
+      --named-long long
+      --unnamed
+      --un-named
+      FILE1
+      FILE2
+    ])
+    assert_equal(expected, result)
+
+    result = subject.parse_argv(%w[
+      -nu name
+      --named-long long
+      --un-named
+      FILE1
+      FILE2
+    ])
+    assert_equal(expected, result)
+  end
+
+  def test_complex_options
+    subject.help <<~HELP, %w[INFILE OUTFILE [OPTFILE]]
+      -n, --named NAME   key 'NAME'
+      -p, --port PORT    key 'PORT'
+      -u, --un-named     key 'unnamed'
+    HELP
+
+    expected = {
+      'INFILE' => 'in',
+      'OUTFILE' => 'out',
+      'NAME' => 'name',
+      'PORT' => 'port',
+      'un-named' => true,
+      'FILES' => []
+    }
+    result = subject.parse_argv(as_argv('-nup name port in out'))
+    assert_equal(expected, result)
+
+    expected = {
+      'INFILE' => 'in',
+      'OUTFILE' => 'out',
+      'OPTFILE' => 'opt',
+      'NAME' => 'name',
+      'PORT' => 'port',
+      'un-named' => true,
+      'FILES' => %w[file]
+    }
+    result = subject.parse_argv(as_argv('-nup name port in out opt file'))
+    assert_equal(expected, result)
+  end
+end

data/test/mini-cli/run_test.rb

@@ -0,0 +1,48 @@
+require_relative '../helper'
+
+class RunTest < Test
+  def setup
+    super
+    @pwd = Dir.pwd + "\n"
+  end
+
+  def test_std_out_only
+    out = subject.run('pwd')
+    assert_equal(@pwd, out)
+
+    out = subject.run('pwd', stdout: true)
+    assert_equal(@pwd, out)
+  end
+
+  def test_status
+    result = subject.run('pwd', stdout: false)
+    assert_instance_of(TrueClass, result)
+
+    status = subject.run('pwd', status: true)
+    assert_instance_of(Process::Status, status)
+
+    out, status = subject.run('pwd', stdout: true, status: true)
+    assert_equal(@pwd, out)
+    assert_instance_of(Process::Status, status)
+    assert(status.success?)
+  end
+
+  def test_std_error
+    err = subject.run('ls /no-valid-dir', stderr: true)
+    assert_match(/No such file or directory/, err)
+
+    out, err = subject.run('ls /no-valid-dir', stdout: true, stderr: true)
+    assert_empty(out)
+    assert_match(/No such file or directory/, err)
+
+    err, status = subject.run('ls /no-valid-dir', stderr: true, status: true)
+    assert_match(/No such file or directory/, err)
+    assert_instance_of(Process::Status, status)
+    refute(status.success?)
+  end
+
+  def test_failure
+    result = subject.run('this-is-not-a-valid-command')
+    assert_instance_of(NilClass, result)
+  end
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: mini-cli
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mike Blumtritt
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-03-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  This gem is a minimalistic, easy to use CLI framework with a very small
+  footprint. I provides an easy to use argument parsing, help displaying and
+  minimalistic error handling.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- README.md
+- gems.rb
+- lib/mini-cli.rb
+- lib/mini-cli/run.rb
+- lib/mini-cli/version.rb
+- mini-cli.gemspec
+- rakefile.rb
+- samples/custom_args.rb
+- samples/demo.rb
+- samples/simple.rb
+- test/helper.rb
+- test/mini-cli/main_test.rb
+- test/mini-cli/run_test.rb
+homepage: https://github.com/mblumtritt/mini-cli
+licenses: []
+metadata:
+  source_code_uri: https://github.com/mblumtritt/mini-cli
+  bug_tracker_uri: https://github.com/mblumtritt/mini-cli/issues
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key: 
+specification_version: 4
+summary: The minimalistic CLI framework for Ruby
+test_files:
+- test/helper.rb
+- test/mini-cli/main_test.rb
+- test/mini-cli/run_test.rb