slop 2.0.0 → 2.1.0

data/CHANGES.md

@@ -1,5 +1,14 @@
+2.1.0 (2011-08-03)
+------------------
+
+* Added `Slop#missing` for returning a list of missing options parsed
+* Allow `Slop#present?` to accept multiple arguments
+* Added `:all_accept_arguments` to Slop configuration options, this saves
+  having to specify that every option takes an argument
+* Added `Slop#to_struct` for building new classes from options
+
 2.0.0 (2011-07-07)
------------
+------------------
 
 * Deprecations:
   * Removed `Slop::Options#to_hash` continue using `Slop#to_hash` directly.

data/lib/slop.rb

@@ -23,23 +23,56 @@ class Slop
   class Option < Struct.new(:short_flag, :long_flag, :description,
     :tail, :match, :help, :required, :forced, :count)
 
-    # @param [Slop] slop
-    # @param [String, #to_s] short
-    # @param [String, #to_s] long
-    # @param [String] description
-    # @param [Boolean] argument
-    # @param [Hash] options
+    # @param [Slop] slop The Slop object this Option belongs to
+    #
+    # @param [String, #to_s] short The short flag representing this Option
+    #   without prefix (ie: `a`)
+    #
+    # @param [String, #to_s] long The long flag representing this Option
+    #   without the prefix (ie: `foo`)
+    #
+    # @param [String] description This options description
+    #
+    # @param [Boolean] argument True if this option takes an argument
+    #
     # @option options [Boolean] :optional
+    #   * When true, this option takes an optional argument, ie an argument
+    #     does not **have** to be supplied.
+    #
     # @option options [Boolean] :argument
+    #   * True if this option takes an argument.
+    #
     # @option options [Object] :default
+    #   * The default value for this option when no argument is given
+    #
     # @option options [Proc, #call] :callback
+    #   * The callback object, used instead of passing a block to this option
+    #
     # @option options [String, #to_s] :delimiter (',')
+    #   * A delimiter string when processing this option as a list
+    #
     # @option options [Integer] :limit (0)
+    #   * A limit, used when processing this option as a list
+    #
     # @option options [Boolean] :tail (false)
+    #   * When true, this option will be grouped at the bottom of the help
+    #     text instead of in order of processing
+    #
     # @option options [Regexp] :match
+    #   * A regular expression this option should match
+    #
     # @option options [String, #to_s] :unless
+    #   * Used by `omit_exec` for omitting execution of this options callback
+    #     if another option exists
+    #
     # @option options [Boolean, String] :help (true)
+    #   * If this option is a string, it'll be appended to the long flag
+    #     help text (before the description). When false, no help information
+    #     will be displayed for this option
+    #
     # @option options [Boolean] :required (false)
+    #   * When true, this option is considered mandatory. That is, when not
+    #     supplied, Slop will raise a `MissingOptionError`
     def initialize(slop, short, long, description, argument, options, &blk)
       @slop = slop
 
@@ -66,7 +99,10 @@ class Slop
       @callback = blk if block_given?
       @callback ||= @options[:callback]
 
-      build_longest_flag
+      if long_flag && long_flag.size > @slop.longest_flag
+        @slop.longest_flag = long_flag.size
+        @slop.longest_flag += help.size if help.respond_to?(:to_str)
+      end
     end
 
     # @return [Boolean] true if this option expects an argument
@@ -194,13 +230,6 @@ class Slop
       end
     end
 
-    def build_longest_flag
-      if long_flag && long_flag.size > @slop.longest_flag
-        @slop.longest_flag = long_flag.size
-        @slop.longest_flag += help.size if help.respond_to? :to_str
-      end
-    end
-
   end
 
   # Used to hold a list of Option objects. This class inherits from Array
@@ -234,7 +263,7 @@ class Slop
   end
 
   # @return [String] The current version string
-  VERSION = '2.0.0'
+  VERSION = '2.1.0'
 
   # Parses the items from a CLI format into a friendly object
   #
@@ -329,9 +358,13 @@ class Slop
   # @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
+  #
+  # @option options [Boolean] :all_accept_arguments (false)
+  #   * When true, every option added will take an argument, this saves
+  #     having to enable it for every option
   def initialize(*opts, &block)
     sloptions = opts.last.is_a?(Hash) ? opts.pop : {}
-    sloptions[:banner] = opts.shift if opts[0].respond_to? :to_str
+    sloptions[:banner] = opts.shift if opts[0].respond_to?(:to_str)
     opts.each { |o| sloptions[o] = true }
 
     @options = Options.new
@@ -433,7 +466,7 @@ class Slop
     option = @options[key]
     option ? option.argument_value : @commands[key]
   end
-  alias :get :[]
+  alias get []
 
   # Specify an option with a short or long version, description and type
   #
@@ -459,15 +492,18 @@ class Slop
   def option(*args, &block)
     options = args.last.is_a?(Hash) ? args.pop : {}
 
-    short, long, desc, arg, extras = clean_options args
+    short, long, desc, arg, extras = clean_options(args)
+
     options.merge!(extras)
-    option = Option.new self, short, long, desc, arg, options, &block
+    options[:argument] = true if @sloptions[:all_accept_arguments]
+
+    option = Option.new(self, short, long, desc, arg, options, &block)
     @options << option
 
     option
   end
-  alias :opt :option
-  alias :on :option
+  alias opt option
+  alias on option
 
   # Namespace options depending on what command is executed
   #
@@ -515,7 +551,7 @@ class Slop
   def on_empty(obj=nil, &block)
     @on_empty ||= (obj || block)
   end
-  alias :on_empty= :on_empty
+  alias on_empty= on_empty
 
   # Trigger an event when the arguments contain no options
   #
@@ -529,7 +565,7 @@ class Slop
   def on_noopts(obj=nil, &block)
     @on_noopts ||= (obj || block)
   end
-  alias :on_optionless :on_noopts
+  alias on_optionless on_noopts
 
   # Add an execution block (for commands)
   #
@@ -546,7 +582,7 @@ class Slop
   # @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
+  # @yield [Slop] an instance of Slop for this command
   def execute(args=[], &block)
     if block_given?
       @execution_block = block
@@ -571,7 +607,52 @@ class Slop
       hsh
     end
   end
-  alias :to_h :to_hash
+  alias to_h to_hash
+
+  # Return parsed items as a new Class
+  #
+  # @example
+  #   opts = Slop.new do
+  #     on :n, :name, 'Persons name', true
+  #     on :a, :age, 'Persons age', true, :as => :int
+  #     on :s, :sex, 'Persons sex m/f', true, :match => /^[mf]$/
+  #     on :A, :admin, 'Enable admin mode'
+  #   end
+  #
+  #   opts.parse %w[ --name Lee --age 22 -s m --admin ]
+  #
+  #   person = opts.to_struct("Person")
+  #   person.class  #=> Struct::Person
+  #   person.name   #=> 'Lee'
+  #   person.age    #=> 22
+  #   person.sex    #=> m
+  #   person.admin  #=> true
+  #
+  # @param [String] name The name of this class
+  # @return [Class] The new class, or nil if there are no options
+  # @since 2.0.0
+  def to_struct(name=nil)
+    hash = to_hash
+    Struct.new(name, *hash.keys).new(*hash.values) unless hash.empty?
+  end
+
+  # Fetch a list of options which were missing from the parsed list
+  #
+  # @example
+  #   opts = Slop.new do
+  #     on :n, :name, 'Your name', true
+  #     on :p, :password, 'Your password', true
+  #     on :A, 'Use auth?'
+  #   end
+  #
+  #   opts.parse %w[ --name Lee ]
+  #   opts.missing #=> ['password', 'a']
+  #
+  # @return [Array] A list of options missing from the parsed string
+  # @since 2.1.0
+  def missing
+    @options.select { |opt| not present?(opt.key) }.map { |opt| opt.key }
+  end
 
   # Allows you to check whether an option was specified in the parsed list
   #
@@ -599,11 +680,11 @@ class Slop
   # Does the same as Slop#option? but a convenience method for unacceptable
   # method names
   #
-  # @param [Object] The object name to check
+  # @param [Object] The object name(s) to check
   # @since 1.5.0
-  # @return [Boolean] true if this option is present, false otherwise
-  def present?(option_name)
-    @options[option_name] && @options[option_name].count > 0
+  # @return [Boolean] true if these options are present, false otherwise
+  def present?(*option_names)
+    option_names.all? { |opt| @options[opt] && @options[opt].count > 0 }
   end
 
   # Returns the banner followed by available options listed on the next line
@@ -634,7 +715,7 @@ class Slop
 
     parts.join("\n\n")
   end
-  alias :help :to_s
+  alias help to_s
 
   # @return [String] This Slop object will options and configuration
   #   settings revealed
@@ -669,10 +750,10 @@ class Slop
   # * Remove non-parsed items if `delete` is true
   # * Yield any non-options to the block (if one is given)
   def parse_items(items, delete=false, &block)
-    if items.empty? && @on_empty.respond_to?(:call)
+    if items.empty? and @on_empty.respond_to?(:call)
       @on_empty.call self
       return items
-    elsif !items.any? {|i| i.to_s[/\A--?/] } && @on_noopts.respond_to?(:call)
+    elsif not items.any? {|i| i.to_s[/\A--?/] } and @on_noopts.respond_to?(:call)
       @on_noopts.call self
       return items
     elsif execute_command(items, delete)
@@ -695,7 +776,7 @@ class Slop
       autocreate(flag, index, items) if @autocreate
       option, argument = extract_option(item, flag)
 
-      if @multiple_switches && item[/\A-[^-]/] && !option
+      if @multiple_switches and item[/\A-[^-]/] and not option
         trash << index
         next
       end
@@ -706,16 +787,16 @@ class Slop
         next if option.forced
         option.argument_value = true
 
-        if option.expects_argument? || option.accepts_optional_argument?
+        if option.expects_argument? or option.accepts_optional_argument?
           argument ||= items.at(index + 1)
           trash << index + 1
 
-          if !option.accepts_optional_argument? && argument =~ /\A--?[a-zA-Z][a-zA-Z0-9_-]*\z/
+          if not option.accepts_optional_argument? and argument =~ /\A--?[a-zA-Z][a-zA-Z0-9_-]*\z/
             raise MissingArgumentError, "'#{option.key}' expects an argument, none given"
           end
 
           if argument
-            if option.match && !argument.match(option.match)
+            if option.match and not argument.match(option.match)
               raise InvalidArgumentError, "'#{argument}' does not match #{option.match.inspect}"
             end
 
@@ -729,8 +810,8 @@ class Slop
           option.call unless option.omit_exec?(items)
         end
       else
-        @invalid_options << flag if item[/\A--?/] && @strict
-        block.call(item) if block_given? && !trash.include?(index)
+        @invalid_options << flag if item[/\A--?/] and @strict
+        block.call(item) if block_given? and not trash.include?(index)
       end
     end
 
@@ -749,7 +830,7 @@ class Slop
   end
 
   def raise_if_invalid_options!
-    return if !@strict || @invalid_options.empty?
+    return if not @strict or @invalid_options.empty?
     message = "Unknown option#{'s' if @invalid_options.size > 1}"
     message << ' -- ' << @invalid_options.map { |o| "'#{o}'" }.join(', ')
     raise InvalidOptionError, message
@@ -770,10 +851,13 @@ class Slop
   # flag was not found
   def enable_multiple_switches(item)
     item[1..-1].each_char do |switch|
-      if option = @options[switch]
+      option = @options[switch]
+
+      if option
         if option.expects_argument?
           raise MissingArgumentError, "'-#{switch}' expects an argument, used in multiple_switch context"
         end
+
         option.argument_value = true
         option.count += 1
       else
@@ -812,6 +896,7 @@ class Slop
       option = @options[flag]
       option ||= @options[flag.downcase] if @ignore_case
     end
+
     unless option
       case item
       when /\A-[^-]/
@@ -828,6 +913,7 @@ class Slop
         option.force_argument_value(false) if option
       end
     end
+
     [option, argument]
   end
 
@@ -881,7 +967,7 @@ 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) if extras[:as].nil?
 
@@ -895,12 +981,13 @@ class Slop
 
     long = args.first
     boolean = [true, false].include? long
-    if !boolean && long.to_s =~ /\A(?:--?)?[a-z_-]+\s[A-Z\s\[\]]+\z/
+
+    if not boolean and long.to_s =~ /\A(?:--?)?[a-z_-]+\s[A-Z\s\[\]]+\z/
       arg, help = args.shift.split(/ /, 2)
       options.push arg.sub(/\A--?/, '')
       extras[:optional] = help[0, 1] == '[' && help[-1, 1] == ']'
       extras[:help] = help
-    elsif !boolean && long.to_s =~ /\A(?:--?)?[a-zA-Z][a-zA-Z0-9_-]+\z/
+    elsif not boolean and long.to_s =~ /\A(?:--?)?[a-zA-Z][a-zA-Z0-9_-]+\z/
       options.push args.shift.to_s.sub(/\A--?/, '')
     else
       options.push nil

data/slop.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = 'slop'
-  s.version = '2.0.0'
+  s.version = '2.1.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/slop_test.rb

@@ -112,6 +112,18 @@ class SlopTest < TestCase
     assert_equal 'Print this help message', slop.options[:help].description
   end
 
+  test ':all_accept_arguments' do
+    opts = Slop.new(:all_accept_arguments) do
+      on :foo
+      on :bar, :optional => true
+    end
+    opts.parse %w[ --foo hello --bar ]
+
+    assert_equal 'hello', opts[:foo]
+    assert_nil opts[:bar]
+    assert_raises(Slop::MissingArgumentError) { opts.parse %w[ --foo --bar ] }
+  end
+
   test 'yielding non-options when a block is passed to "parse"' do
     opts = Slop.new do
       on :name, true
@@ -300,6 +312,7 @@ class SlopTest < TestCase
 
     assert opts.present?('foo-bar')
     refute opts.present?('bar-baz')
+    refute opts.present?('foo-bar', 'bar-baz')
     assert opts.present?(:h)
   end
 
@@ -517,4 +530,26 @@ class SlopTest < TestCase
       "    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
+
+  test 'to_struct' do
+    assert_nil Slop.new.to_struct
+
+    slop = Slop.new { on :a, true }
+    slop.parse %w[ -a foo -b ]
+    struct = slop.to_struct
+
+    assert_equal 'foo', struct.a
+    assert_kind_of Struct, struct
+    assert_raises(NoMethodError) { struct.b }
+
+    pstruct = slop.to_struct('Foo')
+    assert_kind_of Struct::Foo, pstruct
+  end
+
+  test 'returning missing options' do
+    slop = Slop.new { on :a; on :b, :bar; on :c; }
+    slop.parse %w[ -a ]
+
+    assert_equal %w[ bar c ], slop.missing
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: slop
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-07-07 00:00:00.000000000 +01:00
+date: 2011-08-03 00:00:00.000000000 +01:00
 default_executable: 
 dependencies: []
 description: A simple DSL for gathering options and parsing the command line