class OptionParser

Overview

OptionParser is a class for command-line options processing. It supports:

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

Constructors

Instance Method Summary

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

Constructor 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, unsafe_as(type : T.class) forall T unsafe_as

Constructor methods inherited from class Object

from_json(string_or_io, root : String) : self
from_json(string_or_io) : self from_json, from_yaml(string_or_io) : self from_yaml

Constructor Detail

def self.new #

Creates a new parser.


View source
def self.new(&block) #

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


View source
def self.parse(args, &block) : self #

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


View source
def self.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.


View source

Instance Method Detail

def banner=(banner : String?) #

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

View source
def invalid_option(&invalid_option : String -> ) #

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.


View source
def missing_option(&missing_option : String -> ) #

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.


View source
def on(short_flag : String, long_flag : String, description : String, &block : String -> ) #

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

See the other definition of #on for examples.


View source
def on(flag : String, description : String, &block : String -> ) #

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)

View source
def parse(args) #

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


View source
def parse! #

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


View source
def separator(message = "") #

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.


View source
def to_s(io : IO) #

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


View source
def unknown_args(&unknown_args : Array(String), Array(String) -> ) #

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)


View source