consoler 1.0.1 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 114e6fa695bcd034b3fbeb8a7e176aaa63493e9c
-  data.tar.gz: f16bae2dc6e43d138735e889b0d49db1280b2491
+SHA256:
+  metadata.gz: 924c498b6db12469aef2fb31bbe7cc0bbcaa0e10cccb2a18b91584484b3cb189
+  data.tar.gz: f99cdb84ac04f1ce5baa60ce29ccd7667a5239c0b959b1310ce8f8a9da4292a9
 SHA512:
-  metadata.gz: 2cd8d0e7daf27c4df2937c8e4a181b97eb759b03d3083a79df5959deac6f9d631497b8a6193d8a7c0d318ed1cc87e37f69a5ade1c52ee65367440767825307ab
-  data.tar.gz: f21ecd390a02b5751a00ec6a4aa53e5d4bdc9b5b5cb2bbfbd8fa5451ce0a46f175589b46eed77e588ea8ba1c0acf405800ce1a9ec94f3a243d0882cd859b75da
+  metadata.gz: 20ff199169e12d2bff2be0d12b3bcb6e615eb5613166406c4e46963e6716fd9b70306f7b6f561525f0783866f6d8e0d4c7315b73f98150d2133bccf4a643bc48
+  data.tar.gz: 34fb00e04d57de3fbcfc0b8242d01f5a76010860cac2fc78a69622ee3c7c89eb656a3f6d0abe05a7c38bdf71b97a97871c6738e488d52be203c5a2cc8bb603d4

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/.yardopts

@@ -0,0 +1,2 @@
+--private
+--protected

data/README.md

@@ -1,27 +1,51 @@
-# Consoler [![Build Status](https://api.travis-ci.org/justim/consoler-rb.svg?branch=master)](http://travis-ci.org/justim/consoler-rb)
+# Consoler [![Gem Version](https://badge.fury.io/rb/consoler.svg)](https://badge.fury.io/rb/consoler)
 
 > Sinatra-like application builder for the console
 
-## Usage
+## Quick usage
 
 ```ruby
-# create a application
+# create an application
 app = Consoler::Application.new description: 'A simple app'
 
 # define a command
-app.build 'target [--clean]' do |target, clean|
+app.build '[--clean] <output_dir>' do |clean, output_dir|
   # clean contains a boolean
   clean_up if clean
 
-  # target contains a string
-  build_project target
+  # 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
 ```
 
+## Features
+
+- 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.4.x`
+- `2.5.x`
+- `2.6.x`
+- `2.7.x`
+- `3.0.x`
+
+No other requirements exist.
+
 ## Installation
 
 ```sh
@@ -31,13 +55,242 @@ gem install consoler
 or add to your `Gemfile` for applications
 
 ```ruby
-gem 'consoler', '~> 1.0.0'
+gem 'consoler', '~> 1.2.1'
 ```
 
 or to your `.gemspec` file for gems
 
 ```ruby
-Gem::Specification.new do |s|
-  s.add_dependency 'consoler', '~> 1.0.0'
+Gem::Specification.new do |spec|
+  spec.add_dependency 'consoler', '~> 1.2.1'
+end
+```
+
+## Docs
+
+Full API documentation can the found here: https://www.rubydoc.info/gems/consoler/1.2.1
+
+### API
+
+#### Creating an application
+
+```ruby
+# create an application
+app = Consoler::Application.new
+
+# .. or with a description that will show up in the usage message
+app = Consoler::Application.new description: 'A simple app'
+```
+
+#### Adding commands
+
+All actions you want to create must have a command name, there is no top-level matching available at this point.
+
+```ruby
+# create an application
+app = Consoler::Application.new
+
+# in the most simple way, you provide a name (the method name) and a block you
+# want to execute if it matches
+app.build do
+  # your code here
+end
+
+# to add options to your command, provide a options definition as an argument
+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
+  # `verbose` contains a number, counting the times it occurred in the arguments
+  # `output_dir` contains a string, if needed to match this command
+end
+```
+
+#### Running the application
+
+```ruby
+# filename: app.rb
+
+# create an application
+app = Consoler::Application.new
+
+# a build command
+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 verbose > 0
 end
+
+# a deploy command
+app.build '[-v|--verbose] [--env=]' do |env|
+  puts 'Starting deploy...' if verbose > 0
+
+  do_deploy env || 'development'
+
+  puts 'Deploy complete' if verbose > 0
+end
+```
+
+_Shell commands:_
+```sh
+# start a build
+ruby app.rb build --env production dist
+
+# 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`            |
+| `-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]` |
+
+Some notes about these options:
+
+- 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|
+  # by definition, `last_name` is also filled
+  unless first_name.nil? then
+    puts "Hello #{first_name} #{last_name}!"
+  end
+
+  unless name.nil? then
+    puts "Hello #{name}!"
+  end
+end
+
+# calling with two arguments can fill the first group
+# prints "Hello 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!']
+```
+
+#### Return types in action block
+
+| Option type | Return type (ex.)       | Default (if optional) |
+| ----------- | ----------------------- | --------------------- |
+| Short       | `Integer` (`1`)         | `0`                   |
+| Long        | `Boolean` (`true`)      | `false`               |
+| 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.
+
+```ruby
+# filename: app.rb
+
+# create a subapplication
+android = Consoler::Application.new
+android.build do; end
+
+# options are supported just like regular apps
+android.clean '--force|-f' do; end
+
+# create an application
+app = Consoler::Application.new
+
+# mount the android application on top of the android command
+# note that the command does not support options
+app.android android
+```
+
+You can now run the next bit to run the android build command:
+
+```sh
+ruby app.rb android build
+```
+
+You can build them as complicated as you like :)
+
+### Complete example
+
+```ruby
+#!/usr/bin/env ruby
+
+db = Consoler::Application.new
+db.migrate '-- run all pending migrations' do
+  run_migrate
+end
+
+db.rollback '[--migrations=] -- rollback a number of migrations' do |migrations|
+  run_rollback migrations || 1
+end
+
+cache = Consoler::Application.new
+cache.clear '[--env=] -- clear the cache for a given environment' do |env|
+  run_cache_clear env || 'development'
+end
+
+cache.warmup '[--env=] -- warmup the cache for a given environment' do |env|
+  run_cache_warmup env || 'development'
+end
+
+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|
+  puts 'Starting build...' if v > 0
+
+  if clean
+    puts 'Starting clean...' if v > 1
+    do_clean_up if clean
+  end
+
+  do_build env || 'development', output_dir
+
+  puts 'Build complete' if v > 0
+end
+```
+
+Make the file executable with `chmod a+x app.rb`, you can now call it with `./app.rb` without `ruby` in front of it, saves a couple keystrokes.
+
+```sh
+# run all migration
+./app.rb db migrate
+# rollback the last 4 migrations
+./app.rb db rollback 4
+# clean production cache
+./app.rb cache clear --env production
+# build the project, including cleaning and logging
+./app.rb build --clean --env production -vv dist/
+# print the usage message
+./app.rb
+```
+
+## 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,25 @@ 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={})
+    def initialize(options = {})
       @description = options[:description]
       @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 +52,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 +74,7 @@ module Consoler
 
       _add_command(command, options_def, action)
 
-      return nil
+      nil
     end
 
     # Run the application with a list of arguments
@@ -75,15 +83,15 @@ 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)
+      result, matched = _run(args.dup)
 
-      if not matched and not disable_usage_message
+      if !matched && !disable_usage_message
         usage
       end
 
-      return result
+      result
     end
 
     # Show the usage message
@@ -93,21 +101,48 @@ module Consoler
       puts "#{@description}\n\n" unless @description.nil?
       puts 'Usage:'
 
-      _commands_usage $0
+      _commands_usage $PROGRAM_NAME
     end
 
     protected
 
+    # Run the app
+    #
+    # @param [Array<String>] args Arguments
+    # @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.action.instance_of? Consoler::Application 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)
             result, matched = command.action._run(args)
 
-            if matched then
+            if matched
               return result, true
             end
           else
@@ -120,45 +155,95 @@ module Consoler
         end
       end
 
-      return nil, false
+      [nil, false]
     end
 
-    def _commands_usage(prefix='')
+    # 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 = '')
       @commands.each do |command|
-        if command.action.instance_of? Consoler::Application then
+        # print the usage message of a subapp with a prefix from the current command
+        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
 
           print "\n"
         end
       end
+
+      self
     end
 
     private
 
+    # Add a command
+    #
+    # @param [String] command Command name
+    # @param [String] options_def Definition of options
+    # @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
 
+    # Execute an action with argument match info
+    #
+    # @param [Proc] action Action
+    # @param [Hash] match Argument match information
     def _dispatch(action, match)
+      # match parameter names to indices of match information
       arguments = action.parameters.map do |parameter|
-        match[parameter[1].to_s]
+        parameter_name = parameter[1].to_s
+
+        if match.key? parameter_name
+          match[parameter_name]
+        else
+          # check for the normalized name of every match to see
+          # if it fits the parameter name
+          match.each do |name, value|
+            normalized_name = _normalize name
+
+            if parameter_name == normalized_name
+              break value
+            end
+          end
+        end
       end
 
       action.call(*arguments)
     end
+
+    # Normalize a name to be used as a variable name
+    #
+    # @param [String] name Name
+    # @return [String] Normalized name
+    def _normalize(name)
+      # maybe do something more, maybe not.. ruby does allow for
+      # some weird stuff to be used as a variable name. the user
+      # should use some common sense. and, other things might
+      # also be an syntax error, like starting with a number.
+      # this normalization is more of a comvenience than anything
+      # else
+      name.tr('-', '_')
+    end
   end
 end