Skip to contents

Unpack a package call into a self-contained, self-verifying replay script

Source: R/unpack_call.R
unpack_call.Rd

Runs the call once, captures its inputs and result, extracts the source of the executed function and its same-package helpers, and writes a replay project:

Usage

unpack_call(
  expr,
  output_dir,
  max_depth = 5L,
  overwrite = FALSE,
  dispatch = c("candidates", "static"),
  eval_dispatch = TRUE
)

Arguments

expr

An unevaluated function call, written as you would normally run it, e.g. predict(fit, newdata = recent_data) or stats::fivenum(x). For S3 generics the dispatch argument can be evaluated once to determine the method, controlled by eval_dispatch.

output_dir

Directory to create the replay project in.

max_depth

Maximum depth to follow same-package internal helpers.

overwrite

Overwrite an existing non-empty output_dir?

dispatch

How unresolved internal S3 dispatch is handled. The default, "candidates", extracts package-internal candidate methods for runtime dispatch; "static" retains static-only extraction.

eval_dispatch

Should a computed (call-shaped) dispatch argument be evaluated once to resolve the S3/S4 method? The default TRUE gives accurate method resolution but executes that piece of your code; the printed output says so whenever it happens. Set FALSE to leave computed dispatch unresolved and analyze the generic itself. Bare symbols are still inspected to resolve dispatch and may force a promise binding; literals are inspected directly.

Value

Invisibly, a insider_unpack object describing what was written.

Details

output_dir/
  replay.R            self-contained script: documented functions,
                      input loading, the reproducing call, and a
                      verification block
  customize.R         hand-editable copy of the extracted function sources
  compare.R           placeholder comparison script using customize.R
  data/*.rds          captured inputs and the original result
  insider_manifest.rds machine-readable unpack metadata

Running source("replay.R") from output_dir re-executes the call using the extracted functions and checks the result against the stored original (and, when the package is installed, against a live package call). The script header records provenance (package, version, source repository) and the findings of a static security scan of the extracted code.

Hidden state the resolved target silently depends on is captured before its invocation and stored in data/hidden_state.rds. When method dispatch evaluates a computed argument, the snapshot includes those effects because replay loads the captured dispatch value instead of evaluating it again. Behavior-changing options (contrasts, na.action) are always captured and restored by the script; the RNG state (RNGkind() and .Random.seed) is captured and restored when the extracted call path uses random-number functions. The script header lists what was restored, what is reported only (locale, timezone), and what could not be captured.

Examples

x <- c(1, 3, 5, 7, 100)
dir <- file.path(tempdir(), "fivenum_replay")
unpack_call(stats::fivenum(x), output_dir = dir, overwrite = TRUE)
#> 
#> ── insideR unpack ──────────────────────────────────────────────────────────────
#> Call: `stats::fivenum(x = x)`
#> Replay project written to /tmp/Rtmpvw2GbA/fivenum_replay
#> • Script: /tmp/Rtmpvw2GbA/fivenum_replay/replay.R
#> • Extracted function: `fivenum()`
#> • Captured input: "x"
#> • Replay status: full
#> • Security scan: no risky calls detected
#> Run it with: `setwd("/tmp/Rtmpvw2GbA/fivenum_replay"); source("replay.R")`