class OptionParser

• OptionParser
• Reference
• Object

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)
• Subcommands
• 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") 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:

Constructors

• .new

  Creates a new parser.

• .new(&)

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

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

Instance Method Summary

• #banner=(banner : String?)

  Establishes the initial message for the help printout.

• #before_each(&before_each : String -> )

  Sets a handler which runs before each argument is parsed.

• #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 or subcommand.

• #parse(args = ARGV) : Nil

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

• #separator(message = "") : Nil

  Adds a separator, with an optional header message, that will be used to print the help.

• #stop : Nil

  Stops the current parse and returns immediately, leaving the remaining flags unparsed.

• #to_s(io : IO) : Nil

  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.

Constructor Detail

Instance Method Detail

require "option_parser"

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