commander-openflighthpc 2.0.2 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a830a7be0e3333c0ae748dac3a27d0dfc5065790a0b4cbe15e750ca9956d391a
-  data.tar.gz: 1e2f63e323e25e41f78ae4991ddc0813cc03f6d4af3d9c41f99b92b1b8286f07
+  metadata.gz: 2de2c466191b2e6eec17147fa3f65c84910946e26986eac3b2b0542dc339ae6f
+  data.tar.gz: b4e6443b1c09467439509b0661d4c43c6c7c324d62d900ed111a41431d8cc742
 SHA512:
-  metadata.gz: b098f2e2c8be6c35cb026a0b0e77a7afc87b8f1132b31bef900237d48c43cce9d37690e98b48829fa76e2bb4dd291d19ae6d1ff82e70f2b42cdf52c530955f27
-  data.tar.gz: 255fcf43aa072382f0448cd49c177868e95e51607193972fcfcdbd7d8cd57f9111300fc9612416afaa74ac62aa58cce461c2ce43e33755473227872f52fc4612
+  metadata.gz: b5c5216978964ac2a4e100cd37d89835ca432372ee57f760f1f9d940d4319c2d3579f980d0adf6bbd9ef77c8de1c6b9476f1c4ac2f0e504a89e84f53d98c1086
+  data.tar.gz: 8b2650058b67db6b92d9ec19d924e171004019a6ddc730ed34f35144613bfd101509e45461b882e7213bcfcbd9899295cc10d32f5a2a76e24ac79b522d007ea8

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,42 +21,26 @@ 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
@@ -87,8 +69,8 @@ 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.option '--prefix STRING', 'Adds a prefix to bar'
+  c.option '--suffix STRING', 'Adds a suffix to bar'
   c.action do |args, options|
     options.default :prefix => '(', :suffix => ')'
     say "#{options.prefix}bar#{options.suffix}"
@@ -142,8 +124,8 @@ to set defaults in a clean manner for options which have not been set.
 
 ```ruby
 command :foo do |c|
-  c.option '--interval SECONDS', Integer, 'Interval in seconds'
-  c.option '--timeout SECONDS', Integer, 'Timeout in seconds'
+  c.option '--interval SECONDS', 'Interval in seconds'
+  c.option '--timeout SECONDS', 'Timeout in seconds'
   c.action do |args, options|
     options.default \
       :interval => 2,
@@ -239,74 +221,12 @@ 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:
-
-```ruby
-global_option('-c', '--config FILE', 'Load config data for your commands to use') { |file| ... }
-```
-
-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:
-
-```ruby
-program :help_formatter, :compact
-```
-
-This abstraction could be utilized to generate HTML documentation for your executable.
+WIP: Update globals behaviour
 
 ### 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

@@ -19,6 +19,7 @@ Gem::Specification.new do |s|
   s.require_paths = ['lib']
 
   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.traceable_error_handler(*args) do |new_args|
+        run(*new_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,72 @@ 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
-
-    def sub_command_group?
-      !!@sub_command_group
-    end
-
-    def sub_command_group=(value)
-      @sub_command_group = value
-      self.action { raise SubCommandGroupError } if value
-    end
+    # Causes the option parsing to be skipped. The flags will be passed
+    # down within the args instead
+    #
 
-    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
-      end
+    def skip_option_parsing(set = true)
+      @skip_option_parsing ||= set
     end
 
     ##
-    # Run the command with _args_.
-    #
-    # * parses options, call option blocks
-    # * invokes when_called proc
+    # Flags the command not to appear in general help text
     #
 
-    def run(*args)
-      call parse_options_and_call_procs(*args)
+    def hidden(set = true)
+      @hidden ||= set
     end
 
-    #:stopdoc:
-
-    ##
-    # Parses options and calls associated procs,
-    # returning the arguments remaining.
+    def inspect
+      "<Commander::Command:#{name}>"
+    end
 
-    def parse_options_and_call_procs(*args)
-      opt = @options.each_with_object(OptionParser.new) do |option, opts|
-        opts.on(*option[:args], &option[:proc])
-        opts
+    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
-      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)
+    end
+
+    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 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 optional_argument_count
+      syntax_parts.select do |part|
+        part[0] == '[' && part[-1] == ']'
+      end.length
     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 variable_arg?
+      syntax_parts.any? {|part| part[-4..-1] == '...]' || part[-3..-1] == '...'}
+    end
 
-    def option_proc(switches)
-      ->(value) { proxy_options << [Runner.switch_to_sym(switches.last), value] }
+    def required_argument_count
+      total_argument_count - optional_argument_count
     end
 
-    def inspect
-      "<Commander::Command:#{name}>"
+    def too_many_args?(args)
+      !variable_arg? && args.length > total_argument_count
+    end
+
+    def too_few_args?(args)
+      args.length < required_argument_count
     end
   end
 end