slop 1.0.0.rc1 → 1.0.0

data/.yardopts

@@ -1 +1,5 @@
---hide-void-return -m markdown
+--hide-void-return 
+-m markdown
+--title "slop"
+lib/**/*.rb
+--no-private

data/README.md

@@ -3,16 +3,12 @@ Slop
 
 Slop is a simple option collector with an easy to remember syntax and friendly API.
 
-**NOTE** This branch refers to the prerelease 1.0.0.rc1 version, this version has
-incompatible changes from version 0.0.3 (the latest stable version). You **should**
-upgrade.
-
 Installation
 ------------
 
 ### Rubygems
 
-    gem install slop --pre
+    gem install slop
 
 ### GitHub
 
@@ -26,10 +22,11 @@ Usage
 	opts = Slop.parse do
 	  on :v, :verbose, 'Enable verbose mode' 	   # boolean value
 	  on :n, :name, 'Your name', true              # compulsory argument
+	  on :s, :sex, 'Your sex', :optional => false  # the same thing
 	  on :a, :age, 'Your age', :optional => true   # optional argument
 	end
 
-	# if ARGV is `-v --name 'lee jarvis'`
+	# if ARGV is `-v --name 'lee jarvis' -s male`
 	opts.verbose? #=> true
 	opts.name?    #=> true
 	opts[:name]   #=> 'lee jarvis'
@@ -38,7 +35,7 @@ Usage
 
 You can also return your options as a Hash
 
-	opts.to_hash #=> {:name => 'Lee Jarvis', :verbose => true, :age => nil}
+	opts.to_hash #=> {'name' => 'Lee Jarvis', 'verbose' => true, 'age' => nil, 'sex' => 'male'}
 
 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.
@@ -134,7 +131,7 @@ do this:
 You can also try other variations:
 
     on :name, "Your name"
-    on :n, :name)
+    on :n, :name
     on :name, true
 
 Lists
@@ -156,6 +153,44 @@ You can also change both the split delimiter and limit
     end
     opts[:people] #=> ["lee", "injekt:bob"]
 
+Woah woah, why you hating on OptionParser?
+------------------------------------------
+
+I'm not, honestly! I love OptionParser. I really do, it's a fantastic library.
+So why did I build Slop? Well, I find myself using OptionParser to simple
+gather a bunch of key/value options, usually you would do something like this:
+
+	require 'optparse'
+
+	things = {}
+
+	opt = OptionParser.new do |opt|
+	  opt.on('-n', '--name NAME', 'Your name') do |name|
+	    things[:name] = name
+	  end
+
+	  opt.on('-a', '--age AGE', 'Your age') do |age|
+		things[:age] = age
+	  end
+
+	  # you get the point
+	end
+
+	opt.parse
+	# do something with things
+
+Which is all great and stuff, but it can lead to some repetition, the same
+thing in Slop:
+
+	require 'slop'
+
+	opts = Slop.parse do
+	  on :n, :name, 'Your name', true
+	  on :a, :age, 'Your age', true
+	end
+
+	things = opts.to_hash
+
 Contributing
 ------------
 

data/Rakefile

@@ -4,4 +4,6 @@ task :test do
   require 'minitest/autorun'
   begin; require 'turn'; rescue LoadError; end
   Dir.glob("test/**/*_test.rb").each { |test| require_relative test }
-end
+end
+
+task :default => :test

data/lib/slop.rb

@@ -6,6 +6,21 @@ class Slop
 
   class MissingArgumentError < ArgumentError; end
 
+  # Parses the items from a CLI format into a friendly object.
+  #
+  # @param [Array] items Items to parse into options.
+  # @yield Specify available CLI arguments using Slop# methods such as Slop#banner and Slop#option
+  # @return [Slop] Returns an instance of Slop.
+  # @example Specifying three options to parse:
+  #  opts = Slops.parse do
+  #    on :v, :verbose, 'Enable verbose mode'
+  #    on :n, :name,    'Your name'
+  #    on :a, :age,     'Your age'
+  #  end
+  #  -------
+  #  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)
@@ -14,24 +29,42 @@ class Slop
 
   attr_reader :options
   attr_writer :banner
+  attr_accessor :longest_flag
 
   def initialize(&block)
     @options = Options.new
     @banner = nil
+    @longest_flag = 0
+
     if block_given?
       block.arity == 1 ? yield(self) : instance_eval(&block)
     end
   end
 
+  # Set or return banner text.
+  #
+  # @param [String] text Displayed banner text.
+  # @return [String] Returns current banner.
+  # @example
+  #   opts = Slop.parse do
+  #     banner "Usage - ruby foo.rb [arguments]"
+  #   end
+  # @see Slop#to_s
   def banner(text=nil)
     @banner = text if text
     @banner
   end
 
+  # Parse a list of options, leaving the original Array unchanged.
+  #
+  # @param items
   def parse(items=ARGV)
     parse_items(items)
   end
 
+  # Parse a list of options, removing parsed options from the original Array.
+  #
+  # @parse items
   def parse!(items=ARGV)
     parse_items(items, true)
   end
@@ -42,20 +75,43 @@ class Slop
     @options.each { |option| yield option }
   end
 
+  # Return the value of an option via the subscript operator.
+  #
+  # @param [Symbol] key Option symbol.
+  # @return [Object] Returns the object associated with that option.
+  # @example
+  #   opts[:name]
+  #   #=> "Emily"
+  # @see Slop#method_missing
   def [](key)
     option = @options[key]
     option ? option.argument_value : nil
   end
 
-  # :short_flag
-  # :long_flag
-  # :description
-  # :argument
+  # Specify an option with a short or long version, description and type.
+  #
+  # @param [*] args Option configuration.
+  # @option args [Symbol, String] :short_flag Short option name.
+  # @option args [Symbol, String] :long_flag Full option name.
+  # @option args [String] :description Option description for use in Slop#help
+  # @option args [Boolean] :argument Specifies whether a required option or not.
+  # @option args [Hash] :options Optional option configurations.
+  # @example
+  #   opts = Slop.parse do
+  #     on :n, :name, 'Your username', true # Required argument
+  #     on :a, :age,  'Your age (optional)', :optional => true # Optional argument
+  #     on :g, :gender, 'Your gender', :optional => false # Required argument
+  #     on :V, :verbose, 'Run in verbose mode', :default => true # Runs verbose mode by default
+  #     on :P, :people, 'Your friends', true, :as => Array # Required, list of people.
+  #     on :h, :help, 'Print this help screen' do
+  #       puts help
+  #     end # Runs a block
+  #   end
   def option(*args, &block)
     options = args.pop if args.last.is_a?(Hash)
     options ||= {}
 
-    option = Option.new(*clean_options(args), options, &block)
+    option = Option.new(self, *clean_options(args), options, &block)
     @options << option
 
     option
@@ -63,10 +119,26 @@ class Slop
   alias :opt :option
   alias :on :option
 
+  # Returns the parsed list into a option/value hash.
+  #
+  # @return [Hash] Returns a hash with each specified option as a symbolic key with an associated value.
+  # @example
+  #   opts.to_hash
+  #   #=> { :name => 'Emily' }
   def to_hash
     @options.to_hash
   end
 
+  # Allows you to check whether an option was specified in the parsed list.
+  #
+  # @return [Boolean] Whether the desired option was specified.
+  # @example
+  #   #== ruby foo.rb -v
+  #   opts.verbose?
+  #   #=> true
+  #   opts.name?
+  #   #=> false
+  # @see Slop#[]
   def method_missing(meth, *args, &block)
     if meth.to_s =~ /\?$/
       !!self[meth.to_s.chomp('?')]
@@ -75,6 +147,17 @@ class Slop
     end
   end
 
+  # Returns the banner followed by available options listed on the next line.
+  #
+  # @return [String] Help text.
+  # @example
+  #  opts = Slop.parse do
+  #    banner "Usage - ruby foo.rb [arguments]"
+  #    on :v, :verbose, "Enable verbose mode"
+  #  end
+  #  opts.to_s
+  #  #=> "Usage - ruby foo.rb [options]\n    -v, --verbose      Enable verbose mode"
+  # @see Slop#banner
   def to_s
     banner = "#{@banner}\n" if @banner
     (banner || '') + options.map(&:to_s).join("\n")
@@ -87,38 +170,34 @@ private
     trash = []
 
     items.each do |item|
-
       flag = item.to_s.sub(/^--?/, '')
-      if flag.length == 1
-        option = find { |option| option.short_flag == flag }
-      else
-        option = find { |option| option.long_flag == flag }
-      end
 
-      if option
+      if option = @options[flag]
+        trash << item if delete
         option.argument_value = true
 
         if option.expects_argument? || option.accepts_optional_argument?
           argument = items.at(items.index(item) + 1)
-          trash << argument if delete && argument !~ /^--?/
+          trash << argument if delete
 
           if argument
             option.argument_value = argument
-            option.callback.call(option.argument_value) if option.has_callback?
+            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.has_callback?
+              option.callback.call(nil) if option.callback
             else
               raise MissingArgumentError,
                 "'#{flag}' expects an argument, none given"
             end
           end
-        elsif option.has_callback?
+        elsif option.callback
           option.callback.call(nil)
         end
-        trash << item if delete
       end
     end
+
     items.delete_if { |item| trash.include? item }
   end
 

data/lib/slop/option.rb

@@ -8,8 +8,8 @@ class Slop
 
     def [](item)
       item = item.to_s
-      if item =~ /^\d+/
-        super
+      if item =~ /^\d+$/
+        slice(item.to_i)
       else
         find do |option|
           option.short_flag == item || option.long_flag == item
@@ -26,18 +26,20 @@ class Slop
     attr_reader :callback
     attr_writer :argument_value
 
-    @@longest_flag = 0
-
-    def initialize(short, long, description, argument, options={}, &block)
-      @short_flag, @long_flag = short, long
-      @description, @expects_argument = description, argument
+    def initialize(slop, short, long, description, argument, options={}, &blk)
+      @slop = slop
+      @short_flag = short
+      @long_flag = long
+      @description = description
       @options = options
+      @expects_argument = argument
+      @expects_argument = true if options[:optional] == false
 
-      if @long_flag && @long_flag.size > @@longest_flag
-        @@longest_flag = @long_flag.size
+      if @long_flag && @long_flag.size > @slop.longest_flag
+        @slop.longest_flag = @long_flag.size
       end
 
-      @callback = block if block_given?
+      @callback = blk if block_given?
       @callback ||= options[:callback]
       @argument_value = nil
     end
@@ -50,10 +52,6 @@ class Slop
       @options[:optional]
     end
 
-    def has_callback?
-      !!@callback && @callback.respond_to?(:call)
-    end
-
     def key
       @long_flag || @short_flag
     end
@@ -64,15 +62,15 @@ class Slop
 
     def argument_value
       value = @argument_value || default
-      return unless value
+      return if value.nil?
 
       case @options[:as].to_s
       when 'Array'
         value.split(@options[:delimiter] || ',', @options[:limit] || 0)
       when 'String';  value.to_s
       when 'Symbol';  value.to_s.to_sym
-      when 'Integer'; value.to_i
-      when 'Float';   value.to_f
+      when 'Integer'; value.to_s.to_i
+      when 'Float';   value.to_s.to_f
       else
         value
       end
@@ -80,28 +78,25 @@ class Slop
 
     def to_s
       out = "    "
-      out += @short_flag ?  "-#{@short_flag}, " : ' ' * 4
-
-      out += "--#{@long_flag}" if @long_flag
+      out += @short_flag ? "-#{@short_flag}, " : ' ' * 4
 
       if @long_flag
-        diff = @@longest_flag - @long_flag.size
+        out += "--#{@long_flag}"
+        diff = @slop.longest_flag - @long_flag.size
         spaces = " " * (diff + 6)
         out += spaces
       else
-        spaces = " " * (@@longest_flag + 8)
+        spaces = " " * (@slop.longest_flag + 8)
         out += spaces
       end
 
-      out += @description if @description
-
-      out
+      "#{out}#{@description}"
     end
 
     def inspect
       "#<Slop::Option short_flag=#{@short_flag.inspect} " +
       "long_flag=#{@long_flag.inspect} " +
-      "description=#{@description.inspect} "
+      "description=#{@description.inspect}>"
     end
   end
 

data/lib/slop/version.rb

@@ -1,3 +1,3 @@
 class Slop
-  VERSION = '1.0.0.rc1'
+  VERSION = '1.0.0'
 end

data/test/option_test.rb

@@ -17,9 +17,10 @@ class OptionTest < TestCase
     option_with_argument(*args, &block).argument_value
   end
 
-  test 'expects an argument if argument is true' do
+  test 'expects an argument if argument is true or optional is false' do
     assert option(:f, :foo, 'foo', true).expects_argument?
     assert option(:f, :argument => true).expects_argument?
+    assert option(:f, :optional => false).expects_argument?
 
     refute option(:f, :foo).expects_argument?
   end
@@ -32,10 +33,10 @@ class OptionTest < TestCase
   end
 
   test 'has a callback when passed a block or callback option' do
-    assert option(:f){}.has_callback?
-    assert option(:callback => proc {}).has_callback?
+    assert option(:f){}.callback
+    assert option(:callback => proc {}).callback
 
-    refute option(:f).has_callback?
+    refute option(:f).callback
   end
 
   test 'splits argument_value with :as => array' do
@@ -77,4 +78,16 @@ class OptionTest < TestCase
     assert_equal "        --age       Your age", slop.options[:age].to_s
     assert_equal "    -V,             Display the version", slop.options[:V].to_s
   end
+
+  test 'falls back to default option' do
+    slop = Slop.new
+    slop.opt :foo, :optional => true, :default => 'lee'
+    slop.parse %w/--foo/
+    assert_equal 'lee', slop[:foo]
+  end
+
+  test 'key should default to long flag otherwise use short flag' do
+    assert_equal 'foo', option(:f, :foo).key
+    assert_equal 'b', option(:b).key
+  end
 end

data/test/slop_test.rb

@@ -26,8 +26,22 @@ class SlopTest < TestCase
     slop.each { |option| assert option }
   end
 
-  test 'parsing options' do
+  test 'passing a block' do
+    assert Slop.new {}
+    slop = nil
+    assert Slop.new {|s| slop = s }
+    assert_kind_of Slop, slop
+  end
+
+  test 'setting the banner' do
+    slop = Slop.new
+    slop.banner = "foo bar"
+
+    assert_equal "foo bar", slop.banner
+    assert slop.to_s =~ /^foo bar/
 
+    slop.banner = nil
+    assert_equal "", slop.to_s
   end
 
   test '#parse does not remove parsed items' do
@@ -103,6 +117,35 @@ class SlopTest < TestCase
     assert slop.parse %w/--name 'foo'/
   end
 
+  test 'returning a hash of options' do
+    slop = Slop.new
+    slop.opt :name, true
+    slop.opt :version
+    slop.opt :V, :verbose, :default => false
+    slop.parse %w/--name lee --version/
+
+    assert_equal({'name' => 'lee', 'version' => true, 'verbose' => false}, slop.to_hash)
+  end
+
+  test 'iterating options' do
+    slop = Slop.new
+    slop.opt :a, :abc
+    slop.opt :f, :foo
+
+    assert_equal 2, slop.count
+    slop.each {|opt| assert_kind_of Slop::Option, opt }
+  end
+
+  test 'fetching options and option values' do
+    slop = Slop.new
+    slop.opt :foo, true
+    slop.parse %w/--foo bar/
+
+    assert_kind_of Slop::Option, slop.options[:foo]
+    assert_equal "bar", slop[:foo]
+    assert_equal "bar", slop['foo']
+  end
+
   test 'printing help' do
     slop = Slop.new
     slop.banner = 'Usage: foo [options]'

metadata

@@ -1,8 +1,8 @@
 --- !ruby/object:Gem::Specification 
 name: slop
 version: !ruby/object:Gem::Version 
-  prerelease: 6
-  version: 1.0.0.rc1
+  prerelease: 
+  version: 1.0.0
 platform: ruby
 authors: 
 - Lee Jarvis
@@ -54,9 +54,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version 
-      version: 1.3.1
+      version: "0"
 requirements: []
 
 rubyforge_project: