simple_scripting 0.9.4 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fb9a4aca2b7495bf0ce6236f6052bcc7c55c2624
-  data.tar.gz: 5e4c2c1cdc733a142955b1462546ef7ab0535e07
+  metadata.gz: bb1844c9f2da48418b9fc91c3b4026c7fd1a1fbf
+  data.tar.gz: 5a30040d716b0e544027261f5bbe6fba834d75af
 SHA512:
-  metadata.gz: 6c96951fcb96d49f0e4b4e512788b8f45c860d28d1dba22be29023db869f44bebf87b188458e8f264fc23503f104e0bd53f50bbe9b3df6efeec880c4c944b836
-  data.tar.gz: 2f8f5c74c08f01e5a5ac020df7bd3011b21e2c0ebfc6282a7fc6e6a0d347ffd87acf4d59513dccba9a3fdf8c646229f9b455aceae55d4b14293bd88f0a0c9a90
+  metadata.gz: 39c51fd57bb624894fbb9b0adbfc731d365c2fd36d7b6e9e0a17d2e06fc36ba2f78c014f007b5dd360079daf449beb1ed433d694d827d15f17e664bf10bfdd0e
+  data.tar.gz: 6013724a8eb488ed73b2c8918096af8fc4c37a70e5e04aedcf66abd228412ec19606716b9a80a5b4ec829a99f4b071fe0978079ba35db9e023c58a4ea8265190

data/.simplecov

@@ -0,0 +1,8 @@
+require 'simplecov'
+require 'coveralls'
+
+SimpleCov.formatter = Coveralls::SimpleCov::Formatter
+
+SimpleCov.start do
+   add_filter '/spec/'
+end

data/.travis.yml

@@ -1,9 +1,6 @@
 language: ruby
+cache: bundler
 rvm:
-  - 2.2
   - 2.3
   - 2.4
   - 2.5
-# Bundler+Rubygems issue; see https://github.com/travis-ci/travis-ci/issues/8978
-before_install:
-  - gem update --system

data/Gemfile

@@ -1,12 +1,12 @@
 source 'https://rubygems.org'
 
-gem 'parseconfig', '~> 1.0'
-
-group :development do
-  gem 'rake', '~> 12.0'
-end
+gemspec
 
 group :test do
-  gem 'rspec', '~> 3.6'
   gem 'coveralls', '~> 0.8.21', require: false
 end
+
+group :tools do
+  gem 'byebug', '~> 10.0.2'
+  gem 'rubocop', '= 0.58.1'
+end

data/Gemfile.lock

@@ -1,6 +1,14 @@
+PATH
+  remote: .
+  specs:
+    simple_scripting (0.9.4)
+      parseconfig (~> 1.0)
+
 GEM
   remote: https://rubygems.org/
   specs:
+    ast (2.4.0)
+    byebug (10.0.2)
     coveralls (0.8.21)
       json (>= 1.8, < 3)
       simplecov (~> 0.14.1)
@@ -9,8 +17,14 @@ GEM
       tins (~> 1.6)
     diff-lcs (1.3)
     docile (1.1.5)
+    jaro_winkler (1.5.1)
     json (2.1.0)
+    parallel (1.12.1)
     parseconfig (1.0.8)
+    parser (2.5.1.2)
+      ast (~> 2.4.0)
+    powerpack (0.1.2)
+    rainbow (3.0.0)
     rake (12.0.0)
     rspec (3.6.0)
       rspec-core (~> 3.6.0)
@@ -25,6 +39,15 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.6.0)
     rspec-support (3.6.0)
+    rubocop (0.58.1)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.5, != 2.5.1.1)
+      powerpack (~> 0.1)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.0, >= 1.0.1)
+    ruby-progressbar (1.9.0)
     simplecov (0.14.1)
       docile (~> 1.1.0)
       json (>= 1.8, < 3)
@@ -34,15 +57,18 @@ GEM
       tins (~> 1.0)
     thor (0.19.4)
     tins (1.15.0)
+    unicode-display_width (1.4.0)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
+  byebug (~> 10.0.2)
   coveralls (~> 0.8.21)
-  parseconfig (~> 1.0)
   rake (~> 12.0)
   rspec (~> 3.6)
+  rubocop (= 0.58.1)
+  simple_scripting!
 
 BUNDLED WITH
-   1.11.2
+   1.16.1

data/README.md

@@ -1,21 +1,93 @@
 [![Gem Version][GV img]](https://rubygems.org/gems/simple_scripting)
 [![Build Status][BS img]](https://travis-ci.org/saveriomiroddi/simple_scripting)
-[![Dependency Status][DS img]](https://gemnasium.com/saveriomiroddi/simple_scripting)
 [![Code Climate][CC img]](https://codeclimate.com/github/saveriomiroddi/simple_scripting)
 [![Coverage Status][CS img]](https://coveralls.io/r/saveriomiroddi/simple_scripting)
 
 # SimpleScripting
 
-`SS` is a library composed of two modules (`Argv` and `Configuration`) which simplify two common scripting tasks:
+`SimpleScripting` is a library composed of three modules (`TabCompletion`, `Argv` and `Configuration`) that simplify three common scripting tasks:
 
+- writing autocompletion scripts
 - implementing the commandline options parsing (and the related help)
 - loading and decoding the configuration for the script/application
 
-`SS` is an interesting (and useful) exercise in design, aimed at finding the simplest and most expressive data/structures which accomplish the given task(s). For this reason, the library can be useful for people who frequently write small scripts (eg. devops or nerds).
+`SimpleScripting` is an interesting (and useful) exercise in design, aimed at finding the simplest and most expressive data/structures that accomplish the given task(s). For this reason, the library can be useful for people who frequently write small scripts (eg. devops or nerds).
+
+## SimpleScripting::TabCompletion
+
+`TabCompletion` makes trivial to define tab-completion for terminal commands on Linux/Mac systems; it's so easy that an example is much simpler than an explanation.
+
+### Example
+
+Suppose we have the command:
+
+```sh
+open_project [-e|--with-editor EDITOR] <project_name>
+```
+
+We want to add tab completion both for the option and the project name. Easy!!
+
+Install the gem (`simple_scripting`), then create this class (`/my/completion_scripts/open_project_completion.rb`):
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'simple_scripting/tab_completion'
+
+class OpenProjectTabCompletion
+  SYSTEM_EDITORS = `update-alternatives --list editor`.split("\n").map { |filename| File.basename(filename) }
+
+  def with_editor(prefix, suffix, context)
+    SYSTEM_EDITORS.grep /^#{prefix}/
+  end
+
+  def project_name(prefix, suffix, context)
+    Dir["/my/home/my_projects/#{prefix}*"]
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  completion_definition = [
+    ["-e", "--with-editor EDITOR"],
+    'project_name'
+  ]
+
+  SimpleScripting::TabCompletion.new(completion_definition).complete(OpenProjectTabCompletion.new)
+end
+```
+
+then chmod and register it:
+
+```sh
+$ chmod +x /my/completion_scripts/open_project_completion.rb
+$ complete -C /my/completion_scripts/open_project_completion.rb -o default open_project
+```
+
+Done!
+
+Now type the following, and get:
+
+```sh
+$ open_project g<tab>           # lists: "geet", "gitlab-ce", "gnome-terminal"
+$ open_project --with-editor v  # lists: "vim.basic", "vim.tiny"
+$ open_project --wi<tab>        # autocompletes "--with-editor"; this is built-in!
+```
+
+Happy completion!
+
+### Supported shells
+
+TabCompletion supports Bash, and Zsh with bashcompinit.
+
+Note that a recent version of Zsh is required - the Ubuntu 16.04 standard version has a bug that breaks bash-compatible completion.
+
+### More complex use cases
+
+For a description of the more complex use cases, including edge cases and error handling, see the [wiki](https://github.com/saveriomiroddi/simple_scripting/wiki/SimpleScripting::TabCompletion-Guide).
 
 ## SimpleScripting::Argv
 
-`SS::A` is a module which acts as frontend to the standard Option Parser library (`optparse`), giving a very convenient format for specifying the arguments. `SS::A` also generates the help.
+`Argv` is a module which acts as frontend to the standard Option Parser library (`optparse`), giving a very convenient format for specifying the arguments. `Argv` also generates the help.
 
 This is a definition example:
 
@@ -76,7 +148,7 @@ For the guide, see the [wiki page](https://github.com/saveriomiroddi/simple_scri
 
 ## SimpleScripting::Configuration
 
-`SS::C` is a module which acts as frontend to the ParseConfig gem (`parseconfig`), giving compact access to the configuration and its values, and adding a few helpers for common tasks.
+`Configuration` is a module which acts as frontend to the ParseConfig gem (`parseconfig`), giving compact access to the configuration and its values, and adding a few helpers for common tasks.
 
 Say one writes a script (`foo_my_bar.rb`), with a corresponding (`$HOME/.foo_my_bar`) configuration, which contains:
 
@@ -88,7 +160,7 @@ Say one writes a script (`foo_my_bar.rb`), with a corresponding (`$HOME/.foo_my_
     [a_group]
     group_key=baz
 
-This is the workflow and functionality offered by `SS::C`:
+This is the workflow and functionality offered by `Configuration`:
 
     require 'simple_scripting/configuration'
 
@@ -115,6 +187,5 @@ See the [wiki](https://github.com/saveriomiroddi/simple_scripting/wiki) for addi
 
 [GV img]: https://badge.fury.io/rb/simple_scripting.png
 [BS img]: https://travis-ci.org/saveriomiroddi/simple_scripting.svg?branch=master
-[DS img]: https://gemnasium.com/saveriomiroddi/simple_scripting.png
 [CC img]: https://codeclimate.com/github/saveriomiroddi/simple_scripting.png
 [CS img]: https://coveralls.io/repos/saveriomiroddi/simple_scripting/badge.png?branch=master

data/lib/simple_scripting/argv.rb

@@ -4,32 +4,57 @@ module SimpleScripting
 
   module Argv
 
-    class ExitError < StandardError; end
+    # The fact that the following errors don't descend from OptionParser::InvalidOption is somewhat
+    # annoying, however, there should be no practical problem.
+    #
+    class InvalidCommand < StandardError; end
+    class ArgumentError < StandardError; end
+
+    class ExitWithCommandsHelpPrinting < Struct.new(:commands_definition)
+      # Note that :long_help is not used.
+      def print_help(output, long_help)
+        output.puts "Valid commands:", "", "  " + commands_definition.keys.join(', ')
+      end
+    end
+
+    class ExitWithArgumentsHelpPrinting < Struct.new(:commands_stack, :args, :parser_opts_copy)
+      def print_help(output, long_help)
+        parser_opts_help = parser_opts_copy.to_s
+
+        if commands_stack.size > 0
+          parser_opts_help = parser_opts_help.sub!('[options]', commands_stack.join(' ') + ' [options]')
+        end
+
+        if args.size > 0
+          args_display = args.map { |name, mandatory| mandatory ? "<#{ name }>" : "[<#{ name }>]" }.join(' ')
+          parser_opts_help = parser_opts_help.sub!(/^(Usage: .*)/) { |text| "#{text} #{args_display}" }
+        end
+
+        output.puts parser_opts_help
+        output.puts "", long_help if long_help
+      end
+    end
 
     extend self
 
-    def decode(*params_definition, arguments: ARGV, long_help: nil, output: $stdout)
+    def decode(*params_definition, arguments: ARGV, long_help: nil, auto_help: true, output: $stdout)
       # WATCH OUT! @long_help can also be set in :decode_command!. See issue #17.
       #
       @long_help = long_help
-      @output = output
 
-      if params_definition.first.is_a?(Hash)
-        decode_command!(params_definition, arguments)
-      else
-        decode_arguments!(params_definition, arguments)
+      exit_data = catch(:exit) do
+        if params_definition.first.is_a?(Hash)
+          return decode_command!(params_definition, arguments, auto_help)
+        else
+          return decode_arguments!(params_definition, arguments, auto_help)
+        end
       end
-    rescue ExitError
-      # return nil, to be used with the 'decode(...) || exit' pattern
-    ensure
-      # Clean up the instance variables.
-      #
-      # There is a balance to strike between instance variables, and local variables
-      # passed around. One of the options, which is this case, is to set and instance
-      # variables only these two, which are constant.
 
+      exit_data.print_help(output, @long_help)
+
+      nil # to be used with the 'decode(...) || exit' pattern
+    ensure
       @long_help = nil
-      @output = nil
     end
 
     private
@@ -40,7 +65,7 @@ module SimpleScripting
     #
     #   [{"command1"=>["arg1", {:long_help=>"This is the long help."}], "command2"=>["arg2"]}]
     #
-    def decode_command!(params_definition, arguments, commands_stack=[])
+    def decode_command!(params_definition, arguments, auto_help, commands_stack=[])
       commands_definition = params_definition.first
 
       # Set the `command` variable only after; in the case where we print the help, this variable
@@ -48,8 +73,19 @@ module SimpleScripting
       #
       command_for_check = arguments.shift
 
+      # Note that `--help` is baked into OptParse, so without a workaround, we need to always include
+      # it.
+      #
       if command_for_check == '-h' || command_for_check == '--help'
-        print_optparse_commands_help(nil, commands_definition)
+        if auto_help
+          throw :exit, ExitWithCommandsHelpPrinting.new(commands_definition)
+        else
+          # This is tricky. Since the common behavior of `--help` is to trigger an unconditional
+          # help, it's not clear what to do with other tokens. For simplicity, we just return
+          # this flag.
+          #
+          return { help: true }
+        end
       end
 
       command = command_for_check
@@ -57,13 +93,13 @@ module SimpleScripting
 
       case command_params_definition
       when nil
-        print_optparse_commands_help(command, commands_definition)
+        raise InvalidCommand.new("Invalid command: #{command}")
       when Hash
         commands_stack << command
 
         # Nested case! Decode recursively
         #
-        decode_command!([command_params_definition], arguments, commands_stack)
+        decode_command!([command_params_definition], arguments, auto_help, commands_stack)
       else
         commands_stack << command
 
@@ -74,12 +110,12 @@ module SimpleScripting
 
         [
           compose_returned_commands(commands_stack),
-          decode_arguments!(command_params_definition, arguments, commands_stack),
+          decode_arguments!(command_params_definition, arguments, auto_help, commands_stack),
         ]
       end
     end
 
-    def decode_arguments!(params_definition, arguments, commands_stack=[])
+    def decode_arguments!(params_definition, arguments, auto_help, commands_stack=[])
       result           = {}
       parser_opts_copy = nil  # not available outside the block
       args             = {}   # { 'name' => mandatory? }
@@ -92,12 +128,24 @@ module SimpleScripting
           when String
             process_argument_definition!(param_definition, args)
           else
+            # This is an error in the params definition, so it doesn't follow the user error/help
+            # workflow.
+            #
             raise "Unrecognized value: #{param_definition}"
           end
         end
 
+        # See --help note in :decode_command!.
+        #
         parser_opts.on('-h', '--help', 'Help') do
-          print_optparse_arguments_help(commands_stack, args, parser_opts_copy)
+          if auto_help
+            throw :exit, ExitWithArgumentsHelpPrinting.new(commands_stack, args, parser_opts_copy)
+          else
+            # Needs to be better handled. When help is required, generally, it trumps the
+            # correctness of the rest of the options/arguments.
+            #
+            result[:help] = true
+          end
         end
 
         parser_opts_copy = parser_opts
@@ -146,7 +194,7 @@ module SimpleScripting
       # Mandatory argument
       if args.fetch(first_arg_name.to_sym)
         if arguments.empty?
-          print_optparse_arguments_help(commands_stack, args, parser_opts_copy)
+          raise ArgumentError.new("Missing mandatory argument(s)")
         else
           name = args.keys.first[1..-1].to_sym
 
@@ -163,43 +211,17 @@ module SimpleScripting
     def process_regular_argument!(arguments, result, commands_stack, args, parser_opts_copy)
       min_args_size = args.count { |_, mandatory| mandatory }
 
-      case arguments.size
-      when (min_args_size .. args.size)
+      if arguments.size < min_args_size
+        raise ArgumentError.new("Missing mandatory argument(s)")
+      elsif arguments.size > args.size
+        raise ArgumentError.new("Too many arguments")
+      else
         arguments.zip(args) do |value, (name, _)|
           result[name] = value
         end
-      else
-        print_optparse_arguments_help(commands_stack, args, parser_opts_copy)
       end
     end
 
-    # HELP #################################################
-
-    def print_optparse_commands_help(command, commands_definition)
-      @output.print "Invalid command. " if command
-      @output.puts "Valid commands:", "", "  " + commands_definition.keys.join(', ')
-
-      raise ExitError
-    end
-
-    def print_optparse_arguments_help(commands_stack, args, parser_opts_copy)
-      parser_opts_help = parser_opts_copy.to_s
-
-      if commands_stack.size > 0
-        parser_opts_help = parser_opts_help.sub!('[options]', commands_stack.join(' ') + ' [options]')
-      end
-
-      if args.size > 0
-        args_display = args.map { |name, mandatory| mandatory ? "<#{ name }>" : "[<#{ name }>]" }.join(' ')
-        parser_opts_help = parser_opts_help.sub!(/^(Usage: .*)/) { |text| "#{text} #{args_display}" }
-      end
-
-      @output.puts parser_opts_help
-      @output.puts "", @long_help if @long_help
-
-      raise ExitError
-    end
-
     # HELPERS ##############################################
 
     def compose_returned_commands(commands_stack)

data/lib/simple_scripting/tab_completion.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative 'tab_completion/commandline_processor'
+
+module SimpleScripting
+
+  # The naming of each of the the commandline units is not standard, therefore we establish the
+  # following arbitrary, but consistent, naming:
+  #
+  #     executable --option option_parameter argument
+  #
+  # The commandline is divided into words, as Bash would split them. All the words, except the
+  # executable, compose an array that we call `argv` (as Ruby would do).
+  #
+  # We define each {option name => value} or {argument name => value} as `pair`.
+  #
+  # In the context of a pair, each pair is composed of a `key` and a `value`.
+  #
+  class TabCompletion
+
+    def initialize(switches_definition, output: $stdout)
+      @switches_definition = switches_definition
+      @output = output
+    end
+
+    # Currently, any completion suffix is ignored and stripped.
+    #
+    def complete(execution_target, source_commandline=ENV.fetch('COMP_LINE'), cursor_position=ENV.fetch('COMP_POINT').to_i)
+      commandline_processor = CommandlineProcessor.process_commandline(source_commandline, cursor_position, @switches_definition)
+
+      if commandline_processor.completing_an_option?
+        complete_option(commandline_processor, execution_target)
+      elsif commandline_processor.parsing_error?
+        return
+      else # completing_a_value?
+        complete_value(commandline_processor, execution_target)
+      end
+    end
+
+    private
+
+    #############################################
+    # Completion!
+    #############################################
+
+    def complete_option(commandline_processor, execution_target)
+      all_switches = @switches_definition.select { |definition| definition.is_a?(Array) }.map { |definition| definition[1][/^--\S+/] }
+
+      matching_switches = all_switches.select { |switch| switch.start_with?(commandline_processor.completing_word_prefix) }
+
+      output_entries(matching_switches)
+    end
+
+    def complete_value(commandline_processor, execution_target)
+      key, value_prefix, value_suffix, other_pairs = commandline_processor.parsed_pairs
+
+      selected_entries = execution_target.send(key, value_prefix, value_suffix, other_pairs)
+
+      output_entries(selected_entries)
+    end
+
+    #############################################
+    # Helpers
+    #############################################
+
+    def output_entries(entries)
+      @output.print entries.join("\n")
+    end
+  end
+
+end

data/lib/simple_scripting/tab_completion/commandline_processor.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+require_relative '../argv'
+
+module SimpleScripting
+
+  class TabCompletion
+
+    class CommandlineProcessor < Struct.new(:processed_argv, :cursor_marker, :switches_definition)
+
+      # Arbitrary; can be anything (except an empty string).
+      BASE_CURSOR_MARKER = "<tab>"
+
+      OPTIONS_TERMINATOR = "--"
+      LONG_OPTIONS_PREFIX = "--"
+
+      def self.process_commandline(source_commandline, cursor_position, switches_definition)
+        # An input string with infinite "<tabN>" substrings will cause an infinite cycle (hehe).
+        0.upto(Float::INFINITY) do |i|
+          cursor_marker = BASE_CURSOR_MARKER.sub(">", "#{i}>")
+
+          if !source_commandline.include?(cursor_marker)
+            commandline_with_marker = source_commandline[0...cursor_position] + cursor_marker + source_commandline[cursor_position..-1].to_s
+
+            # Remove the executable.
+            processed_argv = Shellwords.split(commandline_with_marker)[1..-1]
+
+            return new(processed_argv, cursor_marker, switches_definition)
+          end
+        end
+      end
+
+      # We're abstracted from the commandline, with this exception. This is because while an option
+      # is being completed, the decoder would not recognize the key.
+      #
+      def completing_an_option?
+        processed_argv[marked_word_position].start_with?(LONG_OPTIONS_PREFIX) && marked_word_position < options_terminator_position
+      end
+
+      def parsing_error?
+        parse_argv.nil?
+      end
+
+      def completing_word_prefix
+        word = processed_argv[marked_word_position]
+
+        # Regex alternative: [/\A(.*?)#{cursor_marker}/m, 1]
+        word[0, word.index(cursor_marker)]
+      end
+
+      # Returns key, value prefix (before marker), value suffix (after marker), other_pairs
+      #
+      def parsed_pairs
+        parsed_pairs = parse_argv || raise("Parsing error")
+
+        key, value = parsed_pairs.detect do |_, value|
+          !boolean?(value) && value.include?(cursor_marker)
+        end
+
+        # Impossible case, unless there is a programmatic error.
+        #
+        key || raise("Guru meditation! (#{self.class}##{__method__}:#{__LINE__})")
+
+        value_prefix, value_suffix = value.split(cursor_marker)
+
+        parsed_pairs.delete(key)
+
+        [key, value_prefix || "", value_suffix || "", parsed_pairs]
+      end
+
+      private
+
+      def marked_word_position
+        processed_argv.index { |word| word.include?(cursor_marker) }
+      end
+
+      # Returns Float::INFINITY when there is no options terminator.
+      #
+      def options_terminator_position
+        processed_argv.index(OPTIONS_TERMINATOR) || Float::INFINITY
+      end
+
+      #############################################
+      # Helpers
+      #############################################
+
+      def parse_argv
+        # We need to convert all the arguments to optional, otherwise it's not possible to
+        # autocomplete arguments when not all the mandatory ones are not typed yet, eg:
+        #
+        #   `my_command <tab>` with definition ['mand1', 'mand2']
+        #
+        adapted_switches_definition = switches_definition.dup
+
+        adapted_switches_definition.each_with_index do |definition, i|
+          adapted_switches_definition[i] = "[#{definition}]" if definition.is_a?(String) && !definition.start_with?('[')
+        end
+
+        SimpleScripting::Argv.decode(*adapted_switches_definition, arguments: processed_argv.dup, auto_help: false)
+      rescue Argv::InvalidCommand, Argv::ArgumentError, OptionParser::InvalidOption
+        # OptionParser::InvalidOption: see case "-O<tab>" in test suite.
+
+        # return nil
+      end
+
+      # For the lulz.
+      #
+      def boolean?(value)
+        !!value == value
+      end
+
+    end # CommandlineProcessor
+
+  end # TabCompletion
+
+end # SimpleScripting

data/lib/simple_scripting/version.rb

@@ -1,5 +1,5 @@
 module SimpleScripting
 
-  VERSION = "0.9.4"
+  VERSION = "0.10.0"
 
 end

data/simple_scripting.gemspec

@@ -8,8 +8,9 @@ Gem::Specification.new do |s|
   s.name        = "simple_scripting"
   s.version     = SimpleScripting::VERSION
   s.platform    = Gem::Platform::RUBY
+  s.required_ruby_version = '>= 2.3.0'
   s.authors     = ["Saverio Miroddi"]
-  s.date        = "2018-01-26"
+  s.date        = "2018-07-26"
   s.email       = ["saverio.pub2@gmail.com"]
   s.homepage    = "https://github.com/saveriomiroddi/simple_scripting"
   s.summary     = "Library for simplifying some typical scripting functionalities."
@@ -20,7 +21,6 @@ Gem::Specification.new do |s|
 
   s.add_development_dependency "rake",        "~> 12.0"
   s.add_development_dependency "rspec",       "~> 3.6"
-  s.add_development_dependency 'coveralls',   "~> 0.8.21"
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- spec/*`.split("\n")

data/spec/helpers/tab_completion_custom_rspec_matchers.rb

@@ -0,0 +1,55 @@
+require 'stringio'
+
+# Custom matchers for the tab completion test suite.
+#
+# Require :subject and :output_buffer to be defined/accessible.
+#
+# The matchers are simplistic (but still adequate); the (most) appropriate choice would be
+# [diffable matchers](https://relishapp.com/rspec/rspec-expectations/v/3-6/docs/custom-matchers/define-diffable-matcher)
+#
+# Note that the semantic of the expected value is different from the standard rspec one, since we
+# process it, therefore, we need to use intermediate instance variables.
+#
+module TabCompletionCustomRSpecMatchers
+
+  extend RSpec::Matchers::DSL
+
+  # Doesn't matter in this context.
+  #
+  PHONY_EXECUTABLE = '/path/to/executable'
+
+  matcher :complete_with do |expected_entries|
+    match do |symbolic_commandline_options|
+      commandline = "#{PHONY_EXECUTABLE} #{symbolic_commandline_options}"
+      cursor_position = commandline.index("<tab>")
+      commandline = commandline.sub("<tab>", "")
+
+      subject.complete(execution_target, commandline, cursor_position)
+
+      @actual_output = output_buffer.string
+      expected_output = expected_entries.join("\n")
+
+      expect(@actual_output).to eql(expected_output)
+    end
+
+    failure_message do |actual|
+      actual_entries = @actual_output.split("\n")
+
+      "#{actual} listed #{actual_entries} instead of #{expected}"
+    end
+  end
+
+  matcher :not_complete do
+    match do |symbolic_commandline_options|
+      expect(symbolic_commandline_options).to complete_with([])
+    end
+
+    failure_message do |actual|
+      @actual_output = output_buffer.string
+      actual_entries = @actual_output.split("\n")
+
+      "#{actual} listed #{actual_entries} instead of no entries"
+    end
+  end
+
+end # TabCompletionCustomRSpecMatchers

data/spec/simple_scripting/argv_spec.rb

@@ -23,27 +23,59 @@ describe SimpleScripting::Argv do
       output:     output_buffer,
     ]}
 
-    it 'should implement the help' do
-      decoder_params.last[:arguments] = ['-h']
-
-      return_value = described_class.decode(*decoder_params)
-
-      expected_output = %Q{\
-Usage: rspec [options] <mandatory> [<optional>]
-    -a
-    -b                               "-b" description
-    -c, --c-switch
-    -d, --d-switch                   "-d" description
-    -e, --e-switch VALUE
-    -f, --f-switch VALUE             "-f" description
-    -h, --help                       Help
-
-This is the long help!
-}
-
-      expect(output_buffer.string).to eql(expected_output)
-      expect(return_value).to be(nil)
-    end
+    context 'help' do
+
+      it 'should print help automatically by default' do
+        decoder_params.last[:arguments] = ['-h']
+
+        return_value = described_class.decode(*decoder_params)
+
+        expected_output = <<~OUTPUT
+          Usage: rspec [options] <mandatory> [<optional>]
+              -a
+              -b                               "-b" description
+              -c, --c-switch
+              -d, --d-switch                   "-d" description
+              -e, --e-switch VALUE
+              -f, --f-switch VALUE             "-f" description
+              -h, --help                       Help
+
+          This is the long help!
+        OUTPUT
+
+        expect(output_buffer.string).to eql(expected_output)
+        expect(return_value).to be(nil)
+      end
+
+      it 'should not interpret the --help argument, and not print the help, on auto_help: false' do
+        decoder_params.last.merge!(
+          arguments: ['--help', 'm_arg'],
+          auto_help: false
+        )
+
+        actual_result = described_class.decode(*decoder_params)
+
+        expected_result = {
+          help: true,
+          mandatory: 'm_arg',
+        }
+
+        expect(output_buffer.string).to eql('')
+        expect(actual_result).to eql(expected_result)
+      end
+
+      it "should check all the options/arguments when --help is passed, raising an error when they're not correct" do
+        decoder_params.last.merge!(
+          arguments: ['--help'],
+          auto_help: false
+        )
+
+        decoding = -> { described_class.decode(*decoder_params) }
+
+        expect(decoding).to raise_error(SimpleScripting::Argv::ArgumentError, "Missing mandatory argument(s)")
+      end
+
+    end # context 'help'
 
     it "should implement basic switches and arguments (all set)" do
       decoder_params.last[:arguments] = ['-a', '-b', '-c', '-d', '-ev_swt', '-fv_swt', 'm_arg', 'o_arg']
@@ -76,7 +108,62 @@ This is the long help!
       expect(actual_result).to eql(expected_result)
     end
 
-  end
+    context "multiple optional arguments" do
+
+      let(:decoder_params) {[
+        '[optional1]',
+        '[optional2]',
+        output:     output_buffer,
+      ]}
+
+      it "should correctly decode a single argument passed" do
+        decoder_params.last[:arguments] = ['o_arg1']
+
+        actual_result = described_class.decode(*decoder_params)
+
+        expected_result = {
+          optional1: 'o_arg1',
+        }
+
+        expect(actual_result).to eql(expected_result)
+      end
+
+      it "should correctly decode all arguments passed" do
+        decoder_params.last[:arguments] = ['o_arg1', 'o_arg2']
+
+        actual_result = described_class.decode(*decoder_params)
+
+        expected_result = {
+          optional1: 'o_arg1',
+          optional2: 'o_arg2',
+        }
+
+        expect(actual_result).to eql(expected_result)
+      end
+
+    end
+
+    context "error handling" do
+
+      it "should raise an error when mandatory arguments are missing" do
+        decoder_params.last[:arguments] = []
+
+        decoding = -> { described_class.decode(*decoder_params) }
+
+        expect(decoding).to raise_error(SimpleScripting::Argv::ArgumentError, "Missing mandatory argument(s)")
+      end
+
+      it "should print an error and the help when there are too many arguments" do
+        decoder_params.last[:arguments] = ['arg1', 'arg2', 'excessive_arg']
+
+        decoding = -> { described_class.decode(*decoder_params) }
+
+        expect(decoding).to raise_error(SimpleScripting::Argv::ArgumentError, "Too many arguments")
+      end
+
+    end # context "error handling"
+
+  end # describe 'Basic functionality'
 
   describe 'Varargs' do
 
@@ -99,17 +186,19 @@ This is the long help!
         expect(actual_result).to eql(expected_result)
       end
 
-      it "should exit when they are not specified" do
-        decoder_params.last[:arguments] = []
+      context "error handling" do
 
-        actual_result = described_class.decode(*decoder_params)
+        it "should exit when they are not specified" do
+          decoder_params.last[:arguments] = []
 
-        expected_result = nil
+          decoding = -> { described_class.decode(*decoder_params) }
 
-        expect(actual_result).to eql(expected_result)
-      end
+          expect(decoding).to raise_error(SimpleScripting::Argv::ArgumentError, "Missing mandatory argument(s)")
+        end
 
-    end
+      end # context "error handling"
+
+    end # describe '(mandatory)'
 
     describe '(optional)' do
 
@@ -142,9 +231,9 @@ This is the long help!
         expect(actual_result).to eql(expected_result)
       end
 
-    end
+    end # describe '(optional)'
 
-  end
+  end # describe 'Varargs'
 
   describe 'Commands' do
 
@@ -171,50 +260,86 @@ This is the long help!
         expect(actual_result).to eql(expected_result)
       end
 
-      it 'print a message on wrong command' do
-        decoder_params[:arguments] = ['pizza']
+      context "error handling" do
 
-        described_class.decode(decoder_params)
+        it "should raise an error on invalid command" do
+          decoder_params[:arguments] = ['pizza']
 
-        expected_output = %Q{\
-Invalid command. Valid commands:
+          decoding = -> { described_class.decode(decoder_params) }
 
-  command1, command2
-}
+          expect(decoding).to raise_error(SimpleScripting::Argv::InvalidCommand, "Invalid command: pizza")
+        end
 
-        expect(output_buffer.string).to eql(expected_output)
-      end
+      end # context "error handling"
 
-      it 'should implement the commands help' do
-        decoder_params[:arguments] = ['-h']
+      context "help" do
 
-        described_class.decode(decoder_params)
+        it 'should implement the commands help' do
+          decoder_params[:arguments] = ['-h']
 
-        expected_output = %Q{\
-Valid commands:
+          described_class.decode(decoder_params)
 
-  command1, command2
-}
+          expected_output = <<~OUTPUT
+            Valid commands:
 
-        expect(output_buffer.string).to eql(expected_output)
-      end
+              command1, command2
+          OUTPUT
 
-      it "should display the command given command's help" do
-        decoder_params[:arguments] = ['command1', '-h']
-$a = true
-        described_class.decode(decoder_params)
+          expect(output_buffer.string).to eql(expected_output)
+        end
 
-        expected_output = %Q{\
-Usage: rspec command1 [options] <arg1>
-    -h, --help                       Help
+        it "should display the command given command's help" do
+          decoder_params[:arguments] = ['command1', '-h']
 
-This is the long help.
-}
+          described_class.decode(decoder_params)
 
-        expect(output_buffer.string).to eql(expected_output)
-      end
+          expected_output = <<~OUTPUT
+            Usage: rspec command1 [options] <arg1>
+                -h, --help                       Help
 
-    end
+            This is the long help.
+          OUTPUT
+
+          expect(output_buffer.string).to eql(expected_output)
+        end
+
+        context 'auto_help: false' do
+
+          it 'should not interpret the --help argument, and not print the help' do
+            decoder_params.merge!(
+              arguments: ['-h'],
+              auto_help: false,
+            )
+
+            actual_result = described_class.decode(decoder_params)
+
+            expected_result = {
+              help: true,
+            }
+
+            expect(actual_result).to eql(expected_result)
+          end
+
+          it 'should ignore and not return all the other arguments' do
+            decoder_params.merge!(
+              arguments: ['-h', 'pizza'],
+              auto_help: false,
+            )
+
+            actual_result = described_class.decode(decoder_params)
+
+            expected_result = {
+              help: true,
+            }
+
+            expect(actual_result).to eql(expected_result)
+          end
+
+        end # context 'auto_help: false'
+
+      end # context 'help'
+
+    end # describe 'regular case'
 
     describe 'Nested commands' do
 
@@ -259,11 +384,11 @@ This is the long help.
 
         actual_result = described_class.decode(decoder_params)
 
-        expected_output = "\
-Valid commands:
+        expected_output = <<~OUTPUT
+          Valid commands:
 
-  nested1a, nested1b
-"
+            nested1a, nested1b
+        OUTPUT
 
         expect(output_buffer.string).to eql(expected_output)
       end
@@ -273,33 +398,35 @@ Valid commands:
 
         actual_result = described_class.decode(decoder_params)
 
-        expected_output = "\
-Usage: rspec command1 nested1a [options] <arg1>
-    -h, --help                       Help
+        expected_output = <<~OUTPUT
+          Usage: rspec command1 nested1a [options] <arg1>
+              -h, --help                       Help
 
-nested1a long help.
-"
+          nested1a long help.
+        OUTPUT
 
         expect(output_buffer.string).to eql(expected_output)
       end
-    end
+    end # describe 'Nested commands'
 
-    describe 'No argv case' do
+  end # describe 'Commands'
 
-      let(:decoder_params) {{
-        output:     output_buffer,
-      }}
+  # Special case.
+  #
+  describe 'No definitions given' do
 
-      it 'should avoided options being interpreted as definitions' do
-        decoder_params[:arguments] = ['pizza']
+    let(:decoder_params) {{
+      output:     output_buffer,
+    }}
 
-        actual_result = described_class.decode(decoder_params)
+    it 'should avoid options being interpreted as definitions' do
+      decoder_params[:arguments] = ['pizza']
 
-        expect(actual_result).to be(nil)
-      end
+      decoding = -> { described_class.decode(decoder_params) }
 
+      expect(decoding).to raise_error(SimpleScripting::Argv::ArgumentError, "Too many arguments")
     end
 
-  end
+  end # describe 'No definitions given'
 
 end

data/spec/simple_scripting/tab_completion_spec.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require_relative '../../lib/simple_scripting/tab_completion.rb'
+
+describe SimpleScripting::TabCompletion do
+
+  include TabCompletionCustomRSpecMatchers
+
+  let(:output_buffer) {
+    StringIO.new
+  }
+
+  let(:switches_definition) {
+    [
+      ["-o", "--opt1 ARG"],
+      ["-O", "--opt2"],
+      "arg1",               # this and the following are internally converted to optional, as
+      "arg2",               # according to the Argv spec, without brackets they are mandatory.
+    ]
+  }
+
+  let(:execution_target) {
+    # Simplistic implementation. In real world, regex are not to be used this way, for multiple
+    # reasons.
+    #
+    Class.new do
+      def opt1(prefix, suffix, context)
+        %w(opt1v1 _opt1v2).select { |entry| entry =~ /^#{prefix}#{suffix}/ }
+      end
+
+      def arg1(prefix, suffix, context)
+        # A value starting with space is valid.
+        #
+        ['arg1v1', 'arg1v2', '_arg1v3', ' _argv1spc'].select { |entry| entry =~ /^#{prefix}#{suffix}/ }
+      end
+
+      def arg2(prefix, suffix, context)
+        # A value starting with minus is valid.
+        #
+        %w(arg2v1 arg2v2 --arg2v3).select { |entry| entry =~ /^#{prefix}#{suffix}/ }
+      end
+    end.new
+  }
+
+  subject { described_class.new(switches_definition, output: output_buffer) }
+
+  context "with a correct configuration" do
+
+    context "standard cases" do
+
+      # Note that the conversion of mandatory to optional argument is defined by most of the cases.
+      #
+      STANDARD_CASES = {
+        "<tab>"             => ["arg1v1", "arg1v2", "_arg1v3", " _argv1spc"],
+        "a<tab>"            => %w(arg1v1 arg1v2),
+        "--opt2 <tab>"      => ["arg1v1", "arg1v2", "_arg1v3", " _argv1spc"],
+        "-- <tab>"          => ["arg1v1", "arg1v2", "_arg1v3", " _argv1spc"],
+
+        "a <tab>"           => %w(arg2v1 arg2v2 --arg2v3),
+        "a -- --<tab>"      => %w(--arg2v3),
+        "-- --aaa <tab>"    => %w(arg2v1 arg2v2 --arg2v3),
+
+        "--<tab>"           => %w(--opt1 --opt2),
+        "--<tab> a"         => %w(--opt1 --opt2),
+        "--<tab> -- a"      => %w(--opt1 --opt2),
+        "--<tab> -- b"      => %w(--opt1 --opt2),
+        "--<tab> --xyz"     => %w(--opt1 --opt2),
+        "--opt1 <tab> a"    => %w(opt1v1 _opt1v2),
+        "--opt1 o<tab> a"   => %w(opt1v1),
+
+        "-o<tab>"           => %w(opt1v1 _opt1v2),
+        "-o <tab>"          => %w(opt1v1 _opt1v2),
+        "-o -O <tab>"       => ["arg1v1", "arg1v2", "_arg1v3", " _argv1spc"],
+        "-O <tab>"          => ["arg1v1", "arg1v2", "_arg1v3", " _argv1spc"],
+      }
+
+      STANDARD_CASES.each do |symbolic_commandline_options, expected_entries|
+        it "should output the entries for #{symbolic_commandline_options.inspect}" do
+          expect(symbolic_commandline_options).to complete_with(expected_entries)
+        end
+      end
+
+    end # context "standard cases"
+
+    context "suffix management" do
+
+      SUFFIX_CASES = {
+        "arg1<tab>v"        => %w(arg1v1 arg1v2), # the execution target of the test suite doesn't
+        "arg1<tab>x"        => %w(),              # ignore the suffix; programmer-defined
+
+        "--o<tab>p"         => %w(--opt1 --opt2), # options ignore the suffix (like bash); can't be
+        "--o<tab>x"         => %w(--opt1 --opt2), # currently changed by the programmer.
+      }
+
+      SUFFIX_CASES.each do |symbolic_commandline_options, expected_entries|
+        it "should output the entries for #{symbolic_commandline_options.inspect}, ignoring the suffix" do
+          expect(symbolic_commandline_options).to complete_with(expected_entries)
+        end
+      end
+
+    end # context "suffix management"
+
+    context "escaped cases" do
+
+      ESCAPED_CASES = {
+        "\ <tab>"           => [" _argv1spc"],
+        '\-<tab>'           => %w(),                       # this is the result of typing `command "\-<tab>`
+        'a \-<tab>'         => %w(--arg2v3),
+      }
+
+      ESCAPED_CASES.each do |symbolic_commandline_options, _|
+        it "should output the entries for #{symbolic_commandline_options.inspect}"
+      end
+
+    end # context "escaped cases"
+
+    it "should support multiple values for an option"
+
+    it "should keep parsing also when --help is passed" do
+      expect("--help a<tab>").to complete_with(%w(arg1v1 arg1v2))
+    end
+
+  end # context "with a correct configuration"
+
+  context "with an incorrect configuration" do
+
+    INCORRECT_CASES = [
+      "a b <tab>",        # too many args
+      "-O<tab>",          # no values for this option
+    ]
+
+    INCORRECT_CASES.each do |symbolic_commandline_options|
+      it "should not output any entries for #{symbolic_commandline_options.inspect}" do
+        expect(symbolic_commandline_options).to not_complete
+      end
+    end
+
+  end # context "with an incorrect configuration"
+
+end # describe SimpleScripting::TabCompletion

data/spec/spec_helper.rb

@@ -49,3 +49,5 @@ RSpec.configure do |config|
   # triggering implicit auto-inclusion in groups with matching metadata.
   config.shared_context_metadata_behavior = :apply_to_host_groups
 end
+
+require_relative 'helpers/tab_completion_custom_rspec_matchers'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simple_scripting
 version: !ruby/object:Gem::Version
-  version: 0.9.4
+  version: 0.10.0
 platform: ruby
 authors:
 - Saverio Miroddi
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-01-26 00:00:00.000000000 Z
+date: 2018-07-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: parseconfig
@@ -52,20 +52,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.6'
-- !ruby/object:Gem::Dependency
-  name: coveralls
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.8.21
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.8.21
 description: Simplifies options parsing and configuration loading.
 email:
 - saverio.pub2@gmail.com
@@ -75,6 +61,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".rspec"
+- ".simplecov"
 - ".travis.yml"
 - Gemfile
 - Gemfile.lock
@@ -84,11 +71,15 @@ files:
 - lib/simple_scripting/argv.rb
 - lib/simple_scripting/configuration.rb
 - lib/simple_scripting/configuration/value.rb
+- lib/simple_scripting/tab_completion.rb
+- lib/simple_scripting/tab_completion/commandline_processor.rb
 - lib/simple_scripting/version.rb
 - simple_scripting.gemspec
+- spec/helpers/tab_completion_custom_rspec_matchers.rb
 - spec/simple_scripting/argv_spec.rb
 - spec/simple_scripting/configuration/value_spec.rb
 - spec/simple_scripting/configuration_spec.rb
+- spec/simple_scripting/tab_completion_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/saveriomiroddi/simple_scripting
 licenses:
@@ -102,7 +93,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -110,12 +101,14 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.14
+rubygems_version: 2.6.13
 signing_key: 
 specification_version: 4
 summary: Library for simplifying some typical scripting functionalities.
 test_files:
+- spec/helpers/tab_completion_custom_rspec_matchers.rb
 - spec/simple_scripting/argv_spec.rb
 - spec/simple_scripting/configuration/value_spec.rb
 - spec/simple_scripting/configuration_spec.rb
+- spec/simple_scripting/tab_completion_spec.rb
 - spec/spec_helper.rb