slop 0.2.0 → 1.0.0.rc1

data/.gitignore

@@ -0,0 +1,4 @@
+.yardoc
+doc
+*.swp
+*.gem

data/.yardopts

@@ -0,0 +1 @@
+--hide-void-return -m markdown

data/README.md

@@ -3,74 +3,81 @@ 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
+    gem install slop --pre
 
 ### GitHub
 
     git clone git://github.com/injekt/slop.git
-    cd slop
-    rake install
+	gem build slop.gemspec
+	gem install slop-<version>.gem
 
 Usage
 -----
+	# parse assumes ARGV, otherwise you can pass it your own Array
+	opts = Slop.parse do
+	  on :v, :verbose, 'Enable verbose mode' 	   # boolean value
+	  on :n, :name, 'Your name', true              # compulsory argument
+	  on :a, :age, 'Your age', :optional => true   # optional argument
+	end
 
-    s = Slop.parse(ARGV) do
-      option(:v, :verbose, "Enable verbose mode", :default => false)
-      option(:n, :name, "Your name", true) # compulsory argument
-      option(:c, :country, "Your country", :argument => true) # the same thing
+	# if ARGV is `-v --name 'lee jarvis'`
+	opts.verbose? #=> true
+	opts.name?    #=> true
+	opts[:name]   #=> 'lee jarvis'
+	opts.age?     #=> false
+	opts[:age]    #=> nil
 
-      option(:a, :age, "Your age", true, :optional => true) # optional argument
-      option(:address, "Your address", :optional => true)   # the same
+You can also return your options as a Hash
 
-      # shortcut option aliases
-      opt(:height, "Your height")
-      o(:weight, "Your weight")
-    end
+	opts.to_hash #=> {:name => 'Lee Jarvis', :verbose => true, :age => nil}
 
-    # using `--name Lee -a 100`
-    s.options_hash #=> {:verbose=>false, :name=>"Lee", :age=>"100", :address=>nil}
-    s.value_for(:name) #=> "Lee"
+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.
 
-    # or grab the Option object directly
-    option = s.option_for(:name)
-    option.description #=> "Your name"
+	on :v, :verbose
+	opt :v, :verbose
+	option :v, :verbose
 
-    # You can also use switch values to set options according to arguments
-    s = Slop.parse(ARGV) do
-      option(:v, :verbose, :default => false, :switch => true)
-      option(:applicable_age, :default => 10, :switch => 20)
-    end
+If you don't like that Slop evaluates your block, or you want slop access
+inside of your block without referring to `self`, you can pass a block argument to
+`parse`.
 
-    # without `-v`
-    s[:verbose] #=> false
+	Slop.parse do |opts|
+	  opts.on :v, :verbose
+	  opts.on :n, :name, 'Your name', true
+	end
 
-    # using `-v`
-    s[:verbose] #=> true
+If you want some pretty output for the user to see your options, you can just
+send the Slop object to `puts` or use the `help` method.
 
-    # using `--applicable_age`
-    s[:applicable_age] #=> 20
+	puts opts
+	puts opts.help
 
-Want these options back in a nice readable help string? Just call `Slop.to_s`
-and Slop will return a nice indented option list. You can even add a banner to
-the help text using the `banner` method like so:
+Will output something like
 
-    opts = Slop.new do
-      banner("Usage: foo [options]")
+	-v, --verbose      Enable verbose mode
+    -n, --name         Your name
+    -a, --age          Your age
 
-      opt(:n, :name, "Your name", true)
-    end
+You can also add a banner using the `banner` method
 
-    puts opts
+	opts = Slop.parse
+	opts.banner = "Usage: foo.rb [options]"
 
-Returns:
+or
 
-    Usage: foo [options]
-	      -n, --name <name>	     Your name
+	opts = Slop.parse do
+	  banner "Usage: foo.rb [options]"
+	end
 
 Callbacks
 ---------
@@ -78,26 +85,37 @@ 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(ARGV) do
-      opt(:v, :version, "Display the version") do
-        puts "Version 1.0.1"
-        exit
-      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.
 
-Casting
--------
+Ugh, Symbols
+------------
 
-If you want to return values of specific types, for example a Symbol or Integer
-you can pass the `:as` attribute to your option.
+Fine, don't use them
 
-    s = Slop.parse("--age 20") do
-      opt(:age, true, :as => Integer) # :int/:integer both also work
-    end
-    s[:age] #=> 20 # not "20"
+	Slop.parse do
+	  on :n, :name, 'Your name'
+	  on 'n', 'name', 'Your name'
+	  on '-n', '--name', 'Your name'
+	end
+
+All of these options will do the same thing
+
+Ugh, Blocks
+-----------
+
+C'mon man, this is Ruby, GTFO if you don't like blocks.
+
+	opts = Slop.new
+	opts.on :v, :verbose
+	opts.parse
 
 Smart
 -----
@@ -106,39 +124,41 @@ Slop is pretty smart when it comes to building your options, for example if you
 want your option to have a flag attribute, but no `--option` attribute, you
 can do this:
 
-    opt(:n, "Your name")
+    on :n, "Your name"
 
 and Slop will detect a description in place of an option, so you don't have to
 do this:
 
-    opt(:n, nil, "Your name")
+    on :n, nil, "Your name", true
 
 You can also try other variations:
 
-    opt(:name, "Your name")
-    opt(:n, :name)
-    opt(:name)
+    on :name, "Your name"
+    on :n, :name)
+    on :name, true
 
 Lists
 -----
 
 You can of course also parse lists into options. Here's how:
 
-    s = Slop.parse("--people lee,injekt") do
-      opt(:people, true, :as => Array)
-    end
-    s[:people] #=> ["lee", "injekt"]
+	opts = Slop.parse do
+	  opt :people, true, :as => Array
+	end
+
+	# ARGV is `--people lee,john,bill`
+	opts[:people] #=> ['lee', 'john', 'bill']
 
 You can also change both the split delimiter and limit
 
-    s = Slop.parse("--people lee:injekt:bob") do
-      opt(:people, true, :as => Array, :delimiter => ':', :limit => 2)
+    opts = Slop.parse do
+      opt :people, true, :as => Array, :delimiter => ':', :limit => 2)
     end
-    s[:people] #=> ["lee", "injekt:bob"]
+    opts[:people] #=> ["lee", "injekt:bob"]
 
 Contributing
 ------------
 
 If you'd like to contribute to Slop (it's **really** appreciated) please fork
-the GitHub repository, create your feature/bugfix branch, add specs, and send
+the GitHub repository, create your feature/bugfix branch, add tests, and send
 me a pull request. I'd be more than happy to look at it.

data/Rakefile

@@ -0,0 +1,7 @@
+task :test do
+  $LOAD_PATH.unshift './lib'
+  require 'slop'
+  require 'minitest/autorun'
+  begin; require 'turn'; rescue LoadError; end
+  Dir.glob("test/**/*_test.rb").each { |test| require_relative test }
+end

data/lib/slop.rb

@@ -1,208 +1,151 @@
-require 'set'
-
 require 'slop/option'
+require 'slop/version'
 
 class Slop
   include Enumerable
 
-  VERSION = '0.2.0'
-
-  # Raised when an option expects an argument and none is given
   class MissingArgumentError < ArgumentError; end
 
-  # @return [Set]
+  def self.parse(items=ARGV, &block)
+    slop = new(&block)
+    slop.parse(items)
+    slop
+  end
+
   attr_reader :options
+  attr_writer :banner
 
-  # @return [Set] the last set of options used
-  def self.options
-    @@options
+  def initialize(&block)
+    @options = Options.new
+    @banner = nil
+    if block_given?
+      block.arity == 1 ? yield(self) : instance_eval(&block)
+    end
   end
 
-  # Sugar for new(..).parse(stuff)
-  def self.parse(values=[], &blk)
-    new(&blk).parse(values)
+  def banner(text=nil)
+    @banner = text if text
+    @banner
   end
 
-  def initialize(&blk)
-    @banner = nil
-    @options = Set.new
-    @@options = @options
-    instance_eval(&blk) if block_given?
+  def parse(items=ARGV)
+    parse_items(items)
   end
 
-  # set the help string banner
-  # @param [String,#to_s] banner
-  # @return The banner, or nil
-  def banner(banner=nil)
-    @banner = banner if banner
-    @banner
+  def parse!(items=ARGV)
+    parse_items(items, true)
   end
 
-  # add an option
-  def option(*args, &blk)
-    opts = args.pop if args.last.is_a?(Hash)
-    opts ||= {}
+  # Enumerable interface
+  def each
+    return enum_for(:each) unless block_given?
+    @options.each { |option| yield option }
+  end
 
-    if args.size > 4
-      raise ArgumentError, "Argument size must be no more than 4"
-    end
+  def [](key)
+    option = @options[key]
+    option ? option.argument_value : nil
+  end
 
-    attributes = [:flag, :option, :description, :argument]
-    options = Hash[attributes.zip(pad_options(args))]
-    options.merge!(opts)
-    options[:callback] = blk if block_given?
+  # :short_flag
+  # :long_flag
+  # :description
+  # :argument
+  def option(*args, &block)
+    options = args.pop if args.last.is_a?(Hash)
+    options ||= {}
 
-    @options << Option.new(options)
+    option = Option.new(*clean_options(args), options, &block)
+    @options << option
+
+    option
   end
   alias :opt :option
-  alias :o :option
+  alias :on :option
+
+  def to_hash
+    @options.to_hash
+  end
 
-  # add an argument
-  def argument(*args)
+  def method_missing(meth, *args, &block)
+    if meth.to_s =~ /\?$/
+      !!self[meth.to_s.chomp('?')]
+    else
+      super
+    end
+  end
 
+  def to_s
+    banner = "#{@banner}\n" if @banner
+    (banner || '') + options.map(&:to_s).join("\n")
   end
-  alias :arg :argument
-  alias :args :argument
-  alias :arguments :argument
+  alias :help :to_s
+
+private
 
-  # Parse an Array (usually ARGV) of options
-  #
-  # @param [Array, #split] Array or String of options to parse
-  # @raise [MissingArgumentError] raised when a compulsory argument is missing
-  def parse(values=[])
-    values = values.split(/\s+/) if values.respond_to?(:split)
+  def parse_items(items, delete=false)
+    trash = []
 
-    values.each do |value|
-      if flag_or_option?(value)
-        opt   = value.size == 2 ? value[1] : value[2..-1]
-        index = values.index(value)
+    items.each do |item|
 
-        next unless option = option_for(opt) # skip unknown values for now
+      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
 
-        option.execute_callback if option.has_callback?
-        option.switch_argument_value if option.has_switch?
+      if option
+        option.argument_value = true
 
-        if option.requires_argument?
-          value = values.at(index + 1)
+        if option.expects_argument? || option.accepts_optional_argument?
+          argument = items.at(items.index(item) + 1)
+          trash << argument if delete && argument !~ /^--?/
 
-          unless option.optional_argument?
-            if not value or flag_or_option?(value)
+          if argument
+            option.argument_value = argument
+            option.callback.call(option.argument_value) if option.has_callback?
+          else
+            if option.accepts_optional_argument?
+              option.callback.call(nil) if option.has_callback?
+            else
               raise MissingArgumentError,
-                  "#{option.key} requires a compulsory argument, none given"
-              end
-          end
-
-          unless not value or flag_or_option?(value)
-            option.argument_value = values.delete_at(values.index(value))
+                "'#{flag}' expects an argument, none given"
+            end
           end
+        elsif option.has_callback?
+          option.callback.call(nil)
         end
-      else
-        # not a flag or option, parse as an argument
+        trash << item if delete
       end
     end
-
-    self
+    items.delete_if { |item| trash.include? item }
   end
 
-  # A simple Hash of options with option labels or flags as keys
-  # and option values as.. values.
-  #
-  # @return [Hash]
-  def options_hash
-    out = {}
-    options.each do |opt|
-      if opt.requires_argument? or opt.has_default?
-        out[opt.key] = opt.argument_value || opt.default
-      end
-    end
-    out
-  end
-  alias :to_hash :options_hash
-  alias :to_h :options_hash
-
-  # Find an option using its flag or label
-  #
-  # @example
-  #   s = Slop.new do
-  #     option(:n, :name, "Your name")
-  #   end
-  #
-  #   s.option_for(:name).description #=> "Your name"
-  #
-  # @return [Option] the option flag or label
-  def option_for(flag)
-    find do |opt|
-      opt.has_flag?(flag) || opt.has_option?(flag)
+  # @param [Array] args
+  # @return [Array]
+  def clean_options(args)
+    options = []
+
+    short = args.first.to_s.sub(/^--?/, '')
+    if short.size == 1
+      options.push short
+      args.shift
+    else
+      options.push nil
     end
-  end
 
-  # Find an options argument using the option name.
-  # Essentially this is the same as `s.options_hash[:name]`
-  #
-  # @example When passing --name Lee
-  #   s = Slop.new do
-  #     option(:n, :name, true)
-  #   end
-  #
-  #   s.value_for(:name) #=> "Lee"
-  #
-  def value_for(flag)
-    return unless option = option_for(flag)
-    option.argument_value
-  end
-  alias :[] :value_for
-
-  # Implement #each so our options set is enumerable
-  def each
-    return enum_for(:each) unless block_given?
-    @options.each { |opt| yield opt }
-  end
-
-  def to_s
-    str = ""
-    str << @banner + "\n" if @banner
-    each do |opt|
-      str << "#{opt}\n"
+    long = args.first
+    if !long.is_a?(TrueClass) && !long.is_a?(FalseClass) && long.to_s =~ /\A(--?)?[a-zA-Z0-9_-]+\z/
+      options.push args.shift.to_s.sub(/^--?/, '')
+    else
+      options.push nil
     end
-    str
-  end
-
-  private
 
-  def flag_or_option?(flag)
-    return unless flag && flag.size > 1
+    options.push args.first.respond_to?(:to_sym) ? args.shift : nil
+    options.push args.shift ? true : false # force true/false
 
-    if flag[1] == '-'
-      return flag[0] == '-' && flag[3]
-    elsif flag[0] == '-'
-      return !flag[3]
-    end
+    options
   end
 
-  def pad_options(args)
-    # if the first value is not a single character, it's probably an option
-    # so we just replace it with nil
-    args.unshift nil if args.first.nil? || args.first.size > 1
-
-    # if there's only one or two arguments, we pad the values out
-    # with nil values, eventually adding a 'false' to the end of the stack
-    # because that's the default to represent required arguments
-    args.push nil if args.size == 1
-    args.push nil if args.size == 2
-    args.push false if args.size == 3
-
-    # if the second argument includes a space or some odd character it's
-    # probably a description, so we insert a nil into the option field and
-    # insert the original value into the description field
-    args[1..2] = [nil, args[1]] unless args[1].to_s =~ /\A[a-zA-Z_-]*\z/
-
-    # if there's no description given but the option requires an argument, it'll
-    # probably look like this: `[:f, :option, true]`
-    # so we replace the third option with nil to represent the description
-    # and push the true to the end of the stack
-    args[2..3] = [nil, true] if args[2] == true
-
-    # phew
-    args
-  end
 end