Stencila Schema for R

Build Status Code coverage CRAN Docs

This package provides R bindings for the Stencila Schema. It is primarily aimed at R developers wanting to programmatically generate, or modify, executable documents. For example, it is used in rasta, a Stencila plugin for R.

Install

This package isn’t on CRAN yet, but you can install it directly from this repository using the remotes package,

remotes::install_github("stencila/schema", subdir = "r", upgrade = "ask")

Use

This package exports a factory function for each type of document node in the Stencila Schema e.g. Article, Paragraph, CodeChunk.

For example,

chunk <- CodeChunk(
  text = "SELECT * FROM data",
  programmingLanguage = "sql"
)
> names(chunk)
[1] "type"                "text"                "programmingLanguage"
> chunk$type
[1] "CodeChunk"
attr(,"class")
[1] "scalar"    "character"

Note that the type property is set automatically. The class of the node also includes the full hierarchy of ancestor types, so you can use the inherits function as needed:

> class(chunk)
[1] "list"      "Entity"    "Code"      "CodeBlock" "CodeChunk"
> inherits(chunk, "CodeChunk")
[1] TRUE
> inherits(chunk, "Code")
[1] TRUE
> inherits(chunk, "Pizza")
[1] FALSE

Each constructor function checks that the arguments provided conform to the Schema. For example,

# Wrong type for a property supplied
Article(
  authors = Paragraph('My article title')
)
Error: CreativeWork$authors is type Paragraph, expected type Array(Union(Person, Organization))

# Required property not supplied
Article(
  authors = list(Person(givenNames = 'John',  familyNames = 'Smith'))
)
Error: Article$title is required

# Success!
Article(
  authors = list(Person(givenNames = 'John',  familyNames = 'Smith')),
  title = 'My article title'
)

Develop

Get started by cloning this repository,

git clone [email protected]:stencila/schema
cd schema/r

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

Task make R/RStudio
Install development dependencies make setup
Regenerate R/types.R make regen
Run linting make lint lintr::lint_package()
Run tests make test devtools::test() or Ctrl+Shift+T
Re-run tests on changes make autotest testthat::auto_test_package()
Run tests with coverage make cover covr::package_coverage()
Build documentation make docs devtools::document()
Check the package make check Ctrl+Shift+E
Build the package make build devtools::build() or Ctrl+Shift+B
Clean make clean

Testing

Unit tests live in the tests folder and are written using testthat.

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 Azure Pipelines and code coverage tracked at Codecov.