README.md
In stencila/rasta: R interpreter for Stencila executable documents

🌴 Rasta

R interpreter for Stencila executable documents

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")

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

Get started by cloning this repository,

git clone git@github.com: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 |

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 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/.

Tests are run on Azure Pipelines and code coverage tracked at Codecov.

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.