consoler 1.0.3 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 317d28b9a15f0ea07c01410191cac9d0d59a41dd
-  data.tar.gz: f9a363ba2b596a02df673c1600441f2f6d7b7010
+SHA256:
+  metadata.gz: 4ce3b8eca4b35ef9a82bb1ac0886aae0f49614dca29721c06e20bb94fdfc3d3b
+  data.tar.gz: addc213497a379b6d68fe844df9374bb93c48bb38ac40e7174343a50463e6a5a
 SHA512:
-  metadata.gz: b42c0a91ed2df03ef7d76796f1da5e986782d2d0415a14167159f34b10b76eb939e97f378109328bdd768c7f234607907871bcd03e2e5ad097180c7edaf385c6
-  data.tar.gz: df6627a850424d6053c4525bea35014c1c8ec42bbe9cbe43f981119b535a747af53c4130dec92242309d36891c9e7368450c49838c37c55ea2662a682582fb26
+  metadata.gz: 15b94900e561a891e02f88d57f43b0614abb76b6ed75e59810d5a1ded0945874e71e1ceafacc320fd725be1ad470895bfc912f7f853601c45ce0ffc374ffd8a7
+  data.tar.gz: 0305b071d1b40ebd593d0cd81795787898d9081e2cbebee5636b406136ecbb325facade699426202e18bb6e4a39fc20c6760d3b18a90af33cb308e3d1141b4e2

data/.github/workflows/tests.yml

@@ -0,0 +1,34 @@
+name: tests
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ['2.4', '2.5', '2.6', '2.7', '3.0']
+
+    name: Ruby ${{ matrix.ruby }}
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Set up Ruby
+        # change this to (see https://github.com/ruby/setup-ruby#versioning):
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Report Ruby version
+        run: ruby -v
+
+      - name: Run tests
+        run: bundle exec rake

data/.rubocop.yml

@@ -0,0 +1,45 @@
+AllCops:
+  TargetRubyVersion: 2.2
+
+  Exclude:
+    - 'test/**/*'
+
+# 80 is not enough these days
+Metrics/LineLength:
+  Max: 100
+
+# Not ready for 100 yet
+Metrics/ClassLength:
+  Max: 250
+
+# Not ready for 20 yet
+Metrics/MethodLength:
+  Max: 100
+
+Metrics/AbcSize:
+  Enabled: false
+
+# not ready for 10 just yet
+Metrics/CyclomaticComplexity:
+  Max: 30
+
+Metrics/BlockNesting:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+# I prefer regular if statements in some cases
+Style/IfUnlessModifier:
+  Enabled: false
+Style/GuardClause:
+  Enabled: false
+
+# `super` makes no sense in this case
+# `#respond_to_missing?` is implemented
+Style/MethodMissingSuper:
+  Enabled: false
+
+# I like the comma
+Style/TrailingCommaInArguments:
+  Enabled: false

data/README.md

@@ -1,4 +1,4 @@
-# Consoler [![Build Status](https://api.travis-ci.org/justim/consoler-rb.svg?branch=master)](https://travis-ci.org/justim/consoler-rb) [![Gem Version](https://badge.fury.io/rb/consoler.svg)](https://badge.fury.io/rb/consoler)
+# Consoler [![Gem Version](https://badge.fury.io/rb/consoler.svg)](https://badge.fury.io/rb/consoler)
 
 > Sinatra-like application builder for the console
 
@@ -9,17 +9,19 @@
 app = Consoler::Application.new description: 'A simple app'
 
 # define a command
-app.build '[--clean] output_dir' do |clean, output_dir|
+app.build '[--clean] <output_dir>' do |clean, output_dir|
   # clean contains a boolean
   clean_up if clean
 
   # output_dir contains a string
   build_project output_dir
 end
-app.run(['build', 'production', '--clean'])
+
+# run with own args
+app.run ['build', 'production', '--clean']
 
 # this does not match, nothing is executed and the usage message is printed
-app.run(['deploy', 'production'])
+app.run ['deploy', 'production']
 
 # defaults to ARGV
 app.run
@@ -30,15 +32,17 @@ app.run
 - No fiddling with `ARGV` and friends
 - Arguments filled based on their name, for easy access
 - Grouped optionals
+- Easy option aliasing
 
 ## Requirements
 
 Tests are run against multiple ruby versions (latest supported):
 
-- `2.2.x`
-- `2.3.x`
 - `2.4.x`
 - `2.5.x`
+- `2.6.x`
+- `2.7.x`
+- `3.0.x`
 
 No other requirements exist.
 
@@ -51,20 +55,20 @@ gem install consoler
 or add to your `Gemfile` for applications
 
 ```ruby
-gem 'consoler', '~> 1.0.3'
+gem 'consoler', '~> 1.3.0'
 ```
 
 or to your `.gemspec` file for gems
 
 ```ruby
 Gem::Specification.new do |spec|
-  spec.add_dependency 'consoler', '~> 1.0.3'
+  spec.add_dependency 'consoler', '~> 1.3.0'
 end
 ```
 
 ## Docs
 
-Full API documentation can the found here: http://www.rubydoc.info/github/justim/consoler-rb/
+Full API documentation can the found here: https://www.rubydoc.info/gems/consoler/1.3.0
 
 ### API
 
@@ -93,11 +97,11 @@ app.build do
 end
 
 # to add options to your command, provide a options definition as an argument
-app.build '[--clean] [--env=] [-v] output_dir' do |clean, env, v, output_dir|
+app.build '[--clean] [--env=] [-v|--verbose] <output_dir>' do |clean, env, verbose, output_dir|
   # parameters are matched based on name
   # `clean` contains a boolean
   # `env` contains a string or nil if not provided
-  # `v` contains a number, counting the times it occurred in the arguments
+  # `verbose` contains a number, counting the times it occurred in the arguments
   # `output_dir` contains a string, if needed to match this command
 end
 ```
@@ -111,23 +115,23 @@ end
 app = Consoler::Application.new
 
 # a build command
-app.build '[--clean] [--env=] [-v] output_dir' do |clean, env, v, output_dir|
-  puts 'Starting build...' if v > 0
+app.build '[--clean] [--env=] [-v|--verbose] <output_dir>' do |clean, env, verbose, output_dir|
+  puts 'Starting build...' if verbose > 0
 
   do_clean_up if clean
 
   do_build env || 'development', output_dir
 
-  puts 'Build complete' if v > 0
+  puts 'Build complete' if verbose > 0
 end
 
 # a deploy command
-app.build '[-v] [--env=]' do |env|
-  puts 'Starting deploy...' if v > 0
+app.build '[-v|--verbose] [--env=]' do |env|
+  puts 'Starting deploy...' if verbose > 0
 
   do_deploy env || 'development'
 
-  puts 'Deploy complete' if v > 0
+  puts 'Deploy complete' if verbose > 0
 end
 ```
 
@@ -137,29 +141,40 @@ _Shell commands:_
 ruby app.rb build --env production dist
 
 # deploy
-ruby app.rb deploy
+ruby app.rb deploy --verbose
+
+# or, you can use command shortcuts. this works by prefix matching and only if
+# there is one match, exact matches always have priority
+ruby app.rb b --env production dist
+ruby app.rb d --verbose
+
 ```
 
 #### Options definition
 
-| Option       | Meaning                         | Example                                |
-| ------------ | ------------------------------- | -------------------------------------- |
-| `-f`         | Short option with name `f`      | `ruby app.rb build -f`                 |
-| `--clean`    | Long option with name `clean`   | `ruby app.rb build --clean`            |
-| `output_dir` | Argument with name `output_dir` | `ruby app.rb build dist/`              |
-| `--env=`     | Long option with value          | `ruby app.rb build --env production`   |
-| `-e=`        | Short option with value         | `ruby app.rb build -e production`      |
-| `[ .. ]`     | Optional options/arguments      | `ruby app.rb build` would match `[-v]` |
+| Option          | Meaning                         | Example                                |
+| --------------- | ------------------------------- | -------------------------------------- |
+| `-f`            | Short option with name `f`      | `ruby app.rb build -f`                 |
+| `--clean`       | Long option with name `clean`   | `ruby app.rb build --clean`            |
+| `-v\|--verbose` | Alias option for `v`            | `ruby app.rb build --verbose`          |
+| `<output_dir>`  | Argument with name `output_dir` | `ruby app.rb build dist/`              |
+| `--env=`        | Long option with value          | `ruby app.rb build --env production`   |
+| `-e=`           | Short option with value         | `ruby app.rb build -e production`      |
+| `[ .. ]`        | Optional options/arguments      | `ruby app.rb build` would match `[-v]` |
 
-Optional-tokens can occur anywhere in the options, as long as they are not nested and properly closed. You can group optional parts, meaning that both options/arguments should be available or both not.
+Some notes about these options:
 
-Options and/or arguments are mandatory unless specified otherwise.
+- The `<`, `>` around the argument name a optional, but are always shown in de usage message for better legibility
+- Optional-tokens can occur anywhere in the options, as long as they are not nested and properly closed. You can group optional parts, meaning that both options/arguments should be available or both not.
+- Options and/or arguments are mandatory unless specified otherwise.
+- Aliases should be the same "type", meaning that if the original option expands an value, the alias must do as well
+- Aliases are only allowed for short and long options, with or without value and can be optional, just like regular options
 
 Grouping of optionals allows you do things like this:
 
 ```ruby
 app = Consoler::Application.new
-app.shout '[first_name last_name] [name]' do |first_name, last_name, name|
+app.shout '[<first_name> <last_name>] [<name>]' do |first_name, last_name, name|
   # by definition, `last_name` is also filled
   unless first_name.nil? then
     puts "Hello #{first_name} #{last_name}!"
@@ -172,11 +187,11 @@ end
 
 # calling with two arguments can fill the first group
 # prints "Hello John Doe!"
-app.run(['shout', 'John', 'Doe'])
+app.run ['shout', 'John', 'Doe']
 
 # calling with one argument it is not possible to fill the first group
 # prints "Hello Mr. White!"
-app.run(['shout', 'Mr. White!'])
+app.run ['shout', 'Mr. White!']
 ```
 
 #### Return types in action block
@@ -188,6 +203,8 @@ app.run(['shout', 'Mr. White!'])
 | Value       | `String` (`production`) | `nil`                 |
 | Argument    | `String` (`dist/`)      | `nil`                 |
 
+Aliased keep the properties as the original options; with a definition of `-v|--verbose` and providing `--verbose` as an argument, both `v` and `verbose` contain a number (`1` in this case). Same goes the other way around; with a definition of `--force|-f` and providing `-f` as an argument, both `force` and `f` contain a boolean (`true` in this case).
+
 #### Subapplications
 
 To make application nesting possible you can provide a complete application to a command, instead of an action block.
@@ -200,7 +217,7 @@ android = Consoler::Application.new
 android.build do; end
 
 # options are supported just like regular apps
-android.clean '--force' do; end
+android.clean '--force|-f' do; end
 
 # create an application
 app = Consoler::Application.new
@@ -245,7 +262,7 @@ app = Consoler::Application.new
 app.db db
 app.cache cache
 
-app.build '[--clean] [--env=] [-v] output_dir -- build the project' do |clean, env, v, output_dir|
+app.build '[--clean] [--env=] [-v] <output_dir> -- build the project' do |clean, env, v, output_dir|
   puts 'Starting build...' if v > 0
 
   if clean
@@ -274,10 +291,6 @@ Make the file executable with `chmod a+x app.rb`, you can now call it with `./ap
 ./app.rb
 ```
 
-### Current wish-list
-
-- Aliases, mostly to "document" short options, `-v|--verbose`
-
 ## Final notes
 
 If you like what you see, feel free to use it anyway you like. Also, don't hold back if you have suggestions/question and create an issue to let me know, and we can talk about it. And if you don't like what you see, PRs are welcome. You should probably file an issue first to make sure it's something worth doing, and the right way to do it.

data/consoler.gemspec

@@ -22,9 +22,10 @@ Gem::Specification.new do |spec|
   # build docs on install
   spec.metadata['yard.run'] = 'yri'
 
-  spec.add_development_dependency 'bundler', '~> 1.15'
-  spec.add_development_dependency 'rake', '~> 12.3.0'
+  spec.required_ruby_version = '>= 2.4'
+  spec.add_development_dependency 'bundler', '~> 2.0'
   spec.add_development_dependency 'minitest', '~> 5.11.3'
+  spec.add_development_dependency 'rake', '~> 12.3.0'
+  spec.add_development_dependency 'simplecov', '~> 0.16.1'
   spec.add_development_dependency 'yard', '~> 0.9.12'
-  spec.add_development_dependency 'simplecov', '~> 0.15.1'
 end

data/lib/consoler/application.rb

@@ -4,7 +4,6 @@ require_relative 'options'
 require_relative 'arguments'
 
 module Consoler
-
   # Consoler application
   #
   # @example A simple application
@@ -24,16 +23,31 @@ module Consoler
   #   # this does not match, nothing is executed and the usage message is printed
   #   app.run(['deploy', 'production'])
   class Application
-
     # Create a consoler application
     #
     # @param options [Hash] Options for the application
     # @option options [String] :description The description for the application (optional)
-    def initialize(options={})
+    # @option options [bool] :rescue_errors Should the application catch errors (optional)
+    def initialize(options = {})
       @description = options[:description]
+      @rescue_errors = if !options[:rescue_errors].nil? then
+                        options[:rescue_errors]
+                       else
+                         true
+                       end
       @commands = []
     end
 
+    # Accept all method_missing call
+    #
+    # We use the name as a command name, thus we accept all names
+    #
+    # @param _method_name [String] Name of the method
+    # @param _include_private [bool] Name of the method
+    def respond_to_missing?(_method_name, _include_private = false)
+      true
+    end
+
     # Register a command for this app
     #
     # @param command_name [Symbol] Name of the command
@@ -44,21 +58,21 @@ module Consoler
       action = nil
       options_def = ''
 
-      unless block.nil? then
+      unless block.nil?
         action = block
         options_def = input
 
-        if not options_def.nil? and not options_def.instance_of? String then
+        if !options_def.nil? && !options_def.instance_of?(String)
           raise 'Invalid options'
         end
       end
 
-      if input.instance_of? Consoler::Application then
+      if input.instance_of? Consoler::Application
         action = input
         options_def = ''
       end
 
-      if action.nil? then
+      if action.nil?
         raise 'Invalid subapp/block'
       end
 
@@ -66,7 +80,7 @@ module Consoler
 
       _add_command(command, options_def, action)
 
-      return nil
+      nil
     end
 
     # Run the application with a list of arguments
@@ -75,15 +89,22 @@ module Consoler
     # @param disable_usage_message [Boolean] Disable the usage message when nothing it matched
     # @return [mixed] Result of your matched command, <tt>nil</tt> otherwise
     def run(args = ARGV, disable_usage_message = false)
-      # TODO signal handling of some kind?
+      # TODO: signal handling of some kind?
 
       result, matched = _run(args.dup)
 
-      if not matched and not disable_usage_message
+      if !matched && !disable_usage_message
         usage
       end
 
-      return result
+      result
+    rescue RuntimeError => e
+      if @rescue_errors
+        $stderr.puts "A runtime error occured: #{e.message.strip}"
+        nil
+      else
+        raise e
+      end
     end
 
     # Show the usage message
@@ -93,7 +114,7 @@ module Consoler
       puts "#{@description}\n\n" unless @description.nil?
       puts 'Usage:'
 
-      _commands_usage $0
+      _commands_usage $PROGRAM_NAME
     end
 
     protected
@@ -104,16 +125,37 @@ module Consoler
     # @return [(mixed, Boolean)] Result of the command, and, did the args match a command at all
     def _run(args)
       arg = args.shift
+
+      return [nil, false] if arg.nil?
+
       arguments = Consoler::Arguments.new args
+      exact_matches = []
+      partial_matches = []
 
       @commands.each do |command|
-        if command.command == arg then
+        if command.command == arg
+          exact_matches.push command
+        elsif command.command.start_with? arg
+          partial_matches.push command
+        end
+      end
+
+      # we only allow a single partial match to prevent ambiguity
+      partial_match = if partial_matches.size == 1
+                        partial_matches[0]
+                      end
+
+      unless exact_matches.empty? && partial_match.nil?
+        matches = exact_matches
+        matches.push partial_match unless partial_match.nil?
+
+        matches.each do |command|
           # the matched command contains a subapp, run subapp with the same
           # arguments (excluding the arg that matched this command)
-          if command.action.instance_of? Consoler::Application then
+          if command.action.instance_of?(Consoler::Application)
             result, matched = command.action._run(args)
 
-            if matched then
+            if matched
               return result, true
             end
           else
@@ -126,26 +168,26 @@ module Consoler
         end
       end
 
-      return nil, false
+      [nil, false]
     end
 
     # Print the usage message for this command
     #
     # @param [String] prefix A prefix for the command from a parent app
     # @return [Consoler::Application]
-    def _commands_usage(prefix='')
+    def _commands_usage(prefix = '')
       @commands.each do |command|
         # print the usage message of a subapp with a prefix from the current command
-        if command.action.instance_of? Consoler::Application then
+        if command.action.instance_of?(Consoler::Application)
           command.action._commands_usage "#{prefix} #{command.command}"
         else
           print "  #{prefix} #{command.command}"
 
-          if command.options.size then
+          if command.options.size
             print " #{command.options.to_definition}"
           end
 
-          unless command.options.description.nil? then
+          unless command.options.description.nil?
             print "  -- #{command.options.description}"
           end
 
@@ -165,11 +207,13 @@ module Consoler
     # @param [Proc, Consoler::Application] action Action or subapp
     # @return [Consoler::Application]
     def _add_command(command, options_def, action)
-      @commands.push(Consoler::Command.new(
-        command: command,
-        options: Consoler::Options.new(options_def),
-        action: action,
-      ))
+      @commands.push(
+        Consoler::Command.new(
+          command: command,
+          options: Consoler::Options.new(options_def),
+          action: action,
+        )
+      )
 
       self
     end
@@ -183,7 +227,7 @@ module Consoler
       arguments = action.parameters.map do |parameter|
         parameter_name = parameter[1].to_s
 
-        if match.has_key? parameter_name then
+        if match.key? parameter_name
           match[parameter_name]
         else
           # check for the normalized name of every match to see
@@ -191,8 +235,8 @@ module Consoler
           match.each do |name, value|
             normalized_name = _normalize name
 
-            if parameter_name == normalized_name then
-              return value
+            if parameter_name == normalized_name
+              break value
             end
           end
         end
@@ -212,7 +256,7 @@ module Consoler
       # also be an syntax error, like starting with a number.
       # this normalization is more of a comvenience than anything
       # else
-      name.gsub('-', '_')
+      name.tr('-', '_')
     end
   end
 end

data/lib/consoler/arguments.rb

@@ -3,7 +3,6 @@
 require_relative 'matcher'
 
 module Consoler
-
   # Arguments
   #
   # @attr_reader [Array<String>] args Raw arguments

data/lib/consoler/command.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 module Consoler
-
   # Consoler command
   #
   # Basically a named hash