https://github.com/leejarvis/slop

Simple Lightweight Option Parsing - ✨ new contributors welcome ✨
https://github.com/leejarvis/slop

Keywords

beginner-friendly command-line easy-to-use option-parser ruby simple

Keywords from Contributors

rubygems rack activerecord mvc activejob sinatra rspec ruby-gem rdoc rubocop

Last synced: about 22 hours ago
JSON representation

Repository metadata

Simple Lightweight Option Parsing - ✨ new contributors welcome ✨

Host: GitHub
URL: https://github.com/leejarvis/slop
Owner: leejarvis
License: mit
Created: 2010-11-26T22:09:15.000Z (over 15 years ago)
Default Branch: master
Last Pushed: 2025-10-06T14:14:05.000Z (5 months ago)
Last Synced: 2026-02-22T13:47:35.522Z (9 days ago)
Topics: beginner-friendly, command-line, easy-to-use, option-parser, ruby, simple
Language: Ruby
Homepage:
Size: 1.16 MB
Stars: 1,129
Watchers: 15
Forks: 72
Open Issues: 2
Releases: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Slop - Simple, Lightweight Option Parser

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

Installation

gem install slop

Usage

opts = Slop.parse do |o|
  o.string '-h', '--host', 'a hostname'
  o.integer '--port', 'custom port', default: 80
  o.string '-l', '--login', required: true
  o.symbol '-m', '--method', default: :get
  o.bool '-v', '--verbose', 'enable verbose mode'
  o.bool '-q', '--quiet', 'suppress output (quiet mode)'
  o.bool '-c', '--check-ssl-certificate', 'check SSL certificate for host'
  o.bool '-k', '--use-keychain', 'store passphrase in OS keychain'
  o.on '--version', 'print the version' do
    puts Slop::VERSION
    exit
  end
end

ARGV #=> -v --login alice --host 192.168.0.1 -m post --check-ssl-certificate --use-keychain false

opts[:host]         #=> 192.168.0.1
opts[:login]        #=> alice
opts[:method]       #=> :post
opts[:use_keychain] #=> false

# We can also check if a flag was passed (this has no bearing on the options default value):
opts.use_keychain?          #=> true
opts.verbose?               #=> true
opts.quiet?                 #=> false
opts.check_ssl_certificate? #=> true

opts.to_hash  #=> { host: "192.168.0.1", port: 80, login: "alice", method: :post, verbose: true, quiet: false, check_ssl_certificate: true }

Note that the block we've added to the --version flag will be executed
during parse time. Therefore these blocks should be reserved
for immediately reacting to the presence of a flag. If you want to
access other options or mutate values, check out the "Custom option types"
section below and implement the #finish method.

Option types

Built in Option types are as follows:

o.string  #=> Slop::StringOption, expects an argument
o.bool    #=> Slop::BoolOption, argument optional, aliased to BooleanOption
o.integer #=> Slop::IntegerOption, expects an argument, aliased to IntOption
o.float   #=> Slop::FloatOption, expects an argument
o.array   #=> Slop::ArrayOption, expects an argument
o.regexp  #=> Slop::RegexpOption, expects an argument
o.symbol  #=> Slop::SymbolOption, expects an argument
o.null    #=> Slop::NullOption, no argument and ignored from `to_hash`
o.on      #=> alias for o.null

You can see all built in types in slop/types.rb. Suggestions or pull requests
for more types are welcome.

Advanced Usage

This example is really just to describe how the underlying API works.
It's not necessarily the best way to do it.

opts = Slop::Options.new
opts.banner = "usage: connect [options] ..."
opts.separator ""
opts.separator "Connection options:"
opts.string "-H", "--hostname", "a hostname"
opts.int "-p", "--port", "a port", default: 80
opts.separator ""
opts.separator "Extra options:"
opts.array "--files", "a list of files to import"
opts.bool "-v", "--verbose", "enable verbose mode", default: true

parser = Slop::Parser.new(opts)
result = parser.parse(["--hostname", "192.168.0.1", "--no-verbose"])

result.to_hash #=> { hostname: "192.168.0.1", port: 80,
                 #     files: [], verbose: false }

puts opts # prints out help

Arguments

It's common to want to retrieve an array of arguments that were not processed
by the parser (i.e options or consumed arguments). You can do that with the
Result#arguments method:

args = %w(connect --host google.com GET)
opts = Slop.parse args do |o|
  o.string '--host'
end

p opts.arguments #=> ["connect", "GET"] # also aliased to `args`

This is particularly useful when writing scripts with ARGF:

opts = Slop.parse do |blah|
  # ...
end

# make sure sloptions aren't consumed by ARGF
ARGV.replace opts.arguments

ARGF.each { |line|
  # ...
}

Arrays

Slop has a built in ArrayOption for handling array values:

opts = Slop.parse do |o|
  # the delimiter defaults to ','
  o.array '--files', 'a list of files', delimiter: ','
end

# Both of these will return o[:files] as ["foo.txt", "bar.rb"]:
# --files foo.txt,bar.rb
# --files foo.txt --files bar.rb
# This will return o[:files] as []:
# --files ""

If you want to disable the built-in string-splitting, set the delimiter to
nil.

Custom option types

Slop uses option type classes for every new option added. They default to the
NullOption. When you type o.array Slop looks for an option called
Slop::ArrayOption. This class must contain at least 1 method, call. This
method is executed at parse time, and the return value of this method is
used for the option value. We can use this to build custom option types:

module Slop
  class PathOption < Option
    def call(value)
      Pathname.new(value)
    end
  end
end

opts = Slop.parse %w(--path ~/) do |o|
  o.path '--path', 'a custom path name'
end

p opts[:path] #=> #<Pathname:~/>

Custom options can also implement a finish method. This method by default
does nothing, but it's executed once all options have been parsed. This
allows us to go back and mutate state without having to rely on options
being parsed in a particular order. Here's an example:

module Slop
  class FilesOption < ArrayOption
    def finish(opts)
      if opts.expand?
        self.value = value.map { |f| File.expand_path(f) }
      end
    end
  end
end

opts = Slop.parse %w(--files foo.txt,bar.rb -e) do |o|
  o.files '--files', 'an array of files'
  o.bool '-e', '--expand', 'if used, list of files will be expanded'
end

p opts[:files] #=> ["/full/path/foo.txt", "/full/path/bar.rb"]

Errors

Slop will raise errors for the following:

An option used without an argument when it expects one: Slop::MissingArgument
An option used that Slop doesn't know about: Slop::UnknownOption
An option marked as required when not provided: Slop::MissingRequiredOption
An option marked as validate_types, with an argument that does not match its
type (i.e. bla for integer): Slop::InvalidOptionValue

These errors inherit from Slop::Error, so you can rescue them all.
Alternatively you can suppress these errors with the suppress_errors config
option:

opts = Slop.parse suppress_errors: true do
  o.string '-name'
end

# or per option:

opts = Slop.parse do
  o.string '-host', suppress_errors: true
  o.int '-port'
end

Validating Types

By default, Slop does not validate whether an argument is a valid value for a
given option; instead, if the option has a default value, it will be used over
the invalid argument provided.
In order to have types (such as integer and float) validate and indicate
that the provided value is invalid, an extra option can be either provided to
the argument itself, or its option set:

opts = Slop::Options.new
opts.int "-p", "--port", "a port", default: 80, validate_types: true

parser = Slop::Parser.new(opts)
result = parser.parse(["--port", "bla"])
# invalid value for -p, --port (Slop::InvalidOptionValue)

# Or to the option set...
opts = Slop::Options.new(validate_types: true)
opts.int "-p", "--port", "a port", default: 80

parser = Slop::Parser.new(opts)
result = parser.parse(["--port", "bla"])
# invalid value for -p, --port (Slop::InvalidOptionValue)

Printing help

The return value of Slop.parse is a Slop::Result which provides a nice
help string to display your options. Just puts opts or call opts.to_s:

opts = Slop.parse do |o|
  o.string '-h', '--host', 'hostname'
  o.int '-p', '--port', 'port (default: 80)', default: 80
  o.string '--username'
  o.separator ''
  o.separator 'other options:'
  o.bool '--quiet', 'suppress output'
  o.on '-v', '--version' do
    puts "1.1.1"
  end
end

puts opts

Output:

% ruby run.rb
usage: run.rb [options]
    -h, --host     hostname
    -p, --port     port (default: 80)
    --username

other options:
    --quiet        suppress output
    -v, --version

This method takes an optional prefix value, which defaults to " " * 4:

puts opts.to_s(prefix: "  ")

It'll deal with aligning your descriptions according to the longest option
flag.

Here's an example of adding your own help option:

o.on '--help' do
  puts o
  exit
end

Owner metadata

Name: Lee Jarvis
Login: leejarvis
Email: lee@jrvs.uk
Kind: user
Description: Experienced Ruby and Elixir developer. CTO and Co-Founder at @sprk
Website: lee.jrvs.uk
Location: U.K.
Twitter:
Company:
Icon url: https://avatars.githubusercontent.com/u/197567?u=a2c298edbedde77374bdf4ce5c0d7e9fb3096c89&v=4
Repositories: 53
Last ynced at: 2026-02-20T05:31:09.016Z
Profile URL: https://github.com/leejarvis

GitHub Events

Total

Issues event: 1
Watch event: 9
Push event: 1
Pull request event: 2
Fork event: 2

Last Year

Issues event: 1
Watch event: 6
Push event: 1
Pull request event: 2
Fork event: 1

Committers metadata

Last synced: 7 days ago

Total Commits: 1,140
Total Committers: 57
Avg Commits per committer: 20.0
Development Distribution Score (DDS): 0.354

Commits in past year: 2
Committers in past year: 1
Avg Commits per committer in past year: 2.0
Development Distribution Score (DDS) in past year: 0.0

Name	Email	Commits
Lee Jarvis	l**e@j**o	737
Lee Jarvis	l**s@g**m	238
Olle Jonsson	o**n@g**m	32
Kenichi Kamiya	k**1@g**m	22
sigurdsvela	s**a@g**m	8
Andrew Horsman	m**s@g**m	7
Dominik Honnef	d**h@f**g	7
Amon Sha	a**a@g**m	5
George Anderson	g**e@b**m	5
Victor Gama	h**y@v**o	4
Juha Ylitalo	j**o@r**i	3
Nobuhiro IMAI	n**v@y**p	3
Naoki Mizuno	n**r@g**m	3
Laurent Arnoud	l**t@s**t	3
Kyrylo Silin	k**n@g**m	3
Hansuk	f**3@g**m	3
Eric Anderson	e**c@p**m	3
Autumn Perrault	a**n@d**t	3
Greg Fitzgerald	n**n@g**m	2
Ben Brady	b**y@e**m	2
Conrad Irwin	c**n@g**m	2
Denis Defreyne	d**e@s**g	2
Jimmy Cuadra	j**y@j**m	2
Joe Gracyk	j**k@s**m	2
Koichi ITO	k**o@g**m	2
Peter Goldstein	p**n@g**m	2
Peter Zotov	w**k@w**g	2
Rick Hull	r**l@g**m	2
Teemu Matilainen	t**n@i**i	2
William Woodruff	w**m@t**m	2
and 27 more...

Committer domains:

Issue and Pull Request metadata

Last synced: 16 days ago

Total issues: 53
Total pull requests: 54
Average time to close issues: 5 months
Average time to close pull requests: 4 months
Total issue authors: 37
Total pull request authors: 30
Average comments per issue: 2.92
Average comments per pull request: 2.33
Merged pull request: 42
Bot issues: 0
Bot pull requests: 0

Past year issues: 2
Past year pull requests: 2
Past year average time to close issues: 13 minutes
Past year average time to close pull requests: 1 minute
Past year issue authors: 1
Past year pull request authors: 1
Past year average comments per issue: 1.5
Past year average comments per pull request: 0.0
Past year merged pull request: 0
Past year bot issues: 0
Past year bot pull requests: 0

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/leejarvis/slop

Top Issue Authors

fawaf (6)
dg1727 (3)
MadBomber (3)
ankane (2)
voltechs (2)
marwal-88 (2)
alexherbo2 (2)
akun1 (2)
lbriais (2)
olleolleolle (2)
duckinator (1)
sepastian (1)
jdh-invicara (1)
retorquere (1)
unleashy (1)

Top Pull Request Authors

olleolleolle (16)
leejarvis (3)
woodruffw (2)
felixcuello (2)
tmatilai (2)
burke (2)
jylitalo (2)
MadBomber (2)
petergoldstein (2)
koic (1)
kch (1)
ConnorWGarvey (1)
eugeneotto (1)
mwpastore (1)
TomCrypto (1)

Top Issue Labels

bug (3)
feature (1)
v3 (1)

Top Pull Request Labels

feature (1)

Package metadata

Total packages: 13
Total downloads:
- rubygems: 304,004,665 total
Total docker downloads: 1,483,490,408
Total dependent packages: 510 (may contain duplicates)
Total dependent repositories: 172,933 (may contain duplicates)
Total versions: 262
Total maintainers: 1

gem.coop: slop

A DSL for gathering options and parsing command line flags

Homepage: http://github.com/leejarvis/slop
Documentation: http://www.rubydoc.info/gems/slop/
Licenses: MIT
Latest release: 4.10.1 (published about 3 years ago)
Last Synced: 2026-02-25T06:31:52.805Z (6 days ago)
Versions: 85
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 152,013,661 Total
Docker Downloads: 741,745,204
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 0.071%
- Docker downloads count: 0.123%
- Downloads: 0.161%
Maintainers (1)
- leejarvis

rubygems.org: slop