🌴 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,

executa execute --repl --lang r

Develop

Get started by cloning this repository,

git clone [email protected]:stencila/rasta
cd rasta

Then install the necessary development dependencies,

make setup

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

Task	make	R/RStudio
Install development dependencies	make setup	devtools::install_dev_deps()
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 at https://stencila.github.io/rasta/.

Continuous integration

Tests are run on Azure Pipelines 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.