This is a convenience function designed for use within an rmarkdown
document. It overrides the knitr
output hooks by using
knitr::knit_hooks$set
. It replaces the hooks with ones that convert
Control Sequences into HTML. In addition to replacing the hook functions,
this will output a <STYLE> HTML block to stdout. These two actions are
side effects as a result of which R chunks in the rmarkdown
document that
contain CSI SGR are shown in their HTML equivalent form.
set_knit_hooks(
hooks,
which = "output",
proc.fun = function(x, class) html_code_block(to_html(html_esc(x)), class = class),
class = sprintf("fansi fansi-%s", which),
style = getOption("fansi.css", dflt_css()),
split.nl = FALSE,
.test = FALSE
)
named list with the prior output hooks for each of which
.
list, this should the be knitr::knit_hooks
object; we
require you pass this to avoid a run-time dependency on knitr
.
character vector with the names of the hooks that should be replaced, defaults to 'output', but can also contain values 'message', 'warning', and 'error'.
function that will be applied to output that contains
CSI SGR sequences. Should accept parameters x
and class
, where x
is
the output, and class
is the CSS class that should be applied to
the <PRE><CODE> blocks the output will be placed in.
character the CSS class to give the output chunks. Each type of
output chunk specified in which
will be matched position-wise to the
classes specified here. This vector should be the same length as which
.
character a vector of CSS styles; these will be output inside
HTML >STYLE< tags as a side effect. The default value is designed to
ensure that there is no visible gap in background color with lines with
height 1.5 (as is the default setting in rmarkdown
documents v1.1).
TRUE or FALSE (default), set to TRUE to split input strings
by any newlines they may contain to avoid any newlines inside SPAN tags
created by to_html()
. Some markdown->html renders can be configured
to convert embedded newlines into line breaks, which may lead to a doubling
of line breaks. With the default proc.fun
the split strings are
recombined by html_code_block()
, but if you provide your own proc.fun
you'll need to account for the possibility that the character vector it
receives will have a different number of elements than the chunk output.
This argument only has an effect if chunk output contains CSI SGR
sequences.
TRUE or FALSE, for internal testing use only.
The replacement hook function tests for the presence of CSI SGR
sequences in chunk output with has_ctl
, and if it is detected then
processes it with the user provided proc.fun
. Chunks that do not contain
CSI SGR are passed off to the previously set hook function. The default
proc.fun
will run the output through html_esc
, to_html
, and
finally html_code_block
.
If you require more control than this function provides you can set the
knitr
hooks manually with knitr::knit_hooks$set
. If you are seeing your
output gaining extra line breaks, look at the split.nl
option.
has_ctl
, to_html
, html_esc
, html_code_block
,
knitr
output hooks,
embedding CSS in Rmd,
and the vignette vignette(package='fansi', 'sgr-in-rmd')
.