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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
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.

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

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

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.

Note

These functions check whether the binding in envir is an active binding, but they cannot check whether the active binding has the correct function associated with it because R provides no mechanism for R-level access to the function associated with active bindings.

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