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

track.status:returns a data.frame if what=="all", or a character vector otherwise.
track.dir:returns a single character string that is the full path to the directory where copies of objects are stored (the "tracking directory").
tracked, untracked, track.orphaned, track.masked, untrackable, track.unsaved:all return a character vector naming the variables with a particular status.

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 inenvirwhich 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: rllll{ 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 } The arguments expr, list, pattern, and glob all serve to restrict the set of variables considered.

Examples

Run this code

library(track)
unlink("tmp1", recursive=TRUE)
remove(list=ls(all=TRUE))
track.start("tmp1", cache=TRUE)
x1 <- 123
x2 <- 456
x3 <- 789
track.status()
rm(x3)
track.status()
track.stop(pos=1)
unlink("tmp1", recursive=TRUE)