Easily Build Command Line Applications.

Rapp

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
n <- 1L

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:

Options

Simple assignments of scalar literals at the top level of the R script are automatically treated as command line options.

n <- 1

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:

echo <- TRUE

means that at the command line the following are supported:

my-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

Positional Arguments

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.

args... <- c()

or

first_arg      <- c()
...middle_args <- c()
last_arg       <- c()

Shipping an Rapp as part of an R package

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>
  

Windows

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

More examples

See the inst/examples folder for more example R apps.

Other Approaches

This package is just one set of ideas for how to build command line apps in R. Some other packages in this space:

• littler (typically paired with one of the below)
• docopt
• optparse
• argparse
• argparser

Also, some interesting examples of other approaches to exporting cli interfaces from R packages:

• renv
• bspm.