Learn R Programming
tinkr (version 0.3.1)

yarn: R6 class containing XML representation of Markdown

Description

Wrapper around an XML representation of a Markdown document. It contains four publicly accessible slots: path, frontmatter, body, and ns.

Arguments

Public fields

path

[character] path to file on disk

frontmatter

[character] text block at head of file

frontmatter_format

[character] 'YAML', 'TOML' or 'JSON'

body

[xml_document] an xml document of the (R)Markdown file.

ns

[xml_document] an xml namespace object defining "md" to commonmark.

Active bindings

yaml

[character] [Deprecated] frontmatter

Methods

Method new()

Create a new yarn document

Usage

yarn$new(path = NULL, encoding = "UTF-8", sourcepos = FALSE, ...)

Arguments

path

[character] path to a markdown episode file on disk

encoding

[character] encoding passed to readLines()

sourcepos

passed to commonmark::markdown_xml(). If TRUE, the source position of the file will be included as a "sourcepos" attribute. Defaults to FALSE.

...

arguments passed on to to_xml().

Returns

A new yarn object containing an XML representation of a (R)Markdown file.

Examples

path <- system.file("extdata", "example1.md", package = "tinkr")
ex1 <- tinkr::yarn$new(path)
ex1
path2 <- system.file("extdata", "example2.Rmd", package = "tinkr")
ex2 <- tinkr::yarn$new(path2)
ex2

Method reset()

reset a yarn document from the original file

Usage

yarn$reset()

Examples


path <- system.file("extdata", "example1.md", package = "tinkr")
ex1 <- tinkr::yarn$new(path)
# OH NO
ex1$body
ex1$body <- xml2::xml_missing()
ex1$reset()
ex1$body

Method write()

Write a yarn document to Markdown/R Markdown

Usage

yarn$write(path = NULL, stylesheet_path = stylesheet())

Arguments

path

path to the file you want to write

stylesheet_path

path to the xsl stylesheet to convert XML to markdown.

Examples

path <- system.file("extdata", "example1.md", package = "tinkr")
ex1 <- tinkr::yarn$new(path)
ex1
tmp <- tempfile()
try(readLines(tmp)) # nothing in the file
ex1$write(tmp)
head(readLines(tmp)) # now a markdown file
unlink(tmp)

Method show()

show the markdown contents on the screen

Usage

yarn$show(lines = TRUE, stylesheet_path = stylesheet())

Arguments

lines

a subset of elements to show. Defaults to TRUE, which shows all lines of the output. This can be either logical or numeric.

stylesheet_path

path to the xsl stylesheet to convert XML to markdown.

Returns

a character vector with one line for each line in the output

Examples

path <- system.file("extdata", "example2.Rmd", package = "tinkr")
ex2 <- tinkr::yarn$new(path)
ex2$head(5)
ex2$tail(5)
ex2$show()

Method head()

show the head of the markdown contents on the screen

Usage

yarn$head(n = 6L, stylesheet_path = stylesheet())

Arguments

n

the number of elements to show from the top. Negative numbers

stylesheet_path

path to the xsl stylesheet to convert XML to markdown.

Returns

a character vector with n elements

Method tail()

show the tail of the markdown contents on the screen

Usage

yarn$tail(n = 6L, stylesheet_path = stylesheet())

Arguments

n

the number of elements to show from the bottom. Negative numbers

stylesheet_path

path to the xsl stylesheet to convert XML to markdown.

Returns

a character vector with n elements

Method md_vec()

query and extract markdown elements

Usage

yarn$md_vec(xpath = NULL, stylesheet_path = stylesheet())

Arguments

xpath

a valid XPath expression

stylesheet_path

path to the xsl stylesheet to convert XML to markdown.

Returns

a vector of markdown elements generated from the query

Examples

path <- system.file("extdata", "example1.md", package = "tinkr")
ex <- tinkr::yarn$new(path)
# all headings
ex$md_vec(".//md:heading")
# all headings greater than level 3
ex$md_vec(".//md:heading[@level>3]")
# all links
ex$md_vec(".//md:link")
# all links that are part of lists
ex$md_vec(".//md:list//md:link")
# all code
ex$md_vec(".//md:code | .//md:code_block")

Method add_md()

add an arbitrary Markdown element to the document

Usage

yarn$add_md(md, where = 0L)

Arguments

md

a string of markdown formatted text.

where

the location in the document to add your markdown text. This is passed on to xml2::xml_add_child(). Defaults to 0, which indicates the very top of the document.

Examples

path <- system.file("extdata", "example2.Rmd", package = "tinkr")
ex <- tinkr::yarn$new(path)
# two headings, no lists
xml2::xml_find_all(ex$body, "md:heading", ex$ns)
xml2::xml_find_all(ex$body, "md:list", ex$ns)
ex$add_md(
  "# Hello\n\nThis is *new* formatted text from `{tinkr}`!",
  where = 1L
)$add_md(
  " - This\n - is\n - a new list",
  where = 2L
)
# three headings
xml2::xml_find_all(ex$body, "md:heading", ex$ns)
xml2::xml_find_all(ex$body, "md:list", ex$ns)
tmp <- tempfile()
ex$write(tmp)
readLines(tmp, n = 20)

Method append_md()

append abritrary markdown to a node or set of nodes

Usage

yarn$append_md(md, nodes = NULL, space = TRUE)

Arguments

md

a string of markdown formatted text.

nodes

an XPath expression that evaulates to object of class xml_node or xml_nodeset that are all either inline or block nodes (never both). The XPath expression is passed to xml2::xml_find_all(). If you want to append a specific node, you can pass that node to this parameter.

space

if TRUE, inline nodes will have a space inserted before they are appended.

Details

this is similar to the add_md() method except that it can do the following:

  1. append content after a specific node or set of nodes

  2. append content to multiple places in the document

Examples

path <- system.file("extdata", "example2.Rmd", package = "tinkr")
ex <- tinkr::yarn$new(path)
# append a note after the first heading

txt <- c("> Hello from *tinkr*!", ">", "> :heart: R") ex$append_md(txt, ".//md:heading[1]")$head(20)

Method prepend_md()

prepend arbitrary markdown to a node or set of nodes

Usage

yarn$prepend_md(md, nodes = NULL, space = TRUE)

Arguments

md

a string of markdown formatted text.

nodes

an XPath expression that evaulates to object of class xml_node or xml_nodeset that are all either inline or block nodes (never both). The XPath expression is passed to xml2::xml_find_all(). If you want to append a specific node, you can pass that node to this parameter.

space

if TRUE, inline nodes will have a space inserted before they are prepended.

Details

this is similar to the add_md() method except that it can do the following:

  1. prepend content after a specific node or set of nodes

  2. prepend content to multiple places in the document

Examples

path <- system.file("extdata", "example2.Rmd", package = "tinkr")
ex <- tinkr::yarn$new(path)

# prepend a table description to the birds table ex$prepend_md("Table: BIRDS, NERDS", ".//md:table[1]")$tail(20)

Method protect_math()

Protect math blocks from being escaped

Usage

yarn$protect_math()

Examples

path <- system.file("extdata", "math-example.md", package = "tinkr")
ex <- tinkr::yarn$new(path)
ex$tail() # math blocks are escaped :(
ex$protect_math()$tail() # math blocks are no longer escaped :)

Method protect_curly()

Protect curly phrases {likethat} from being escaped

Usage

yarn$protect_curly()

Examples

path <- system.file("extdata", "basic-curly.md", package = "tinkr")
ex <- tinkr::yarn$new(path)
ex$protect_curly()$head()

Method protect_fences()

Protect fences of Pandoc fenced divs :::

Usage

yarn$protect_fences()

Examples

path <- system.file("extdata", "fenced-divs.md", package = "tinkr")
ex <- tinkr::yarn$new(path)
ex$protect_fences()$head()

Method protect_unescaped()

Protect unescaped square braces from being escaped.

This is applied by default when you use yarn$new(sourcepos = TRUE).

Usage

yarn$protect_unescaped()

Examples

path <- system.file("extdata", "basic-curly.md", package = "tinkr")
ex <- tinkr::yarn$new(path, sourcepos = TRUE, unescaped = FALSE)
ex$tail()
ex$protect_unescaped()$tail()

Method get_protected()

Return nodes whose contents are protected from being escaped

Usage

yarn$get_protected(type = NULL)

Arguments

type

a character vector listing the protections to be included. Defaults to NULL, which includes all protected nodes:

  • math: via the protect_math() function

  • curly: via the protect_curly() function

  • fence: via the protect_fences() function

  • unescaped: via the protect_unescaped() function

Examples

path <- system.file("extdata", "basic-curly.md", package = "tinkr")
ex <- tinkr::yarn$new(path, sourcepos = TRUE)
# protect curly braces
ex$protect_curly()
# add fenced divs and protect then
ex$add_md(c("::: alert\n",
  "blabla",
  ":::")
)
ex$protect_fences()
# add math and protect it
ex$add_md(c("## math\n",
  "$c^2 = a^2 + b^2$\n",
  "$$",
  "\\sum_{i}^k = x_i + 1",
  "$$\n")
)
ex$protect_math()
# get protected now shows all the protected nodes
ex$get_protected()
ex$get_protected(c("math", "curly")) # only show the math and curly

Method clone()

The objects of this class are cloneable with this method.

Usage

yarn$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Details

This class is a fancy wrapper around the results of to_xml() and has methods that make it easier to add, analyze, remove, or write elements of your markdown document.

See Also

to_md_vec() for a way to generate the same vector from a nodelist without a yarn object

Examples

Run this code

## ------------------------------------------------
## Method `yarn$new`
## ------------------------------------------------

path <- system.file("extdata", "example1.md", package = "tinkr")
ex1 <- tinkr::yarn$new(path)
ex1
path2 <- system.file("extdata", "example2.Rmd", package = "tinkr")
ex2 <- tinkr::yarn$new(path2)
ex2

## ------------------------------------------------
## Method `yarn$reset`
## ------------------------------------------------


path <- system.file("extdata", "example1.md", package = "tinkr")
ex1 <- tinkr::yarn$new(path)
# OH NO
ex1$body
ex1$body <- xml2::xml_missing()
ex1$reset()
ex1$body

## ------------------------------------------------
## Method `yarn$write`
## ------------------------------------------------

path <- system.file("extdata", "example1.md", package = "tinkr")
ex1 <- tinkr::yarn$new(path)
ex1
tmp <- tempfile()
try(readLines(tmp)) # nothing in the file
ex1$write(tmp)
head(readLines(tmp)) # now a markdown file
unlink(tmp)

## ------------------------------------------------
## Method `yarn$show`
## ------------------------------------------------

path <- system.file("extdata", "example2.Rmd", package = "tinkr")
ex2 <- tinkr::yarn$new(path)
ex2$head(5)
ex2$tail(5)
ex2$show()

## ------------------------------------------------
## Method `yarn$md_vec`
## ------------------------------------------------

path <- system.file("extdata", "example1.md", package = "tinkr")
ex <- tinkr::yarn$new(path)
# all headings
ex$md_vec(".//md:heading")
# all headings greater than level 3
ex$md_vec(".//md:heading[@level>3]")
# all links
ex$md_vec(".//md:link")
# all links that are part of lists
ex$md_vec(".//md:list//md:link")
# all code
ex$md_vec(".//md:code | .//md:code_block")

## ------------------------------------------------
## Method `yarn$add_md`
## ------------------------------------------------

path <- system.file("extdata", "example2.Rmd", package = "tinkr")
ex <- tinkr::yarn$new(path)
# two headings, no lists
xml2::xml_find_all(ex$body, "md:heading", ex$ns)
xml2::xml_find_all(ex$body, "md:list", ex$ns)
ex$add_md(
  "# Hello\n\nThis is *new* formatted text from `{tinkr}`!",
  where = 1L
)$add_md(
  " - This\n - is\n - a new list",
  where = 2L
)
# three headings
xml2::xml_find_all(ex$body, "md:heading", ex$ns)
xml2::xml_find_all(ex$body, "md:list", ex$ns)
tmp <- tempfile()
ex$write(tmp)
readLines(tmp, n = 20)

## ------------------------------------------------
## Method `yarn$append_md`
## ------------------------------------------------

path <- system.file("extdata", "example2.Rmd", package = "tinkr")
ex <- tinkr::yarn$new(path)
# append a note after the first heading

txt <- c("> Hello from *tinkr*!", ">", ">  :heart: R")
ex$append_md(txt, ".//md:heading[1]")$head(20)

## ------------------------------------------------
## Method `yarn$prepend_md`
## ------------------------------------------------

path <- system.file("extdata", "example2.Rmd", package = "tinkr")
ex <- tinkr::yarn$new(path)

# prepend a table description to the birds table
ex$prepend_md("Table: BIRDS, NERDS", ".//md:table[1]")$tail(20)

## ------------------------------------------------
## Method `yarn$protect_math`
## ------------------------------------------------

path <- system.file("extdata", "math-example.md", package = "tinkr")
ex <- tinkr::yarn$new(path)
ex$tail() # math blocks are escaped :(
ex$protect_math()$tail() # math blocks are no longer escaped :)

## ------------------------------------------------
## Method `yarn$protect_curly`
## ------------------------------------------------

path <- system.file("extdata", "basic-curly.md", package = "tinkr")
ex <- tinkr::yarn$new(path)
ex$protect_curly()$head()

## ------------------------------------------------
## Method `yarn$protect_fences`
## ------------------------------------------------

path <- system.file("extdata", "fenced-divs.md", package = "tinkr")
ex <- tinkr::yarn$new(path)
ex$protect_fences()$head()

## ------------------------------------------------
## Method `yarn$protect_unescaped`
## ------------------------------------------------

path <- system.file("extdata", "basic-curly.md", package = "tinkr")
ex <- tinkr::yarn$new(path, sourcepos = TRUE, unescaped = FALSE)
ex$tail()
ex$protect_unescaped()$tail()

## ------------------------------------------------
## Method `yarn$get_protected`
## ------------------------------------------------

path <- system.file("extdata", "basic-curly.md", package = "tinkr")
ex <- tinkr::yarn$new(path, sourcepos = TRUE)
# protect curly braces
ex$protect_curly()
# add fenced divs and protect then
ex$add_md(c("::: alert\n",
  "blabla",
  ":::")
)
ex$protect_fences()
# add math and protect it
ex$add_md(c("## math\n",
  "$c^2 = a^2 + b^2$\n",
  "$$",
  "\\sum_{i}^k = x_i + 1",
  "$$\n")
)
ex$protect_math()
# get protected now shows all the protected nodes
ex$get_protected()
ex$get_protected(c("math", "curly")) # only show the math and curly

Run the code above in your browser using DataLab