slop 1.3.1 → 1.4.0

data/.yardopts

@@ -3,3 +3,4 @@
 --title "Slop - Option gathering made easy"
 lib/**/*.rb
 --no-private
+--main README.md

data/README.md

@@ -103,12 +103,12 @@ Parsing
 
 Slop's pretty good at parsing, let's take a look at what it'll extract for you
 
-	Slop.parse do
-		on 's', 'server', true
-		on 'p', 'port', true, :as => :integer
-		on 'username', true, :matches => /[^a-zA-Z]+$/
-		on 'password', true
-	end
+    Slop.parse do
+      on 's', 'server', true
+      on 'p', 'port', true, :as => :integer
+      on 'username', true, :matches => /[^a-zA-Z]+$/
+      on 'password', true
+    end
 
 Now throw some options at it:
 
@@ -129,12 +129,12 @@ Callbacks
 If you'd like to trigger an event when an option is used, you can pass a
 block to your option. Here's how:
 
-	Slop.parse do
-		on :V, :version, 'Print the version' do
-			puts 'Version 1.0.0'
-			exit
-		end
-	end
+    Slop.parse do
+      on :V, :version, 'Print the version' do
+        puts 'Version 1.0.0'
+        exit
+      end
+    end
 
 Now when using the `--version` option on the command line, the trigger will
 be called and its contents executed.
@@ -176,6 +176,26 @@ to return a false value.
 	opts[:verbose] #=> false
 	opts.verbose?  #=> false
 
+Short Switches
+--------------
+
+Want to enable multiple switches at once like rsync does? By default Slop will
+parse `-abcd` as the option `a` with the argument `bcd`, this can be disabled
+by passing the `:multiple_switches` option to a new Slop object.
+
+    opts = Slop.new(:strict, :multiple_switches) do
+      on :a, 'First switch'
+      on :b, 'Second switch'
+      on :c, 'Third switch'
+    end
+
+    opts.parse
+
+    # Using `-ac`
+    opts[:a] #=> true
+    opts[:b] #=> false
+    opts[:c] #=> true
+
 Ugh, Symbols
 ------------
 
@@ -233,7 +253,7 @@ You can of course also parse lists into options. Here's how:
 You can also change both the split delimiter and limit
 
     opts = Slop.parse do
-    	opt :people, true, :as => Array, :delimiter => ':', :limit => 2)
+      opt :people, true, :as => Array, :delimiter => ':', :limit => 2)
     end
 
     # ARGV is `--people lee:injekt:bob`
@@ -260,8 +280,8 @@ Significantly, however, Slop will still parse the valid options:
       on :n, :name, 'Your name'
     end
 
-		begin
-			slop.parse(%w/--foo --bar -z/)
+    begin
+      slop.parse(%w/--foo --bar -z/)
     rescue Slop::InvalidOptionError => e
       puts "\n#{e.message}\n\n"
       puts slop

data/lib/slop/option.rb

@@ -1,59 +1,28 @@
 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|
-        key = option.key
-        key = key.to_sym if symbols
-        out[key] = option.argument_value
-      end
-      out
-    end
-
-    # @param [Object] flag
-    # @return [Option] the option assoiated with this flag
-    def [](flag)
-      item = flag.to_s
-      if item =~ /\A\d+\z/
-        slice item.to_i
-      else
-        find do |option|
-          option.short_flag == item || option.long_flag == item
-        end
-      end
-    end
-
-    # @return [String]
-    def to_help
-      heads = reject {|x| x.tail }
-      tails = select {|x| x.tail }
-      (heads + tails).map(&:to_s).join("\n")
-    end
-  end
-
   class Option
 
-    # @return [String, #to_s]
+    # @return [String, #to_s] The short flag used for this option
     attr_reader :short_flag
 
-    # @return [String, #to_s]
+    # @return [String, #to_s] The long flag used for this option
     attr_reader :long_flag
 
-    # @return [String]
+    # @return [String] This options description
     attr_reader :description
 
-    # @return [Proc, #call]
+    # @return [Proc, #call] The object to execute when this option is used
     attr_reader :callback
 
-    # @return [Boolean]
+    # @return [Boolean] True if the option should be grouped at the
+    #   tail of the help list
     attr_reader :tail
 
-    # @return [Regex]
+    # @return [Regexp] If provided, an options argument **must** match this
+    #   regexp, otherwise Slop will raise an InvalidArgumentError
     attr_reader :match
 
+    # @overload argument_value=(value)
+    #   Set this options argument value
     attr_writer :argument_value
 
     # @param [Slop] slop
@@ -66,9 +35,9 @@ class Slop
     # @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 [String, #to_s] :delimiter (',')
+    # @option options [Integer] :limit (0)
+    # @option options [Boolean] :tail (false)
     # @option options [Regexp] :match
     def initialize(slop, short, long, description, argument, options={}, &blk)
       @slop = slop
@@ -102,7 +71,7 @@ class Slop
       @expects_argument || @options[:argument]
     end
 
-    # @return [Boolean] true if this option expects an optional argument
+    # @return [Boolean] true if this option accepts an optional argument
     def accepts_optional_argument?
       @options[:optional]
     end
@@ -140,10 +109,15 @@ class Slop
       @forced = true
     end
 
+    # @return [Boolean] true if this argument value has been forced
     def forced?
       @forced
     end
 
+    # This option in a nice pretty string, including a short flag, long
+    #   flag, and description (if they exist).
+    # @see Slop#help
+    # @return [String]
     def to_s
       out = "    "
       out += @short_flag ? "-#{@short_flag}, " : ' ' * 4
@@ -161,6 +135,7 @@ class Slop
       "#{out}#{@description}"
     end
 
+    # @return [String]
     def inspect
       "#<Slop::Option short_flag=#{@short_flag.inspect} " +
       "long_flag=#{@long_flag.inspect} " +

data/lib/slop/options.rb

@@ -0,0 +1,37 @@
+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|
+        key = option.key
+        key = key.to_sym if symbols
+        out[key] = option.argument_value
+      end
+      out
+    end
+
+    # @param [Object] flag The short/long flag representing the option
+    # @return [Option] the option assoiated with this flag
+    def [](flag)
+      item = flag.to_s
+      if item =~ /\A\d+\z/
+        slice item.to_i
+      else
+        find do |option|
+          option.short_flag == item || option.long_flag == item
+        end
+      end
+    end
+
+    # @see Slop#help
+    # @return [String] All options in a pretty help string
+    def to_help
+      heads = reject {|x| x.tail }
+      tails = select {|x| x.tail }
+      (heads + tails).map(&:to_s).join("\n")
+    end
+  end
+end

data/lib/slop.rb

@@ -1,13 +1,23 @@
+require 'slop/options'
 require 'slop/option'
-require 'slop/version'
 
 class Slop
   include Enumerable
 
+  # Raised when an option expects an argument and none is given
   class MissingArgumentError < RuntimeError; end
+
+  # Raised when an option specifies the `:match` attribute and this
+  # options argument does not match this regexp
   class InvalidArgumentError < RuntimeError; end
+
+  # Raised when the `:strict` option is enabled and an unknown
+  # or unspecified option is used
   class InvalidOptionError < RuntimeError; end
 
+  # @return [String] The current version string
+  VERSION = '1.4.0'
+
   # Parses the items from a CLI format into a friendly object.
   #
   # @param [Array] items Items to parse into options.
@@ -38,21 +48,29 @@ class Slop
   attr_accessor :longest_flag
 
   # @param [Hash] options
-  # @option options [Boolean] :help Automatically add the `help` option
-  # @option options [Boolean] :strict Strict mode raises when a non listed
+  # @option opts [Boolean] :help Automatically add the `help` option
+  # @option opts [Boolean] :strict Strict mode raises when a non listed
   #   option is found, false by default
-  def initialize(options={}, &block)
+  # @option opts [Boolean] :multiple_switches Allows `-abc` to be processed
+  #   as the options 'a', 'b', 'c' and will force their argument values to
+  #   true. By default Slop with parse this as 'a' with the argument 'bc'
+  def initialize(*opts, &block)
+    sloptions = {}
+    sloptions.merge! opts.pop if opts.last.is_a? Hash
+    opts.each { |o| sloptions[o] = true }
+
     @options = Options.new
     @banner = nil
     @longest_flag = 0
-    @strict = options[:strict]
+    @strict = sloptions[:strict]
     @invalid_options = []
+    @multiple_switches = sloptions[:multiple_switches]
 
     if block_given?
       block.arity == 1 ? yield(self) : instance_eval(&block)
     end
 
-    if options[:help]
+    if sloptions[:help]
       on :h, :help, 'Print this help message', :tail => true do
         puts help
         exit
@@ -201,8 +219,13 @@ private
       unless option
         case item
         when /\A-[^-]/
-          flag, argument = flag.split('', 2)
-          option = @options[flag]
+          if @multiple_switches
+            enable_multiple_switches(item)
+            next
+          else
+            flag, argument = flag.split('', 2)
+            option = @options[flag]
+          end
         when /\A--([^=]+)=(.+)\z/
           option = @options[$1]
           argument = $2
@@ -270,6 +293,23 @@ private
     @invalid_options << flag if item[/\A--?/] && @strict
   end
 
+  def enable_multiple_switches(item)
+    item[1..-1].split('').each do |switch|
+      if option = @options[switch]
+        if option.expects_argument?
+          raise MissingArgumentError,
+            "'-#{switch}' expects an argument, used in multiple_switch context"
+        else
+          option.argument_value = true
+        end
+      else
+        if @strict
+          raise InvalidOptionError, "Unknown option '-#{switch}'"
+        end
+      end
+    end
+  end
+
   def clean_options(args)
     options = []
 

data/slop.gemspec

@@ -1,5 +1,5 @@
 $:.push File.expand_path('../lib', __FILE__)
-require 'slop/version'
+require 'slop'
 
 Gem::Specification.new do |s|
   s.name = 'slop'

data/test/slop_test.rb

@@ -5,14 +5,18 @@ class SlopTest < TestCase
     Slop.new.send(:clean_options, args)
   end
 
-  def parse(items, &block)
-    Slop.parse(items, &block)
-  end
-
   test 'includes Enumerable' do
     assert Slop.included_modules.include?(Enumerable)
   end
 
+  test 'new accepts a hash or array of symbols' do
+    slop = Slop.new :strict, :multiple_switches => true
+
+    [ :@multiple_switches, :@strict ].each do |var|
+      assert slop.instance_variable_get var
+    end
+  end
+
   test 'parse returns a Slop object' do
     slop = Slop.parse([])
     assert_kind_of Slop, slop
@@ -26,6 +30,21 @@ class SlopTest < TestCase
     slop.each { |option| assert option }
   end
 
+  test 'multiple switches with the :multiple_switches flag' do
+    slop = Slop.new :multiple_switches => true, :strict => true
+    %w/a b c/.each { |f| slop.on f }
+    slop.on :z, true
+    slop.parse %w/-abc/
+
+    %w/a b c/.each do |flag|
+      assert slop[flag]
+      assert slop.send(flag + '?')
+    end
+
+    assert_raises(Slop::InvalidOptionError, /d/)   { slop.parse %w/-abcd/ }
+    assert_raises(Slop::MissingArgumentError, /z/) { slop.parse %w/-abcz/ }
+  end
+
   test 'passing a block' do
     assert Slop.new {}
     slop = nil

metadata

@@ -2,7 +2,7 @@
 name: slop
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 1.3.1
+  version: 1.4.0
 platform: ruby
 authors: 
 - Lee Jarvis
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-30 00:00:00 +01:00
+date: 2011-04-03 00:00:00 +01:00
 default_executable: 
 dependencies: []
 
@@ -31,7 +31,7 @@ files:
 - Rakefile
 - lib/slop.rb
 - lib/slop/option.rb
-- lib/slop/version.rb
+- lib/slop/options.rb
 - slop.gemspec
 - test/helper.rb
 - test/option_test.rb

data/lib/slop/version.rb

@@ -1,3 +0,0 @@
-class Slop
-  VERSION = '1.3.1'
-end