tracked_environment: An environment object that tracks changes made to its...
In robertzk/objectdiff: Objectdiff

Description Usage Arguments Details Note Examples

A typical R environment is like a mathematical set. It is a bag of stuff and not much else. A tracked environment is like such an environment that can also replay "changes" to its history.

1
2
3

tracked_environment(env = new.env(parent = emptyenv()), snapshot = 10)

env %$% name

`env`	environment. When converted to a `tracked_environment`, all changes will be remembered whenever a "commit" is registered on the environment. Commits can be named and labeled. The default is `new.env(parent = emptyenv())` (a new environment with no parent).
`snapshot`	integer. The interval at which to snapshot the environment. For example, if 100 commits have been made, and you would like to go back to commit 95, it would be very time-consuming to apply all the commits starting from the beginning. Instead a full copy of the environment will be made every `snapshot` commits.
`name`	character. When using the `%$%` infix operator, access a meta-datum from the `tracked_environment` (for example, "env", "reference", "ghost", "universe", "commits", or "snapshot").

To create a tracked environment from any environment e, simply write tracked_environment(e).

A tracked_environment is itself an environment that contains

env. The environment that is getting tracked.
reference. When the first commit is published, a full copy of the original environment gets saved so that it can be replayed during rollbacks. Any additional snapshots (i.e., full copies of the environment) will be appended to this list at the snapshot interval.
ghost. An environment that holds the "before" version of objects prior to committing a change. When a tracked_environment receives a commit, it will clear its ghost environment.
universe. Essentially just running base::ls (i.e., fetching the names of all objects in) the env before any changes occur. This is re-computed after a commit or rollback.
commits. A list of commits (a curated list of patches that represent the history of the tracked_environment).
snapshot. The integer number of commits to wait before recording a full copy of the environment for rollbacks and for peeking back to past commits.

From within the objectdiff package, it is possible to access these explicitly using the %$% operator, for example, some_tracked_env%$%commits.

e <- tracked_environment()
e$x <- 1
commit(e) <- 'First message'
e$x <- 2
commit(e) <- 'Second message'
stopifnot(identical(e$x, 2))
rollback(e) <- 1
stopifnot(identical(e$x, 1)) # The changes have been rolled back one step.

classical_env <- list2env(list(x = 1, y = 2))
e <- tracked_environment(classical_env, snapshot = 5)
# Any changes to e will record full snapshots of the environment
# every 5 commits. This way, when the environment is rolled back to an
# earlier commit, it will not have to apply patches starting from the
# very beginning.