S-PLUS help

Add to or View the Search List

DESCRIPTION:: Adds a directory or other object to the S-PLUS search list or returns the current search list.
The attach function is generic (see Methods); objects that the default method handles include directories, lists (and other recursive S-PLUS objects), compiled databases (see cdump) and user-defined databases (see dbread). In addition methods exists for objects of class: pframe and data.frame.

USAGE:

attach(what, ...)
attach.default(what = NULL, pos = 2, name = <<see below>>)
attach
search()

REQUIRED ARGUMENTS:

what:: a directory or S-PLUS object to attach onto the search list. what can be a (quoted) character string giving the name of a new data directory to be accessed; the name must be a correct UNIX file-system pathname, specifying an S-PLUS data directory. The (unquoted) name of an S-PLUS object (or any expression evaluating to an S-PLUS object) is also acceptable (the object must be a recursive object, such as a list or data frame). what may be a couple of other esoteric things, which are considered experimental now. A character string which is the name of an S-PLUS compiled database (see cdump) that is to be attached may also be given (the compiled database must be already loaded, dynamically or statically, into S-PLUS). If what has a class attribute and a dbobjects method for that class exists, then a user-defined database is attached. The initial list of objects for that database is the returned value of dbobjects(what), which should be either NULL or a character vector. See dbobjects or dbread for details.

OPTIONAL ARGUMENTS:

...:: some methods may have additional arguments.
pos:: position in the search list that what should occupy. The data directories originally in position pos or beyond are moved down the list after what. If pos=1, what will be attached as the working directory (you must have write permission).
name:: character string, the name on the search list to use for this object. If none is given, a name will be constructed out of the what argument.

VALUE:: attach returns NULL.
search returns the names of the search list.

SIDE EFFECTS:: attach changes the current search list by inserting what into position pos.
This is not an ordinary dataset, and is accessible only via the functions search and database.object. If errors occur during the top level expression containing the call to attach, the changes will be backed out and the previous search list re-installed. However, a call to synchronize commits the new search list. Errors after this will not back out changes occuring before the synchronize call.

DETAILS:

The search list of data directories is valid only for the current session with S-PLUS, i.e., it does not persist across S-PLUS sessions. Directories that do not contain S-PLUS objects should not be attached as S-PLUS data directories; ordinary ASCII data files should be read by, for instance, the scan function.

S-PLUS objects can be attached to the search list if they are recursive and all of their components have names. Uniqueness of the names is not enforced-only one component with a particular name will be used. It can be particularly useful to attach data frames.

Assignments to an attached object are allowed in any position, provided that you have write permission. The underlying object is not updated until the object itself is removed from the search list, either by using detach or by quitting S-PLUS. At this time, the revised object will be written back to the file from which it came at the time it was attached.

Note that using a tilde or an environmental variable to specify the first part of a path (e.g., ~cathy/.Data or $HOME/.Data) will not work with attach. These are shell constructs and attach does not use a shell to process the file names.

You may find it useful to put one or more calls to attach in your .First function to automatically attach directories or objects.

At the beginning of a session with S-PLUS, usually seven data directories are attached: the user's working directory, three system function directories and three system data directories. The working directory will be set via the S_WORK environment variable. By default, it uses the subdirectory .Data of the current directory; if that does not exist it will be .Data in your home directory; and if that does not exist, S-PLUS will create .Data in your home directory.

If you try to attach a (writable) directory that has a more restrictive naming scheme than the computer from which you are running S-PLUS, then you will get a warning that you may not be able to access all of the data that you write to that directory under the original name.

BUGS:: There is some ambiguity in determining what kind of database the what argument refers to. In the usual cases, a quoted string is used to denote a UNIX directory name and an unquoted name (or more general S-PLUS expression) denotes an S-PLUS object. If you have a compiled database called "foo" and a directory named "foo", then attach("foo") will attach the directory. If the what argument has a class attribute and a method of dbobjects for that class exists, then S-PLUS will attach that user-defined database instead of the directory or compiled database by the same name.

SEE ALSO:: attach.pframe , attach.data.frame , cdump , database.attr , database.type, dbobjects , dbread , detach , .First , ls , objects .

EXAMPLES:

attach("/usr/joe/.Data")  # attach Joe's data directory in position 2
attach("/usr/joe/.Data", pos = 1)
amp;# attach Joe's data directory as the working directory
attach(wafer) # attach a data frame
search()  # what is current search list?