15.6 Write the chunk content to a file via the cat engine

Sometimes it could be useful to write the content of a code chunk to an external file, and use this file later in other code chunks. Of course, you may do this via the R functions like writeLines(), but the problem is that when the content is relatively long, or contains special characters, the character string that you would pass to writeLines() may look awkward. Below is an example of writing a long character string to a file my-file.txt:

  1. writeLines("This is a long character string.
  2. It has multiple lines. Remember to escape
  3. double quotes \"\", but 'single quotes' are OK.
  4. I hope you not to lose your sanity when thinking
  5. about how many backslashes you need, e.g., is it
  6. '\t' or '\\t' or '\\\\t'?", 
  7.   con = "my-file.txt")

This problem has been greatly alleviated since R 4.0.0, because R started to support raw strings in r"( )" (see the help page ?Quotes), and you do not need to remember all the rules about special characters. Even with raw strings, it can still be a little distracting for readers to see a long string written to a file explicitly in a code chunk.

The cat engine in knitr has provided a way for you to present text content in a code chunk and/or write it to an external file, without thinking about all the rules about R’s character strings (e.g., you need double backslashes when you need a literal backslash).

To write the chunk content to a file, specify the file path in the chunk option engine.opts, e.g., engine.opts = list(file = 'path/to/file'). Under the hood, the list of values specified in engine.opts will be passed to the function base::cat(), and file is one of the arguments of base::cat().

Next we will present three examples to illustrate the use of the cat engine.

15.6.1 Write to a CSS file

As shown in Section 7.3, you can embed a css code chunk in an Rmd document to style elements with CSS. An alternative way is to provide a custom CSS file to Pandoc via the css option of some R Markdown output formats such as html_document. The cat engine can be used to write this CSS file from Rmd.

This example below shows how to generate a file custom.css from a chunk in the document, and pass the file path to the css option of the html_document format:

  1. ---
  2. title: "Create a CSS file from a code chunk"
  3. output: 
  4.   html_document:
  5.     css: custom.css
  6. ---
  8. The chunk below will be written to `custom.css`, which
  9. will be used during the Pandoc conversion.
  11. ```{cat, engine.opts = list(file = "my_custom.css")}
  12. h2 {
  13.   color: blue;
  14. }
  15. ```
  17. ## And this title will blue

The only difference between the css code chunk approach and this approach is that the former approach writes the CSS code in place (i.e., in the place of the code chunk), which is inside the <body> tag of the output document, and the latter approach writes CSS to the <head> area of the output document. There will not be any practical visual differences in the output document.

15.6.2 Include LaTeX code in the preamble

In Section 6.1, we introduced how to add LaTeX code to the preamble, which requires an external .tex file. This file can also be generated from Rmd, and here is an example:

  1. ---
  2. title: "Create a .tex file from a chunk"
  3. author: "Jane Doe"
  4. classoption: twoside
  5. output: 
  6.   pdf_document:
  7.     includes:
  8.       in_header: preamble.tex
  9. ---
  11. # How it works
  13. Write a code chunk to a file `preamble.tex` to define
  14. the header and footer of the PDF output document:
  16. ```{cat, engine.opts=list(file = 'preamble.tex')}
  17. \usepackage{fancyhdr}
  18. \usepackage{lipsum}
  19. \pagestyle{fancy}
  20. \fancyhead[CO,CE]{This is fancy header}
  21. \fancyfoot[CO,CE]{And this is a fancy footer}
  22. \fancyfoot[LE,RO]{\thepage}
  23. \fancypagestyle{plain}{\pagestyle{fancy}}
  24. ```
  26. \lipsum[1-15]
  28. # More random content
  30. \lipsum[16-30]

In the LaTeX code in the cat code chunk above, we have defined the header and footer of the PDF document. If we also want to show the author name in the footer, we can append the author information to preamble.tex in another cat code chunk with options engine.opts = list(file = 'preamble.tex', append = TRUE) and code = sprintf('\\fancyfoot[LO,RE]{%s}', rmarkdown::metadata$author). To understand how this works, recall that we mentioned earlier in this section that engine.opts is passed to base::cat() (so append = TRUE is passed to cat()), and you may understand the chunk option code by reading Section 16.2.

15.6.3 Write YAML data to a file and also display it

By default, the content of the cat code chunk will not be displayed in the output document. If you also want to display it after writing it out, set the chunk option class.source to a language name. The language name is used for syntax highlighting. In the example below, we specify the language to be yaml:

  1. ```{cat, engine.opts=list(file='demo.yml'), class.source='yaml'}
  2. a:
  3.   aa: "something"
  4.   bb: 1
  5. b:
  6.   aa: "something else"
  7.   bb: 2
  8. ```

Its output is displayed below, and it also generated a file demo.yml.

  1. a:
  2.   aa: "something"
  3.   bb: 1
  4. b:
  5.   aa: "something else"
  6.   bb: 2

To show the file demo.yml is really generated, we can try to read it into R with the yaml package (Stephens et al. 2020):

  1. xfun::tree(yaml::read_yaml("demo.yml"))
  1. ## List of 2
  2. ##  |-a:List of 2
  3. ##  |  |-aa: chr "something"
  4. ##  |  |-bb: int 1
  5. ##  |-b:List of 2
  6. ##     |-aa: chr "something else"
  7. ##     |-bb: int 2

References

Stephens, Jeremy, Kirill Simonov, Yihui Xie, Zhuoer Dong, Hadley Wickham, Jeffrey Horner, reikoch, Will Beasley, Brendan O’Connor, and Gregory R. Warnes. 2020. Yaml: Methods to Convert r Data to YAML and Back. https://github.com/viking/r-yaml/.