R: Mark character strings as raw output that should not be...

extract_raw_output {knitr} | R Documentation

## 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 character vector of length 2 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()`

### 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.

### 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`.

### Examples

    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)

[Package knitr version 1.16 Index]