Skip to contents

Generate a usage string

Source: R/getopt.R
getusage.Rd

Generate a usage string from a getopt spec matrix.

Usage

getusage(spec, command = getfile(), usage = "Usage: %command %options")

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.

command

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

usage

A template string for the usage line. "%command" is replaced by the value of command and "%options" is replaced by the computed options string.

Value

A character string with the usage message.

Examples

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 = 4)
cat(getusage(spec, command = "myscript"))
#> Usage: myscript [-[-verbose|v] [<integer>]] [-[-help|h]] [-[-count|c] <integer>] [-[-mean|m] <double>] [-[-sd|s] <double>]
cat(getusage(spec, command = "myscript",
             usage = "Usage: %command %options FILE"))
#> Usage: myscript [-[-verbose|v] [<integer>]] [-[-help|h]] [-[-count|c] <integer>] [-[-mean|m] <double>] [-[-sd|s] <double>] FILE