Rapp (short for “R application”) makes it fun to write and share command line applications in R.
It is an alternative front end to R, a drop-in replacement for
Rscript
that does automatic handling of command line
arguments. It converts a simple R script into a command line application
with a rich and robust support for command line arguments.
It aims to provides a seamless transition from interactive repl-driven development at the R console to non-interactive execution at the command line.
Here is a simple example Rapp:
#!/usr/bin/env Rapp
#| name: flip-coin
#| description: Flip a coin.
#| description: Number of coin flips
<- 1
n
cat(sample(c("heads", "tails"), n, TRUE), fill = TRUE)
Then you can invoke it from the command line:
$ flip-coin
tails
$ flip-coin --n=3
tails heads tails
$ flip-coin --help --yaml
name: flip-coin
description: Flip a coin.
options:
'n':
default: 1.0
val_type: float
arg_type: option
description: Number of coin flips
arguments: {}
Application options and arguments work like this:
Simple assignments of scalar literals at the top level of the R script are automatically treated as command line options.
<- 1 n
becomes an option at the command line:
flip-coin --n 1
Option values passed from the command line are parsed as yaml/json,
and then coerced to the original R type. The following option value
types are supported: int, float, string, and bool. Values can be
supplied after the option, or as part of the option with =
.
The following two usages are the same:
flip-coin --n=1
flip-coin --n 1
Bool options, (that is, assignments of TRUE
or
FALSE
in an R app) are a little different. They support
usage as switches at the command line. For example in an R script:
<- TRUE echo
means that at the command line the following are supported:
-app --echo # TRUE
my-app --echo=yes # TRUE
my-app --echo=true # TRUE
my-app --echo=1 # TRUE
my
-app --no-echo # FALSE
my-app --echo=no # FALSE
my-app --echo=false # FALSE
my-app --echo=0 # FALSE my
Simple assignments of length-0 objects at the top level of an R
script become positional arguments. If the R symbol has a
...
suffix or prefix, it becomes a collector for a variable
number of positional arguments. Positional arguments always come into
the R app as character strings.
<- c() args...
or
<- c()
first_arg <- c()
...middle_args <- c() last_arg
You can easily share your R app command line executable as part of an R package.
exec
folder in your package, e.g:
exec/myapp
. Apps are automatically installed as
executable.export PATH=$(Rscript -e 'cat(system.file("exec", package = "Rapp"))'):$PATH
export PATH=$(Rscript -e 'cat(system.file("exec", package = "my.package.name"))'):$PATH
Rapp works on Windows. However, because there is no native support
for !#
shebang executable on Windows, you must invoke Rapp
directly.
Rapp flip-coin --n 3
See the inst/examples
folder for more example R
apps.
This package is just one set of ideas for how to build command line apps in R. Some other packages in this space:
Also, some interesting examples of other approaches to exporting cli interfaces from R packages: