Rebuild database information for tracked objects

Share:

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

1
2
3
4
5
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 not made.

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 changed. The default is TRUE to guard against changing things when it would have been better not to have changed things, but this default may change in future.

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.

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.

Value

The value returned is a list with between two and four components:

fileMap

The mapping from object names to files (excluding the suffix)

summary

The 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.

Author(s)

Tony Plate <tplate@acm.org>

See Also

Overview and design of the track package.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
##############################################################
# Warning: running this example will cause variables currently
# in the R global environment to be written to .RData files
# in a tracking database on the filesystem under R's temporary
# directory, and will cause the variables to be removed temporarily
# from the R global environment.
# It is recommended to run this example with a fresh R session
# with no important variables in the global environment.
##############################################################

# Rebuild a damaged tracking database
library(track)
# first build a tracking dir populated with some variables
track.start(dir=file.path(tempdir(), 'rdatadir7'))
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(file.path(tempdir(), 'rdatadir7', 'filemap.txt'))
# and rebuild
track.rebuild(dir=file.path(tempdir(), 'rdatadir7'), verbose=2, dryRun=FALSE, fix=TRUE)
track.start(file.path(tempdir(), 'rdatadir7'))
track.summary()
track.status()
# Would normally not call track.stop(), but do so here to clean up after
# running this example.
track.stop(pos=1, keepVars=TRUE)