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
<- 1L
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
Flip a coin.
Usage: flip-coin [options]
Options:
--n <value> (Default: 1, Type: integer)
Number of coin flips
$ flip-coin --help --yaml
name: flip-coin
description: Flip a coin.
options:
'n':
default: 1
val_type: integer
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.
Add {Rapp} as a dependency in your DESCRIPTION
Place your app in the exec
folder in your package,
e.g: exec/myapp
. Apps are automatically installed as
executable.
Instruct your users to add executables from Rapp and your package
to their PATH
. On Linux and macOS, add the following to
.bashrc or .zshrc (or equivalent)
export PATH=$(Rscript -e 'cat(system.file("exec", package = "Rapp"))'):$PATH
export PATH=$(Rscript -e 'cat(system.file("exec", package = "my.package.name"))'):$PATH
If rig
is
already on the PATH
, you can also use rig
to
run a script in a packages exec
directory:
rig run <pkg>::<script>
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: