OptionParser

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.cr

Class 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`

, , , , , , ,

Class methods inherited from class `Reference`

Instance methods inherited from class `Object`

, , , , , , , , , , , , , , , , , ,

Class methods inherited from class `Object`

Class Method Detail

def self.newSource

Creates a new parser.

def self.new(&block)Source

Creates a new parser, with its configuration specified in the block.

def self.parse(args, &block) : selfSource

Creates a new parser, with its configuration specified in the block, and uses it to parse the passed args.

def self.parse!(&block) : selfSource

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

def banner=(banner : String?)Source

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

def invalid_option(&invalid_option : String -> )Source

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.

def missing_option(&missing_option : String -> )Source

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.

def on(short_flag : String, long_flag : String, description : String, &block : String -> )Source

Establishes a handler for a pair of short and long flags.

See the other definition of #on for examples.

def on(flag : String, description : String, &block : String -> )Source

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)

def parse(args)Source

Parses the passed args, running the handlers associated to each option.

def parse!Source

Parses the passed the arguments passed to the program, running the handlers associated to each option.

def separator(message = "")Source

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.

def to_s(io : IO)Source

Returns all the setup options, formatted in a help message.

def unknown_args(&unknown_args : Array(String), Array(String) -> )Source

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)

© 2012–2017 Manas Technology Solutions.
Licensed under the Apache License, Version 2.0.
https://crystal-lang.org/api/0.22.0/OptionParser.html