track.status: Return information about the status of tracking

Description

Return information about the status of tracking in a particular environment. Functions tell which variables are and which are not tracked, and whether objects exist in memory or in files.

Usage

track.status(pos = 1, envir = as.environment(pos), expr, qexpr = NULL, list = NULL, pattern = NULL, glob = NULL, file.status = TRUE, tracked = NA, reserved = FALSE, all.names = FALSE, what = c("all", "tracked", "trackable", "untracked", "orphaned", "masked", "unsaved", "untrackable"))
tracked(        pos=1, envir=as.environment(pos), list=NULL, pattern=NULL, glob=NULL, all.names = TRUE)
untracked(      pos=1, envir=as.environment(pos), list=NULL, pattern=NULL, glob=NULL, all.names = TRUE)
track.orphaned( pos=1, envir=as.environment(pos), list=NULL, pattern=NULL, glob=NULL, all.names = TRUE)
track.masked(   pos=1, envir=as.environment(pos), list=NULL, pattern=NULL, glob=NULL, all.names = TRUE)
untrackable(    pos=1, envir=as.environment(pos), list=NULL, pattern=NULL, glob=NULL, all.names = TRUE)
track.unsaved(  pos=1, envir=as.environment(pos), list=NULL, pattern=NULL, glob=NULL, all.names = TRUE)

Arguments

pos

The search path position of the environment being tracked (default is 1 for the global environment)

envir

The environment being tracked. This is an alternate way (to the use of pos=) of specifying the environment being tracked, but should be rarely needed.

expr

An unquoted variable name

qexpr

A variable name as an expression -- not intended for use by end-users

list

A character vector of variable names

pattern

A regular expression specifying variable names to operate upon

glob

A glob pattern specifying variable names to operate upon

file.status

Check whether or not the file associated with a tracked object exists

tracked

If TRUE, return information only on tracked objects, if FALSE, return information only on objects that are not tracked, and if NA return information on all variables (subject to other filtering).

all.names

should names beginning with a period be included (like all.names in ls)

what

controls the information returned: "all" means return a data frame of status, other values means return a list of names of objects having that status

reserved

If TRUE, include info about non-tracked variables with reserved names. The default is to always omit these variables from the status summary.

Value

Details

These functions return information about the status of tracking on some or all variables in envir and the tracking environment. Tracking status depends on the relationship among four entities used for a tracked object:

the name of the object
the binding in envir which should be an active binding that refers to the tracking environment
the cached object in the tracking environment (i.e., stored in memory in R)
the corresponding disk file in the tracking directory

Statuses are defined as follows:

Status	object name	variable	cached object
file	tracked	ordinary	active binding
maybe	yes, maybe up-to-date	untrackable	reserved name
ordinary	no	no	untracked
ordinary	ordinary	no	no
masked	ordinary	ordinary	yes
maybe	orphaned	ordinary	none
yes	maybe	unsaved	ordinary
active binding	yes	not up-to-date	Status

The arguments expr, list, pattern, and glob all serve to restrict the set of variables considered.

Examples

Run this code

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

library(track)
track.start(dir=file.path(tempdir(), 'rdatadir10'))
x1 <- 123
x2 <- 456
x3 <- 789
track.status()
rm(x3)
track.status()
# Would normally not call track.stop(), but do so here to clean up after
# running this example.
track.stop(pos=1, keepVars=1)