1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/knitr.R
\name{knit_ex}
\alias{knit_ex}
\alias{hook_try}
\alias{hook_backspace}
\alias{hook_toggle}
\title{Knitr Extensions}
\usage{
knit_ex(x, ..., quiet = TRUE, open = FALSE)
hook_try(before, options, envir)
hook_backspace()
hook_toggle()
}
\arguments{
\item{x}{text to knit as a character vector}
\item{...}{arguments passed to \code{\link[knitr]{knit2html}} or \code{\link[knitr]{knit}}}
\item{quiet}{logical that indicates if knitting should be quiet (no progress bars etc..).}
\item{open}{logical, only used when \code{x} is in .Rmd format, that indicates
if the generated document result should be open in a browse, instead of
being printed on screen.
Not that a browser will not open in non-interactive sessions, and the result will
be returned invisibly.}
\item{before}{logical that indicates when the hook is being called:
before or after the chunk is processed.}
\item{options}{list of current knitr chunk options}
\item{envir}{environment where the chunk is evaluated}
}
\value{
\code{knit_ex} returns the generated code, although invisibly when \code{open=TRUE}.
\itemize{
\item \code{hook_try} returns a function.
}
\itemize{
\item \code{hook_backspace} returns a function.
}
\itemize{
\item \code{hook_toggle}: returns a hook function.
}
}
\description{
\code{knit_ex} is a utility function for running small knitr examples,
e.g., to illustrate functionalities or issues.
\code{hook_backspace} is a chunk hook that enables the use of backspace
characters in the output (e.g., as used in progress bars), and still
obtain a final output as in the console.
}
\section{Functions}{
\itemize{
\item \code{hook_try()}: is a knitr hook to enable showing error
messages thrown by \code{\link{try}}.
The function is not meant to be called directly, but only registered
using \link[knitr:knit_hooks]{knitr::knit_hooks} (see details on this dedicated man page).
This simply defines a function \code{try} in \code{envir} that prints
the error message if any, and is called instead of base \code{\link{try}}.
\item \code{hook_toggle()}: a chunk hook that adds clickable elements to toggle \emph{indvidual}
code chunks in HTML documents generated from .Rmd files.
}}
\examples{
library(knitr)
knit_ex("1 + 1")
library(knitr)
# standard error message is caught
knit_ex("stop('ah ah')")
# with try the error is output on stderr but not caughted by knitr
knit_ex("try( stop('ah ah') )")
\donttest{
# no message caught
knit_ex("
^^^{r, include = FALSE}
knit_hooks$set(try = pkgmaker::hook_try)
^^^
^^^{r, try=TRUE}
try( stop('ah ah') )
^^^")
}
\donttest{
# Correctly formatting backspaces in chunk outputs
tmp <- tempfile(fileext = '.Rmd')
cat(file = tmp, "
^^^{r, include = FALSE}
library(knitr)
knit_hooks$set(backspace = pkgmaker::hook_backspace())
^^^
Default knitr does not handle backspace and adds a special character:
^^^{r}
cat('abc\bd')
^^^
Using the hook backspace solves the issue:
^^^{r, backspace=TRUE}
cat('abc\bd')
^^^
")
# knit
out <- knitr::knit2html(tmp, template = FALSE)
}
# look at output
\dontrun{
browseURL(out)
edit( file = out)
}
\donttest{
# cleanup
out_files <- list.files(dirname(out), full.names = TRUE,
pattern = paste0("^", tools::file_path_sans_ext(out)))
unlink(c(tmp, out_files))
}
\donttest{
knit_ex("
Declare chunk hook:
^^^{r, setup}
library(knitr)
knit_hooks$set(toggle = hook_toggle())
^^^
The R code of this chunk can be toggled on/off, and starts visible:
^^^{r, toggle=TRUE}
print(1:10)
^^^
The R code of this chunk can be toggled on/off, and starts hidden:
^^^{r, toggle=FALSE}
print(1:10)
^^^
This is a plain chunk that cannot be toggled on/off:
^^^{r}
print(1:10)
^^^
Now all chunks can be toggled and start visible:
^^^{r, toggle_all}
opts_chunk$set(toggle = TRUE)
^^^
^^^{r}
sample(5)
^^^
To disable the toggle link, one can pass anything except TRUE/FALSE:
^^^{r, toggle = NA}
sample(5)
^^^
", open = FALSE)
}
}
|
