yarn: R6 class containing XML representation of Markdown
In ropenscilabs/tinkr: Cast '(R)Markdown' Files to 'XML' and Back Again
yarn R Documentation
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.
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.
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]](../help/figures/lifecycle-deprecated.svg)
frontmatter
Methods
Public 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()
sourcepospassed 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
pathpath to the file you want to write
stylesheet_pathpath 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
linesa subset of elements to show. Defaults to TRUE, which
shows all lines of the output. This can be either logical or numeric.
stylesheet_pathpath 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
nthe number of elements to show from the top. Negative numbers
stylesheet_pathpath 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
nthe number of elements to show from the bottom. Negative numbers
stylesheet_pathpath 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
xpatha valid XPath expression
stylesheet_pathpath 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
mda string of markdown formatted text.
wherethe 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 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_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
typea 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
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 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
deepWhether to make a deep clone.
Note
this requires the sourcepos attribute to be recorded when the
object is initialised. See protect_unescaped() for details.
See Also
to_md_vec() for a way to generate the same vector from a
nodelist without a yarn object
Examples
## ------------------------------------------------
## 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$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_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 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
ropenscilabs/tinkr documentation built on Feb. 24, 2025, 6:43 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| yarn | R Documentation |
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.
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.
Public fields
path[
character] path to file on diskfrontmatter[
character] text block at head of filefrontmatter_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] frontmatter
Methods
Public 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 diskencoding[
character] encoding passed toreadLines()sourcepospassed to
commonmark::markdown_xml(). IfTRUE, the source position of the file will be included as a "sourcepos" attribute. Defaults toFALSE....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
pathpath to the file you want to write
stylesheet_pathpath 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
linesa subset of elements to show. Defaults to
TRUE, which shows all lines of the output. This can be either logical or numeric.stylesheet_pathpath 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
nthe number of elements to show from the top. Negative numbers
stylesheet_pathpath 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
nthe number of elements to show from the bottom. Negative numbers
stylesheet_pathpath 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
xpatha valid XPath expression
stylesheet_pathpath 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
mda string of markdown formatted text.
wherethe 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 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_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
typea character vector listing the protections to be included. Defaults to
NULL, which includes all protected nodes:math: via the
protect_math()functioncurly: via the
protect_curly()functionunescaped: 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 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
deepWhether to make a deep clone.
Note
this requires the sourcepos attribute to be recorded when the
object is initialised. See protect_unescaped() for details.
See Also
to_md_vec() for a way to generate the same vector from a
nodelist without a yarn object
Examples
## ------------------------------------------------
## 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$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_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 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
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.