yarn {tinkr} | 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
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()
sourcepos
passed 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
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
orxml_nodeset
that are all either inline or block nodes (never both). The XPath expression is passed toxml2::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:
append content after a specific node or set of nodes
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
orxml_nodeset
that are all either inline or block nodes (never both). The XPath expression is passed toxml2::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:
prepend content after a specific node or set of nodes
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()
functioncurly: via the
protect_curly()
functionfence: via the
protect_fences()
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 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.
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$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