Rmd selection helper functions

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_heading() - selects heading nodes (only) with titles matching the given glob pattern(s).

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

• has_shortcode() - selects nodes containing shortcodes matching the given function name(s).

• by_fenced_div() - selects fenced div sections matching specified id, class, and/or attributes.

Usage

has_type(types)

by_section(sec_ref, keep_parents = TRUE)

has_label(label)

has_heading(heading)

has_code(code)

has_option(...)

has_shortcode(func_name = NULL)

has_inline_code(engine = NULL)

by_fenced_div(id = NULL, class = NULL, attr = NULL)

Arguments

types

Vector of character type names, e.g. rmd_chunk, rmd_heading, etc.

sec_ref

character vector, a section reference selector. See details below for further details on how these are constructed.

keep_parents

Logical, retain the parent headings of selected sections. Default: TRUE

label

character vector, glob patterns for matching chunk labels.

heading

character vector, glob patterns for matching heading titles.

code

character vector, regex patterns for matching chunk code line(s)

...

Either option names represented by a scalar string or a named argument with the form opt = value where opt is the option name and value is the value to be checked. For example eval = TRUE would check for the option eval being set to TRUE.

func_name

character vector, optional glob patterns for matching shortcode function names. If NULL (default), matches any shortcode.

engine

character vector, optional glob patterns for matching inline code engine names. If NULL (default), matches any inline code.

id

Character, optional ID to match (with or without # prefix)

class

Character vector, optional class names to match (with . prefix). All specified classes must be present in the fenced div (subset matching).

attr

Either a character vector of attribute names to check for existence, or a named list/vector where names are attribute names and values must match exactly.

Value

All helper functions return an integer vector of selected indexes.

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.

See also

rmd_select() for the main selection function that uses these helpers.

Examples

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

rmd_select(rmd, has_type("rmd_chunk"))
#> ├── YAML [2 fields]
#> ├── Chunk [r, 2 lines] - load-packages
#> ├── Chunk [r, 5 lines] - plot-dino
#> ├── Chunk [r, 2 lines] - cor-dino
#> ├── Chunk [r, 1 line] - plot-star
#> └── Chunk [r, 1 line] - cor-star

rmd_select(rmd, has_label("*dino"))
#> ├── YAML [2 fields]
#> ├── Chunk [r, 5 lines] - plot-dino
#> └── Chunk [r, 2 lines] - cor-dino

rmd_select(rmd, has_heading("Exercise *"))
#> ├── YAML [2 fields]
#> ├── Heading [h3] - Exercise 1
#> ├── Heading [h3] - Exercise 2
#> └── Heading [h3] - Exercise 3

rmd_select(rmd, has_option("message"))
#> ├── YAML [2 fields]
#> └── Chunk [r, 2 lines] - load-packages
rmd_select(rmd, has_option(message = FALSE))
#> ├── YAML [2 fields]
#> └── Chunk [r, 2 lines] - load-packages
rmd_select(rmd, has_option(message = TRUE))
#> └── YAML [2 fields]

rmd_select(rmd, has_shortcode())
#> └── YAML [2 fields]
rmd_select(rmd, has_shortcode("video"))
#> └── YAML [2 fields]

fdiv = parse_rmd(system.file("examples/fenced-divs.qmd", package="parsermd"))

rmd_select(fdiv, by_fenced_div())  # Select all fenced div pairs
#> ├── YAML [2 fields]
#> ├── Fenced div (open) [.note]
#> │   └── Markdown [1 line]
#> ├── Fenced div (close) 
#> ├── Fenced div (open) [.warning, .important]
#> │   └── Markdown [2 lines]
#> ├── Fenced div (close) 
#> ├── Fenced div (open) [.info]
#> │   └── Markdown [1 line]
#> ├── Fenced div (close) 
#> ├── Fenced div (open) [#special-section, .sidebar]
#> │   └── Markdown [2 lines]
#> ├── Fenced div (close) 
#> ├── Fenced div (open) [.callout-note, icon="true"]
#> │   └── Markdown [1 line]
#> ├── Fenced div (close) 
#> ├── Fenced div (open) [.callout-warning, collapse="true"]
#> │   └── Markdown [3 lines]
#> ├── Fenced div (close) 
#> ├── Fenced div (open) [.outer]
#> │   └── Markdown [1 line]
#> ├── Fenced div (open) [.inner]
#> │   └── Markdown [1 line]
#> ├── Fenced div (close) 
#> │   └── Markdown [1 line]
#> ├── Fenced div (close) 
#> ├── Fenced div (open) [#example-complex, .demo, .interactive, data-toggle="collapse", aria-expanded="false"]
#> │   └── Markdown [4 lines]
#> ├── Fenced div (close) 
#> ├── Fenced div (open) [.note]
#> │   └── Markdown [1 line]
#> └── Fenced div (close) 
rmd_select(fdiv, by_fenced_div(class = "note"))
#> Warning: Classes "note" should start with '.' prefix, adding it automatically
#> ├── YAML [2 fields]
#> ├── Fenced div (open) [.note]
#> │   └── Markdown [1 line]
#> ├── Fenced div (close) 
#> ├── Fenced div (open) [.note]
#> │   └── Markdown [1 line]
#> └── Fenced div (close) 
rmd_select(fdiv, by_fenced_div(id = "special-section"))
#> Warning: ID "special-section" should start with '#' prefix, adding it automatically
#> ├── YAML [2 fields]
#> ├── Fenced div (open) [#special-section, .sidebar]
#> │   └── Markdown [2 lines]
#> └── Fenced div (close) 
rmd_select(fdiv, by_fenced_div(class = c("warning", "important")))
#> Warning: Classes "warning" and "important" should start with '.' prefix, adding it
#> automatically
#> ├── YAML [2 fields]
#> ├── Fenced div (open) [.warning, .important]
#> │   └── Markdown [2 lines]
#> └── Fenced div (close) 
rmd_select(fdiv, by_fenced_div(attr = "icon"))
#> ├── YAML [2 fields]
#> ├── Fenced div (open) [.callout-note, icon="true"]
#> │   └── Markdown [1 line]
#> └── Fenced div (close)