R.utils: commandArgs – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

commandArgs

Extract command-line arguments

Description

Provides access to a copy of the command-line arguments supplied when this R session was invoked. This function is backward compatible with commandArgs() of the base package, but adds more features.

Usage

commandArgs(trailingOnly=FALSE, asValues=FALSE, defaults=NULL, always=NULL, adhoc=FALSE,
  unique=FALSE, excludeReserved=FALSE, excludeEnvVars=FALSE, os=NULL, .args=NULL, ...)

Arguments

`trailingOnly`	If `TRUE`, only arguments after `--args` are returned.
`asValues`	If `TRUE`, a named `list` is returned, where command line arguments of type `--foo` will be returned as `TRUE` with name `foo`, and arguments of type `-foo=value` will be returned as `character` string `value` with name `foo`. In addition, if `-foo value` is given, this is interpreted as `-foo=value`, as long as `value` does not start with a double dash (`--`).
`defaults`	A `character` `vector` or a named `list` of default arguments. Any command-line or fixed arguments will override default arguments with the same name.
`always`	A `character` `vector` or a named `list` of fixed arguments. These will override default and command-line arguments with the same name.
`adhoc`	(ignored if `asValues=FALSE`) If `TRUE`, then additional coercion of `character` command-line arguments to more specific data types is performed, iff possible.
`unique`	If `TRUE`, the returned set of arguments contains only unique arguments such that no two arguments have the same name. If duplicates exists, it is only the last one that is kept.
`excludeReserved`	If `TRUE`, arguments reserved by R are excluded, otherwise not. Which the reserved arguments are depends on operating system. For details, see Appendix B on "Invoking R" in An Introduction to R.
`excludeEnvVars`	If `TRUE`, arguments that assigns environment variable are excluded, otherwise not. As described in `R --help`, these are arguments of format <key>=<value>.
`os`	A `vector` of `character` strings specifying which set of reserved arguments to be used. Possible values are `"unix"`, `"mac"`, `"windows"`, `"ANY"` or `"current"`. If `"current"`, the current platform is used. If `"ANY"` or `NULL`, all three OSs are assumed for total cross-platform compatibility.
`args`	A named `list` of arguments.
`.args`	A `character` `vector` of command-line arguments.
`...`	Passed to `commandArgs`() of the base package.

Value

If asValue is FALSE, a character vector is returned, which contains the name of the executable and the non-parsed user-supplied arguments.

If asValue is TRUE, a named list containing is returned, which contains the the executable and the parsed user-supplied arguments.

The first returned element is the name of the executable by which R was invoked. As far as I am aware, the exact form of this element is platform dependent. It may be the fully qualified name, or simply the last component (or basename) of the application. The returned attribute isReserved is a logical vector specifying if the corresponding command-line argument is a reserved R argument or not.

Backward compatibility

This function should be fully backward compatible with the same function in the base package, except when littler is used (see below).

Compatibility with littler

The littler package provides the r binary, which parses user command-line options and assigns them to character vector argv in the global environment. The commandArgs() of this package recognizes argv arguments as well.

Coercing to non-character data types

When asValues is TRUE, the command-line arguments are returned as a named list. By default, the values of these arguments are character strings. However, any command-line argument that share name with one of the 'always' or 'default' arguments, then its value is coerced to the corresponding data type (via as). This provides a mechanism for specifying data types other than character strings.

Furthermore, when asValues and adhoc are TRUE, any remaining character string command-line arguments are coerced to more specific data types (via type.convert), if possible.

Author(s)

Henrik Bengtsson

Examples

######################################################################
# Non-parsed command-line arguments
######################################################################
# Display how this instance of R was invoked.
cmd <- paste(commandArgs(), collapse=" ")
cat("How R was invoked:\n");
cat(cmd, "\n")

# Get all arguments
args <- commandArgs()
print(args)

# Get only "private" arguments and not the name of the R executable.
args <- commandArgs(excludeReserved=TRUE)[-1]
print(args)

# Assert backward compatibility
args0 <- base::commandArgs()
args <- commandArgs()
stopifnot(all.equal(args, args0, check.attributes=FALSE))


######################################################################
# Parsed command-line arguments
######################################################################
# Get all arguments as a named list, e.g. if R is started as:
#
#   R DATAPATH=../data --args --root="do da" --foo bar --details --a=2
#
# then 'args' below will equal
#
#   list(R=NA, DATAPATH="../data" args=TRUE, root="do da",
#        foo="bar", details=TRUE, a="2")
args <- commandArgs(asValue=TRUE)
str(args)

# Turn arguments into R variables
args <- commandArgs(asValue=TRUE, excludeReserved=TRUE)[-1]
keys <- attachLocally(args)
cat("Command-line arguments attached to global environment:\n");
print(keys);
str(mget(keys, envir=globalenv()))

R.utils

Various Programming Utilities

v2.10.1

LGPL (>= 2.1)

Authors

Henrik Bengtsson [aut, cre, cph]

Initial release