OptionParser is a class for command-line options processing. It supports:
-h, --help)-f filename.txt)Run crystal for an example of a CLI built with OptionParser.
NOTE To use OptionParser, you must explicitly import it with require "option_parser"
Short example:
require "option_parser"
upcase = false
destination = "World"
OptionParser.parse do |parser|
parser.banner = "Usage: salute [arguments]"
parser.on("-u", "--upcase", "Upcases the salute") { upcase = true }
parser.on("-t NAME", "--to=NAME", "Specifies the name to salute") { |name| destination = name }
parser.on("-h", "--help", "Show this help") do
puts parser
exit
end
parser.invalid_option do |flag|
STDERR.puts "ERROR: #{flag} is not a valid option."
STDERR.puts parser
exit(1)
end
end
destination = destination.upcase if upcase
puts "Hello #{destination}!" OptionParser also supports subcommands.
Short example:
require "option_parser"
verbose = false
salute = false
welcome = false
name = "World"
parser = OptionParser.new do |parser|
parser.banner = "Usage: example [subcommand] [arguments]"
parser.on("salute", "Salute a name") do
salute = true
parser.banner = "Usage: example salute [arguments]"
parser.on("-t NAME", "--to=NAME", "Specify the name to salute") { |_name| name = _name }
end
parser.on("welcome", "Print a greeting message") do
welcome = true
parser.banner = "Usage: example welcome"
end
parser.on("-v", "--verbose", "Enabled verbose output") { verbose = true }
parser.on("-h", "--help", "Show this help") do
puts parser
exit
end
end
parser.parse
if salute
STDERR.puts "Saluting #{name}" if verbose
puts "Hello #{name}"
elsif welcome
STDERR.puts "Welcoming #{name}" if verbose
puts "Welcome!"
else
puts parser
exit(1)
end Creates a new parser.
Creates a new parser, with its configuration specified in the block.
Creates a new parser, with its configuration specified in the block, and uses it to parse the passed args (defaults to ARGV).
Establishes the initial message for the help printout.
Sets a handler which runs before each argument is parsed.
Returns whether the GNU convention is followed for optional arguments.
Returns whether the GNU convention is followed for optional arguments.
Sets a handler for option arguments that didn't match any of the setup options.
Sets a handler for when a option that expects an argument wasn't given any.
Establishes a handler for a pair of short and long flags.
Establishes a handler for a flag or subcommand.
Parses the passed args (defaults to ARGV), running the handlers associated to each option.
Adds a separator, with an optional header message, that will be used to print the help.
Stops the current parse and returns immediately, leaving the remaining flags unparsed.
Indentation for summary.
Indentation for summary.
Width for option list portion of summary.
Width for option list portion of summary.
Returns all the setup options, formatted in a help message.
Sets a handler for regular arguments that didn't match any of the setup options.
Reference
Reference
Reference
Object
Object
Object
Creates a new parser.
Refer to #gnu_optional_args? for the behaviour of the named parameter.
Creates a new parser, with its configuration specified in the block.
Refer to #gnu_optional_args? for the behaviour of the named parameter.
Creates a new parser, with its configuration specified in the block, and uses it to parse the passed args (defaults to ARGV).
Refer to #gnu_optional_args? for the behaviour of the named parameter.
Establishes the initial message for the help printout. Typically, you want to write here the name of your program, and a one-line template of its invocation.
Example:
require "option_parser" parser = OptionParser.new parser.banner = "Usage: crystal [command] [switches] [program file] [--] [arguments]"
Sets a handler which runs before each argument is parsed. This callback is not passed flag arguments. For example, --foo=foo_arg --bar bar_arg would pass --foo=foo_arg and --bar to the callback only.
You typically use this to implement advanced option parsing behaviour such as treating all options after a filename differently (along with #stop).
Returns whether the GNU convention is followed for optional arguments.
If true, any optional argument must follow the preceding flag in the same token immediately, without any space inbetween:
require "option_parser"
OptionParser.parse(%w(-a1 -a 2 -a --b=3 --b 4), gnu_optional_args: true) do |parser|
parser.on("-a", "--b [x]", "optional") { |x| p x }
parser.unknown_args { |args, _| puts "Remaining: #{args}" }
end Prints:
"1" "" "" "3" "" Remaining: ["2", "4"]
Without gnu_optional_args: true, prints the following instead:
"1" "2" "--b=3" "4" Remaining: []
Returns whether the GNU convention is followed for optional arguments.
If true, any optional argument must follow the preceding flag in the same token immediately, without any space inbetween:
require "option_parser"
OptionParser.parse(%w(-a1 -a 2 -a --b=3 --b 4), gnu_optional_args: true) do |parser|
parser.on("-a", "--b [x]", "optional") { |x| p x }
parser.unknown_args { |args, _| puts "Remaining: #{args}" }
end Prints:
"1" "" "" "3" "" Remaining: ["2", "4"]
Without gnu_optional_args: true, prints the following instead:
"1" "2" "--b=3" "4" Remaining: []
Sets a handler for option arguments that didn't match any of the setup options.
You typically use this to display a help message. The default behaviour is to raise InvalidOption.
Sets a handler for when a option that expects an argument wasn't given any.
You typically use this to display a help message. The default behaviour is to raise MissingOption.
Establishes a handler for a pair of short and long flags.
See the other definition of #on for examples. This method does not support subcommands.
Establishes a handler for a flag or subcommand.
Flags must start with a dash or double dash. They can also have an optional argument, which will get passed to the block. Each flag has a description, which will be used for the help message.
Subcommands are any flag passed which does not start with a dash. They cannot take arguments. When a subcommand is parsed, all subcommands are removed from the OptionParser, simulating a "tree" of subcommands. All flags remain valid. For a longer example, see the examples at the top of the page.
Examples of valid flags:
-a, -B
--something-longer-f FILE, --file FILE, --file=FILE (these will yield the passed value to the block as a string)Examples of valid subcommands:
foo, run
Parses the passed args (defaults to ARGV), running the handlers associated to each option.
Adds a separator, with an optional header message, that will be used to print the help. The separator is placed between the flags registered (#on) before, and the flags registered after the call.
This way, you can group the different options in an easier to read way.
Stops the current parse and returns immediately, leaving the remaining flags unparsed. This is treated identically to -- being inserted behind the current parsed flag.
Sets a handler for regular arguments that didn't match any of the setup options.
You typically use this to get the main arguments (not modifiers) that your program expects (for example, filenames). The default behaviour is to do nothing. The arguments can also be extracted from the args array passed to #parse after parsing.
© 2012–2026 Manas Technology Solutions.
Licensed under the Apache License, Version 2.0.
https://crystal-lang.org/api/1.19.0/OptionParser.html