Source a history document, regenerating stale blocks without running the old code

Evaluates file top-level expression by expression in envir, like source() with keep.source = TRUE. A peter() call whose block is fresh replays without calling a model and the block's code then runs as ordinary R. A call whose block is stale (its prompt or the values interpolated into it changed), or every call under replay = "live", asks the model again and rewrites its block in place, and the old block is skipped, which base source() cannot do.

Usage

gptr_source(
  file,
  replay = getOption("gptr.replay", "auto"),
  envir = parent.frame(),
  echo = FALSE
)

Arguments

file

Path of an .R document.

replay

Replay mode for the calls in the file: "auto", "replay", "live" or "record". A call's own replay = argument wins. Left missing, each call resolves its mode as peter() does: the gptr.replay option, then the GPTR_REPLAY environment variable, then the replay setting, then "auto".

envir

Environment in which the expressions are evaluated.

echo

TRUE prints each expression before it is evaluated.

Value

Invisibly, the gptr_blocks listing of the file after the run with an extra column action: replayed, regenerated, ran, skipped, or NA for blocks no call touched. A stale block whose call ran but could not be rewritten (for example without write consent) is ran and keeps its status.

Details

Replay executes the recorded R code, including its ordinary side effects. It does not freeze package versions, supply external inputs or validate the analysis. This function accepts .R scripts; render .Rmd and .qmd with their report tools, and execute .ipynb through its R kernel. Use gptr_blocks() to inspect any supported format.

Examples

f = tempfile(fileext = ".R")
writeLines(c("x = 1", "y = x + 1"), f)
gptr_source(f, replay = "replay", envir = new.env())