parsermd: Formal Parser and Related Tools for R Markdown Documents

Description

An implementation of a formal grammar and parser for R Markdown documents using the Boost Spirit X3 library. It also includes a collection of high level functions for working with the resulting abstract syntax tree.

Author(s)

Maintainer: Colin Rundel rundel@gmail.com

See Also

Useful links:

• https://rundel.github.io/parsermd/

• https://github.com/rundel/parsermd

• Report bugs at https://github.com/rundel/parsermd/issues

Convert an object into an rmd_ast.

Description

Currently only supports conversion of rmd_tibble objects back to rmd_ast.

Usage

as_ast(x, ...)

Arguments

Value

Returns an rmd_ast object.

Examples

parse_rmd(system.file("hw01.Rmd", package="parsermd")) %>%
  as_tibble() %>%
  as_ast()

Convert an rmd_ast, rmd_tibble, or any ast node into text.

Description

Convert an rmd_ast, rmd_tibble, or any ast node into text.

Usage

as_document(x, padding = "", collapse = NULL, ...)

Arguments

Value

Returns a character vector.

Get and set code chunk options

Description

Helper functions for obtaining or changing chunk options within an rmd object.

Usage

rmd_set_options(x, ...)

rmd_get_options(x, ..., defaults = list())

Arguments

Value

rmd_set_options returns the modified version of the original object.

rmd_get_options returns a list of the requested options (or all options if none are specified). Non-chunk nodes return NULL.

Examples

rmd = parse_rmd(system.file("minimal.Rmd", package = "parsermd"))

str(rmd_get_options(rmd))
str(rmd_get_options(rmd), "include")

rmd_set_options(rmd, include = TRUE)

Parse an R Markdown document

Description

Documents are parse into an rmd_ast object.

Usage

parse_rmd(rmd, allow_incomplete = FALSE, parse_yaml = TRUE)

Arguments

Value

Returns a rmd_ast object.

Examples

parse_rmd(system.file("hw01.Rmd", package="parsermd"))

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

magrittr

%>%

pillar

type_sum

tibble

as_tibble

Render parsermd objects using rmarkdown::render()

Description

Object contents are converted to a character vector and written to a temporary directory before rendering.

Note that this function has the potential to overwrite existing output files (e.g. .html, .pdf, etc).

Usage

render(x, name = NULL, ...)

Arguments

Value

Returns the results of rmarkdown::render().

Check an Rmd against a template

Description

This function compares the provided Rmd against a template and reports on discrepancies (e.g. missing or unmodified components).

Usage

rmd_check_template(rmd, template, ...)

Arguments

Value

Invisibly returns TRUE if the rmd matches the template, FALSE otherwise.

Examples

tmpl = parse_rmd(system.file("hw01.Rmd", package = "parsermd")) %>%
  rmd_select(by_section(c("Exercise *", "Solution"))) %>%
  rmd_template(keep_content = TRUE)

rmd_check_template(
  system.file("hw01-student.Rmd", package = "parsermd"),
  tmpl
)

rmd node utility functions

Description

Functions for extracting information for Rmd nodes.

Usage

rmd_node_label(x, ...)

rmd_node_type(x, ...)

rmd_node_length(x, ...)

rmd_node_content(x, ...)

rmd_node_attr(x, attr, ...)

rmd_node_engine(x, ...)

rmd_node_options(x, ...)

rmd_node_code(x, ...)

Arguments

Value

• rmd_node_label() - returns a character vector of node labels, nodes without labels return NA.

• rmd_node_type() - returns a character vector of node types.

• rmd_node_length() - returns an integer vector of node lengths (i.e. lines of code, lines of text, etc.), nodes without a length return NA.

• rmd_node_content() - returns a character vector of node textual content, nodes without content return NA.

• rmd_node_attr() - returns a list of node attribute values.

• rmd_node_engine() - returns a character vector of chunk engines, NA for all other node types.

• rmd_node_options() - returns a list of chunk node options (named list), MULL for all other node types.

• rmd_node_code() - returns a list of chunk node code (character vector), NULL for all other node types.

Examples

rmd = parse_rmd(system.file("hw01.Rmd", package="parsermd"))

rmd_node_label(rmd)
rmd_node_type(rmd)
rmd_node_content(rmd)
rmd_node_attr(rmd, "level")
rmd_node_engine(rmd)
rmd_node_options(rmd)
rmd_node_code(rmd)

Find the sections for each rmd object node

Description

Uses the section headings of an rmd object to identify the hierarchical structure of the document.

Usage

rmd_node_sections(x, levels = 1:6, drop_na = FALSE)

Arguments

Value

A list of section names for each node.

Select nodes of an Rmd ast

Description

This function is implemented using tidyselect::eval_select() which enables a variety of useful syntax for selecting nodes from the ast.

Additionally, a number of additional parsermd specific selection helpers are available: by_section(), has_type(), has_label(), and has_option().

Usage

rmd_select(x, ...)

Arguments

Value

Returns a subset Rmd object (either rmd_ast or rmd_tibble depending on input).

Examples

rmd = parse_rmd(system.file("hw01.Rmd", package = "parsermd"))

rmd_select(rmd, "plot-dino", "cor-dino")
rmd_select(rmd, "plot-dino":"cor-dino")
rmd_select(rmd, `plot-dino`:`cor-dino`)

rmd_select(rmd, has_type("rmd_chunk"))

rmd_select(rmd, by_section(c("Exercise *", "Solution")))

Rmd selection helper functions

Description

These functions are used in conjunction with rmd_select() to select nodes from an Rmd ast.

• by_section() - uses section selectors to select nodes.

• has_type() - selects all nodes that have the given type(s).

• has_label() - selects nodes with labels matching the given glob.

• has_option() - selects nodes that have the given option(s) set.

Usage

has_type(types)

by_section(sec_ref, keep_parents = TRUE)

has_label(label)

has_option(...)

Arguments

Details

Section reference selectors

Section reference selectors are a simplified version of CSS selectors that are designed to enable the selection nodes in a way that respects the implied hierarchy of a document's section headings.

They consist of a character vector of heading names where each subsequent value is assumed to be nested within the preceding value. For example, the section selector c("Sec 1", "Sec 2") would select all nodes that are contained within a section named ⁠Sec 2⁠ that is in turn contained within a section named ⁠Sec 1⁠ (or a section contained within a section named ⁠Sec 1⁠, and so on).

The individual section names can be specified using wildcards (aka globbing patterns), which may match one or more sections within the document, e.g. c("Sec 1", "Sec *"). See utils::glob2rx() or wikipedia for more details on the syntax for these patterns.

Value

All helper functions return an integer vector of selected indexes.

Examples

rmd = parse_rmd(system.file("hw01.Rmd", package="parsermd"))

rmd_select(rmd, has_type("rmd_chunk"))

rmd_select(rmd, has_label("*dino"))

rmd_select(rmd, has_option("message"))
rmd_select(rmd, has_option(message = FALSE))
rmd_select(rmd, has_option(message = TRUE))

Source the code chunks of an Rmd document

Description

This is the equivalent of the source() function for Rmd files or their resulting asts.

Usage

rmd_source(x, local = FALSE, ..., label_comment = TRUE, use_eval = TRUE)

Arguments

Value

Returns the result of source() for any R code chunks.

Examples

rmd_source(system.file("minimal.Rmd", package = "parsermd"), echo=TRUE)

Subset the nodes of an rmd object

Description

Subset an rmd object based on sections, node types, or names.

Usage

rmd_subset(
  x,
  sec_refs = NULL,
  type_refs = NULL,
  name_refs = NULL,
  exclude = FALSE,
  keep_yaml = TRUE,
  keep_setup = FALSE,
  ...
)

Arguments

Value

Returns a subset Rmd object (either rmd_ast or rmd_tibble depending on input).

rmd_subset utility functions

Description

Tools for selecting or checking a single node using rmd_subset() selection.

Usage

rmd_get_node(x, sec_refs = NULL, type_refs = NULL, name_refs = NULL, ...)

rmd_get_chunk(x, sec_refs = NULL, name_refs = NULL)

rmd_get_markdown(x, sec_refs = NULL)

rmd_has_node(x, sec_refs = NULL, type_refs = NULL, name_refs = NULL, ...)

rmd_has_chunk(x, sec_refs = NULL, name_refs = NULL, ...)

rmd_has_markdown(x, sec_refs = NULL, ...)

Arguments

Value

• ⁠rmd_get_*()⁠ functions returns a single Rmd node object (e.g. rmd_heading, rmd_chunk, rmd_markdown, etc.)

• ⁠rmd_has_*()⁠ functions return TRUE if a matching node exists, FALSE otherwise.

Create a template from an rmd object.

Description

Templates are objects which are meant to capture the structure of an R Markdown document and facilitate the comparison between the template and new Rmd documents, usually to ensure the structure and/or content matches sufficiently.

Usage

rmd_template(
  rmd,
  keep_content = FALSE,
  keep_labels = TRUE,
  keep_headings = FALSE,
  keep_yaml = FALSE,
  ...
)

Arguments

Value

Returns an rmd_template object, which is a derived tibble containing relevant structural details of the document.

Examples

rmd = parse_rmd(system.file("hw01.Rmd", package="parsermd"))

rmd_select(rmd, by_section(c("Exercise *", "Solution"))) %>%
  rmd_template()