this.path (version 1.2.0)

Args: Providing Arguments to a Script

Description

withArgs allows you to source an R script while providing arguments. As opposed to running with Rscript, the code will be evaluated in the same session, in an environment of your choosing.

fileArgs() / / progArgs() are generalized versions of commandArgs(trailingOnly = TRUE), allowing you to access the script's arguments whether it was sourced or run from a shell.

asArgs coerces R objects into a character vector, for use with command line applications and withArgs.

Usage

asArgs(...)
fileArgs()
progArgs()
withArgs(...)

Value

for asArgs, fileArgs, and progArgs, a character vector.

for withArgs, the result of evaluating expr.

Arguments

...

R objects to turn into scripts arguments; typically logical, numeric, character, Date, and POSIXt vectors.

for withArgs, the first argument should be an (unevaluated) call to source, sys.source, debugSource in ‘RStudio’, testthat::source_file, or knitr::knit.

Details

fileArgs() will return the arguments associated with the executing script, or character(0) when there is no executing script.

progArgs() will return the arguments assocaited with the executing script, or commandArgs(trailingOnly = TRUE) when there is no executing script.

asArgs() coerces objects into command-line arguments. ... is first put into a list, and then each non-list element is converted to character. They are converted as follows:

Factors (class "factor")

using as.character.factor

Date-Times (class "POSIXct" and "POSIXlt")

using format "%Y-%m-%d %H:%M:%OS6" (retains as much precision as possible)

Numbers (class "numeric" and "complex")

with 17 significant digits (retains as much precision as possible) and "." as the decimal point character.

Raw Bytes (class "raw")

using sprintf("0x%02x", ) (can easily convert back to raw with as.raw() or as.vector(, "raw"))

All others will be converted to character using as.character and its methods.

The arguments will then be unlisted, and all attributes will be removed. Arguments that are NA_character_ after conversion will be converted to "NA" (since the command-line arguments also never have missing strings).

Examples

this.path::asArgs(
    NULL,
    c(TRUE, FALSE, NA),
    1:5,
    pi,
    exp(6i),
    letters[1:5],
    as.raw(0:4),
    as.Date("1970-01-01"),
    as.POSIXct("1970-01-01 00:00:00"),
    list(
        list(
            list(
                "lists are recursed"
            )
        )
    )
)


FILE <- tempfile(fileext = ".R")
this.path:::write.code({
    withAutoprint({
        this.path::this.path()
        this.path::fileArgs()
        this.path::progArgs()
    }, spaced = TRUE, verbose = FALSE, width.cutoff = 60L)
}, FILE)


# wrap your source call with a call to 'withArgs'
this.path::withArgs(
    source(FILE, local = TRUE, verbose = FALSE),
    letters, pi, exp(1)
)
this.path::withArgs(
    sys.source(FILE, environment()),
    letters, pi + 1i * exp(1)
)
this.path:::.Rscript(c("--default-packages=this.path", "--vanilla", FILE,
    this.path::asArgs(letters, pi, as.POSIXct("2022-07-17 04:25"))))


# with R >= 4.1.0, use the forward pipe operator '|>' to
# make calls to 'withArgs' more intuitive:
# source(FILE, local = TRUE, verbose = FALSE) |> this.path::withArgs(
#     letters, pi, exp(1)
# )
# sys.source(FILE, environment()) |> this.path::withArgs(
#     letters, pi + 1i * exp(1)
# )


# withArgs() also works with inside.source() and wrap.source()
sourcelike <- function (file, envir = parent.frame())
{
    file <- inside.source(file)
    envir <- as.environment(envir)
    exprs <- parse(n = -1, file = file, srcfile = NULL, keep.source = FALSE)
    for (i in seq_along(exprs)) eval(exprs[i], envir)
}
this.path::withArgs(sourcelike(FILE), letters)


sourcelike2 <- function (file, envir = parent.frame())
{
    envir <- as.environment(envir)
    exprs <- parse(n = -1, file = file, srcfile = NULL, keep.source = FALSE)
    for (i in seq_along(exprs)) eval(exprs[i], envir)
}
sourcelike3 <- function (file, envir = parent.frame())
{
    envir <- as.environment(envir)
    wrap.source(sourcelike2(file = file, envir = envir))
}
this.path::withArgs(sourcelike3(FILE), letters)
this.path::withArgs(wrap.source(sourcelike2(FILE)), letters)
unlink(FILE)