Output filters for code blocks in markdown

Output filters for code blocks in markdown

output_table(code, language = "R", id = "", ...)

output_figure(code, language = "R", id = "", ...)

output_eval(
  code,
  language = "R",
  id = "",
  echo = TRUE,
  results = TRUE,
  drop_empty = TRUE,
  eval = TRUE,
  formatter = getOption("md_formatter", default = format_traditional),
  capture_warnings = FALSE,
  capture_messages = results,
  muffle_warnings = FALSE,
  muffle_messages = TRUE,
  ...
)

output_raw(code, language = "R", id = "", ...)

output_str(code, language = "R", id = "", ...)

output_shell(
  code,
  language,
  id = "",
  cmd = language,
  echo = TRUE,
  results = TRUE,
  comment_char = "# ",
  ...
)

Arguments

code

character vector containing the code of the code block

language

the language in which the code is written (as specified in the markdown file).

id

the identifier of the code block.

...

additional arguments specified as arguments in the code block are passed on to the filter function. Often these are ignored, or they are passed on to other functions (see 'Details').

echo

the code in code is repeated in the output.

results

include the results of running the code in the output. The output of code that explicitly writes to standard output is always included.

drop_empty

do not include any output if the resulting code block would be empty.

eval

if FALSE do not run the code and just include the code in the output.

formatter

function that will format the R-code and resulting output (if requested). See format_traditional for possible options.

capture_warnings

include warnings in the output.

capture_messages

include messages in the output.

muffle_warnings

do not show warnings in the console.

muffle_messages

do not show messages in the console.

cmd

the command to use in the system2 call. Only needed when different than the language.

comment_char

string prepended to output of commands run by output_shell.

Value

The functions either return a character vector with markdown, or return a list with the correct structure to include in the pandoc parse tree.

Details

The filter functions output_table and output_figure call md_table and md_figure respectively; additional arguments are passed on to those functions. Other filter functions ignore the additional arguments.

It is also possible to write custom output filter. An output filter should have code, language and id as its first three arguments. It should either return a character vector containing the markdown that should be included in the resulting markdown file or an object that can be directly included in the pandoc parse tree. If the function does not return a character vector it is assumed the latter is returned. simplermarkdown defines a small number of valid object constructors: raw_block and markdown_block.

The custom function should be available when running the markdown document through pandoc. The easiest way is to source or define the function in the markdown document before using it.

The filter function output_shell can be used to process chunks of code from other languages than R. These chunks of code are written to a temporary file which is then ran using the cmd using a call to system2. The output of that is captured and when results = TRUE included in the output. The output lines are prepended by comment_char. When echo = TRUE the code is also included before the output.