R: Read chunks from an external script

read_chunk {knitr} | R Documentation

## 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 = readLines(path, warn = FALSE), labels = NULL, from = NULL,
        to = NULL, from.offset = 0L, to.offset = 0L)

    read_demo(topic, package = NULL, ...)

### Arguments

`path` | the path to the R script
`lines` | a character vector of the code lines (by default read from `path`)
`labels` | a character vector of chunk labels (default `NULL`)
`from, to` | a numeric vector specifying the starting/ending line numbers of code chunks, or a character vector; see Details
`from.offset, to.offset` | an offset to be added to `from`/`to`
`topic, package` | name of the demo and the package see `demo`
`...` | arguments to be passed to `read_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`.

### 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.

### Note

This function can only be used in a chunk which is not cached (chunk option `cache = FALSE`), and the code is read and stored in the current session without being executed (to actually run the code, you have to use a chunk with a corresponding label).

### Author(s)

Yihui Xie; the idea of the second approach came from Peter Ruckdeschel (author of the SweaveListingUtils package)

### References

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

### Examples

    ## 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

[Package knitr version 1.16 Index]