scribe (version 0.3.0)

scribeCommandArgs-class: scribe command arguments

Description

Reference class object for managing command line arguments.

Fields

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

Methods

add_argument( ..., action = arg_actions(), options = NULL, convert = scribe_convert(), default = NULL, n = NA_integer_, info = NULL, execute = invisible )

Add a scribeArg to args

...

Either aliases or a scribeArg. If the latter, all other arguments are ignored. Note that only the first value (..1) is used.

action, options, convet, default, n, info

See new_arg()

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

Details

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.

See Also

Other scribe: command_args(), new_arg(), scribeArg-class

Examples

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