track.rebuild: Rebuild database information for tracked objects

Description

Rebuild database information (the file map, and/or the object summary) for objects in an active tracking environment, or for saved objects in a tracking directory.

Usage

track.rebuild(pos = 1, envir = as.environment(pos), dir = NULL,
        fix = FALSE, level=c("missing", "all"), trust=c("unspecified", "environment", "db"),
        verbose=1, RDataSuffix=NULL, dryRun=TRUE, replace.wd=TRUE,
        use.file.times=TRUE)

Arguments

pos

The position of the environment to which the tracking database to rebuild is linked (for active tracking databases.

envir

The tracked environment for which to rebuild the tracking database (for active tracking databases.

dir

The directory where the tracking database is stored (for tracking databases not currently active.

fix

If TRUE, try to fix various problems such as illegal file names by renaming files or moving unusable RData files to a 'quarantine' directory. If fix=TRUE and dryRun=TRUE, changes will be reported but

level

If "missing", rebuild only missing information, if "all", rebuild information for all objects.

trust

When rebuilding an active tracking database, and there are conflicts between the data in the environment versus that in files, which should be trusted?

verbose

Controls number of messages about progress

RDataSuffix

What suffix should be used for RData files? (Usually worked out automatically.)

dryRun

If TRUE, no data objects in R or files on disk are changed: the return value is a list containing the rebuilt file map and the rebuilt object summary. If FALSE, objects in R environments and files on disk can be c

replace.wd

If TRUE, file paths in diagnostic output are printed starting with "./" where possible -- this makes comparisons of test output more portable.

use.file.times

If TRUE, file creation, modification and access times are used for objects that were not found in existing summary objects. If FALSE, the current time is used, which can be useful for testing purposes.

Value

The value returned is a list with between two and four components:
fileMapThe mapping from object names to files (excluding the suffix)
summaryThe dataframe that summarizes objects
unsaved(optional) The names of variables that are not saved to disk. This component is only present if it is non-empty.
masked(optinal) The names of tracked variables that are masked by other variables in the tracked environment. This component is only present if it is non-empty.
The returned value is invisible.

Details

The file map and/or the object summary are rebuilt. If level=="all", all RData files will be read, which could take a long time if there are many files. If level=="missing", RData files will be read only where there is missing information. If there are incompatible RData files in the directory (e.g., illegal or duplicated object names, or multiple objects), track.rebuild will stop with an error unless fix==TRUE, in which case the incompatible RData files will either be renamed or moved to a quarantine subdirectory. In the case of duplicated object names, the second object encountered will be moved.

Examples

Run this code

# Rebuild a damaged tracking database
library(track)
unlink("tmp1", recursive=TRUE)
# first build a tracking dir populated with some variables
track.start("tmp1")
x <- 33
X <- array(1:24, dim=2:4)
Y <- list(a=1:3,b=2)
X[2] <- -1
abc <- "def"
def <- list(1,2,3)
invisible(Y); invisible(abc); invisible(abc); invisible(abc)
track.summary()
track.stop(pos=1)
# damage the database (remove the filemap)
unlink("tmp1/filemap.txt")
# and rebuild
track.rebuild(dir="tmp1", verbose=2, dryRun=FALSE, fix=TRUE)
track.start("tmp1")
track.summary()
track.status()
track.stop(pos=1)
unlink("tmp1", recursive=TRUE)