knitr (version 1.31)

extract_raw_output: Mark character strings as raw output that should not be converted

Description

These functions provide a mechanism to protect the character output of R code chunks. The output is annotated with special markers in raw_output; extract_raw_output() will extract raw output wrapped in the markers, and replace the raw output with its MD5 digest; restore_raw_output() will restore the MD5 digest with the original raw output.

Usage

extract_raw_output(text, markers = raw_markers)
restore_raw_output(text, chunks, markers = raw_markers)
raw_output(x, markers = raw_markers, ...)

Arguments

text

For extract_raw_output(), the content of the input file (e.g. Markdown); for restore_raw_output(), the content of the output file (e.g. HTML generated by Pandoc from Markdown).

markers

A length-2 character vector to be used to wrap x; see knitr:::raw_markers for the default value.

chunks

A named character vector returned from extract_raw_output().

x

The character vector to be protected.

...

Arguments to be passed to asis_output().

Value

For extract_raw_output(), a list of two components: value (the text with raw output replaced by MD5 digests) and chunks (a named character vector, of which the names are MD5 digests and values are the raw output). For restore_raw_output(), the restored text.

Details

This mechanism is designed primarily for R Markdown pre/post-processors. In an R code chunk, you generate raw_output() to the Markdown output. In the pre-processor, you can extract_raw_output() from the Markdown file, store the raw output and MD5 digests, and remove the actual raw output from Markdown so Pandoc will never see it. In the post-processor, you can read the Pandoc output (e.g., an HTML or RTF file), and restore the raw output.

Examples

# NOT RUN {
library(knitr)
out = c("*hello*", raw_output("<special>content</special> *protect* me!"), 
    "*world*")
pre = extract_raw_output(out)
str(pre)
pre$value = gsub("[*]([^*]+)[*]", "<em>\\1</em>", 
    pre$value)  # think this as Pandoc conversion
pre$value
# raw output was protected from the conversion (e.g.
# *protect* was not converted)
restore_raw_output(pre$value, pre$chunks)
# }