Custom Print Methods

Customize Printing

After we evaluate each R expression in a code chunk, there is an object returned. For example, 1 + 1 returns 2. This object is passed to the chunk option render, which is a function with two arguments, x and options, or x and .... The default value for the render option is knit_print, an S3 function in knitr:

library(knitr)
knit_print  # an S3 generic function

## function (x, ...) 
## {
##     if (need_screenshot(x, ...)) {
##         html_screenshot(x)
##     }
##     else {
##         UseMethod("knit_print")
##     }
## }
## <bytecode: 0x7f901aea0d28>
## <environment: namespace:knitr>

methods(knit_print)

##  [1] knit_print.css*            knit_print.data.frame*    
##  [3] knit_print.default*        knit_print.grouped_df*    
##  [5] knit_print.html*           knit_print.knit_asis*     
##  [7] knit_print.knit_asis_url*  knit_print.knitr_kable*   
##  [9] knit_print.rowwise_df*     knit_print.sass*          
## [11] knit_print.shiny.tag*      knit_print.shiny.tag.list*
## [13] knit_print.tbl_sql*       
## see '?methods' for accessing help and source code

getS3method('knit_print', 'default')  # the default method

## function (x, ..., inline = FALSE) 
## {
##     if (inline) 
##         x
##     else normal_print(x)
## }
## <bytecode: 0x7f901e8ebe70>
## <environment: namespace:knitr>

normal_print

## function (x, ...) 
## if (isS4(x)) methods::show(x) else print(x)
## <bytecode: 0x7f901f275650>
## <environment: namespace:evaluate>

As we can see, knit_print() has a default method, which is basically print() or show(), depending on whether the object is an S4 object. This means it does nothing special when printing R objects:

knit_print(1:10)
##  [1]  1  2  3  4  5  6  7  8  9 10
knit_print(head(mtcars))
##                    mpg cyl disp  hp drat    wt  qsec vs am gear carb
## Mazda RX4         21.0   6  160 110 3.90 2.620 16.46  0  1    4    4
## Mazda RX4 Wag     21.0   6  160 110 3.90 2.875 17.02  0  1    4    4
## Datsun 710        22.8   4  108  93 3.85 2.320 18.61  1  1    4    1
## Hornet 4 Drive    21.4   6  258 110 3.08 3.215 19.44  1  0    3    1
## Hornet Sportabout 18.7   8  360 175 3.15 3.440 17.02  0  0    3    2
## Valiant           18.1   6  225 105 2.76 3.460 20.22  1  0    3    1

S3 generic functions are extensible in the sense that we can define custom methods for them. A method knit_print.foo() will be applied to the object that has the class foo. Here is quick example of how we can print data frames as tables:

library(knitr)
# define a method for objects of the class data.frame
knit_print.data.frame = function(x, ...) {
  res = paste(c('', '', kable(x)), collapse = '\n')
  asis_output(res)
}
# register the method
registerS3method("knit_print", "data.frame", knit_print.data.frame)

If you define a method in a code chunk in a knitr document, the call to registerS3method() will be necessary for R >= 3.5.0, because the S3 dispatch mechanism has changed since R 3.5.0. If you are developing an R package, see the section For package authors below.

We expect the print method to return a character vector, or an object that can be coerced into a character vector. In the example above, the kable() function returns a character vector, which we pass to the asis_output() function so that later knitr knows that this result needs no special treatment (just write it as is), otherwise it depends on the chunk option results (= 'asis' / 'markup' / 'hide') how a normal character vector should be written. The function asis_output() has the same effect as results = 'asis', but saves us the effort to provide this chunk option explicitly. Now we check how the printing behavior is changed. We print a number, a character vector, a list, a data frame, and write a character value using cat() in the chunk below:

1 + 1

## [1] 2

head(letters)

## [1] "a" "b" "c" "d" "e" "f"

list(a = 1, b = 9:4)

## $a
## [1] 1
## 
## $b
## [1] 9 8 7 6 5 4

head(mtcars)

cat('This is cool.')

## This is cool.

We see all objects except the data frame were printed “normally”². The data frame was printed as a real table. Note you do not have to use kable() to create tables – there are many other options such as xtable. Just make sure the print method returns a character string.

The printr package is a companion to knitr containing printing methods for some common objects like matrices and data frames. Users only need to load this package to get attractive printed results. A major factor to consider (which has been considered in printr) when defining a printing method is the output format. For example, the table syntax can be entirely different when the output is LaTeX vs when it is Markdown.

It is strongly recommended that your S3 method has a ... argument, so that your method can safely ignore arguments that are passed to knit_print() but not defined in your method. At the moment, a knit_print() method can have two optional arguments:

• the options argument takes a list of the current chunk options;
• the inline argument indicates if the method is called in code chunks or inline R code;

Depending on your application, you may optionally use these arguments. Here are some examples:

knit_print.classA = function(x, ...) {
  # ignore options and inline
}
knit_print.classB = function(x, options, ...) {
  # use the chunk option out.height
  asis_output(paste0(
    '<iframe src="https://yihui.org" height="', options$out.height, '"></iframe>',
  ))
}
knit_print.classC = function(x, inline = FALSE, ...) {
  # different output according to inline=TRUE/FALSE
  if (inline) {
    'inline output for classC'
  } else {
    'chunk output for classC'
  }
}
knit_print.classD = function(x, options, inline = FALSE, ...) {
  # use both options and inline
}

Note that when using your (or another) knit_print() method inline (if it supports that), you must not call knit_print() on the object, but just have it return. For example, your inline code should read `r c("foo")` and not `r knit_print(c("foo"))`. The latter inline code would yield the methods’ result for in-chunk (not inline), because, as set up in the above, knit_print() methods default to inline = FALSE. This default gets overwritten depending on the context in which knit_print() is called (inline or in-chunk), only when knit_print() is called by knitr (not you) via the render option (see below). You can, of course, always manually set the inline option `r knit_print(c("foo"), inline = TRUE)`, but that’s a lot of typing.

A Low-level Explanation

You can skip this section if you do not care about the low-level implementation details.

dummy_print = function(x, ...) {
  cat("I do not know what to print!")
  # this function implicitly returns an invisible NULL
}

1 + 1
## I do not know what to print!
head(letters)
## I do not know what to print!
list(a = 1, b = 9:4)
## I do not know what to print!
head(mtcars)
## I do not know what to print!
cat('This is cool.')
## This is cool.

1 + 1

## [1] 2

invisible(1 + 1)
invisible(head(mtcars))
x = 1:10  # invisibly returns 1:10

# pseudo code
knit_print.ggvis = function(x, ...) {
  res = ggvis::print_this_object(x)
  knitr::asis_output(res, meta = list(
    ggvis = list(
      version = '0.1.0',
      js  = system.file('www', 'js',  'ggvis.js',  package = 'ggvis'),
      css = system.file('www', 'www', 'ggvis.css', package = 'ggvis')
    )
  ))
}

library(knitr)
knit_print.foo = function(x, ...) {
  res = paste('> **This is a `foo` object**:', x)
  asis_output(res, meta = list(
    js  = system.file('www', 'shared', 'shiny.js',  package = 'shiny'),
    css = system.file('www', 'shared', 'shiny.css', package = 'shiny')
  ))
}

new_foo = function(x) structure(x, class = 'foo')
new_foo('hello')

str(knit_meta(clean = FALSE))

## List of 2
##  $ js : chr "/Users/yihui/R/shiny/www/shared/shiny.js"
##  $ css: chr ""
##  - attr(*, "knit_meta_id")= chr [1:2] "unnamed-chunk-9" "unnamed-chunk-9"

new_foo('world')

knit_print.bar = function(x, ...) {
  asis_output(x, meta = list(head = '<script>console.log("bar!")</script>'))
}
new_bar = function(x) structure(x, class = 'bar')
new_bar('> **hello** world!')

new_bar('> hello **world**!')

str(knit_meta())

## List of 6
##  $ js  : chr "/Users/yihui/R/shiny/www/shared/shiny.js"
##  $ css : chr ""
##  $ js  : chr "/Users/yihui/R/shiny/www/shared/shiny.js"
##  $ css : chr ""
##  $ head: chr "<script>console.log(\"bar!\")</script>"
##  $ head: chr "<script>console.log(\"bar!\")</script>"
##  - attr(*, "knit_meta_id")= chr [1:6] "unnamed-chunk-9" "unnamed-chunk-9" "unnamed-chunk-11" "unnamed-chunk-11" ...

str(knit_meta()) # empty now, because clean = TRUE by default

##  list()