Objects to manipulate options, patterns and hooks


The knitr package uses a special object to control options and settings (denoted as obj below); it has the following methods:

These objects are visible to users in knitr:

Except knit_patterns, all other objects are initialized with default values, and knit_patterns will be automatically determined according to the type of input document if not provided. The knit_hooks object is supposed to be used most frequently, and the other three are usually not to be used directly. For example, opts_chunk is usually set in the input document rather than using the command line directly.

Knitr’s settings must be set in a chunk before any chunks which rely on those settings to be active. It is recommended to create a knit configuration chunk as the first chunk in a script with cache = FALSE and include = FALSE options set. This chunk must not contain any commands which expect the settings in the configuration chunk to be in effect at the time of execution. The configuration chunk could look something like this:

<<setup, cache=FALSE, include=FALSE>>=
opts_knit$set(upload.fun = imgur_upload, self.contained = FALSE,
              root.dir = '~/R/project')

On a technical note, these objects are similar to closures – they consist of a list of functions returned by a function. For details, see the unexported function knitr:::new_defaults. The chunk options are also managed by closures.