scribeCommandArgs-class {scribe} | R Documentation |
Reference class object for managing command line arguments.
This class manages the command line argument inputs when passed via
the Rscript utility. Take the simple script below which adds two
numbers, which we will save in an executable file called add.R
,
#!/usr/bin/env Rscript library(scribe) ca <- command_args() ca$add_argument("--value1", default = 0L) ca$add_argument("--value2", default = 0L) args <- ca$parse() writeLines(args$value1 + args$value2)
When called by a terminal, we can pass arguments and return a function.
add.R --value1 10 --value2 1 11
When testing, you can simulate command line arguments by passing them into
the input
field. By default, this will grab values from
base::commandArgs()
, so use with the Rscript utility doesn't require
any extra steps.
Most methods are designed to return .self
, or the scribeCommandArgs
class. The exceptions to these are the the $get_*()
methods, which return
their corresponding values, and $parse()
which returns a named list
of
the parsed input values.
input
[character]
A character vector of command line arguments.
See also command_args()
values
[list]
A named list
of values. Empty on initialization
and populated during argument resolving.
args
[list]
a List of scribeArgs
description
[character]
Additional help information
included
[character]
Default scribeArgs to include
examples
[character]
Examples to print with help
comments
[character]
Comments printed with
resolved
[logical]
A logical
value indicated if the
$resolve()
method has been successfully executed.
working
[character]
A copy of input
. Note: this is used to
track parsing progress and is not meant to be accessed directly.
stop
[character]
Determines parsing
add_argument(
...,
action = arg_actions(),
options = NULL,
convert = scribe_convert(),
default = NULL,
n = NA_integer_,
info = NULL,
execute = invisible
)
Add a scribeArg to args
add_description(..., sep = "")
Add a value to description
...
Information to paste into the description
sep
character
separate for ...
add_example(x, comment = "", prefix = "$ ")
Add a value to examples
x
A code example as a character
comment
An optional comment to append
prefix
An optional prefix for the example
get_args(included = TRUE)
Retrieve args
included
If TRUE
also returns included default
scribeArgs defined in $initialize()
get_description()
Retrieve description
get_examples()
Retrieve examples
get_input()
Retrieve input
get_values()
Retrieve values
help()
Print the help information
initialize(input = "", include = c("help", "version", NA_character_))
Initialize the scribeCommandArgs object. The wrapper
command_args()
is recommended rather than
calling this method directly.
input
A character
vector of command line arguments
to parse
include
A character vector denoting which default
scribeArgs to include in args
parse()
Return a named list
of parsed values of from each scribeArg
in args
resolve()
Resolve the values of each scribeArg in args
. This method
is called prior to $parse()
set_description(..., sep = "")
Set the value of description
...
Information to paste into the description
sep
character
separate for ...
set_example(x = character(), comment = "", prefix = "$ ")
Set the value of examples
x
A code example as a character
comment
An optional comment to append
prefix
An optional prefix for the example
set_input(value)
Set input
. Note: when called, resolved
is (re)set to
FALSE
and values need to be parsed again.
value
Value to set
set_values(i = TRUE, value)
Set values
i
Index value of working
to set
value
The value to set
version()
Print the scribe-package version
Other scribe:
command_args()
,
new_arg()
,
scribeArg-class
# command_args() is recommended over direct use of scribeCommandArgs$new()
ca <- command_args(c(1, 2, 3, "--verbose"))
ca$add_argument("--verbose", action = "flag")
ca$add_argument("...", "values", info = "values to add", default = 0.0)
args <- ca$parse()
if (args$verbose) {
message("Adding ", length(args$values), " values")
}
sum(args$values)
# $parse() returns a named list, which means scribeCommandArgs can function
# as a wrapper for calling R functions inside Rscript
ca <- command_args(c("mean", "--size", 20, "--absolute"))
ca$add_argument("fun", action = "list")
ca$add_argument("--size", default = 5L)
ca$add_argument("--absolute", action = "flag")
args <- ca$parse()
my_function <- function(fun, size, absolute = FALSE) {
fun <- match.fun(fun)
x <- sample(size, size, replace = TRUE)
res <- fun(x)
if (absolute) res <- abs(res)
res
}
do.call(my_function, args)