commandArgs
Extract command-line arguments
Provides access to a copy of the command-line arguments supplied when
this Rsession was invoked. This function is backward compatible with
commandArgs
() of the
- Keywords
- internal, programming
Usage
commandArgs(trailingOnly=FALSE, asValues=FALSE, defaults=NULL, always=NULL, adhoc=FALSE,
unique=FALSE, excludeReserved=FALSE, excludeEnvVars=FALSE, os=NULL,
.args=base::commandArgs(trailingOnly = trailingOnly), ...)
Arguments
- trailingOnly
- If
TRUE
, only arguments after--args
are returned. - asValues
- If
TRUE
, a namedlist
is returned, where command line arguments of type--foo
will be returned as - defaults
- A
character
vector
or a namedlist
of default arguments. Any command-line or fixed arguments - always
- A
character
vector
or a namedlist
of fixed arguments. These will override default and comman - adhoc
- (ignored if
asValues=FALSE
) IfTRUE
, then additional coercion ofcharacter
command-line arguments to more specific data t - 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 Rare excluded, otherwise not. Which the reserved arguments are depends on operating system. For details, see Appendix B on "Invoking R" in An Introduc - excludeEnvVars
- If
TRUE
, arguments that assigns environment variable are excluded, otherwise not. As described inR --help
, these are arguments of format= . - os
- A
vector
ofcharacter
strings specifying which set of reserved arguments to be used. Possible values are"unix"
,"mac"<
- args
- A named
list
of arguments. - .args
- A
character
vector
of command-line arguments. - ...
- Passed to
commandArgs
() of thebase package.
Value
- If
asValue
isFALSE
, acharacter
vector
is returned, which contains the name of the executable and the non-parsed user-supplied arguments.If
asValue
isTRUE
, a namedlist
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 Rwas 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 alogical
vector
specifying if the corresponding command-line argument is a reserved Rargument or not.
Backward compatibility
This function should be fully backward compatible with the same
function in the
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.
See Also
For a more user friendly solution, see cmdArgs
().
Internally commandArgs
() is used.
Examples
######################################################################
# Non-parsed command-line arguments
######################################################################
# Display how this instance of R was invoked.
cmd <- paste(commandArgs(), collapse="")
cat("How R was invoked:
");
cat(cmd, "")
# 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:
");
print(keys);
str(mget(keys, envir=globalenv()))