Functions to enable our OptionParser to recognize specific command line options.

add_option() adds a option to a prexisting OptionParser instance whereas make_option() is used to create a list of OptionParserOption instances that will be used in the option_list argument of the OptionParser function to create a new OptionParser instance.

Usage

make_option(
  opt_str,
  action = NULL,
  type = NULL,
  dest = NULL,
  default = NULL,
  help = "",
  metavar = NULL,
  callback = NULL,
  callback_args = NULL,
  const = NULL,
  required = FALSE
)

add_option(
  object,
  opt_str,
  action = NULL,
  type = NULL,
  dest = NULL,
  default = NULL,
  help = "",
  metavar = NULL,
  callback = NULL,
  callback_args = NULL,
  const = NULL,
  required = FALSE
)

Arguments

opt_str

A character vector containing the string of the desired long flag comprised of -- followed by a non-dash character (and optionally more characters), and optionally a string of the desired short flag comprised of the - followed by a single non-dash character. We don't allow = or whitespace characters in flags.

action

A character string describing the action optparse should take when it encounters an option. One of:

"append": appends each occurrence's value to default (or to an empty vector if default is NULL). Returns NULL if never seen and default is NULL.
"callback": stores the return value of the callback function.
"count": counts the number of times the flag is seen and adds it to default (treated as 0L if not supplied). Returns NULL if never seen and no default was supplied.
"store" (default): stores the specified following value.
"store_const": stores const if the flag is seen, otherwise default. Returns NULL if the flag is not seen and default is NULL.
"store_true": stores TRUE if the option is found.
"store_false": stores FALSE if the option is found.

If callback is not NULL the default action is "callback" otherwise it is "store".

type

A character string specifying which data type to store: "logical", "integer", "double", "complex", or "character" ("numeric" is an alias for "double"). Defaults:

if action == "count" then "integer"
if action %in% c("store_false", "store_true") then "logical"
if action == "store" and default is not NULL then typeof(default)else if default is NULL then "character"

dest

A character string specifying what field in the list returned by parse_args() should optparse store the option value. Default is derived from the long flag in opt_str.

default

The default value optparse should use if it does not find the option on the command line.

help

A character string describing the option, used by print_help() in generating a usage message. "%default" will be substituted by the value of default.

metavar

A character string that stands in for the option argument when printing help text. Default is the value of dest.

callback

A function that executes after the option value is fully parsed. Its return value is assigned to the option. Arguments are: the option S4 object, the long flag string, the value of the option, the parser S4 object, and ....

callback_args

A list of additional arguments passed to callback (via do.call()).

const

The value to store when action = "store_const" and the flag is seen. Ignored for all other actions.

required

If TRUE, parse_args() will throw an error if this option is not provided on the command line. Note: Required options are generally considered bad form because users expect options to be optional, and thus they should be avoided when possible.

object

An instance of the OptionParser class

Value

Both make_option() and add_option() return instances of class OptionParserOption.

Errors

The following classed errors may be thrown:

optparse_option_error: invalid option definition (bad flag string, unrecognized action, etc.).
- optparse_option_conflict_error: duplicate flag detected when adding an option to a parser.

References

Python's optparse library, which inspires this package, is described here: https://docs.python.org/3/library/optparse.html

Examples


   make_option("--longflag")
#> An object of class "OptionParserOption"
#> Slot "short_flag":
#> [1] NA
#> 
#> Slot "long_flag":
#> [1] "--longflag"
#> 
#> Slot "action":
#> [1] "store"
#> 
#> Slot "type":
#> [1] "character"
#> 
#> Slot "dest":
#> [1] "longflag"
#> 
#> Slot "default":
#> NULL
#> 
#> Slot "help":
#> [1] ""
#> 
#> Slot "metavar":
#> [1] "longflag"
#> 
#> Slot "callback":
#> NULL
#> 
#> Slot "callback_args":
#> list()
#> 
#> Slot "const":
#> NULL
#> 
#> Slot "required":
#> [1] FALSE
#> 
   make_option(c("-l", "--longflag"))
#> An object of class "OptionParserOption"
#> Slot "short_flag":
#> [1] "-l"
#> 
#> Slot "long_flag":
#> [1] "--longflag"
#> 
#> Slot "action":
#> [1] "store"
#> 
#> Slot "type":
#> [1] "character"
#> 
#> Slot "dest":
#> [1] "longflag"
#> 
#> Slot "default":
#> NULL
#> 
#> Slot "help":
#> [1] ""
#> 
#> Slot "metavar":
#> [1] "longflag"
#> 
#> Slot "callback":
#> NULL
#> 
#> Slot "callback_args":
#> list()
#> 
#> Slot "const":
#> NULL
#> 
#> Slot "required":
#> [1] FALSE
#> 
   make_option("--integer", type = "integer", default = 5)
#> An object of class "OptionParserOption"
#> Slot "short_flag":
#> [1] NA
#> 
#> Slot "long_flag":
#> [1] "--integer"
#> 
#> Slot "action":
#> [1] "store"
#> 
#> Slot "type":
#> [1] "integer"
#> 
#> Slot "dest":
#> [1] "integer"
#> 
#> Slot "default":
#> [1] 5
#> 
#> Slot "help":
#> [1] ""
#> 
#> Slot "metavar":
#> [1] "integer"
#> 
#> Slot "callback":
#> NULL
#> 
#> Slot "callback_args":
#> list()
#> 
#> Slot "const":
#> NULL
#> 
#> Slot "required":
#> [1] FALSE
#> 
   make_option("--integer", default = as.integer(5))  # same as previous
#> An object of class "OptionParserOption"
#> Slot "short_flag":
#> [1] NA
#> 
#> Slot "long_flag":
#> [1] "--integer"
#> 
#> Slot "action":
#> [1] "store"
#> 
#> Slot "type":
#> [1] "integer"
#> 
#> Slot "dest":
#> [1] "integer"
#> 
#> Slot "default":
#> [1] 5
#> 
#> Slot "help":
#> [1] ""
#> 
#> Slot "metavar":
#> [1] "integer"
#> 
#> Slot "callback":
#> NULL
#> 
#> Slot "callback_args":
#> list()
#> 
#> Slot "const":
#> NULL
#> 
#> Slot "required":
#> [1] FALSE
#> 

   # examples from package vignette
   make_option(c("-v", "--verbose"), action = "store_true", default = TRUE,
       help = "Print extra output [default]")
#> An object of class "OptionParserOption"
#> Slot "short_flag":
#> [1] "-v"
#> 
#> Slot "long_flag":
#> [1] "--verbose"
#> 
#> Slot "action":
#> [1] "store_true"
#> 
#> Slot "type":
#> [1] "logical"
#> 
#> Slot "dest":
#> [1] "verbose"
#> 
#> Slot "default":
#> [1] TRUE
#> 
#> Slot "help":
#> [1] "Print extra output [default]"
#> 
#> Slot "metavar":
#> character(0)
#> 
#> Slot "callback":
#> NULL
#> 
#> Slot "callback_args":
#> list()
#> 
#> Slot "const":
#> NULL
#> 
#> Slot "required":
#> [1] FALSE
#> 
   make_option(c("-q", "--quietly"), action = "store_false",
     dest = "verbose", help = "Print little output")
#> An object of class "OptionParserOption"
#> Slot "short_flag":
#> [1] "-q"
#> 
#> Slot "long_flag":
#> [1] "--quietly"
#> 
#> Slot "action":
#> [1] "store_false"
#> 
#> Slot "type":
#> [1] "logical"
#> 
#> Slot "dest":
#> [1] "verbose"
#> 
#> Slot "default":
#> NULL
#> 
#> Slot "help":
#> [1] "Print little output"
#> 
#> Slot "metavar":
#> character(0)
#> 
#> Slot "callback":
#> NULL
#> 
#> Slot "callback_args":
#> list()
#> 
#> Slot "const":
#> NULL
#> 
#> Slot "required":
#> [1] FALSE
#> 
   make_option(c("-c", "--count"), type = "integer", default = 5,
       help = "Number of random normals to generate [default %default]",
       metavar = "number")
#> An object of class "OptionParserOption"
#> Slot "short_flag":
#> [1] "-c"
#> 
#> Slot "long_flag":
#> [1] "--count"
#> 
#> Slot "action":
#> [1] "store"
#> 
#> Slot "type":
#> [1] "integer"
#> 
#> Slot "dest":
#> [1] "count"
#> 
#> Slot "default":
#> [1] 5
#> 
#> Slot "help":
#> [1] "Number of random normals to generate [default %default]"
#> 
#> Slot "metavar":
#> [1] "number"
#> 
#> Slot "callback":
#> NULL
#> 
#> Slot "callback_args":
#> list()
#> 
#> Slot "const":
#> NULL
#> 
#> Slot "required":
#> [1] FALSE
#> 
   make_option("--generator", default = "rnorm",
       help = "Function to generate random deviates [default \"%default\"]")
#> An object of class "OptionParserOption"
#> Slot "short_flag":
#> [1] NA
#> 
#> Slot "long_flag":
#> [1] "--generator"
#> 
#> Slot "action":
#> [1] "store"
#> 
#> Slot "type":
#> [1] "character"
#> 
#> Slot "dest":
#> [1] "generator"
#> 
#> Slot "default":
#> [1] "rnorm"
#> 
#> Slot "help":
#> [1] "Function to generate random deviates [default \"%default\"]"
#> 
#> Slot "metavar":
#> [1] "generator"
#> 
#> Slot "callback":
#> NULL
#> 
#> Slot "callback_args":
#> list()
#> 
#> Slot "const":
#> NULL
#> 
#> Slot "required":
#> [1] FALSE
#> 
   make_option("--mean", default = 0,
       help = "Mean if generator == \"rnorm\" [default %default]")
#> An object of class "OptionParserOption"
#> Slot "short_flag":
#> [1] NA
#> 
#> Slot "long_flag":
#> [1] "--mean"
#> 
#> Slot "action":
#> [1] "store"
#> 
#> Slot "type":
#> [1] "double"
#> 
#> Slot "dest":
#> [1] "mean"
#> 
#> Slot "default":
#> [1] 0
#> 
#> Slot "help":
#> [1] "Mean if generator == \"rnorm\" [default %default]"
#> 
#> Slot "metavar":
#> [1] "mean"
#> 
#> Slot "callback":
#> NULL
#> 
#> Slot "callback_args":
#> list()
#> 
#> Slot "const":
#> NULL
#> 
#> Slot "required":
#> [1] FALSE
#> 
   make_option("--sd", default = 1, metavar = "standard deviation",
       help = "Standard deviation if generator == \"rnorm\" [default %default]")
#> An object of class "OptionParserOption"
#> Slot "short_flag":
#> [1] NA
#> 
#> Slot "long_flag":
#> [1] "--sd"
#> 
#> Slot "action":
#> [1] "store"
#> 
#> Slot "type":
#> [1] "double"
#> 
#> Slot "dest":
#> [1] "sd"
#> 
#> Slot "default":
#> [1] 1
#> 
#> Slot "help":
#> [1] "Standard deviation if generator == \"rnorm\" [default %default]"
#> 
#> Slot "metavar":
#> [1] "standard deviation"
#> 
#> Slot "callback":
#> NULL
#> 
#> Slot "callback_args":
#> list()
#> 
#> Slot "const":
#> NULL
#> 
#> Slot "required":
#> [1] FALSE
#>