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 | Nil)
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(flag, description, &block : String -> )
Establishes a handler for a flag.
-
#on(short_flag, long_flag, description, &block : String -> )
Establishes a handler for a pair of short and long flags.
-
#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)==(other : self) ==, dup dup, hash hash, inspect(io : IO) : Nil inspect, object_id : UInt64 object_id, same?(other : Reference)
same?(other : Nil) same?, to_s(io : IO) : Nil to_s
Instance methods inherited from class Object
!=(other)
!=,
!~(other)
!~,
==(other)
==,
===(other)===(other : YAML::Any)
===(other : JSON::Any) ===, =~(other) =~, class class, crystal_type_id crystal_type_id, dup dup, hash hash, inspect(io : IO)
inspect inspect, itself itself, not_nil! not_nil!, tap(&block) tap, 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
to_yaml(io : IO) to_yaml, try(&block) try
Class methods inherited from class Object
==(other : Class)
==,
===(other)
===,
cast(other) : self
cast,
clone
clone,
dup
dup,
from_json(string_or_io) : selffrom_json(string_or_io, root : String) : self from_json, from_yaml(string : String) : self from_yaml, hash hash, inspect(io) inspect, name : String name, nilable? nilable?, to_s(io) to_s, |(other : U.class) forall U |
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.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 flag.
Flags can (but don't have to) start with a 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)
Establishes a handler for a pair of short and long flags.
See the other definition of #on
for examples.
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.