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") 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}!"

Subcommands

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

Defined in:

option_parser.cr

Constructors

Instance Method Summary

Instance methods inherited from class Reference

==(other : self)
==(other : JSON::Any)
==(other : YAML::Any)
==(other)
==
, dup dup, hash(hasher) 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

! : Bool !, !=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other)
===
, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash(hasher)
hash
hash
, in?(*values : Object) : Bool
in?(collection) : Bool
in?
, inspect : String
inspect(io : IO) : Nil
inspect
, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO)
to_json
to_json
, to_pretty_json(io : IO, indent : String = " ")
to_pretty_json(indent : String = " ")
to_pretty_json
, to_s : String
to_s(io : IO) : Nil
to_s
, to_yaml(io : IO)
to_yaml
to_yaml
, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

Class methods inherited from class Object

from_json(string_or_io, root : String)
from_json(string_or_io)
from_json
, from_yaml(string_or_io : String | IO) from_yaml

Constructor Detail

def self.new #

Creates a new parser.


[View source]
def self.new(&) #

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


[View source]
def self.parse(args = ARGV, &) : self #

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


[View source]
def self.parse!(&) : self #

DEPRECATED Use #parse instead.


[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:

require "option_parser"

parser = OptionParser.new
parser.banner = "Usage: crystal [command] [switches] [program file] [--] [arguments]"

[View source]
def before_each(&before_each : String -> ) #

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


[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 behaviour is to raise 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 behaviour is to raise 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. This method does not support subcommands.


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

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

[View source]
def parse(args = ARGV) #

Parses the passed args (defaults to ARGV), running the handlers associated to each option.


[View source]
def parse! #

DEPRECATED Use #parse instead.


[View source]
def separator(message = "") #

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.


[View source]
def stop #

Stops the current parse and returns immediately, leaving the remaining flags unparsed. This is treated identically to -- being inserted behind the current parsed flag.


[View source]
def to_s(io : IO) : Nil #

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). The default behaviour is to do nothing. The arguments can also be extracted from the args array passed to #parse after parsing.


[View source]