In traitecoevo/callr: Call R Functions from the Command Line

callr

The callr package has two main uses; calling R from other programs (including the shell) and for calling other programs from R.

Calling R from the shell

suppressMessages(devtools::load_all())
file.copy(system.file(c("example.json", "example.R"), package="callr"), ".", overwrite=TRUE)
lang_output <- function(x, lang) {
  cat(c(sprintf("```%s", lang), x, "```"), sep="\n")
}
json_output <- function(x) lang_output(x, "json")
r_output <- function(x) lang_output(x, "r")
plain_output <- function(x) lang_output(x, "plain")

There are myriad interfaces for calling R from other languages (e.g., the python package rpy2) but debugging these interfaces when something goes wrong is challenging. Similarly, ad-hoc decisions about serialisation must be made that can fail subtly. We use the jsonlite package to serialise calls to R from any language to give a simple and consistent interface.

callr lets you specify, in a json file,

• packages to load
• R files to source
• A function to call
• Arguments to the function

The result will then be added back into the original file. For example, suppose you had some R function definitions (in a file example.R)

r_output(readLines("example.R"))

We might write a json file:

json_output(readLines("example.json"))

This will be translated into a function:

r_output(deparse(json_call(filename="example.json")))

Note that because json hashes do not guarantee order, the arguments are in an array (the [ bits), and the argument name goes in the name field. Names are optional.

This can be run from within R like:

callr("example.json")

Though it will certainly be easier to run from the a shell session with:

Rscript -e 'callr::callr("example.json")

or by installing the shell script helper:

callr::install_callr("~/bin")

And running

callr example.json

Regardless of how callr is run, the file example.json now includes output:

json_output(readLines("example.json"))

Further options to the script:

plain_output(callr::call_system("callr", "--help"))

file.remove("example.R", "example.json")

Calling system programs from R

Calling system commands from R error prone as error handling is difficult and varies on things like whether standard output is to be collected. callr includes a function call_system for the case where a system call is blocking (i.e., we want to wait until it completes). It is a very thin wrapper around R's system2 function and hides output unless there is an error, when it will print a (possibly truncated) error message. This makes it useful for things like output of a LaTeX compilation where the amount of generated output is far too much to be useful but when an error occurs, some output is useful.

All output (non-truncated) will be returned, invisibly, by a successful run of call_system.

As an example, due to the travis badge in this README, LaTeX cannot compile the LaTeX that pandoc generates:

callr::call_system("pandoc", c("README.md", "-o", "README.tex", "--standalone"))
callr::call_system("pdflatex",
                   c("-interaction=nonstopmode", "-halt-on-error",
                     "README.tex"))

only the last bit of output is included in the error, with many lines of output dropped.

file.remove("README.aux", "README.log", "README.out", "README.tex")

Installation

Install from github with

devtools::install_github("traitecoevo/callr")
callr::install_callr("~/bin")

replacing the path in the second line with something in your $PATH.

traitecoevo/callr documentation built on May 31, 2019, 7:42 p.m.