knitr (version 1.31)

read_chunk: Read chunks from an external script

Description

Chunks can be put in an external script, and this function reads chunks into the current knitr session; read_demo() is a convenience function to read a demo script from a package.

Usage

read_chunk(
  path,
  lines = read_utf8(path),
  labels = NULL,
  from = NULL,
  to = NULL,
  from.offset = 0L,
  to.offset = 0L,
  roxygen_comments = TRUE
)
read_demo(topic, package = NULL, ...)

Arguments

path

Path to the R script.

lines

Character vector of lines of code. By default, this is read from path.

labels

Character vector of chunk labels (default NULL).

from, to

Numeric vector specifying the starting/ending line numbers of code chunks, or a character vector; see Details.

from.offset, to.offset

Offsets to be added to from/to.

roxygen_comments

Logical dictating whether to keep trailing roxygen-style comments from code chunks in addition to whitespace

topic, package

Name of the demo and the package. See utils::demo.

...

Arguments passed to read_chunk.

Value

As a side effect, code chunks are read into the current session so that future chunks can (re)use the code by chunk label references. If an external chunk has the same label as a chunk in the current session, chunk label references by future chunks will refer to the external chunk.

Details

There are two approaches to read external code into the current session: (1) Use a special separator of the from ## ---- chunk-label (at least four dashes before the chunk label) in the script; (2) Manually specify the labels, starting and ending positions of code chunks in the script.

The second approach will be used only when labels is not NULL. For this approach, if from is NULL, the starting position is 1; if to is NULL, each of its element takes the next element of from minus 1, and the last element of to will be the length of lines (e.g. when from = c(1, 3, 8) and the script has 10 lines in total, to will be c(2, 7, 10)). Alternatively, from and to can be character vectors as regular expressions to specify the positions; when their length is 1, the single regular expression will be matched against the lines vector, otherwise each element of from/to is matched against lines and the match is supposed to be unique so that the numeric positions returned from grep() will be of the same length of from/to. Note labels always has to match the length of from and to.

References

https://yihui.org/knitr/demo/externalization/

Examples

# NOT RUN {
## put this in foo.R and read_chunk('foo.R')

## ---- my-label ----
1 + 1
lm(y ~ x, data = data.frame(x = 1:10, y = rnorm(10)))

## later you can use <<my-label>>= to reference this chunk

## the 2nd approach
code = c("#@a", "1+1", "#@b", "#@a", "rnorm(10)", "#@b")
read_chunk(lines = code, labels = "foo")  # put all code into one chunk named foo
read_chunk(lines = code, labels = "foo", from = 2, to = 2)  # line 2 into chunk foo
read_chunk(lines = code, labels = c("foo", "bar"), from = c(1, 4), to = c(3, 6))
# automatically figure out 'to'
read_chunk(lines = code, labels = c("foo", "bar"), from = c(1, 4))
read_chunk(lines = code, labels = c("foo", "bar"), from = "^#@a", to = "^#@b")
read_chunk(lines = code, labels = c("foo", "bar"), from = "^#@a", to = "^#@b", 
    from.offset = 1, to.offset = -1)

## later you can use, e.g., <<foo>>=
knitr::knit_code$get()  # use this to check chunks in the current session
knitr::knit_code$restore()  # clean up the session
# }