Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

128 lines (90 sloc) 3.238 kb

Slop

Slop is a simple option collector with an easy to remember syntax and friendly API.

Installation

Rubygems

gem install slop

GitHub

git clone git://github.com/injekt/slop.git
cd slop
rake install

Usage

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

  option(:a, :age, "Your age", true, :optional => true) # optional argument
  option(:address, "Your address", :optional => true)   # the same

  # shortcut option aliases
  opt(:height, "Your height")
  o(:weight, "Your weight")
end

# using `--name Lee -a 100`
s.options_hash #=> {:verbose=>false, :name=>"Lee", :age=>"100", :address=>nil}
s.value_for(:name) #=> "Lee"

# or grab the Option object directly
option = s.option_for(:name)
option.description #=> "Your name"

# 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

# without `-v`
s.value_for(:verbose) #=> false

# using `-v`
s.value_for(:verbose) #=> true

# using `--applicable_age`
s.value_for(:applicable_age) #=> 20

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
end

Now when using the --version option on the command line, the trigger will be called and its contents executed.

Casting

If you want to return values of specific types, for example a Symbol or Integer you can pass the :as attribute to your option.

s = Slop.parse("--age 20") do
  opt(:age, true, :as => Integer) # :int/:integer both also work
end
s.value_for(:age) #=> 20 # not "20"

Smart

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")

and Slop will detect a description in place of an option, so you don't have to do this:

opt(:n, nil, "Your name")

You can also try other variations:

opt(:name, "Your name")
opt(:n, :name)
opt(:name)

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.value_for(:people) #=> ["lee", "injekt"]

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)
end
s.value_for(: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 me a pull request. I'd be more than happy to look at it.

Jump to Line
Something went wrong with that request. Please try again.