Bind this R process to a history document

gptr_doc(path) binds every peter() call of this R process, at the console and in scripts, to a history document, and is your explicit consent that gptr writes agent blocks into it. Nothing is written until a block is recorded. gptr_doc(FALSE) removes the binding and gptr_doc() shows it. sync = TRUE writes the blocks that were recorded while the document could not be written: a Jupyter notebook that was open, or the deferred writes of an Rscript run that was killed.

Usage

gptr_doc(path = NULL, format = NULL, sync = FALSE)

Arguments

path

NULL to return the current binding, FALSE to remove it, or the path of an .R, .Rmd, .qmd or .ipynb document.

format

NULL (from the file extension) or the format of that extension: "r", "rmd", "qmd" or "ipynb"; "transcript" records console turns into an .R file as one steered session.

sync

TRUE applies the pending blocks of the document now.

Value

With path = NULL, the binding list(path, format) or NULL, visibly. Otherwise the previous binding, invisibly.

Details

Eligible top-level calls and pipe chains own document blocks; calls nested inside loops or functions do not. Binding supplies recording consent even when automatic recording is off, but .opts = list(record = FALSE) suppresses recording for that call. Binding does not reconstruct earlier unrecorded turns. A narrative summary or model-generated script draft needs review and execution checks before it can serve as a reproducible workflow.

Options

Options of history documents (?gptr_options collects every option): gptr.record (settings, "ask"): "auto" records into documents without asking, "off" prevents automatic recording; an explicit binding supplies consent. Also the settings key record, which a project can only tighten. A call's .opts = list(record = FALSE) opts out even when bound; .opts = list(record = TRUE) retains the usual consent checks. gptr.replay (settings, "auto"): the replay mode "auto", "replay", "live" or "record" (also the GPTR_REPLAY environment variable); a call's replay = argument wins. gptr.doc_output_lines (12): #> output lines recorded per execution. gptr.doc_source_frames (TRUE): FALSE stops gptr from reading source() frames to find calls in scripts sourced without srcrefs. gptr.spill_days (7): gptr_cache("prune") removes temporary files older than this.

Examples

f = tempfile(fileext = ".R")
writeLines("library(gptr)", f)
gptr_doc(f)
gptr_doc()
#> $path
#> [1] "/tmp/Rtmpu3CdAi/rel-site-1ffe1aa9095b/tmp/RtmpPpkUd4/file2008a6fedd8.R"
#> 
#> $format
#> [1] "r"
#> 
gptr_doc(FALSE)