rake-commander 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79568da769a6523e7024fa641eb8d792b2fd4dfcc600f11f0cbf56e6bb1f45d9
-  data.tar.gz: e8e55e77085b67e37fd9befdb1b0b77cd0f8403ff1c0ab939160c3659c0cd67f
+  metadata.gz: ce1bfcde79ef608b7e13c440c626ee3ace47ec5adf3088e6fc969bf85502cc59
+  data.tar.gz: f785888cff61578247dfb1fdfed6c4e44fd076180d8be0dd1e00bf14ac0f1700
 SHA512:
-  metadata.gz: fe77e58170a2e2bed3c9d52202e8deaa039422bda0ded1284f0d8fb316c83a6609fffb6753d2387d573b0ed70c7d5a2c74b5d868e8a89f5ba96dfa2d472b8587
-  data.tar.gz: f75fa6017995dd942cd37cc6494db0a0c9d5273eb28e1b9ef9fe7d909fa39abffc25b6aa681c05ba1dce868b2265fb0bf54f01c55a31fd4298aaf6f70f3b435c
+  metadata.gz: 5d998c21f52d117ff59e5eb066a43cd0c5a0939a4187af2c5ee1dc3cbaead328b65d71ad67e333adf426ab465926fd56fc5830e4e7a3a7b048602f02dea39344
+  data.tar.gz: 2afaaa3bb046e6de18b13fe4b0e762dead4ace9a14b3d097c2b6c37142e7e0e0d111f5eecd9846647e50a64f13cbf8491b291d7572fafaada91cdc408400d064

data/.gitignore

@@ -1,3 +1,9 @@
+# env files
+.env*
+
+# core development-only executables
+/bin/raked*
+
 # it's a gem, ignore the lockfile
 Gemfile.lock
 
@@ -18,3 +24,5 @@ Gemfile.lock
 # rspec failure tracking
 .rspec_status
 scratch.rb
+
+/.byebug_history

data/.rubocop.yml

@@ -17,17 +17,21 @@ Metrics/MethodLength:
   Max: 50
 Metrics/ClassLength:
   Max: 200
+Metrics/ModuleLength:
+  Max: 200
 Metrics/AbcSize:
   Max: 50
 Metrics/CyclomaticComplexity:
-  Max: 15
+  Max: 10
 Metrics/PerceivedComplexity:
-  Max: 15
+  Max: 10
 
 ParameterLists:
   Max: 5
   CountKeywordArgs: false
 
+Style/Alias:
+  EnforcedStyle: prefer_alias_method
 Style/StringLiterals:
   Enabled: false
 Style/FrozenStringLiteralComment:
@@ -49,12 +53,8 @@ Style/ClassAndModuleChildren:
 Style/OptionalBooleanParameter:
   Enabled: false
 
-Layout/SpaceInsideHashLiteralBraces:
-  Enabled: false
-Layout/SpaceInsideBlockBraces:
-  Enabled: false
-Layout/SpaceAroundOperators:
-  Enabled: false
+Layout/HashAlignment:
+  EnforcedColonStyle: table
 Layout/ExtraSpacing:
   AllowForAlignment: true
 Layout/AccessModifierIndentation:
@@ -63,6 +63,12 @@ Layout/DotPosition:
   EnforcedStyle: trailing
 Layout/MultilineMethodCallIndentation:
   EnforcedStyle: indented
+Layout/SpaceInsideHashLiteralBraces:
+  Enabled: false
+Layout/SpaceInsideBlockBraces:
+  Enabled: false
+Layout/SpaceAroundOperators:
+  Enabled: false
 Layout/FirstHashElementIndentation:
   Enabled: false
 Layout/EmptyLineAfterGuardClause:

data/CHANGELOG.md

@@ -2,13 +2,93 @@
 All notable changes to this project will be documented in this file.
 
 ## TO DO
-  - Rake task parameters (see: https://stackoverflow.com/a/825832/4352306)
-  - `OptionParser#parse` result (what to do with unknown ARGV `leftovers`)
+  - Option results
+    - Include the symbol name keys (configurable). Note that dash will be replaced by underscore.
+  - Type Coertions
+    - Add a way to define/redefine a set and use them.
+    - Add more supported type_coertions as native to the gem (i.e. `Symbol`)
+    - Add support [for `ActiveRecord::Enum`](https://apidock.com/rails/ActiveRecord/Enum)
+  - Option definitions
+    - Order: `where: [:tail, :top]` and `[after, before]: :option_name`
+    - Configuration: allow to define option override behaviour and whether it should trigger an exception
+  - Error handlers
+    - See if it would be possible to parse all the valid options so we get all the valid results before some error is raised. Although this can be achieved with `OptionParser#order!`, it destroys switches; which would require to give it two parsing shots whenever there is an error.
+      - It should be ensured that the parsed options results object is remains the same.
+      - Think about options that modify other options. Technically this should be hold only at behaviour level
+    - This would allow to make the order of the options irrelevant when it comes to modify error handling behaviour via options themselves.
+  - Rake task parameters (see: https://stackoverflow.com/a/825832/4352306 & https://stackoverflow.com/a/825832/4352306)
+  - Add `enhance` functionality (when a task is invoked it runs before it; declared with `task` as well)
+  - Add `no_short` option (which should give the result of that option with the option name key)
+  - Add `on_option` handler at instance level, so within a `task` definition, we can decide certain things, such as if the functionality should be active when the `self.class` does not have that option.
+    * This is specially useful to be able to extend through inheritance chain, where we extend `task` (rather than redefining it), but we don't want options we removed (with `option_remove`) to throw unexpected results.
+    * Example: `on_option(:t, defined: true) {|option| do-stuff}` <- block to be called only if the option is defined in the class (alternative: `defined: :only`)
+    * Example: `on_option(:t, defined: false) {|option| do-stuff}` <- block to be called regardless the option exists (alternative: `defined: :ignore`)
+    * Example: `on_options(:t, :s, present: true) {|options| do-stuff}` <- block to be called only when the option `:t` and `:s` are both present in the parsed `options` result.
+    - Once this has been done,  think about it being a hash-alike object with methods for the option names (i.e. `options.debug?`)
 
-## [0.1.2] - 2023-04-19
+## DISCARDED IMPROVENTS
+  - Option to globally enable/disable the 2nd patch?
+    * That would make this gem completely useless.
+
+## [0.2.1] - 2023-04-xx
 
 ### Added
-  - First commit
+### Fixed
+### Changed
+
+
+## [0.2.0] - 2023-04-28
+
+### Added
+  - Better support for `RakeCommander::Options::Set`
+    - `RakeCommander::Options::options_use` accepts it as a parameter.
+    - Added `override` parameter to specify if this should override clashed option names.
+  - `RakeCommander::Options::class_resolver` to define the `RakeCommander::Option` class.
+    - Serves the purpose to ease class extension through inheritance.
+  - Ability to reopen options without changing the order.
+    - `RakeCommander::Options::option_reopen` which upserts (adds if not existing).
+    - New parameter `reopen` to `RakeCommander::Options::option` (redirects to the above method).
+  - Automatic option shortcuts (`implicit_shorts`) show in help and only when applicable.
+    - These are added automatically by `OptionParser`
+  - `OptionParser` leftovers trigger an error by default.
+    - This behaviour can be disabled or modified via callback/block by using `RakeCommander::Options:Error::error_on_leftovers`.
+  - Description auto **multi-line**
+    - Currently based on `RakeCommander::Options::Description::DESC_MAX_LENGTH`
+  - `RakeCommander::Options#remove_option`
+  - `RakeCommander::Options::Error::Base` and children can be raised using different methods (see `RakeCommander::Options::Error` for examples).
+    - The **task** `name` that raised the error is included in the message.
+  - `RakeCommander::Options::Error::Handling` which provides **configurability** around actions on specific option errors with a default to a general options parsing error.
 
 ### Fixed
+  - `RakeCommander::Base::ClassAutoLoader`
+    - Register excluded child classes (singleton classes) into their own property,
+      rather than in the `autoloaded_children` (they are not autoloaded).
+  - Missing `rake` dependency in gemspec file.
+  - Boolean switch detection (pre-parse arguments) and parsing
+    - It adds support for boolean option names such as `--[no-]verbose`
+  - Error messaging. There were missing cases, specially with implicit short options.
+  - `RakeCommander::Options`
+    - `#option_reopen` fixed
+    - **Inheritance fixed**
+
 ### Changed
+  - Development: examples invokation via `Rake`
+  - Refactored `RakeCommander::Options` to acquire functionality through extension.
+  - `attr_inheritable` and `inheritable_class_var` are the new names of previous methods
+    - Behaviour has been changed, so you define if it should `dup` the variables, and you can pass a `block` to do the `dup` yourself. They won **NOT** `freeze` anymore, as we are mostly working at class level.
+
+## [0.1.4] - 2023-04-20
+
+### Fixed
+  - `rubocop` offenders
+  - Added implicity `exit(0)` when wrapping the `task` block
+
+## [0.1.3] - 2023-04-20
+
+### Fixed
+  - Reference to repo and gem
+
+## [0.1.2] - 2023-04-19
+
+### Added
+  - First commit

data/Gemfile

@@ -2,5 +2,5 @@ source "https://rubygems.org"
 
 git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
 
-# Specify your gem's dependencies in ecoportal-api.gemspec
+# Specify your gem's dependencies in rake-commander.gemspec
 gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Oscar Segura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,6 +1,20 @@
-# Ecoportal::API
+# RakeCommander
 
-Another way to define re-usable rake tasks and samples.
+Classing rake tasks with options. Creating re-usable tasks, options and samples thereof.
+
+## Introduction
+
+Rake commander is a way to declare **rake tasks** with re-usable classes. It enhances the command line syntax, as tasks can come with their own **options**, inherit them, re-use declared options sets, modify/re-open or even remove them.
+
+Although the `OptionParser` ruby native class is used for parsing the options, the declaration of options, additionally to the ones of `OptionParser` comes with some **opinionated improvements** and amendments:
+
+1. It is possible to declare options as `required`
+  * This is additional to required option arguments.
+  * Options are inheritable (they get a custom `deep_dup`)
+2. An option can have a `default` value.
+  * Which can optionally be automatically used when the option accepts or requires an argument.
+3. Options parsing raises specific option errors. For a given task/class, each error type can have its own handler or preferred action.
+  * Defined error handling is inheritable and can be redefined.
 
 ## Installation
 
@@ -20,9 +34,87 @@ Or install it yourself as:
 
 ## Usage
 
+See [**the `examples`**](https://github.com/rellampec/rake-commander/tree/main/examples).
+
+```
+rake -T examples
+```
+
+Go through the [basic example](https://github.com/rellampec/rake-commander/blob/main/examples/01_basic_example.rb).
+
+```
+rake examples:basic -- -h
+rake examples:basic -- -z -e prod
+```
+  * The double dash `--` is used to tell to rake-commander where the options section starts.
+
+At the same time the double dash delimiter seems to make rake ignore anything that comes afterwards. Without loading rake commander, you could try:
+
+```
+$ rake --trace rspec
+** Invoke spec (first_time)
+** Execute spec
+rspec logging and results
+```
+
+And then re-try with
+
+```
+$ rake rspec -- --trace
+rspec logging and results
+```
+
+  * The `--trace` option is being natively ignored by `rake` due to the preceding double dash (` -- `).
+
+
+### Syntax
+
+### Declaring and using Task Options
+
+It supports most of options syntax of the native `OptionParser` but for a couple of exceptions perhaps:
+  1. It does **NOT** support definitions or parsing of shortcuts with **embedded argument** (i.e. `-nNAME`).
+  2. It does **NOT** support definitions that include equal sign (i.e. `name=NAME`, `n=NAME`)
+
+An argument should be explicitly declared in the `name` part:
+
+```
+  option :n, '--name NAME'
+```
+
+### Command Line
+
+Although it is planned to extend the syntax, the current version shares the options through all tasks (declared as `RakeCommander` classes) that are invoked in the same command line.
+
+```
+rake [rake-options] task1 task2 -- [shared-task-options]
+```
+
+The double dash ` -- ` delimiter allows to modify the `ARGV` parsing behaviour of `rake`, giving room for **opinionated enhanced syntax**. Anything that comes before the double dash is feed to standard `rake`, and anything after `--` are parsed as option tasks via `rake commander`.
+
+```
+<rake part> -- [tasks options part]
+```
+
+## `rake` full support
+
+Work has been done with the aim of providing a full patch on `rake`, provided that the main invocation command remains as `rake`.
+
+To preserve `rake` as invocation command, though, the patch needs to relaunch the rake application when it has already started. The reason is that `rake` has already pre-parsed `ARGV` when `rake-commander` is loaded (i.e. from a `Rakefile`) and has identified as tasks things that are part of the task options.
+
+  * For compatibility with tasks declared using `RakeCommander`, the rake application is always relaunched. Anything that does not belong to task options should not be feed to rake tasks declared with rake commander classes.
+
+### Patching `Rake`
+
+The two patches:
+
+  1. Rake commander does come with a neat patch to the [`Rake::Application#run` method](https://github.com/ruby/rake/blob/48e798484babf725b0562cc417986da513e5d0ae/lib/rake/application.rb#L79) to clean up the `ARGV` before the rake application starts. But it kicks in too late...
+  2. For this reason a more arguable patch has been applied to [`Rake::Application#top_level` method](https://github.com/ruby/rake/blob/48e798484babf725b0562cc417986da513e5d0ae/lib/rake/application.rb#L131), where the rake application is relaunched.
+
+For further details please see [`RakeCommander::Patcher`](https://github.com/rellampec/rake-commander/blob/main/lib/rake-commander/patcher).
+
 
 ## Development
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-For more info on available `Rake` tasks: `rake -T`
+For more info on available `Rake` tasks: `rake -T` (or `bin/raked -T`)

data/Rakefile

@@ -1,32 +1,30 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-require "yard"
-require "redcarpet"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'yard'
+require 'redcarpet'
 
-desc "run the specs"
+# Install examples and load `rake-commander`
+Rake.add_rakelib 'examples'
+
+desc 'run the specs'
 RSpec::Core::RakeTask.new(:spec)
 
-desc "run rspec showing backtrace"
+desc 'run rspec showing backtrace'
 RSpec::Core::RakeTask.new(:spec_trace) do |task|
   task.rspec_opts = ['--backtrace']
 end
 
-desc "run rspec stopping on first fail, and show backtrace"
+desc 'run rspec stopping on first fail, and show backtrace'
 RSpec::Core::RakeTask.new(:spec_fast) do |task|
   task.rspec_opts = ['--fail-fast', '--backtrace']
 end
 
 # default task name is yard
-desc "Yard: generate all the documentation"
+desc 'Yard: generate all the documentation'
 YARD::Rake::YardocTask.new(:doc) do |t|
   #t.files = ['lib/**/*.rb']
 end
 
-desc "Examples: Run examples (rake examples[basic] -- -h)"
-task :examples, [:sample] do |t, args|
-  require_relative "examples/#{args[:sample]}"
-end
-
 task default: [:spec]
 task rspec_trace: :spec_trace
 task rspec_fast: :spec_fast

data/examples/01_basic_example.rb

@@ -0,0 +1,28 @@
+class RakeCommander::Custom::BasicExample < RakeCommander
+  namespace :examples
+
+  desc 'A simple example to get started'
+  task :basic
+
+  #banner "Usage: basic:example -- [options]"
+  option '-w', :show_time, TrueClass, desc: 'Displays the local time'
+  option :z, '--timezone', TrueClass, default: false, required: true
+  option :o, '--hello NAME', String, desc: 'It greets.'
+  option '-s', '--say [SOMETHING]', "It says 'something'", default: %q(I don't know what to "say"...)
+  option :d, '--folder NAME', default: '.', desc: 'Source local folder', required: true
+  option '-e', :'--enviro ENV', 'The target environment to run this task', required: true
+  option :v, :debug, TrueClass, 'Shows the parsed options'
+  option :V, '[no-]verbose', 'Verbosity', TrueClass
+  #option :f, :folder, required: false, reopen: true
+
+  def task(*_args)
+    puts "Hello #{options[:o]}!!" if options[:o]
+    if options[:v]
+      puts 'We got these options:'
+      pp options
+    end
+    puts Time.now.strftime('%d %b at %H:%M') if options[:w]
+    puts Time.now.zone                       if options[:z]
+    puts options[:s]                         if options.key?(:s)
+  end
+end

data/examples/02_a_chainer_example.rb

@@ -0,0 +1,66 @@
+require_relative 'libs/shell_helpers'
+require_relative '02_a_chainer_options_set'
+
+class RakeCommander::Custom::Chainer < RakeCommander
+  include Examples::Libs::ShellHelpers
+  TARGET_TASK = 'examples:chained'.freeze
+
+  namespace :examples
+
+  task :chainer
+  desc "Uses rake (or raked) to invoke #{TARGET_TASK}"
+
+  # When an option as a default value defined, it is added to `options` result
+  # even when the option was not invoked
+  options_with_defaults true
+
+  # Loads the otions from a pre-defined options set
+  options_use RakeCommander::Custom::ChainerOptionsSet
+  # Redefines the description of the option `:chain`
+  option_reopen :chain, desc: "Calls: '< rake|raked > #{TARGET_TASK} task'"
+  # Adds some option of its own
+  str_desc  = "The method used to shell the call to examples:chained."
+  str_desc << " Options: #{SHELL_METHODS.join(', ')}"
+  option '-m', 'method [METHOD]', default: 'system', desc: str_desc
+
+  def task(*_args)
+    if options[:c]
+      cmd = "#{subcommand_base} -- #{subcommand_arguments.join(' ')}"
+      puts "Calling --> '#{cmd}'"
+      shell(cmd, method: options[:m])
+    else
+      puts "Nothing to do :|"
+    end
+  end
+
+  def subcommand_base
+    with = options[:w] == 'raked' ? 'bin\raked' : 'rake'
+    "#{with} #{self.class::TARGET_TASK}"
+  end
+
+  def subcommand_arguments
+    [].tap do |args|
+      if options.key?(:s)
+        str_opt  = "--say"
+        str_opt << " \"#{options[:s]}\"" if options[:s]
+        args << str_opt
+      end
+      args << "--debug" if options[:b]
+    end
+  end
+
+  private
+
+  def puts(str)
+    return super unless options[:b]
+    super "#{app_id}   #{str}   #{thread_id}"
+  end
+
+  def app_id
+    "(#{self.class.task_fullname}: #{Rake.application.object_id})"
+  end
+
+  def thread_id
+    "(PID: #{Process.pid} ++ Thread: #{Thread.current.object_id})"
+  end
+end

data/examples/02_a_chainer_options_set.rb

@@ -0,0 +1,8 @@
+class RakeCommander::Custom::ChainerOptionsSet < RakeCommander::Options::Set
+  name :chainer_options
+
+  option :c, :chain, TrueClass, desc: "Calls: '< rake|raked > chained-task task'"
+  option :w, '--with CALLER', default: 'rake', desc: "Specifies if should invoke with 'rake' or 'raked'"
+  option '-s', "It makes the chained-task say 'something'", name: '--say [SOMETHING]'
+  option '-b', '--debug', TrueClass, 'Whether to add additional context information to messages'
+end

data/examples/02_b_chained_example.rb

@@ -0,0 +1,13 @@
+class RakeCommander::Custom::Chained < RakeCommander::Custom::Chainer
+  #namespace :examples # <-- inherited
+  desc 'A task you want to chain to'
+  task :chained
+
+  option_reopen :s, "It says 'something'", default: %q(I don't know what to "say"...)
+  option_remove :c, :w, :method
+
+  def task(*_args)
+    puts "Called !!"
+    puts options[:s] if options[:s]
+  end
+end

data/examples/03_a_chainer_plus_example.rb

@@ -0,0 +1,34 @@
+class RakeCommander::Custom::ChainerPlus < RakeCommander::Custom::Chainer
+  TARGET_TASK = 'examples:chained_plus'.freeze
+
+  desc "Uses rake (or raked) to invoke #{TARGET_TASK}"
+  task :chainer_plus
+
+  # Disable using defaults when options are not invoked.
+  options_with_defaults false
+
+  # Update option description
+  option_reopen :chain, desc: "Calls: '< rake|raked > #{TARGET_TASK} task'"
+  # Extend with new options
+  option :e, '--exit-on-error', TrueClass, \
+         desc: "Whether #{TARGET_TASK} should just exit on 'missing argument' error (or raise an exception)"
+  option :o, '--hello NAME', String, desc: 'It greets.'
+
+  # Make it default to `exit 1` when there are errors
+  error_on_options false
+  # Let it trigger/raise the error when an unknown option is used!
+  error_on_options true, error: RakeCommander::Options::Error::InvalidArgument
+
+  def task(*_args)
+    puts "Hello #{options[:o]}!!" if options[:o]
+    options[:m] = :system unless options[:m]
+    super
+  end
+
+  # We add the extended arguments at the beginning
+  def subcommand_arguments
+    [].tap do |args|
+      args << '--exit-on-error' if options[:e]
+    end.concat(super)
+  end
+end

data/examples/03_b_chained_plus_example.rb

@@ -0,0 +1,17 @@
+require 'pp'
+class RakeCommander::Custom::ChainedPlus < RakeCommander::Custom::Chained
+  desc 'A task+ you want to chain to'
+  task :chained_plus
+
+  option_remove :say
+  option :e, '--exit-on-error', TrueClass, desc: 'If it should just exit on "missing argument" error or raise an exception'
+  # Move option to the end, make **required** the argument (SOMETHING) as well as the option itself.
+  option :s, '--say SOMETHING', "It says 'something'", required: true
+
+  error_on_options error: RakeCommander::Options::Error::MissingArgument do |err, _argv, results, _leftovers|
+    msg  = "Parsed results when 'missing argument' error was raised"
+    msg << "\non option '#{err.option.name_full}'" if err.option
+    puts "#{msg} => #{results.pretty_inspect}"
+    !results[:e]
+  end
+end

data/examples/Examples.rake

@@ -0,0 +1,7 @@
+require 'dotenv'
+require 'dotenv/load'
+
+require_relative '../lib/rake-commander'
+RakeCommander::Patcher.debug = ENV['COMMANDER_DEBUG'] == "true"
+Dir["#{__dir__}/*_example.rb"].sort.each {|file| require_relative file }
+RakeCommander.self_load

data/examples/README.md

@@ -0,0 +1,79 @@
+## Examples
+
+  * `RakeCommander` is loaded from the repo branch you are checked out.
+
+The Rakefile `Examples.rake` has three lines that can serve as a guide. One were we require `rake-commander`, another where we define our `RakeCommander` classes, and one where we load them as actual `Rake` tasks.
+
+```ruby
+require_relative '../lib/rake-commander'
+RakeCommander::Patcher.debug = ENV['COMMANDER_DEBUG'] == "true"
+Dir["#{__dir__}/*_example.rb"].sort.each {|file| require_relative file }
+RakeCommander.self_load
+```
+
+  * To see the patches in action, you can add `COMMANDER_DEBUG=true` to a `.env` file
+
+```
+rake -T examples
+```
+
+### Basic Example
+
+```
+rake examples:basic -- -h
+rake examples:basic -- -z -e prod
+```
+
+### Chainer && Chained Example
+
+Two tasks where chainer calls chained through **a `shell` call to `rake`**.
+
+  * Read well the example before running it.
+
+```
+rake examples:chainer -- -h
+rake examples:chained -- -h
+```
+
+### Chainer Plus and Chained Plus Example
+
+Same as the previous example but these tasks inherit from the previous example, extending their behaviour and changing the options.
+
+
+```
+rake examples:chainer_plus -- -h
+rake examples:chained_plus -- -h
+```
+
+#### Error handling mixed with options
+
+The option `--exit-on-error` allows the error handler defined in `chained_plus` to decide if it should raise the error or just do an `exit 1`
+
+  * This is possible because the order that the options have been declared. Observe that they `--say` option has been removed and redefined **after** the option `--exit-on-error` has been defined.
+  * `OptionParser` **switches are processed in order** and, therefore, the error on `--say` only pops up after the `--exit on-error` option has been already parsed.
+
+While this will raise the error (with a trace):
+
+```
+$ rake examples:chainer_plus -- --chain --say
+Calling --> 'rake examples:chained_plus -- --say'
+Parsed results when 'missing argument' error was raised
+on option '--say SOMETHING' => {}
+rake aborted!
+RakeCommander::Options::Error::MissingArgument: (examples:chained_plus) missing required argument in option: --say SOMETHING (-s)
+< here back trace>
+Tasks: TOP => examples:chained_plus
+(See full trace by running task with --trace)
+* Failed to running 'rake examples:chained_plus -- --say'
+```
+
+This will only print the error with an `exit 1`:
+
+```
+$  rake examples:chainer_plus -- --chain --say --exit-on-error
+Calling --> 'rake examples:chained_plus -- --exit-on-error --say'
+Parsed results when 'missing argument' error was raised
+on option '--say SOMETHING' => {:e=>true}
+(examples:chained_plus) missing required argument in option: --say SOMETHING (-s)
+* Failed to running 'rake examples:chained_plus -- --exit-on-error --say'
+```