🌴 Rasta

R interpreter for Stencila executable documents

Install

Rasta is available as a R package. It isn’t on CRAN yet, but you can install it from this repository using the remotes package,

remotes::install_github("stencila/rasta")

Use

Register Rasta so that it can be discovered by other executors on your machine,

rasta::register()

If you have executa installed globally, you can then run Rasta using the execute command and specifying r as the starting language,

Develop

Get started by cloning this repository,

Then install the necessary development dependencies,

Most development tasks can be run from R, using make shortcuts, or RStudio keyboard shortcuts.

Task make R/RStudio
Install development dependencies make setup
Run linting make lint lintr::lint_package()
Run R tests make test-r devtools::test() or Ctrl+Shift+T
Run C++ tests make test-cpp
Run all tests make test
Run tests with coverage make cover covr::package_coverage()
Run benchmarks make bench
Build documentation make docs
Check the package make check Ctrl+Shift+E
Build make build Ctrl+Shift+B
Clean make clean

Testing

Unit tests live in the tests folder. Most of the tests are written using the testthat package. When writing regression tests for a specific issues, please name the test file accordingly e.g. tests/testthat/test-issue-1.R. There is also a tests/cpp folder for C++ tests and a tests/bench folder for benchmarking.

Documentation

Documentation is written using roxygen2 and the documentation site is generated by pkgdown into the docs folder and published on Github pages.

Continuous integration

Tests are run on Travis and code coverage tracked at Codecov.

Notes

  • This package has two functions, stream_read_message and stream_write_message, for reading and writing length prefixed messages from/to streams. These functions are implemented in both R and C++ and there is benchmarking code to compare their performance (run make bench and look for the outputs in tests/bench). The C++ implementations are 2-3 times faster. However, the times involved are small (<100µs for 10k messages) and having C++ code does add complexity and a dependency (Rcpp). Given that, we may remove the C++ implementations in the future.

  • This package provides a StdioServer class which implements Stencila’s execution API over standard input / output streams. It is analogous to the StdioServer class implemented in Typescript in the stencila/executa package. A previous version of this repository implemented a PipeServer class which used named pipes as the transport. However, this was not used in production, and so in the interest of keeping the code base as simple as possible, was removed. This note is intended for developers who might find a need to use the API over named pipes in the future.