consoler 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 54af0ed85f838038f475a6933ccc51cc3cc5f3d6
-  data.tar.gz: c0456cdb8e72feef9b54fa726a532900ae5e0778
+  metadata.gz: 317d28b9a15f0ea07c01410191cac9d0d59a41dd
+  data.tar.gz: f9a363ba2b596a02df673c1600441f2f6d7b7010
 SHA512:
-  metadata.gz: 6c3df9e819bad404d84afd1a9b99263e2ecee61a71a8db9af4507648e495021fcfe45d9338351b1ebe6e3432706be8bd4acb1c57bc0b26a922af5b3c433ddbb1
-  data.tar.gz: 7ebde44d27aaede0fa7a6a1a599a81fe7261808ed1472c068732b550c1e5ce3673199cef9a3733ecee6511ba5f11f05dbc70a046c5f8f2e2de3d48f46b8b796d
+  metadata.gz: b42c0a91ed2df03ef7d76796f1da5e986782d2d0415a14167159f34b10b76eb939e97f378109328bdd768c7f234607907871bcd03e2e5ad097180c7edaf385c6
+  data.tar.gz: df6627a850424d6053c4525bea35014c1c8ec42bbe9cbe43f981119b535a747af53c4130dec92242309d36891c9e7368450c49838c37c55ea2662a682582fb26

data/.yardopts

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

data/README.md

@@ -1,27 +1,47 @@
-# Consoler [![Build Status](https://api.travis-ci.org/justim/consoler-rb.svg?branch=master)](http://travis-ci.org/justim/consoler-rb)
+# 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)
 
 > 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'])
 
 # this does not match, nothing is executed and the usage message is printed
 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
+
+## Requirements
+
+Tests are run against multiple ruby versions (latest supported):
+
+- `2.2.x`
+- `2.3.x`
+- `2.4.x`
+- `2.5.x`
+
+No other requirements exist.
+
 ## Installation
 
 ```sh
@@ -31,13 +51,233 @@ gem install consoler
 or add to your `Gemfile` for applications
 
 ```ruby
-gem 'consoler', '~> 1.0.0'
+gem 'consoler', '~> 1.0.3'
 ```
 
 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.0.3'
+end
+```
+
+## Docs
+
+Full API documentation can the found here: http://www.rubydoc.info/github/justim/consoler-rb/
+
+### 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] output_dir' do |clean, env, v, 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
+  # `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] output_dir' do |clean, env, v, output_dir|
+  puts 'Starting build...' if v > 0
+
+  do_clean_up if clean
+
+  do_build env || 'development', output_dir
+
+  puts 'Build complete' if v > 0
+end
+
+# a deploy command
+app.build '[-v] [--env=]' do |env|
+  puts 'Starting deploy...' if v > 0
+
+  do_deploy env || 'development'
+
+  puts 'Deploy complete' if v > 0
+end
+```
+
+_Shell commands:_
+```sh
+# start a build
+ruby app.rb build --env production dist
+
+# deploy
+ruby app.rb deploy
+```
+
+#### 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]` |
+
+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.
+
+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`                 |
+
+#### 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' 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
+```
+
+### 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/lib/consoler/application.rb

@@ -98,12 +98,18 @@ module Consoler
 
     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
       arguments = Consoler::Arguments.new args
 
       @commands.each do |command|
         if command.command == arg then
+          # 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
             result, matched = command.action._run(args)
 
@@ -123,8 +129,13 @@ module Consoler
       return 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='')
       @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
           command.action._commands_usage "#{prefix} #{command.command}"
         else
@@ -141,24 +152,67 @@ module Consoler
           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,
       ))
+
+      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.has_key? parameter_name then
+          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 then
+              return 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.gsub('-', '_')
+    end
   end
 end

data/lib/consoler/matcher.rb

@@ -26,12 +26,14 @@ module Consoler
     def match
       parse_options = true
 
-      loop_args do |arg|
+      _loop_args do |arg|
         unless parse_options then
           @argument_values.push arg
           next
         end
 
+        # when "argument" is --, then stop parsing the rest of the arguments
+        # and treat the rest as regular arguments
         if arg == '--' then
           parse_options = false
           next
@@ -57,6 +59,10 @@ module Consoler
 
     private
 
+    # Analyze a single argument
+    #
+    # @param [String] arg Single argument
+    # @return [true, nil] true on success, nil on failure
     def _analyze(arg)
       is_long = false
       is_short = false
@@ -70,12 +76,14 @@ module Consoler
         name = arg[1..-1]
       end
 
-      if name.nil?
+      # arg is not a long/short option, add to arguments values
+      unless is_long or is_short then
         @argument_values.push arg
         return true
       end
 
       unless name.nil? then
+        # get the name of the option, short options use the first character
         option_name = if is_short then
                         name[0]
                       else
@@ -84,11 +92,13 @@ module Consoler
 
         option = @options.get option_name
 
+        # no option by this name in options
         return nil if option.nil?
 
         needs_short = option.is_short
         needs_long = option.is_long
 
+        # see if the type if right, short or long
         if needs_long and not is_long then
           return nil
         elsif needs_short and not is_short then
@@ -97,9 +107,10 @@ module Consoler
 
         if is_long then
           if option.is_value then
-            return nil if peek_next.nil?
-            @matched_options[name] = peek_next
-            skip
+            # is_value needs a next argument for its value
+            return nil if _peek_next.nil?
+            @matched_options[name] = _peek_next
+            _skip_next
           else
             @matched_options[name] = true
           end
@@ -107,11 +118,16 @@ module Consoler
 
         if is_short then
           if name.size == 1 and option.is_value then
-            return nil if peek_next.nil?
-            @matched_options[name] = peek_next
-            skip
+            # is_value needs a next argument for its value
+            return nil if _peek_next.nil?
+            @matched_options[name] = _peek_next
+            _skip_next
           else
+            # for every character (short option) increment the option value
             name.split('').each do |n|
+              short_option = @options.get n
+              return nil if short_option.nil?
+
               if @matched_options[n].nil? then
                 @matched_options[n] = 0
               end
@@ -125,29 +141,49 @@ module Consoler
       return true
     end
 
-    def current
-      @arguments.args[@index]
-    end
-
-    def peek_next
-      @arguments.args[@index + 1]
-    end
-
-    def loop_args
+    # Loop through the arguments
+    #
+    # @yield [String] An argument
+    # @return [Consoler::Matcher]
+    def _loop_args
       @index = 0
       size = @arguments.args.size
 
+      # use an incrementing index, to be able to peek to the next in the list
+      # and to skip an item
       while @index < size do
-        yield current
+        yield @arguments.args[@index]
 
-        skip
+        _skip_next
       end
+
+      self
+    end
+
+    # Peek at the next argument
+    #
+    # Only useful inside {Consoler::Matcher#_loop_args}
+    #
+    # @return [String, nil]
+    def _peek_next
+      @arguments.args[@index + 1]
     end
 
-    def skip
+    # Skip to the next argument
+    #
+    # Useful if you use a peeked argument
+    #
+    # @return [nil]
+    # @return [Consoler::Matcher]
+    def _skip_next
       @index += 1
+
+      self
     end
 
+    # Match arguments to defined option arguments
+    #
+    # @return [Array<String>] The remaining args
     def _match_arguments
       @optionals_before = {}
       @optionals_before_has_remaining = false
@@ -157,6 +193,8 @@ module Consoler
       _match_arguments_optionals_before
 
       @optionals_before.each do |mandatory_arg_name, optionals|
+        # fill the optional argument option with a value if there are enough
+        # arguments supplied (info available from optionals map)
         optionals.each do |_, optional|
           optional.each do |before|
             if before[:included] then
@@ -166,6 +204,7 @@ module Consoler
           end
         end
 
+        # only fill mandatory argument if its not the :REMAINING key
         if mandatory_arg_name != :REMAINING then
           @matched_options[mandatory_arg_name] = @argument_values[argument_values_index]
           argument_values_index += 1
@@ -174,6 +213,7 @@ module Consoler
 
       remaining = []
 
+      # left over arguments
       while argument_values_index < @argument_values.size do
         remaining.push @argument_values[argument_values_index]
         argument_values_index += 1
@@ -182,6 +222,9 @@ module Consoler
       remaining
     end
 
+    # Create a map of all optionals and before which mandatory argument they appear
+    #
+    # @return [Consoler::Matcher]
     def _match_arguments_optionals_before
       @optionals_before = {}
       tracker = {}
@@ -190,8 +233,10 @@ module Consoler
         next unless option.is_argument
 
         if option.is_optional then
+          # setup tracker for optional group
           tracker[option.is_optional] = [] if tracker[option.is_optional].nil?
 
+          # mark all optionals as not-included
           tracker[option.is_optional].push({
             included: false,
             name: option.name,
@@ -202,24 +247,35 @@ module Consoler
         end
       end
 
+      # make sure all optionals are accounted for in the map
       if tracker != {} then
+        # use a special key so we can handle it differently in the filling process
         @optionals_before[:REMAINING] = tracker
         @optionals_before_has_remaining = true
       end
 
-      _match_arguments_optoins_before_matcher
+      _match_arguments_options_before_matcher
+
+      self
     end
 
-    def _match_arguments_optoins_before_matcher
+    # Match remaining args against the optionals map
+    #
+    # @return [Consoler::Matcher]
+    def _match_arguments_options_before_matcher
+      # number of arguments that are needed to fill our mandatory argument options
       mandatories_matched = @optionals_before.size
 
+      # there are optionals at the end of the options, don't match the void
       if @optionals_before_has_remaining then
         mandatories_matched -= 1
       end
 
       total = 0
 
+      # loop through optional map
       _each_optional_before_sorted do |before|
+        # are there enough arguments left to fill this optional group
         if (total + before.size + mandatories_matched) <= @argument_values.size then
           total += before.size
 
@@ -228,8 +284,13 @@ module Consoler
           end
         end
       end
+
+      self
     end
 
+    # Give all unmatched optional options there default value
+    #
+    # @return [Consoler::Matcher]
     def _fill_defaults
       @options.each do |option|
         if option.is_optional then
@@ -238,8 +299,15 @@ module Consoler
           end
         end
       end
+
+      self
     end
 
+    # Loop through the optionals before map
+    #
+    # Sorted by number of optionals in a group
+    #
+    # @return [Consoler::Matcher]
     def _each_optional_before_sorted
       @optionals_before.each do |_, optionals|
         tmp = []
@@ -254,6 +322,8 @@ module Consoler
           yield optionals[item[:index]]
         end
       end
+
+      self
     end
   end
 end

data/lib/consoler/option.rb

@@ -27,10 +27,13 @@ module Consoler
     def self.create(option_def, tracker)
       option = Option.new option_def, tracker
 
+      # split short options with more than 1 char in multiple options
       if option.is_short and option.name.size > 1 then
+        # remember state
         old_tracking = tracker.is_tracking
         old_is_value = option.is_value
 
+        # if the complete option is optional, fake the tracker
         if option.is_optional then
           tracker.is_tracking = true
         end
@@ -40,6 +43,7 @@ module Consoler
         names.each_with_index do |name, i|
           new_name = "-#{name}"
 
+          # if the short option should have a value, this only counts for the last option
           if old_is_value and i == names.count - 1 then
             new_name = "#{new_name}="
           end
@@ -47,6 +51,7 @@ module Consoler
           yield Option.new new_name, tracker
         end
 
+        # reset to saved state
         tracker.is_tracking = old_tracking
       else
         yield option
@@ -92,7 +97,12 @@ module Consoler
     #
     # @param [String] option_def Definition of the option
     # @param [Consoler::Tracker] tracker tracker
+    # @raise [RuntimeError] if the option name is empty
+    # @raise [RuntimeError] if the option is long _and_ short
     def initialize(option_def, tracker)
+      # Check for multiple attributes in the option definition till we got the
+      # final name and all of its attributes
+
       option, @is_optional = _is_optional option_def, tracker
       option, @is_long = _is_long option
       option, @is_short = _is_short option
@@ -112,9 +122,22 @@ module Consoler
 
     private
 
+    # Check optional definition
+    #
+    # Does it open an optional group
+    # Does it close an optional group (can be both)
+    # Updates the tracker
+    # Removes leading [ and trailing ]
+    #
+    # @param [String] option Option definition
+    # @param [Consoler::Tracker] tracker Optional tracker
+    # @raise [RuntimeError] if you try to nest optional groups
+    # @raise [RuntimeError] if you try to close an unopened optional
+    # @return [(String, Integer|nil)] Remaining option definition, and, optional group if available
     def _is_optional(option, tracker)
       if option[0] == '[' then
         if !tracker.is_tracking then
+          # mark tracker as tracking
           tracker.is_tracking = true
           tracker.index += 1
           option = option[1..-1]
@@ -123,6 +146,7 @@ module Consoler
         end
       end
 
+      # get optional group index from tracking, if tracking
       optional = if tracker.is_tracking then
                    tracker.index
                  else
@@ -131,6 +155,7 @@ module Consoler
 
       if option[-1] == ']' then
         if tracker.is_tracking then
+          # mark tracker as non-tracking
           tracker.is_tracking = false
           option = option[0..-2]
         else
@@ -141,6 +166,10 @@ module Consoler
       return option, optional
     end
 
+    # Check long definition
+    #
+    # @param [String] option Option definition
+    # @return [(String, Boolean)]
     def _is_long(option)
       if option[0..1] == '--' then
         long = true
@@ -152,6 +181,10 @@ module Consoler
       return option, long
     end
 
+    # Check short definition
+    #
+    # @param [String] option Option definition
+    # @return [(String, Boolean)]
     def _is_short(option)
       if option[0] == '-' then
         short = true
@@ -163,6 +196,11 @@ module Consoler
       return option, short
     end
 
+    # Check value definition
+    #
+    # @param [String] option Option definition
+    # @raise [RuntimeError] if you try to assign a value to an argument
+    # @return [(String, Boolean)]
     def _value(option, argument)
       if option[-1] == '=' then
         if argument then

data/lib/consoler/options.rb

@@ -13,12 +13,14 @@ module Consoler
     # Create a list of option based on a string definition
     #
     # @param options_def [String] A string definition of the desired options
+    # @raise [RuntimeError] if you try to use a duplicate name
     def initialize(options_def)
       @options = []
       @description = nil
 
       return if options_def.nil?
 
+      # strip the description
       if match = /(^|\s+)-- (?<description>.*)$/.match(options_def) then
         @description = match[:description]
         options_def = options_def[0...-match[0].size]
@@ -44,7 +46,7 @@ module Consoler
     # @param name [String] Name of the option
     # @return [Consoler::Option, nil]
     def get(name)
-      each do |option|
+      each do |option, _|
         if option.name == name then
           return option
         end
@@ -72,6 +74,9 @@ module Consoler
       @options.size
     end
 
+    # Get the definition for these options
+    #
+    # @return [String] Options definition
     def to_definition
       definition = ''
       optional = nil
@@ -87,6 +92,7 @@ module Consoler
         definition += option.to_definition
 
         if option.is_optional then
+          # only close when the next option is not optional, or another optional group
           if @options[i + 1].nil? or optional != @options[i + 1].is_optional then
             definition += ']'
             optional = nil

data/lib/consoler/version.rb

@@ -3,5 +3,5 @@
 module Consoler
 
   # Current version number
-  VERSION = '1.0.2'
+  VERSION = '1.0.3'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: consoler
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - Tim
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-03-14 00:00:00.000000000 Z
+date: 2018-03-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -89,6 +89,7 @@ files:
 - ".editorconfig"
 - ".gitignore"
 - ".travis.yml"
+- ".yardopts"
 - Gemfile
 - LICENSE.txt
 - README.md