class OptionParser
Overview
OptionParser
is a class for command-line options processing. It supports:
- Short and long modifier style options (example:
-h
,--help
) - Passing arguments to the flags (example:
-f filename.txt
) - Automatic help message generation
Run crystal
for an example of a CLI built with OptionParser
.
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") { puts parser }
end
destination = destination.upcase if upcase
puts "Hello #{destination}!"
Defined in:
option_parser.crClass Method Summary
-
.new
Creates a new parser.
-
.new(&block)
Creates a new parser, with its configuration specified in the block.
-
.parse(args, &block) : self
Creates a new parser, with its configuration specified in the block, and uses it to parse the passed args.
-
.parse!(&block) : self
Creates a new parser, with its configuration specified in the block, and uses it to parse the arguments passed to the program.
Instance Method Summary
-
#banner=(banner : String?)
Establishes the initial message for the help printout.
-
#invalid_option(&invalid_option : String -> )
Sets a handler for option arguments that didn't match any of the setup options.
-
#missing_option(&missing_option : String -> )
Sets a handler for when a option that expects an argument wasn't given any.
-
#on(short_flag : String, long_flag : String, description : String, &block : String -> )
Establishes a handler for a pair of short and long flags.
-
#on(flag : String, description : String, &block : String -> )
Establishes a handler for a flag.
-
#parse(args)
Parses the passed args, running the handlers associated to each option.
-
#parse!
Parses the passed the arguments passed to the program, running the handlers associated to each option.
-
#separator(message = "")
Adds a separator, with an optional header message, that will be used to print the help.
-
#to_s(io : IO)
Returns all the setup options, formatted in a help message.
-
#unknown_args(&unknown_args : Array(String), Array(String) -> )
Sets a handler for regular arguments that didn't match any of the setup options.
Instance methods inherited from class Reference
==(other : self)==(other) ==, dup dup, hash hash, inspect(io : IO) : Nil inspect, object_id : UInt64 object_id, pretty_print(pp) : Nil pretty_print, same?(other : Reference)
same?(other : Nil) same?, to_s(io : IO) : Nil to_s
Class methods inherited from class Reference
new
new
Instance methods inherited from class Object
!=(other)
!=,
!~(other)
!~,
==(other)
==,
===(other : JSON::Any)===(other : YAML::Any)
===(other) ===, =~(other) =~, class class, dup dup, hash hash, inspect(io : IO)
inspect inspect, itself itself, not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, tap(&block) tap, to_json(io : IO)
to_json to_json, to_pretty_json(indent : String = " ")
to_pretty_json(io : IO, indent : String = " ") to_pretty_json, to_s
to_s(io : IO) to_s, to_yaml(io : IO)
to_yaml to_yaml, try(&block) try
Class methods inherited from class Object
from_json(string_or_io, root : String) : selffrom_json(string_or_io) : self from_json, from_yaml(string_or_io) : self from_yaml
Class Method Detail
Creates a new parser, with its configuration specified in the block, and uses it to parse the passed args.
Creates a new parser, with its configuration specified in the block, and uses it to parse the arguments passed to the program.
Instance Method Detail
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:
parser = OptionParser.new
parser.banner = "Usage: crystal [command] [switches] [program file] [--] [arguments]"
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 raises 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 raises MissingOption
.
Establishes a handler for a pair of short and long flags.
See the other definition of #on
for examples.
Establishes a handler for a flag.
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.
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)
Parses the passed the arguments passed to the program, running the handlers associated to each option.
Adds a separator, with an optional header message, that will be used to print the help.
This way, you can group the different options in an easier to read way.