C-like getopt behavior — getopt • getopt

getopt is primarily intended to be used with Rscript. It facilitates writing #! shebang scripts that accept short and long flags/options. It can also be used from R directly, but is probably less useful in this context.

Usage

getopt(
  spec = NULL,
  opt = NULL,
  command = getfile(),
  usage = FALSE,
  debug = FALSE,
  operand = "after--only"
)

Arguments

spec

The getopt specification, or spec of what options are considered valid. The specification must be either a 4-5 column matrix, a 4-5 column data frame, or a character vector coercible into a 4 column matrix using matrix(x, ncol = 4L, byrow = TRUE) command. The matrix/vector contains:

Column 1: the long flag name. A multi-character string.

Column 2: short flag alias of Column 1. A single-character string. May be NA_character_ if there is no short flag.

Column 3: Action of the flag. A string. Possible values:

"append" (flag takes a required argument; appends it to a vector each time the flag is used)
"count" (flag takes no argument; stores count of how many times the flag was present)
"store_true" (flag takes no argument; stores TRUE)
"store_false" (flag takes no argument; stores FALSE)
"store" (flag takes a required argument)
"store_optional" (flag takes an optional argument but if none present stores TRUE)

For backwards compatibility 0, 1, 2 are accepted as aliases for "store_true", "store", "store_optional" respectively.

Column 4: Data type to which the flag's argument shall be cast using storage.mode(). A multi-character string. Only used when an action took an argument. Possible values: "logical", "integer", "double", "complex", "character". "numeric" is treated as an alias for "double".

Column 5 (optional): A brief description of the purpose of the option.

The terms option, flag, long flag, short flag, and argument have very specific meanings in the context of this document. Read the “Details” section of getopt() for definitions.

opt

This defaults to the return value of commandArgs(TRUE) unless argv is in the global environment in which case it uses that instead (this is for compatibility with littler).

If R was invoked directly via the R command, this corresponds to all arguments passed to R after the --args flag.

If R was invoked via the Rscript command, this corresponds to all arguments after the name of the R script file.

Read about commandArgs() and Rscript to learn more.

command

The string to use in the usage message as the name of the script. See argument usage.

usage

If TRUE, argument opt will be ignored and a usage statement (character string) will be generated and returned from spec.

debug

This is used internally to debug the getopt() function itself.

operand

Controls how positional arguments (operands) are handled.

"after--only" (the default) only collects operands that appear after a "--" separator.
"strict" (in addition to operands that appear after a "--" separator) collects tokens that do not look like flags and were not consumed as a flag argument, while still erroring on unrecognized flags.

Operands are stored in the "operand" attribute of the result and can be retrieved with getoperand().

Value

getopt() returns a list data structure containing names of the flags that were present in the character vector passed in under the opt argument. Each value of the list is coerced to the data type specified according to the value of the spec argument. See the “Details” section for more information. Any positional arguments (operands) are stored in its "operand" attribute and can also be accessed by getoperand().

Details

Notes on naming convention:

An option is one of the shell-split input strings.
A flag is a type of option. a flag can be defined as having no argument (defined below), a required argument, or an optional argument.
An argument is a type of option, and is the value associated with a flag.
A long flag is a type of flag, and begins with the string --. If the long flag has an associated argument, it may be delimited from the long flag by either a trailing =, or may be the subsequent option.
A short flag is a type of flag, and begins with the string -. If a short flag has an associated argument, it is the subsequent option. short flags may be bundled together, sharing a single leading -, but only the final short flag is able to have a corresponding argument.

Many users wonder whether they should use the getopt package, optparse package, or argparse package. Here is some of the major differences:

Features available in getopt unavailable in optparse

getopt allows one to specify options with an optional argument.
Long flags may be abbreviated as long as the abbreviation is unique, e.g. --verb matches --verbose if no other long flag starts with verb.

Some features implemented in the optparse package unavailable in getopt

Support for capturing positional arguments after the optional arguments when positional_arguments set to TRUE in optparse::parse_args()
Automatic generation of an help option and printing of help text when encounters an -h
Option to specify default arguments for options as well the variable name to store option values

There is also package argparse supports all the features of both getopt and optparse (plus more)

Some Features unlikely to be implemented in getopt:

Support for lists, e.g. --define os=linux --define os=redhat would set result$os$linux=TRUE and result$os$redhat=TRUE.

Author

Allen Day and Trevor L. Davis

Examples

#!/path/to/Rscript
library('getopt')
# get options, using the spec as defined by the matrix
spec <- matrix(c(
  'verbose', 'v', 2, "integer",
  'help'   , 'h', 0, "logical",
  'count'  , 'c', 1, "integer",
  'mean'   , 'm', 1, "double",
  'sd'     , 's', 1, "double"
), byrow = TRUE, ncol = 4L)
opt <- getopt(spec)

# if help was asked for print a friendly message and exit
if (isTRUE(opt$help)) {
  cat(getusage(spec))
  q(status = 0)
}

# set reasonable defaults for options that were not specified
if (is.null(opt$mean)) opt$mean <- 0
if (is.null(opt$sd)) opt$sd <- 1
if (is.null(opt$count)) opt$count <- 10L
if (is.null(opt$verbose)) opt$verbose <- FALSE

# print some progress messages to stderr, if requested
if (opt$verbose) write("writing...", stderr())

# do some operation based on user input
cat(rnorm(opt$count, mean = opt$mean, sd = opt$sd), sep = "\n")
#> -1.400044
#> 0.2553171
#> -2.437264
#> -0.005571287
#> 0.6215527
#> 1.148412
#> -1.821818
#> -0.2473253
#> -0.2441996
#> -0.2827054