symbDB and related methods described here
provide an implementation of S user-defined database classes, somewhat
more sophisticated and user-friendly than the dumpDataBase class.
That class simply wrote objects to files with the same name, which
inherently restricts the names of the objects. In this implementation
the database software maintains a separate file for the vector of
current object names.
This file produces a hash table (in the form of a string
vector) used to maintain a parallel table of the contents of the
database.
The position of a name in the string vector is encoded as the file
name.
To make this work easily over removals of objects, empty strings are
kept where objects are removed. The name for a first-time assignment replaces an
empty string or goes on the end of the string vector.
In directory databases, mostly from old tradition, S uses object names as file names when
these are legal and otherwise constructs a table of maps to true file
names.
In fact the strategy used here would work fine for directory databases
as well.
The symbDB class is a slightly more typical example than
its simpler counterpart, in that the code must
worry a little about the consistency of the explicit table in the string
object and the database dictionary kept by the evaluator manager.
Suppose an error takes place in writing a file, for example: what
happens to the two tables?
The implementation shown here does only a minimal amount of
bullet-proofing against such problems.
"database"
and to contain one slot, for the string path name of the corresponding directory.
setClass("symbDB",
representation("database", path = "character"))
"symbDB" =
## make an object of class `"symbDB"' corresponding to the directory
## `path'. The flag `create' allows or suppresses creating the directory if it
## does not exist (by default, the user is asked, if S is in interactive mode).
function(path,
create = identical(dialog(paste("Directory \"", path,
"\"for database does not exist; create?", sep=""), c("y", "n"), 2),1))
{
path = as(path, "character")
if(length(path)!=1) stop("needed a single character string for path")
if(!isDirectory(path)) {
if(create) {
shell(paste("mkdir", path), mustWork=T)
file = paste(path, "objects", sep="/")
cat("", file=file, sep="")
}
else
warning("Directory \"", path, "\"for database does not exist; path validity not checked")
}
if(isDirectory(path))
## get a fully-qualified path
path = shell(paste("cd", path, "; pwd"))
new("symbDB", path = path)
}
dbobjects: Listing the Object Names
For this particular database class, the sdbObjects utility function actually accesses
the information about current database contents, and returns the
appropriate character vector.
setMethod("dbobjects", "symbDB",
function(database)
{
ans = sdbObjects(database)
## may be empty strings corresponding to deleted objects
sort(ans[nchar(ans) > 0])
}
)
dbread: Read an
ObjectdataPut, this method just calls dataGet
to do the reading.
setMethod("dbread", "symbDB",
function(database, name)
{
path = sdbNameToFile(database, name)
if(nchar(path)==0)
stop("object \"", name, "\" not in database")
dataGet(path)
}
)
The check on path is not needed in normal usage, but it
is possible for dataGet to fail, for example if some
other process is concurrently using the same directory and removes the
object.
dbwrite: Write an
ObjectsdbNameToFile is called
to get the path for the corresponding file, and is told to create a
new path if one does not exist.
Once this is done, all that remains is to call the
dataPut function to write the object in standard symbolic
dump format to the corresponding file.
setMethod("dbwrite", "symbDB",
function(database, name, object) {
path = sdbNameToFile(database, name, T)
dataPut(object, path)
}
)
dbremove: Remove an
Objectname from the list of names in
the database, and removes the corresponding file containing the object
as dumped out.
The name is erased from the character vector supplied by sdbObjects; an empty string is
stored in its place, to allow the file name to be reused for a later
assignment.
The utility setSdbObjects stores the
revised vector of names both in the session and externally in the
directory.
The file identified by sdbNameToFile is also removed.
Notice that we have to get the file name before modifying the
session's view of what objects exist in the database.
setMethod("dbremove", "symbDB",
## removes the name from the list of objects, saves the updated list of objects,
## and then removes the corresponding file from the directory.
function(database, name) {
objects = sdbObjects(database)
i = match(name, objects)
if(is.na(i))
stop("bad call to dbremove method: \"",
name, "\" is not in this database")
file = sdbNameToFile(database, name)
if(i == length(objects))
length(objects) = i-1
else el(objects, i) = ""
sdbSetObjects(database, objects)
shell(paste("rm", file))
}
)