slop 1.1.0 → 1.2.0

data/README.md

@@ -37,8 +37,28 @@ You can also return your options as a Hash
 
 	opts.to_hash #=> {'name' => 'Lee Jarvis', 'verbose' => true, 'age' => nil, 'sex' => 'male'}
 
+	# Symbols
+	opts.to_hash(true) #=> {:name => 'Lee Jarvis', :verbose => true, :age => nil, :sex => 'male'}
+
+If you pass a block to `Slop#parse`, Slop will yield non-options as
+they're found, just like
+[OptionParser](http://rubydoc.info/stdlib/optparse/1.9.2/OptionParser:order)
+does it.
+
+	opts = Slop.new do
+	  on :n, :name, :optional => false
+	end
+
+	opts.parse do |arg|
+	  puts arg
+	end
+
+	# if ARGV is `foo --name Lee bar`
+	foo
+	bar
+
 If you don't like the method `on` (because it sounds like the option **expects**
-a callback), you can use the `opt` or `option` alternatives.
+a block), you can use the `opt` or `option` alternatives.
 
 	on :v, :verbose
 	opt :v, :verbose

data/lib/slop.rb

@@ -5,6 +5,8 @@ class Slop
   include Enumerable
 
   class MissingArgumentError < ArgumentError; end
+  class InvalidArgumentError < ArgumentError; end
+  class InvalidOptionError < ArgumentError; end
 
   # Parses the items from a CLI format into a friendly object.
   #
@@ -21,25 +23,42 @@ class Slop
   #  program.rb --verbose -n 'Emily' -a 25
   # @see Slop#banner
   # @see Slop#option
-  def self.parse(items=ARGV, &block)
-    slop = new(&block)
-    slop.parse items
-    slop
+  def self.parse(items=ARGV, options={}, &block)
+    initialize_and_parse(items, false, options, &block)
+  end
+
+  # Identical to {Slop.parse}, but removes parsed options from the original Array.
+  #
+  # @yield Specify available CLI arguments using Slop# methods such as Slop#banner and Slop#option
+  # @return [Slop] Returns an instance of Slop.
+  def self.parse!(items=ARGV, options={}, &block)
+    initialize_and_parse(items, true, options, &block)
   end
 
   attr_reader :options
   attr_writer :banner
   attr_accessor :longest_flag
 
-  def initialize(&block)
+  # @param [Hash] options
+  # @option options [Boolean] :help Automatically add the `help` option
+  # @option options [Boolean] :strict Strict mode raises when a non listed
+  #   option is found, false by default
+  def initialize(options={}, &block)
     @options = Options.new
     @banner = nil
     @longest_flag = 0
-    @items = []
+    @strict = options[:strict]
 
     if block_given?
       block.arity == 1 ? yield(self) : instance_eval(&block)
     end
+
+    if options[:help]
+      on :h, :help, 'Print this help message', :tail => true do
+        puts help
+        exit
+      end
+    end
   end
 
   # Set or return banner text.
@@ -59,21 +78,15 @@ class Slop
   # Parse a list of options, leaving the original Array unchanged.
   #
   # @param items
-  def parse(items=ARGV)
-    @items = parse_items items, block_given?
-
-    if block_given?
-      @items.each { |item| yield item }
-    end
-
-    @items
+  def parse(items=ARGV, &block)
+    parse_items items, &block
   end
 
   # Parse a list of options, removing parsed options from the original Array.
   #
-  # @parse items
-  def parse!(items=ARGV)
-    parse_items items, true
+  # @param items
+  def parse!(items=ARGV, &block)
+    parse_items items, true, &block
   end
 
   # Enumerable interface
@@ -169,46 +182,85 @@ class Slop
   # @see Slop#banner
   def to_s
     banner = "#{@banner}\n" if @banner
-    (banner || '') + options.map(&:to_s).join("\n")
+    (banner || '') + options.to_help
   end
   alias :help :to_s
 
 private
 
-  def parse_items(items, delete=false)
+  def self.initialize_and_parse(items, delete, options, &block)
+    if items.is_a?(Hash) && options.empty?
+      options = items
+      items = ARGV
+    end
+
+    slop = new(options, &block)
+    delete ? slop.parse!(items) : slop.parse(items)
+    slop
+  end
+
+  def parse_items(items, delete=false, &block)
     trash = []
 
     items.each do |item|
-      flag = item.to_s.sub(/^--?/, '')
+      item = item.to_s
+      flag = item.sub(/^--?/, '')
       option = @options[flag]
 
+      if !option && item =~ /^-[^-]/
+        flag, argument = flag.split('', 2)
+        option = @options[flag]
+      end
+
       if option
-        trash << item if delete
+        trash << item
         option.argument_value = true
 
         if option.expects_argument? || option.accepts_optional_argument?
-          argument = items.at(items.index(item) + 1)
-          trash << argument if delete
+          argument ||= items.at(items.index(item) + 1)
+          trash << argument
 
           if argument
+            check_matching_argument(option, argument)
             option.argument_value = argument
             option.callback.call option.argument_value if option.callback
           else
             option.argument_value = nil
-            if option.accepts_optional_argument?
-              option.callback.call nil if option.callback
-            else
-              raise MissingArgumentError,
-                "'#{flag}' expects an argument, none given"
-            end
+            check_optional_argument(option, flag)
           end
         elsif option.callback
           option.callback.call nil
         end
+      else
+        check_invalid_option(item, flag)
+        block.call(item) if block_given? && !trash.include?(item)
       end
     end
 
-    items.delete_if { |item| trash.include? item }
+    items.delete_if { |item| trash.include? item } if delete
+    items
+  end
+
+  def check_matching_argument(option, argument)
+    if option.match && !argument.match(option.match)
+      raise InvalidArgumentError,
+        "'#{argument}' does not match #{option.match.inspect}"
+    end
+  end
+
+  def check_optional_argument(option, flag)
+    if option.accepts_optional_argument?
+      option.callback.call nil if option.callback
+    else
+      raise MissingArgumentError,
+        "'#{flag}' expects an argument, none given"
+    end
+  end
+
+  def check_invalid_option(item, flag)
+    if item[/^--?/] && @strict
+      raise InvalidOptionError, "Unknown option -- '#{flag}'"
+    end
   end
 
   def clean_options(args)

data/lib/slop/option.rb

@@ -1,5 +1,8 @@
 class Slop
   class Options < Array
+
+    # @param [Boolean] symbols true to cast hash keys to symbols
+    # @return [Hash]
     def to_hash(symbols)
       out = {}
       each do |option|
@@ -10,8 +13,10 @@ class Slop
       out
     end
 
-    def [](item)
-      item = item.to_s
+    # @param [Object] flag
+    # @return [Option] the option assoiated with this flag
+    def [](flag)
+      item = flag.to_s
       if item =~ /^\d+$/
         slice item.to_i
       else
@@ -20,16 +25,51 @@ class Slop
         end
       end
     end
+
+    # @return [String]
+    def to_help
+      heads = select {|x| !x.tail }
+      tails = select {|x| x.tail }
+      (heads + tails).map(&:to_s).join("\n")
+    end
   end
 
   class Option
 
+    # @return [String, #to_s]
     attr_reader :short_flag
+
+    # @return [String, #to_s]
     attr_reader :long_flag
+
+    # @return [String]
     attr_reader :description
+
+    # @return [Proc, #call]
     attr_reader :callback
+
+    # @return [Boolean]
+    attr_reader :tail
+
+    # @return [Regex]
+    attr_reader :match
+
     attr_writer :argument_value
 
+    # @param [Slop] slop
+    # @param [String, #to_s] short
+    # @param [String, #to_s] long
+    # @param [String] description
+    # @param [Boolean] argument
+    # @param [Hash] options
+    # @option options [Boolean] :optional
+    # @option options [Boolean] :argument
+    # @option options [Object] :default
+    # @option options [Proc, #call] :callback
+    # @option options [String, #to_s] :delimiter
+    # @option options [Integer] :limit
+    # @option options [Boolean] :tail
+    # @option options [Regexp] :match
     def initialize(slop, short, long, description, argument, options={}, &blk)
       @slop = slop
       @short_flag = short
@@ -38,6 +78,8 @@ class Slop
       @options = options
       @expects_argument = argument
       @expects_argument = true if options[:optional] == false
+      @tail = options[:tail]
+      @match = options[:match]
 
       if @long_flag && @long_flag.size > @slop.longest_flag
         @slop.longest_flag = @long_flag.size
@@ -48,22 +90,28 @@ class Slop
       @argument_value = nil
     end
 
+    # @return [Boolean] true if this option expects an argument
     def expects_argument?
       @expects_argument || @options[:argument]
     end
 
+    # @return [Boolean] true if this option expects an optional argument
     def accepts_optional_argument?
       @options[:optional]
     end
 
+    # @return [String] either the long or short flag for this option
     def key
       @long_flag || @short_flag
     end
 
+    # @return [Object]
     def default
       @options[:default]
     end
 
+    # @return [Object] the argument value after it's been case
+    #   according to the `:as` option
     def argument_value
       value = @argument_value || default
       return if value.nil?
@@ -103,5 +151,4 @@ class Slop
       "description=#{@description.inspect}>"
     end
   end
-
-end
+end

data/lib/slop/version.rb

@@ -1,3 +1,3 @@
 class Slop
-  VERSION = '1.1.0'
+  VERSION = '1.2.0'
 end

data/test/option_test.rb

@@ -88,4 +88,19 @@ class OptionTest < TestCase
     assert_equal 'foo', option(:f, :foo).key
     assert_equal 'b', option(:b).key
   end
+
+  test 'tail to append items to the options list when printing help' do
+    slop = Slop.new
+    slop.on :f, :foo, :tail => true
+    slop.on :b, :bar
+    assert slop.to_s.strip =~ /foo$/
+  end
+
+  test 'argument matching' do
+    slop = Slop.new
+    slop.on :f, :foo, true, :match => /^h/
+
+    assert_raises(Slop::InvalidArgumentError, /world/) { slop.parse %w/--foo world/ }
+    assert slop.parse %w/--foo hello/
+  end
 end

data/test/slop_test.rb

@@ -33,6 +33,15 @@ class SlopTest < TestCase
     assert_kind_of Slop, slop
   end
 
+  test 'automatically adding the help option' do
+    slop = Slop.new
+    assert_empty slop.options
+
+    slop = Slop.new :help => true
+    refute_empty slop.options
+    assert_equal 'Print this help message', slop.options[:help].description
+  end
+
   test 'yielding non-options when a block is passed to "parse"' do
     opts = Slop.new do
       on :name, true
@@ -42,6 +51,15 @@ class SlopTest < TestCase
     end
   end
 
+  test 'preserving order when yielding non-options' do
+    items = []
+
+    slop = Slop.new { on(:name, true) { |name| items << name } }
+    slop.parse(%w/foo --name bar baz/) { |value| items << value }
+
+    assert_equal %w/foo bar baz/, items
+  end
+
   test 'setting the banner' do
     slop = Slop.new
     slop.banner = "foo bar"
@@ -62,6 +80,15 @@ class SlopTest < TestCase
     assert_equal 8, slop.longest_flag
   end
 
+  test 'parse returning the list of arguments left after parsing' do
+    opts = Slop.new do
+      on :name, true
+    end
+
+    assert_equal %w/a/, opts.parse!(%w/--name lee a/)
+    assert_equal %w/--name lee a/, opts.parse(%w/--name lee a/)
+  end
+
   test '#parse does not remove parsed items' do
     items = %w/--foo/
     Slop.new { |opt| opt.on :foo }.parse(items)
@@ -180,4 +207,22 @@ class SlopTest < TestCase
     opts.parse %w/--name lee/
     assert_equal 'lee', name
   end
+
+  test 'strict mode' do
+    strict = Slop.new :strict => true
+    totallynotstrict = Slop.new
+
+    assert_raises(Slop::InvalidOptionError, /--foo/) { strict.parse %w/--foo/ }
+    assert totallynotstrict.parse %w/--foo/
+  end
+
+  test 'short option flag with no space between flag and argument' do
+    slop = Slop.new
+    slop.opt :p, :password, true
+    slop.opt :s, :shortpass, true
+    slop.parse %w/-p foo -sbar/
+
+    assert_equal 'foo', slop[:password]
+    assert_equal 'bar', slop[:shortpass]
+  end
 end

metadata

@@ -1,13 +1,8 @@
 --- !ruby/object:Gem::Specification 
 name: slop
 version: !ruby/object:Gem::Version 
-  hash: 19
   prerelease: 
-  segments: 
-  - 1
-  - 1
-  - 0
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors: 
 - Lee Jarvis
@@ -15,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-17 00:00:00 +00:00
+date: 2011-03-21 00:00:00 +00:00
 default_executable: 
 dependencies: []
 
@@ -55,18 +50,12 @@ 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: []