1% Generated by roxygen2: do not edit by hand
2% Please edit documentation in R/parser.R
3\name{read_chunk}
4\alias{read_chunk}
5\alias{read_demo}
6\title{Read chunks from an external script}
7\usage{
8read_chunk(
9  path,
10  lines = read_utf8(path),
11  labels = NULL,
12  from = NULL,
13  to = NULL,
14  from.offset = 0L,
15  to.offset = 0L,
16  roxygen_comments = TRUE
17)
18
19read_demo(topic, package = NULL, ...)
20}
21\arguments{
22\item{path}{Path to the R script.}
23
24\item{lines}{Character vector of lines of code. By default, this is read from
25\code{path}.}
26
27\item{labels}{Character vector of chunk labels (default \code{NULL}).}
28
29\item{from, to}{Numeric vector specifying the starting/ending line numbers of
30code chunks, or a character vector; see Details.}
31
32\item{from.offset, to.offset}{Offsets to be added to \code{from}/\code{to}.}
33
34\item{roxygen_comments}{Logical dictating whether to keep trailing
35roxygen-style comments from code chunks in addition to whitespace}
36
37\item{topic, package}{Name of the demo and the package. See
38\code{utils::\link{demo}}.}
39
40\item{...}{Arguments passed to \code{\link{read_chunk}}.}
41}
42\value{
43As a side effect, code chunks are read into the current session so
44  that future chunks can (re)use the code by chunk label references. If an
45  external chunk has the same label as a chunk in the current session, chunk
46  label references by future chunks will refer to the external chunk.
47}
48\description{
49Chunks can be put in an external script, and this function reads chunks into
50the current \pkg{knitr} session; \code{read_demo()} is a convenience function
51to read a demo script from a package.
52}
53\details{
54There are two approaches to read external code into the current session: (1)
55Use a special separator of the from \code{## ---- chunk-label} (at least four
56dashes before the chunk label) in the script; (2) Manually specify the
57labels, starting and ending positions of code chunks in the script.
58
59The second approach will be used only when \code{labels} is not \code{NULL}.
60For this approach, if \code{from} is \code{NULL}, the starting position is 1;
61if \code{to} is \code{NULL}, each of its element takes the next element of
62\code{from} minus 1, and the last element of \code{to} will be the length of
63\code{lines} (e.g. when \code{from = c(1, 3, 8)} and the script has 10 lines
64in total, \code{to} will be \code{c(2, 7, 10)}). Alternatively, \code{from}
65and \code{to} can be character vectors as regular expressions to specify the
66positions; when their length is 1, the single regular expression will be
67matched against the \code{lines} vector, otherwise each element of
68\code{from}/\code{to} is matched against \code{lines} and the match is
69supposed to be unique so that the numeric positions returned from
70\code{grep()} will be of the same length of \code{from}/\code{to}. Note
71\code{labels} always has to match the length of \code{from} and \code{to}.
72}
73\note{
74This function can only be used in a chunk which is \emph{not} cached
75  (chunk option \code{cache = FALSE}), and the code is read and stored in the
76  current session \emph{without} being executed (to actually run the code,
77  you have to use a chunk with a corresponding label).
78}
79\examples{
80## put this in foo.R and read_chunk('foo.R')
81
82## ---- my-label ----
831 + 1
84lm(y ~ x, data = data.frame(x = 1:10, y = rnorm(10)))
85
86## later you can use <<my-label>>= to reference this chunk
87
88## the 2nd approach
89code = c("#@a", "1+1", "#@b", "#@a", "rnorm(10)", "#@b")
90read_chunk(lines = code, labels = "foo")  # put all code into one chunk named foo
91read_chunk(lines = code, labels = "foo", from = 2, to = 2)  # line 2 into chunk foo
92read_chunk(lines = code, labels = c("foo", "bar"), from = c(1, 4), to = c(3, 6))
93# automatically figure out 'to'
94read_chunk(lines = code, labels = c("foo", "bar"), from = c(1, 4))
95read_chunk(lines = code, labels = c("foo", "bar"), from = "^#@a", to = "^#@b")
96read_chunk(lines = code, labels = c("foo", "bar"), from = "^#@a", to = "^#@b",
97    from.offset = 1, to.offset = -1)
98
99## later you can use, e.g., <<foo>>=
100knitr::knit_code$get()  # use this to check chunks in the current session
101knitr::knit_code$restore()  # clean up the session
102}
103\references{
104\url{https://yihui.org/knitr/demo/externalization/}
105}
106\author{
107Yihui Xie; the idea of the second approach came from Peter
108  Ruckdeschel (author of the \pkg{SweaveListingUtils} package)
109}
110