commander-openflighthpc 2.0.1 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3febc8843b2d974230cdb5b51f165e65cb268e2b42e193acbbb8de5bef54e107
-  data.tar.gz: eb05690fcc2789518b3bcb78720d863fcab1447ed38677022f86802f0d7a579c
+  metadata.gz: b083e62e1f920ec5cbd706e7fda06f9ea7377de383b36a9778c5b191e63b9fc4
+  data.tar.gz: a6de7d045ea35b3fefd4cc2ca77e64cd4bb5bd29e39eace7cd9047c372e684a0
 SHA512:
-  metadata.gz: 4090ea8ea6a812911cf32fbe3a018a422abc3c8ca72117c09ff1583d114529fa61bde7681e979a6bd7c1a793a7766531e15ff18877dc323f28b7f5e7dd0d10fc
-  data.tar.gz: 3327644d36fba11879f83b62468d2ebb3dd9e35ef24c2996878eaa63347c099104860f8498cbc84d8bde3aefdccbcdb912956d6fe459ff9e91038fc4b40a8783
+  metadata.gz: f37c40606f5ae5d2a0d05a13d0564e2f74d0a303a813bbf11c5f09eb37bdc53bbfd2541534a73c4fa399a8498428abff8fc3edf94f647447916a996af4168e99
+  data.tar.gz: 76a7afbab9913ff565e3d745f49ee532fd11cf84ad8624e858f309cdec856a6fe58b20bb9499ed882e9d1c3701620f2e8cb2cb0683db1128dbe2235e4b6b6f86

data/README.md

@@ -12,8 +12,6 @@ project that support the OpenFlightHPC tools.
 To ship a new release, do the following:
 
  * Increment the version number in `version.rb`
- * Run `rake build`
- * Run `rake release`
 
 Documentation from the upstream project follows.
 
@@ -23,77 +21,59 @@ Documentation from the upstream project follows.
 
 The complete solution for Ruby command-line executables.
 Commander bridges the gap between other terminal related libraries
-you know and love (OptionParser, HighLine), while providing many new
+you know and love (Slop, HighLine), while providing many new
 features, and an elegant API.
 
 ## Features
 
-* Easier than baking cookies
-* Parses options using OptionParser
-* Auto-populates struct with options ( no more `{ |v| options[:recursive] = v }` )
 * Auto-generates help documentation via pluggable help formatters
 * Optional default command when none is present
 * Global / Command level options
-* Packaged with two help formatters (Terminal, TerminalCompact)
+* Packaged with one help formatters (Terminal)
 * Imports the highline gem for interacting with the terminal
 * Adds additional user interaction functionality
 * Highly customizable progress bar with intuitive, simple usage
-* Multi-word command name support such as `drupal module install MOD`, rather than `drupal module_install MOD`
 * Sexy paging for long bodies of text
-* Support for MacOS text-to-speech
 * Command aliasing (very powerful, as both switches and arguments can be used)
-* Growl notification support for MacOS
 * Use the `commander` executable to initialize a commander driven program
 
 ## Installation
 
     $ gem install commander
 
-## Quick Start
-
-To generate a quick template for a commander app, run:
-
-    $ commander init yourfile.rb
-
-To generate a quick modular style template for a commander app, run:
-
-    $ commander init --modular yourfile.rb
-
 ## Example
 
-For more option examples view the `Commander::Command#option` method. Also
-an important feature to note is that action may be a class to instantiate,
-as well as an object, specifying a method to call, so view the RDoc for more information.
-
-### Classic style
-
 ```ruby
 require 'rubygems'
-require 'commander/import'
+require 'commander'
 
+class MyApplication
 # :name is optional, otherwise uses the basename of this executable
-program :name, 'Foo Bar'
-program :version, '1.0.0'
-program :description, 'Stupid command that prints foo or bar.'
-
-command :foo do |c|
-  c.syntax = 'foobar foo'
-  c.description = 'Displays foo'
-  c.action do |args, options|
-    say 'foo'
+  program :name, 'Foo Bar'
+  program :version, '1.0.0'
+  program :description, 'Stupid command that prints foo or bar.'
+
+  command :foo do |c|
+    c.syntax = 'foobar foo'
+    c.description = 'Displays foo'
+    c.action do |args, options|
+      say 'foo'
+    end
   end
-end
 
-command :bar do |c|
-  c.syntax = 'foobar bar [options]'
-  c.description = 'Display bar with optional prefix and suffix'
-  c.option '--prefix STRING', String, 'Adds a prefix to bar'
-  c.option '--suffix STRING', String, 'Adds a suffix to bar'
-  c.action do |args, options|
-    options.default :prefix => '(', :suffix => ')'
-    say "#{options.prefix}bar#{options.suffix}"
+  command :bar do |c|
+    c.syntax = 'foobar bar [options]'
+    c.description = 'Display bar with optional prefix and suffix'
+    c.slop.string '--prefix', 'Adds a prefix to bar'
+    c.slop.string '--suffix', 'Adds a suffix to bar', meta: 'CUSTOM_META'
+    c.action do |args, options, config|
+      options.default :prefix => '(', :suffix => ')'
+      say "#{options.prefix}bar#{options.suffix}"
+    end
   end
 end
+
+MyApplication.run!(ARGV) if $0 == __FILE__
 ```
 
 Example output:
@@ -106,49 +86,27 @@ $ foobar bar --suffix '}' --prefix '{'
 # => {bar}
 ```
 
-### Modular style
-
-**NOTE:** Make sure to use `require 'commander'` rather than `require 'commander/import'`, otherwise Commander methods will still be imported into the global namespace.
-
-```ruby
-require 'rubygems'
-require 'commander'
+## Commander Goodies
 
-class MyApplication
-  extend Commander::CLI
+### Option Parsing
 
-  program :name, 'Foo Bar'
-  program :version, '1.0.0'
-  program :description, 'Stupid command that prints foo or bar.'
+Option parsing is done using [Simple Lightweight Option Parsing](https://github.com/leejarvis/slop) which provides a rich interface for different option types. The main three being:
 
-  command :foo do |c|
-    c.syntax = 'foobar foo'
-    c.description = 'Displays foo'
-    c.action do |args, options|
-      say 'foo'
-    end
-  end
-end
-
-MyApplication.run!(ARGV) if $0 == __FILE__
 ```
+command do |c|
+  # Boolean Flag
+  c.slop.bool '--boolean-flag', 'Sets the :boolean_flag option to true'
 
-## Commander Goodies
-
-### Option Defaults
+  # String Value
+  c.slop.string '--string-value', 'Takes a string from the command line'
+  c.slop.string '--flag', 'Sets the meta variable to META', meta: 'META'
 
-The options struct passed to `#action` provides a `#default` method, allowing you
-to set defaults in a clean manner for options which have not been set.
+  # Interger Value
+  c.slop.integer '--integer-value', 'Takes the input and type casts it to an integer'
 
-```ruby
-command :foo do |c|
-  c.option '--interval SECONDS', Integer, 'Interval in seconds'
-  c.option '--timeout SECONDS', Integer, 'Timeout in seconds'
-  c.action do |args, options|
-    options.default \
-      :interval => 2,
-      :timeout  => 60
-  end
+  # Legacy syntax (boolean and string values only)
+  c.option '--legacy-bool', 'A boolean flag using the legacy syntax'
+  c.option '--legacy-string LEGACY_STRING', 'A string flag using the legacy syntax'
 end
 ```
 
@@ -239,74 +197,23 @@ Which will output the rest of the help doc, along with:
 
 ### Global Options
 
-Although most switches will be at the command level, several are available by
-default at the global level, such as `--version`, and `--help`. Using
-`#global_option` you can add additional global options:
+Global options work in a similar way to command level options. They both are configured using `Slop`. Global options are available on all commands. They are configure on the `global_slop` directive.
 
-```ruby
-global_option('-c', '--config FILE', 'Load config data for your commands to use') { |file| ... }
 ```
+class MyApplication
+  program :name, 'Foo Bar'
 
-This method accepts the same syntax as `Commander::Command#option` so check it out for documentation.
-
-All global options regardless of providing a block are accessable at the command level. This
-means that instead of the following:
-
-```ruby
-global_option('--verbose') { $verbose = true }
-...
-c.action do |args, options|
-  say 'foo' if $verbose
-...
-```
-
-You may:
-
-```ruby
-global_option '--verbose'
-...
-c.action do |args, options|
-  say 'foo' if options.verbose
-...
-```
-
-### Formatters
-
-Two core formatters are currently available, the default `Terminal` formatter
-as well as `TerminalCompact`. To utilize a different formatter simply use
-`:help_formatter` like below:
-
-```ruby
-program :help_formatter, Commander::HelpFormatter::TerminalCompact
-```
+  ...
 
-Or utilize the help formatter aliases:
+  global_slop.string '--custom-global', 'Available on all commands'
+end
 
-```ruby
-program :help_formatter, :compact
 ```
 
-This abstraction could be utilized to generate HTML documentation for your executable.
-
 ### Tracing
 
 WIP: Update OpenFlight --trace behaviour
 
-## Tips
-
-When adding a global or command option, `OptionParser` no longer implicitly adds a small
-switch unless explicitly stated.
-
-## ASCII Tables
-
-For feature rich ASCII tables for your terminal app check out the terminal-table gem at http://github.com/tj/terminal-table
-
-    +----------+-------+----+--------+-----------------------+
-    | Terminal | Table | Is | Wicked | Awesome               |
-    +----------+-------+----+--------+-----------------------+
-    |          |       |    |        | get it while its hot! |
-    +----------+-------+----+--------+-----------------------+
-
 ## Running Specifications
 
     $ rake spec

data/commander-openflighthpc.gemspec

@@ -18,7 +18,8 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
   s.require_paths = ['lib']
 
-  s.add_runtime_dependency('highline', '~> 1.7.2')
+  s.add_runtime_dependency('highline', '> 1.7.2')
+  s.add_runtime_dependency('slop', '~> 4.8')
   s.add_runtime_dependency('paint', '~> 2.1.0')
 
   s.add_development_dependency('rspec', '~> 3.2')

data/lib/commander.rb

@@ -23,11 +23,10 @@
 
 require 'highline'
 $terminal = HighLine.new
+
+require 'commander/error_handler'
 require 'commander/version'
-require 'commander/blank'
-require 'commander/core_ext'
-require 'commander/runner'
 require 'commander/command'
+require 'commander/runner'
 require 'commander/help_formatters'
-require 'commander/platform'
 require 'commander/cli'

data/lib/commander/cli.rb

@@ -1,16 +1,21 @@
+require 'slop'
+
 module Commander
   module CLI
     ##
     # Wrapper run command with error handling
     def run!(*args)
+      Commander::ErrorHandler.new(program(:name)).start do |handler|
+        run(*handler.parse_trace(*args))
+      end
+    end
+
+    def run(*args)
       instance = Runner.new(
         @program, commands, default_command,
-        global_options, aliases, args
+        global_slop, aliases, args
       )
       instance.run
-    rescue StandardError, Interrupt => e
-      $stderr.puts e.backtrace.reverse if args.include?('--trace')
-      error_handler(instance, e)
     end
 
     ##
@@ -24,8 +29,6 @@ module Commander
     #   program :description, 'Commander utility program.'
     #   program :help, 'Copyright', '2008 TJ Holowaychuk'
     #   program :help, 'Anything', 'You want'
-    #   program :help_formatter, :compact
-    #   program :help_formatter, Commander::HelpFormatter::TerminalCompact
     #
     #   # Get data
     #   program :name # => 'Commander'
@@ -35,6 +38,7 @@ module Commander
     #   :version         (required) Program version triple, ex: '0.0.1'
     #   :description     (required) Program description
     #   :name            Program name, defaults to basename of executable
+    #   :config          An optional argument to be passed into the action
     #   :help_formatter  Defaults to Commander::HelpFormatter::Terminal
     #   :help            Allows addition of arbitrary global help blocks
     #   :help_paging     Flag for toggling help paging
@@ -80,37 +84,14 @@ module Commander
 
     ##
     # Hash of Global Options
-    def global_options
-      @global_options ||= begin
-        @global_options = [] # Allows Recursive - Refactor
-        global_option('-h', '--help', 'Display help documentation') do
-          args = @args - %w(-h --help)
-          command(:help).run(*args)
-          exit 0
-        end
-        global_option('--version', 'Display version information') do
-          say version
-          exit 0
-        end
+    #
+    def global_slop
+      @global_slop ||= Slop::Options.new.tap do |slop|
+        slop.bool '-h', '--help', 'Display help documentation'
+        slop.bool '--version', 'Display version information'
       end
     end
 
-    ##
-    # Add a global option; follows the same syntax as Command#option
-    # This would be used for switches such as --version
-    # NOTE: --trace is special and does not appear in the help
-    # It is intended for debugging purposes
-
-    def global_option(*args, &block)
-      switches, description = Runner.separate_switches_from_description(*args)
-      global_options << {
-        args: args,
-        proc: block,
-        switches: switches,
-        description: description,
-      }
-    end
-
     ##
     # Define and get a command by name
     #
@@ -134,47 +115,5 @@ module Commander
       commands[alias_name.to_s] = command name
       aliases[alias_name.to_s] = args
     end
-
-    def error_handler(runner, e)
-      error_msg = "#{Paint[runner.program(:name), '#2794d8']}: #{Paint[e.to_s, :red, :bright]}"
-      exit_code = e.respond_to?(:exit_code) ?  e.exit_code.to_i : 1
-      case e
-      when OptionParser::InvalidOption,
-           Commander::Runner::InvalidCommandError,
-           Commander::Patches::CommandUsageError
-        # Display the error message for a specific command. Most likely due to
-        # invalid command syntax
-        if cmd = runner.active_command
-          $stderr.puts error_msg
-          $stderr.puts "\nUsage:\n\n"
-          runner.command('help').run(cmd.name)
-        # Display the main app help text when called without `--help`
-        elsif runner.args_without_command_name.empty?
-          $stderr.puts "Usage:\n\n"
-          runner.command('help').run(:error)
-        # Display the main app help text when called with arguments. Mostly
-        # likely an invalid syntax error
-        else
-          $stderr.puts error_msg
-          $stderr.puts "\nUsage:\n\n"
-          runner.command('help').run(:error)
-        end
-        exit_code = 254
-      # Display the help text for sub command groups when called without `--help`
-      when SubCommandGroupError
-        if cmd = runner.active_command
-          $stderr.puts "Usage:\n\n"
-          runner.command('help').run(cmd.name)
-        end
-        exit_code = 254
-      when Interrupt
-        $stderr.puts 'Received Interrupt!'
-        exit_code = 255
-      # Catch all error message for all other issues
-      else
-        $stderr.puts error_msg
-      end
-      exit(exit_code)
-    end
   end
 end

data/lib/commander/command.rb

@@ -1,60 +1,37 @@
-require 'optparse'
-require 'commander/patches/implicit-short-tags'
-require 'commander/patches/decimal-integer'
-require 'commander/patches/validate_inputs'
-require 'commander/patches/help_formatter_binding'
-require 'commander/patches/priority_sort'
-
-OptionParser.prepend Commander::Patches::ImplicitShortTags
-OptionParser.prepend Commander::Patches::DecimalInteger
+require 'slop'
 
 module Commander
-  class SubCommandGroupError < StandardError; end
-
   class Command
-    prepend Patches::ValidateInputs
-    prepend Patches::PrioritySort
-
-    attr_accessor :name, :examples, :syntax, :description
-    attr_accessor :summary, :proxy_options, :options, :hidden
-    attr_reader :sub_command_group
+    class CommandUsageError < StandardError; end
 
-    alias sub_command= hidden=
-    alias sub_command hidden
+    attr_accessor :name, :examples, :syntax, :description, :priority
+    attr_accessor :summary, :options
 
     ##
-    # Options struct.
-
-    class Options
-      include Blank
-
-      def initialize
-        @table = {}
-      end
+    # Initialize new command with specified _name_.
 
-      def __hash__
-        @table
-      end
+    def initialize(name)
+      @name, @examples, @when_called = name.to_s, [], []
+      @options = []
+    end
 
-      def method_missing(meth, *args)
-        meth.to_s =~ /=$/ ? @table[meth.to_s.chop.to_sym] = args.first : @table[meth]
-      end
+    # Allows the commands to be sorted via priority
+    def <=>(other)
+      # Different classes can not be compared and thus are considered
+      # equal in priority
+      return 0 unless self.class == other.class
 
-      def default(defaults = {})
-        @table = defaults.merge! @table
-      end
+      # Sort firstly based on the commands priority
+      comp = (self.priority || 0) <=> (other.priority || 0)
 
-      def inspect
-        "<Commander::Command::Options #{ __hash__.map { |k, v| "#{k}=#{v.inspect}" }.join(', ') }>"
-      end
+      # Fall back on name comparison if priority is equal
+      comp == 0 ? self.name <=> other.name : comp
     end
 
-    ##
-    # Initialize new command with specified _name_.
-
-    def initialize(name)
-      @name, @examples, @when_called = name.to_s, [], []
-      @options, @proxy_options = [], []
+    def run!(args, opts, config)
+      assert_correct_number_of_args!(args)
+      callee = @when_called.dup
+      callee.shift&.send(callee.shift || :call, args, opts, config)
     end
 
     ##
@@ -77,59 +54,32 @@ module Commander
     ##
     # Add an option.
     #
-    # Options are parsed via OptionParser so view it
-    # for additional usage documentation. A block may optionally be
-    # passed to handle the option, otherwise the _options_ struct seen below
-    # contains the results of this option. This handles common formats such as:
-    #
-    #   -h, --help          options.help           # => bool
-    #   --[no-]feature      options.feature        # => bool
-    #   --large-switch      options.large_switch   # => bool
-    #   --file FILE         options.file           # => file passed
-    #   --list WORDS        options.list           # => array
-    #   --date [DATE]       options.date           # => date or nil when optional argument not set
-    #
-    # === Examples
-    #
-    #   command :something do |c|
-    #     c.option '--recursive', 'Do something recursively'
-    #     c.option '--file FILE', 'Specify a file'
-    #     c.option('--info', 'Display info') { puts "handle with block" }
-    #     c.option '--[no-]feature', 'With or without feature'
-    #     c.option '--list FILES', Array, 'List the files specified'
-    #
-    #     c.when_called do |args, options|
-    #       do_something_recursively if options.recursive
-    #       do_something_with_file options.file if options.file
-    #     end
-    #   end
-    #
-    # === Help Formatters
-    #
-    # This method also parses the arguments passed in order to determine
-    # which were switches, and which were descriptions for the
-    # option which can later be used within help formatters
-    # using option[:switches] and option[:description].
-    #
-    # === Input Parsing
-    #
-    # Since Commander utilizes OptionParser you can pre-parse and evaluate
-    # option arguments. Simply require 'optparse/time', or 'optparse/date', as these
-    # objects must respond to #parse.
-    #
-    #   c.option '--time TIME', Time
-    #   c.option '--date [DATE]', Date
+    # This is the legacy `option` method which now wraps `slop`
     #
 
     def option(*args, default: nil, &block)
+      # Split the description from the switchers
       switches, description = Runner.separate_switches_from_description(*args)
-      proc = block || option_proc(switches)
-      @options << {
-        args: args,
-        proc: proc,
-        switches: switches,
-        description: description
-      }.tap { |o| o[:default] = default unless default.nil? }
+
+      # Other switches are normally short tags and something like below
+      # In this case the VALUE needs to be ignored
+      # -k VALUE
+      other_switches = switches.dup.tap(&:pop).map do |string|
+        string.split(' ').first
+      end
+
+      long_switch, meta = switches.last.split(' ', 2)
+
+      # The meta flag is the VALUE from denotes if its a boolean or
+      # string method
+      method = meta.nil? ? :bool : :string
+
+      # Adds the option to Slop
+      slop.send(method, *other_switches, long_switch, description, default: default)
+    end
+
+    def slop
+      @slop ||= Slop::Options.new
     end
 
     ##
@@ -139,16 +89,10 @@ module Commander
     # === Examples
     #
     #   # Simple block handling
-    #   c.when_called do |args, options|
+    #   c.when_called do |args, options, config|
     #      # do something
     #   end
     #
-    #   # Create inst of Something and pass args / options
-    #   c.when_called MyLib::Command::Something
-    #
-    #   # Create inst of Something and use arbitrary method
-    #    c.when_called MyLib::Command::Something, :some_method
-    #
     #   # Pass an object to handle callback (requires method symbol)
     #   c.when_called SomeObject, :some_method
     #
@@ -160,102 +104,63 @@ module Commander
     alias action when_called
 
     ##
-    # Handles displaying subcommand help. By default it will set the action to
-    # display the subcommand if the action hasn't already been set
+    # Flags the command not to appear in general help text
+    #
 
-    def sub_command_group?
-      !!@sub_command_group
+    def hidden(set = true)
+      @hidden ||= set
     end
 
-    def sub_command_group=(value)
-      @sub_command_group = value
-      self.action { raise SubCommandGroupError } if value
+    def inspect
+      "<Commander::Command:#{name}>"
     end
 
-    def configure_sub_command(runner)
-      @sub_command_group = true
-      if @when_called.empty?
-        action do |args, opts|
-          unless args.empty?
-            raise Commander::Runner::InvalidCommandError,
-                  "unrecognized subcommand '#{args[0]}'"
-          end
-          runner.command('help').run(ARGV[0])
-        end
+    def assert_correct_number_of_args!(args)
+      return if primary_command_word == 'help'
+      too_many = too_many_args?(args)
+      if too_many
+        raise CommandUsageError, "excess arguments for command '#{primary_command_word}'"
+      elsif too_few_args?(args)
+        raise CommandUsageError, "insufficient arguments for command '#{primary_command_word}'"
       end
     end
 
-    ##
-    # Run the command with _args_.
-    #
-    # * parses options, call option blocks
-    # * invokes when_called proc
-    #
-
-    def run(*args)
-      call parse_options_and_call_procs(*args)
-    end
-
-    #:stopdoc:
-
-    ##
-    # Parses options and calls associated procs,
-    # returning the arguments remaining.
-
-    def parse_options_and_call_procs(*args)
-      opt = @options.each_with_object(OptionParser.new) do |option, opts|
-        opts.on(*option[:args], &option[:proc])
-        opts
-      end
-      default_opt = @options.each_with_object([]) do |h, arr|
-        if h.key?(:default)
-          arr.push(h[:switches][0].split[0])
-          arr.push(h[:default].to_s)
+    def syntax_parts
+      @syntax_parts ||= syntax.split.tap do |parts|
+        while part = parts.shift do
+          break if part == primary_command_word || parts.length == 0
         end
       end
-      opt.parse! default_opt
-      opt.parse! args
     end
 
-    ##
-    # Call the commands when_called block with _args_.
+    def primary_command_word
+      name.split.last
+    end
 
-    def call(args = [])
-      callee = @when_called.dup
-      object = callee.shift
-      meth = callee.shift || :call
-      options = proxy_option_struct
-      case object
-      when Proc then object.call(args, options)
-      when Class then meth != :call ? object.new.send(meth, args, options) : object.new(args, options)
-      else object.send(meth, args, options) if object
-      end
+    def total_argument_count
+      syntax_parts.length
     end
 
-    ##
-    # Creates an Options instance populated with the option values
-    # collected by the #option_proc.
+    def optional_argument_count
+      syntax_parts.select do |part|
+        part[0] == '[' && part[-1] == ']'
+      end.length
+    end
 
-    def proxy_option_struct
-      proxy_options.each_with_object(Options.new) do |(option, value), options|
-        # options that are present will evaluate to true
-        value = true if value.nil?
-        options.__send__ :"#{option}=", value
-        options
-      end
+    def variable_arg?
+      syntax_parts.any? {|part| part[-4..-1] == '...]' || part[-3..-1] == '...'}
     end
 
-    ##
-    # Option proxy proc used when a block is not explicitly passed
-    # via the #option method. This allows commander to auto-populate
-    # and work with option values.
+    def required_argument_count
+      total_argument_count - optional_argument_count
+    end
 
-    def option_proc(switches)
-      ->(value) { proxy_options << [Runner.switch_to_sym(switches.last), value] }
+    def too_many_args?(args)
+      !variable_arg? && args.length > total_argument_count
     end
 
-    def inspect
-      "<Commander::Command:#{name}>"
+    def too_few_args?(args)
+      args.length < required_argument_count
     end
   end
 end