Skip to content
Tutorials Center
My learning

Topics

Lesson 85 of 134 ยท Standard Library

OptionParser and Logger

Build command-line tools with Ruby's OptionParser (flags, typed arguments, help, errors) and record what your program does with Logger (levels, formatters, progname) - all runnable in the browser.

Two small libraries turn a script into a proper tool. OptionParser reads the command line: flags such as -v or --count 3, arguments converted to the right type, an automatic --help text, and clear errors when the user types something wrong. Logger records what the program does, with severities (debug, info, warn, error), timestamps and a format you control, so that you can find out what happened after the fact.

Both ship with Ruby. Both are used in almost every command-line program, background job and web application, so this is a lesson worth learning properly. A real script gets its options from the global ARGV array (see Scripting and Command-Line Tools); here we pass arrays of words by hand, which is exactly what ARGV would contain, so every example is runnable in the browser.

OptionParser basics

You create an OptionParser, describe each option with on, and call parse with the arguments. Each on takes the option's spellings, optional type and description, and a block that runs when the option appears.

Ruby Your first OptionParser

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

parse runs the blocks, then returns the leftover words, the ones that are not options (a.txt and b.txt). Notice how much work was done for you:

  • -n 3 and --count 3 are the same option, and -n3 works too. Because of Integer, the block receives 3, a number, not the string "3".
  • --[no-]verbose defines both --verbose (value true) and --no-verbose (value false).
  • [:json, :text] restricts the value to a list; the block receives the matching symbol.
  • Array splits x,y at commas; Float converts decimals. Other built-in types are Integer, Float, Numeric, String, Symbol, Regexp, TrueClass, Time and more.
  • The help text is generated from your descriptions. Column widths and alignment are automatic.

Options may appear in any order and may be mixed with the files. Give an option an argument that is optional with square brackets: o.on("-o [FILE]") passes nil when none is given.

A long option can be abbreviated

Ruby Abbreviations, -- and parse versus parse!

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

--verb is accepted because no other option starts with those letters, which is handy when typing but a reason to keep long names distinct. Scripts normally use parser.parse!(ARGV), which removes the options from ARGV so that only the file names remain. order is for tools with subcommands: it stops parsing at the first non-option word and leaves the rest for you.

When the user makes a mistake

Bad input raises a subclass of OptionParser::ParseError, a RuntimeError. Each has a readable message, so a small rescue turns a stack trace into good advice.

Ruby The parse errors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Unknown options raise InvalidOption, a missing value raises MissingArgument, and a value of the wrong type or outside the allowed list raises InvalidArgument. All three inherit from ParseError, so one rescue catches them. Unhandled, they end the program with a backtrace, which is a poor experience for a user:

Ruby An unhandled OptionParser error (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

The run stops with main.rb:4:in '<main>': invalid option: --cuont (OptionParser::InvalidOption), followed by a hint line, Did you mean? count, which Ruby adds when it finds a similar name. Compare it with a friendlier program that reports the problem and the help, and exits with a non-zero status so shells and scripts can tell that it failed:

Ruby A complete small command

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Notice the structure: parsing lives in a function that takes the argument array (so tests can call it, see Testing with Minitest), results go into a Struct, mistakes are reported on the error stream with warn, and the numeric return value is the exit status you would pass to exit (0 for success, non-zero for failure). The warn lines appear in the output because the runner shows both streams.

Collecting into a hash

If you do not need a block per option, into: stores values in a hash for you. The key is derived from the long option name:

Ruby parse with into:

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Logger: leaving a trail

print and puts are fine for output a user is meant to read. For messages that explain what a program did and why, use Logger (require 'logger'). Every message has a severity, and the logger drops everything below its configured level. That is the point: you write detailed debug messages once, and switch them off in production without touching the code.

The severities from least to most severe are DEBUG, INFO, WARN, ERROR and FATAL, plus UNKNOWN for "always print". Here is a logger writing into a string, with the volatile parts (time and process id) masked so we can read the structure:

Ruby Severities and the default format

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Each default line has the form I, [time #pid] INFO -- progname: message: the first letter, the timestamp with the process id, the severity, the program name (empty unless you set one) and the message. A new Logger starts at level DEBUG, so everything is shown. Setting level to Logger::WARN makes info and debug calls do nothing. You can also write log.level = :warn or "warn".

Where logs go

Logger.new accepts any destination that has write and close: $stdout, $stderr, a StringIO, a path (Logger.new("app.log")) or nil for a logger that discards everything. Container-based deployments log to $stdout and let the platform collect it. Files can rotate so they do not grow without bound; this is read-only because it needs real files:

Ruby
# read-only example: writes real files
log = Logger.new("app.log", 5, 10_000_000)   # keep 5 old files, rotate at about 10 MB
log2 = Logger.new("daily.log", "daily")       # a new file every day

Custom formats

A logger's formatter is anything that responds to call(severity, time, progname, message) and returns the line to write. A lambda or proc is enough. You can also set progname to tag where messages come from, and pass the options to new.

Ruby formatter, progname and level

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Two details deserve attention. First, the block form log.warn { "..." }: Ruby evaluates the block only when that level is enabled, so expensive messages (log.debug { data.inspect }) cost nothing when debug logging is off. Second, the message argument is whatever you passed: a string, a hash, an exception object. A custom formatter decides how to print each; the default formatter turns exceptions into message plus backtrace. One JSON object per line (the format in the second logger) is what log-collection systems like best, and parses back with JSON.

Logging in real programs

Ruby A class with an injected logger

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Passing the logger in (dependency injection, see Design Principles) keeps the class easy to test: tests give it a StringIO and check what was written, and the default Logger.new(nil) keeps it quiet when nobody cares. Avoid global loggers scattered through the code. Choose severities by who needs to react: debug for developer detail, info for normal milestones, warn for odd-but-handled situations (like the skipped rows above), error for failures that need attention, fatal for "the program cannot continue".

Log the why and the identifiers (which row, which user, which request), not just "something failed". Never log passwords, tokens or personal data. And log an exception once, where you handle it, rather than at every level as it passes through.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does parser.parse(%w[-n 3 a.txt]) return, assuming -n takes a number?

    parse runs the option blocks and returns the leftover words that are not options, here only the file name.
  2. 2. What is the difference between parse and parse!?

    parse leaves the given array unchanged. parse! modifies it in place, which is why scripts call parse!(ARGV) and are left with only the file names.
  3. 3. Which exception does OptionParser raise for --count abc when --count was declared with Integer?

    InvalidOption means the option itself is unknown. A value that cannot be converted raises InvalidArgument. Both inherit from OptionParser::ParseError.
  4. 4. A logger is set to level WARN. Which of these calls writes something?

    Messages below the level are dropped. ERROR is more severe than WARN, so it is written, and DEBUG and INFO are not.
  5. 5. Why prefer log.debug { expensive_dump } over log.debug(expensive_dump)?

    With the argument form the expensive expression is computed before the call whether or not it will be logged. The block is skipped when the level filters the message out.

Summary

  • OptionParser.new { |o| o.on(...) } declares options with short and long names, types (Integer, Float, Array, a list of symbols), help text and a block; parse returns the leftover arguments and parse! removes the consumed ones from the array.
  • Help text is generated; write the banner and use separator for sections. Long options can be abbreviated and -- ends option processing.
  • Mistakes raise OptionParser::InvalidOption, MissingArgument or InvalidArgument, all ParseErrors: rescue them, print the message, and return a non-zero status.
  • Logger has severities DEBUG to FATAL (plus UNKNOWN) and drops messages below its level; use the block form for costly messages.
  • Control the output with formatter, progname and the destination ($stdout, a file, a StringIO, nil); inject loggers into your classes to keep them testable.

Next: ERB Templates