Parse command line options.

parse_args() parses command line options using an OptionParser instance for guidance. parse_args2() is a wrapper to parse_args() setting the options positional_arguments and convert_hyphens_to_underscores to TRUE.

Usage

parse_args(
  object,
  args = commandArgs(trailingOnly = TRUE),
  print_help_and_exit = TRUE,
  positional_arguments = FALSE,
  convert_hyphens_to_underscores = FALSE
)

parse_args2(
  object,
  args = commandArgs(trailingOnly = TRUE),
  print_help_and_exit = TRUE
)

Arguments

object: An OptionParser instance.
args: A character vector containing command line options to be parsed. Default is everything after the Rscript program in the command line. If positional_arguments is not FALSE then parse_args() will look for positional arguments at the end of this vector.
print_help_and_exit: Whether parse_args() should call print_help() to print out a usage message and exit the program. Default is TRUE.
positional_arguments: Number of positional arguments. A numeric denoting the exact number of supported arguments, or a numeric vector of length two denoting the minimum and maximum number of arguments (Inf for no limit). The value TRUE is equivalent to c(0, Inf). The default FALSE is supported for backward compatibility only, as it alters the format of the return value.
convert_hyphens_to_underscores: If the names in the returned list of options contains hyphens then convert them to underscores. The default FALSE is supported for backward compatibility reasons as it alters the format of the return value

Value

Returns a list with field options containing our option values as well as another field args which contains a vector of positional arguments. For backward compatibility, if and only if positional_arguments is FALSE, returns a list containing option values.

Errors

The following classed errors may be thrown:

optparse_parse_error: base class for all parse-time errors.
- optparse_bad_option_error: unrecognized, misused, or argument-requiring option.
  - optparse_ambiguous_option_error: ambiguous abbreviated long flag.
- optparse_bad_positional_arguments_error: wrong number of positional arguments supplied.
- optparse_missing_required_error: a required option was not supplied.

References

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

Examples

# example from vignette
option_list <- list(
   make_option(c("-v", "--verbose"), action = "store_true", default = TRUE,
       help = "Print extra output [default]"),
   make_option(c("-q", "--quietly"), action = "store_false",
       dest = "verbose", help = "Print little output"),
   make_option(c("-c", "--count"), type = "integer", default = 5,
       help = "Number of random normals to generate [default %default]",
       metavar = "number"),
   make_option("--generator", default = "rnorm",
       help = "Function to generate random deviates [default \"%default\"]"),
   make_option("--mean", default = 0,
       help = "Mean if generator == \"rnorm\" [default %default]"),
   make_option("--sd", default = 1, metavar = "standard deviation",
       help = "Standard deviation if generator == \"rnorm\" [default %default]")
   )
parse_args(OptionParser(option_list = option_list), args = c("--sd=3", "--quietly"))
#> $verbose
#> [1] FALSE
#> 
#> $count
#> [1] 5
#> 
#> $generator
#> [1] "rnorm"
#> 
#> $mean
#> [1] 0
#> 
#> $sd
#> [1] 3
#> 
#> $help
#> [1] FALSE
#> 

# example from vignette using positional arguments
option_list2 <- list(
   make_option(c("-n", "--add-numbers"), action = "store_true", default = FALSE,
       help = "Print line number at the beginning of each line [default]")
   )
parser <- OptionParser(usage = "%prog [options] file", option_list = option_list2)

parse_args(parser, args = c("--add-numbers", "example.txt"), positional_arguments = TRUE)
#> $options
#> $options$`add-numbers`
#> [1] TRUE
#> 
#> $options$help
#> [1] FALSE
#> 
#> 
#> $args
#> [1] "example.txt"
#> 

parse_args(parser, args = c("--add-numbers", "example.txt"), positional_arguments = TRUE,
         convert_hyphens_to_underscores = TRUE)
#> $options
#> $options$add_numbers
#> [1] TRUE
#> 
#> $options$help
#> [1] FALSE
#> 
#> 
#> $args
#> [1] "example.txt"
#> 

parse_args2(parser, args = c("--add-numbers", "example.txt"))
#> $options
#> $options$add_numbers
#> [1] TRUE
#> 
#> $options$help
#> [1] FALSE
#> 
#> 
#> $args
#> [1] "example.txt"
#>