R: Extract command-line arguments

commandArgs {R.utils} | R Documentation

## 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

### 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:\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()))

[Package R.utils version 2.7.0 Index]