Bindings for Stencila Schema.
Stencila Schema for R
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.