slop 1.8.0 → 1.9.0

data/CHANGES.md

@@ -1,3 +1,18 @@
+TBA
+---
+
+* Add command completion and support for an error message when ambiguous
+  commands are used
+* Add command aliases
+* Fix: Ensure parsed elements are removed from original arguments when using
+  `:multiple_switches`
+* Ensure anything after `--` is parsed as an argument and not option even
+  if prefixed with `/--?/`
+* Performance improvements when making many calls to `Slop#option?` for
+  checking an options presence (Rob Gleeson)
+* Ensure `execute` passes command arguments to the block
+* Support for summary and description (Denis Defreyne)
+
 1.8.0 (2011-06-12)
 ------------------
 

data/lib/slop.rb

@@ -16,7 +16,7 @@ class Slop
   class InvalidOptionError < RuntimeError; end
 
   # @return [String] The current version string
-  VERSION = '1.8.0'
+  VERSION = '1.9.0'
 
   # Parses the items from a CLI format into a friendly object
   #
@@ -51,9 +51,22 @@ class Slop
   #   @param [String] string The text to set the banner to
   attr_writer :banner
 
+  # @overload summary=(string)
+  #   Set the summary
+  #   @param [String] string The text to set the summary to
+  attr_writer :summary
+
+  # @overload description=(string)
+  #   Set the description
+  #   @param [String] string The text to set the description to
+  attr_writer :description
+
   # @return [Integer] The length of the longest flag slop knows of
   attr_accessor :longest_flag
 
+  # @return [Array] A list of aliases this command uses
+  attr_reader :aliases
+
   # @option opts [Boolean] :help
   #   * Automatically add the `help` option
   #
@@ -91,6 +104,13 @@ class Slop
   # @option opts [Boolean] :arguments (false)
   #   * Set to true to enable all specified options to accept arguments
   #     by default
+  #
+  # @option opts [Array] :aliases ([])
+  #   * Primary uses by commands to implement command aliases
+
+  # @option opts [Boolean] :completion (true)
+  #   * When true, commands will be auto completed. Ie `foobar` will be
+  #     executed simply when `foo` `fo` or `foob` are used
   def initialize(*opts, &block)
     sloptions = opts.last.is_a?(Hash) ? opts.pop : {}
     sloptions[:banner] = opts.shift if opts[0].respond_to? :to_str
@@ -103,13 +123,16 @@ class Slop
     @longest_flag = 0
     @invalid_options = []
 
+    @aliases = Array(sloptions[:aliases] || sloptions[:alias])
     @banner = sloptions[:banner]
     @strict = sloptions[:strict]
     @ignore_case = sloptions[:ignore_case]
     @multiple_switches = sloptions[:multiple_switches]
     @autocreate = sloptions[:autocreate]
+    @completion = sloptions.fetch(:completion, true)
     @arguments = sloptions[:arguments]
     @on_empty = sloptions[:on_empty]
+    @io = sloptions.fetch(:io, $stderr)
     @on_noopts = sloptions[:on_noopts] || sloptions[:on_optionless]
     @sloptions = sloptions
 
@@ -119,7 +142,7 @@ class Slop
 
     if sloptions[:help]
       on :h, :help, 'Print this help message', :tail => true do
-        (sloptions[:io] || $stderr).puts help
+        @io.puts help
         exit unless sloptions[:exit_on_help] == false
       end
     end
@@ -138,6 +161,32 @@ class Slop
     @banner
   end
 
+  # Set or return the summary
+  #
+  # @param [String] text Displayed summary text
+  # @example
+  #   opts = Slop.parse do
+  #     summary "do stuff with more stuff"
+  #   end
+  # @return [String] The current summary
+  def summary(text=nil)
+    @summary = text if text
+    @summary
+  end
+
+  # Set or return the description
+  #
+  # @param [String] text Displayed description text
+  # @example
+  #   opts = Slop.parse do
+  #     description "This command does a lot of stuff with other stuff."
+  #   end
+  # @return [String] The current description
+  def description(text=nil)
+    @description = text if text
+    @description
+  end
+
   # Parse a list of options, leaving the original Array unchanged
   #
   # @param [Array] items A list of items to parse
@@ -226,6 +275,10 @@ class Slop
     slop = Slop.new @sloptions.merge options
     @commands[label] = slop
 
+    Array(options[:aliases] || options[:alias]).each do |a|
+      @commands[a] = @commands[label]
+    end
+
     if block_given?
       block.arity == 1 ? yield(slop) : slop.instance_eval(&block)
     end
@@ -273,15 +326,15 @@ class Slop
   #   end
   #   opts.parse %w[foo --verbose] #=> true
   #
-  # @param [Object, #call] obj The object to be triggered when this command
+  # @param [Array] args The list of arguments to send to this command
   #   is invoked
   # @since 1.8.0
   # @yields [Slop] an instance of Slop for this command
-  def execute(obj=nil, &block)
-    if obj || block_given?
-      @execution_block = obj || block
+  def execute(args=[], &block)
+    if block_given?
+      @execution_block = block
     elsif @execution_block.respond_to?(:call)
-      @execution_block.call(self)
+      @execution_block.call(self, args)
     end
   end
 
@@ -310,7 +363,13 @@ class Slop
   # @return [Boolean] true if this option is present, false otherwise
   def method_missing(meth, *args, &block)
     super unless meth.to_s[-1, 1] == '?'
-    present? meth.to_s.chomp '?'
+    present = present? meth.to_s.chomp '?'
+
+    (class << self; self; end).instance_eval do
+      define_method(meth) { present }
+    end
+
+    present
   end
 
   # Check if an option is specified in the parsed list
@@ -335,8 +394,15 @@ class Slop
   #  puts opts
   # @return [String] Help text.
   def to_s
-    banner = "#{@banner}\n" if @banner
-    (banner || '') + options.to_help
+    parts = []
+
+    parts << banner if banner
+    parts << summary if summary
+    parts << wrap_and_indent(description, 80, 4) if description
+    parts << "options:" if options.size > 0
+    parts << options.to_help if options.size > 0
+
+    parts.join("\n\n")
   end
   alias :help :to_s
 
@@ -374,13 +440,24 @@ class Slop
     end
 
     trash = []
+    ignore_all = false
 
     items.each_with_index do |item, index|
       item = item.to_s
       flag = item.sub(/\A--?/, '')
+
+      if item == '--'
+        trash << index
+        ignore_all = true
+      end
+
+      next if ignore_all
       autocreate(flag, index, items) if @autocreate
       option, argument = extract_option(item, flag)
-      next if @multiple_switches
+      if @multiple_switches && !option
+        trash << index if item[/\A-[^-]/]
+        next
+      end
 
       if option
         option.count += 1
@@ -449,6 +526,31 @@ class Slop
     end
   end
 
+  def wrap_and_indent(string, width, indentation)
+    # Wrap and indent each paragraph
+    string.lines.map do |paragraph|
+      # Initialize
+      lines = []
+      line = ''
+
+      # Split into words
+      paragraph.split(/\s/).each do |word|
+        # Begin new line if it's too long
+        if (line + ' ' + word).length >= width
+          lines << line
+          line = ''
+        end
+
+        # Add word to line
+        line << (line == '' ? '' : ' ' ) + word
+      end
+      lines << line
+
+      # Join lines
+      lines.map { |l| ' '*indentation + l }.join("\n")
+    end.join("\n")
+  end
+
   def extract_option(item, flag)
     if item[0, 1] == '-'
       option = @options[flag]
@@ -474,12 +576,28 @@ class Slop
   end
 
   def execute_command(items, delete)
-    command = @commands.keys.find { |cmd| cmd.to_s == items[0].to_s }
+    str = items[0]
+
+    if str
+      command = @commands.keys.find { |c| c.to_s == str.to_s }
+
+      if !command && @completion
+        cmds = @commands.keys.select { |c| c.to_s[0, str.length] == str }
+
+        if cmds.size > 1
+          @io.puts "Command '#{str}' is ambiguous:"
+          @io.puts "  " + cmds.map(&:to_s).sort.join(', ')
+        else
+          command = cmds.shift
+        end
+      end
+    end
+
     if command
       items.shift
       opts = @commands[command]
       delete ? opts.parse!(items) : opts.parse(items)
-      opts.execute
+      opts.execute(items.reject { |i| i == '--' })
     end
   end
 
@@ -493,9 +611,9 @@ class Slop
   def clean_options(args)
     options = []
     extras = {}
-    extras[:as] = args.find {|c| c.is_a? Class }
+    extras[:as] =args.find {|c| c.is_a? Class }
     args.delete(extras[:as])
-    extras.delete(:as) unless extras[:as]
+    extras.delete(:as) if extras[:as].nil?
 
     short = args.first.to_s.sub(/\A--?/, '')
     if short.size == 1

data/slop.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = 'slop'
-  s.version = '1.8.0'
+  s.version = '1.9.0'
   s.summary = 'Option gathering made easy'
   s.description = 'A simple DSL for gathering options and parsing the command line'
   s.author = 'Lee Jarvis'

data/test/commands_test.rb

@@ -75,15 +75,77 @@ class CommandsTest < TestCase
     slop = Slop.new
     slop.command :foo do
       on :v, :verbose
-      execute { |o| foo = o.verbose? }
+      execute { |o, a| foo = o.verbose? }
     end
     slop.command :bar do
       on :v, :verbose
-      execute { |o| bar = o.verbose? }
+      execute { |o, a| bar = o.verbose? }
     end
     slop.parse %w[ foo --verbose ]
 
     assert foo
     refute bar
   end
+
+  test 'executing blocks and command arguments' do
+    opts = args = nil
+    slop = Slop.new
+    slop.command :foo do
+      execute do |o, a|
+        opts = o
+        args = a
+      end
+    end
+    slop.parse %w[ foo bar baz ]
+
+    assert_equal %w[ bar baz ], args
+    assert_kind_of Slop, opts
+  end
+
+  test 'executing nested commands' do
+    args = nil
+    slop = Slop.new
+    slop.command :foo do
+      command :bar do
+        execute { |o, a| args = a }
+      end
+    end
+    slop.parse %w[ foo bar baz ]
+
+    assert_equal %w[ baz ], args
+  end
+
+  test 'aliases' do
+    slop = Slop.new
+    slop.command :foo, :alias => :bar
+    slop.command :baz, :aliases => [:lorem, :ipsum]
+
+    assert_equal [:bar], slop.commands[:foo].aliases
+    assert_equal [:lorem, :ipsum], slop.commands[:baz].aliases
+
+    assert_raises(ArgumentError) { slop.command :lorem }
+  end
+
+  test 'command completion' do
+    foo = bar = bara = nil
+    slop = Slop.new
+    slop.command(:foo) { execute { foo = true } }
+    slop.parse %w[ fo ]
+    assert foo
+
+    slop.command(:bar) { execute { bar = true } }
+    slop.command(:bara) { execute { bara = true } }
+    slop.parse %w[ bar ]
+    assert bar
+    refute bara
+  end
+
+  test 'ambiguous command completion' do
+    io = StringIO.new
+    slop = Slop.new(:io => io)
+    slop.command :bar
+    slop.command :baz
+    slop.parse %w[ ba ]
+    assert_equal "Command 'ba' is ambiguous:\n  bar, baz\n", io.string
+  end
 end

data/test/helper.rb

@@ -8,15 +8,6 @@ require 'stringio'
 
 class TestCase < MiniTest::Unit::TestCase
   def self.test(name, &block)
-    test_name = "test_#{name.gsub(/\s+/, '_')}".to_sym
-    defined = instance_method(test_name) rescue false
-    raise "#{test_name} is already defined in #{self}" if defined
-    if block_given?
-      define_method(test_name, &block)
-    else
-      define_method(test_name) do
-        flunk "No implementation provided for #{name}"
-      end
-    end
+    define_method("test_#{name.gsub(/\W/, '_')}", &block) if block
   end
 end

data/test/slop_test.rb

@@ -84,6 +84,16 @@ class SlopTest < TestCase
 
     assert_raises(Slop::InvalidOptionError, /d/)   { slop.parse %w/-abcd/ }
     assert_raises(Slop::MissingArgumentError, /z/) { slop.parse %w/-abcz/ }
+
+    slop = Slop.new(:multiple_switches)
+    slop.on :a
+    slop.on :f, true
+    args = %w[-abc -f foo bar]
+    slop.parse! args
+
+    assert_equal %w[ bar ], args
+    assert_equal 'foo', slop[:f]
+    assert slop[:a]
   end
 
   test 'passing a block' do
@@ -140,6 +150,31 @@ class SlopTest < TestCase
     assert_equal "foo bar", slop.banner
   end
 
+  test 'setting the summary' do
+    slop = Slop.new
+    slop.banner = "foo bar"
+    slop.summary = "does stuff"
+
+    assert_equal "foo bar\n\ndoes stuff", slop.to_s
+  end
+
+  test 'setting the description' do
+    slop = Slop.new
+    slop.banner     = "foo bar"
+    slop.summary = "does stuff"
+    slop.description  = "This does stuff."
+
+    assert_equal "foo bar\n\ndoes stuff\n\n    This does stuff.", slop.to_s
+  end
+
+  test 'setting the description without matching summary' do
+    slop = Slop.new
+    slop.banner     = "foo bar"
+    slop.description  = "This does stuff."
+
+    assert_equal "foo bar\n\n    This does stuff.", slop.to_s
+  end
+
   test 'storing long option lengths' do
     slop = Slop.new
     assert_equal 0, slop.longest_flag
@@ -440,6 +475,15 @@ class SlopTest < TestCase
     assert_equal '        --bar [HELLO] ', opts.options[:bar].to_s
   end
 
+  test 'not parsing options if after --' do
+    args = %w[ foo bar -- --foo bar ]
+    opts = Slop.parse!(args) do
+      on :foo, true
+    end
+
+    assert_equal %w[ foo bar --foo bar ], args
+  end
+
   test 'inline classes' do
     opts = Slop.new do
       on :foo, Array, true
@@ -451,4 +495,21 @@ class SlopTest < TestCase
     assert_equal :hello, opts[:bar]
   end
 
+  test 'wrap and indent' do
+    slop = Slop.new
+
+    assert_equal(
+      "Lorem ipsum dolor sit amet, consectetur\n" +
+      "adipisicing elit, sed do eiusmod tempor\n" +
+      "incididunt ut labore et dolore magna\n" +
+      "aliqua.",
+      slop.send(:wrap_and_indent, "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", 40, 0))
+
+    assert_equal(
+      "    Lorem ipsum dolor sit amet,\n" +
+      "    consectetur adipisicing elit, sed\n" +
+      "    do eiusmod tempor incididunt ut\n" +
+      "    labore et dolore magna aliqua.",
+      slop.send(:wrap_and_indent, "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", 36, 4))
+  end
 end

metadata

@@ -1,8 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: slop
 version: !ruby/object:Gem::Version 
+  hash: 51
   prerelease: 
-  version: 1.8.0
+  segments: 
+  - 1
+  - 9
+  - 0
+  version: 1.9.0
 platform: ruby
 authors: 
 - Lee Jarvis
@@ -10,7 +15,8 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-06-12 00:00:00 Z
+date: 2011-06-15 00:00:00 +01:00
+default_executable: 
 dependencies: []
 
 description: A simple DSL for gathering options and parsing the command line
@@ -37,6 +43,7 @@ files:
 - test/helper.rb
 - test/option_test.rb
 - test/slop_test.rb
+has_rdoc: true
 homepage: http://github.com/injekt/slop
 licenses: []
 
@@ -50,17 +57,23 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.8.5
+rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
 summary: Option gathering made easy