About

The knitLiteral package gives authors the ability to easily output the exact the source of a chunk without side-effects. It is simple to use; just remember that knitr processes chunk options as they occur and options can occur more than once.

The main option that knitLiteral allows is literal=TRUE. This option allows you to generate the output you literally want to use in knitr to produce a result without repeating yourself or breaking the parser. (Notice the use of 4 backticks instead of the minimal 3 to allow R syntax highlighting to work.)

If the literal label is used more than once in a particular chunk and the options end with literal=TRUE then only the final literal=TRUE will be removed, which allows for illustrating how the literal chunk was produced.

The rmarkdown in this sample document should produce very similar results using either rmarkdown v1 or v2 and using pandoc to generate Word, pdf or html output. Other output formats have not been tested.

Setup

It is very easy to initialize using kast_on in your first chunk.

````{r "knitr-setup", include=FALSE, cache=FALSE}
# knitr-setup should be the first chunk in the document.
knitLiteral::kast_on()
````

It is very easy to style using dye in your closing chunk.

````{r "include-after", echo=FALSE, results='asis'}
# include-after should be the last chunk in the document.
knitLiteral::dye()
````

Examples

Each sample shows the Source along with the rendered Literal and normal Output.

No output, caching only

Source Following the DRY principle this is the source for all “example” chunks.

````{r "example", eval=FALSE, echo=FALSE, literal=TRUE}
print('hello world!')
print('hello again!')
````

Literal

````{r "example", eval=FALSE, echo=FALSE}
print('hello world!')
print('hello again!')
````

Output (none)

Default

Source

````{r "example", literal=TRUE}
````

Rendered

````{r "example"}
print('hello world!')
print('hello again!')
````
print('hello world!')
## [1] "hello world!"
print('hello again!')
## [1] "hello again!"

Default comment

Set the global default comment option to match normal console output using opts_chunk$set(comment=NA).

Source

````{r "example", literal=TRUE}
````

Rendered

````{r "example"}
print('hello world!')
print('hello again!')
````
print('hello world!')
[1] "hello world!"
print('hello again!')
[1] "hello again!"

Chunk comment

Source

````{r "example", comment="override > ", literal=TRUE}
````

Rendered

````{r "example", comment="override > "}
print('hello world!')
print('hello again!')
````
print('hello world!')
override >  [1] "hello world!"
print('hello again!')
override >  [1] "hello again!"

No echo

Source

````{r "example", echo=FALSE, literal=TRUE}
````

Rendered

````{r "example", echo=FALSE}
print('hello world!')
print('hello again!')
````
[1] "hello world!"
[1] "hello again!"

Collapse

Source

````{r "example", collapse=TRUE, literal=TRUE}
````

Rendered

````{r "example", collapse=TRUE}
print('hello world!')
print('hello again!')
````
print('hello world!')
[1] "hello world!"
print('hello again!')
[1] "hello again!"

Hold

Source

````{r "example", results='hold', literal=TRUE}
````

Rendered

````{r "example", results='hold'}
print('hello world!')
print('hello again!')
````
print('hello world!')
print('hello again!')
[1] "hello world!"
[1] "hello again!"

Collapse & hold

Source

````{r "example", collapse=TRUE, results='hold', literal=TRUE}
````

Rendered

````{r "example", collapse=TRUE, results='hold'}
print('hello world!')
print('hello again!')
````
print('hello world!')
print('hello again!')
[1] "hello world!"
[1] "hello again!"

Echo & no-eval, no-echo & hold combo

Source

````{r "example", eval=FALSE, literal=TRUE, echo=FALSE}
````
````{r "example", echo=FALSE, results='hold', opts.label="literal-reuse"}
````
````{r "example", eval=FALSE}
````
````{r "example", echo=FALSE, results='hold'}
````

Rendered (the normal output is the same as a simple hold)

````{r "example", eval=FALSE}
print('hello world!')
print('hello again!')
````
````{r "example", echo=FALSE, results='hold'}
````
print('hello world!')
print('hello again!')
[1] "hello world!"
[1] "hello again!"

Echo & no-eval, no-echo & collapse combo

Source

````{r "example", eval=FALSE, literal=TRUE, echo=FALSE}
````
````{r "example", echo=FALSE, collapse=TRUE, opts.label="literal-reuse"}
````
````{r "example", eval=FALSE}
````
````{r "example", echo=FALSE, collapse=TRUE}
````

Rendered

````{r "example", eval=FALSE}
print('hello world!')
print('hello again!')
````
````{r "example", echo=FALSE, collapse=TRUE}
````
print('hello world!')
print('hello again!')
[1] "hello world!"
[1] "hello again!"

Silent Tidy of training chunk.

Imagine having a chunk to use for training, but it needs tidying, and the tidying has nothing to do with the training. By taking advantage of how knitr handles chunk options a chunk can be silently turned into a nice example.

Starting with a cached chunk like this

````{r "tidy-example", echo=FALSE, eval=FALSE}
# This should not be displayed, it is just a note to myself

# that this coding is horrible and would be _wrong_.

##' Without a doubt!

if ( ( knitr::opts_current$get("literal") == TRUE ) && ( knitr::opts_current$get("literal") == TRUE ) )
  {
  foo<-FALSE } else {
    foo = TRUE
  listfoo <- list( first="second", second="third", third="fourth", fourth=fifth, and="so on")
}
````

Make a new options template like this

````{r "opt_template", include=FALSE, cache=FALSE}
knitr::opts_template$set( "literal-tidy"=
  list( literal=TRUE, echo=FALSE, eval=FALSE, tidy=TRUE,
        tidy.opts=c( width.cutoff=50, keep.comment=FALSE,
                     keep.blank.line=FALSE, replace.assign=TRUE)))
````

And use it like this

````{r "tidy-example", opts.label="literal-tidy"}
````

To get results like this

````{r "tidy-example", echo=FALSE, eval=FALSE}
if ((knitr::opts_current$get("literal") == TRUE) && 
    (knitr::opts_current$get("literal") == TRUE)) {
    foo <- FALSE
} else {
    foo <- TRUE
    listfoo <- list(first = "second", second = "third", 
        third = "fourth", fourth = fifth, and = "so on")
}
````

Which is a much better, although still bad, example.

knit markdown output.

If you are interested in keeping a clean and readable markdown file the following is the knitr generated markdown from the Echo & no-eval, no-echo & collapse combo example.

`````` {.knitr .r .markdown}
````{r "example", eval=FALSE}
print('hello world!')
print('hello again!')
````
``````

`````` {.knitr .r .markdown}
````{r "example", echo=FALSE, collapse=TRUE}
````
``````


```r
print('hello world!')
print('hello again!')
```


```
[1] "hello world!"
[1] "hello again!"
```

Styling Information

HTML Classes

The knitr chunk pre class and code class.

<pre class="sourceCode knitr r markdown"><code class="sourceCode r">

CSS

The style for the knitr blocks was accomplished by simply using four back ticks instead of three so the R syntax highlighter would work and by defining a style.

<!-- knitLiteral support for v1 and v2 rmarkdown literal blocks -->
<style>
  table.sourceCode.r pre {
    background-color:#f5f5f5;
  }
  table.sourceCode.knitr.r.markdown.number > tbody > tr > td.lineNumbers > pre {
    border-left:thick solid rgba(0,0,0,.25);
  }
  table.sourceCode.knitr pre {
    background-color:#f5f5f5;
    background: rgba(0,0,0,.06);
  }
  pre.knitr {
    background: rgba(0,0,0,.06);
    padding-left: 1em;
    border-left:thick solid rgba(0,0,0,.25);
  }
  pre.knitr.literal {
    background: rgba(0,0,0,.06);
    padding-left: 1em;
    border-left:thick solid rgba(0,0,0,.25);
  }
  code.knitr {
    background: rgba(0,0,0,.06);
    padding-left: 1em;
    border-left:thick solid rgba(0,0,0,.25);
  }
  code.knitr.literal {
    background: rgba(0,0,0,.06);
    padding-left: 1em;
    border-left:thick solid rgba(0,0,0,.25);
  }
</style>

Javascript for rmarkdown v1

<!-- knitLiteral support to left-align block -->
<script>
  window.jQuery || document.write('<script src="http://code.jquery.com/jquery-latest.min.js"><\/script>')
</script>

<script defer src="https://rawgithub.com/cowboy/jquery-replacetext/master/jquery.ba-replacetext.min.js"></script>

<script defer>
  $(document).ready(function() {
    $('.r').replaceText(/^\s{4}/mg, "", true)
  } );
</script>