Attach a Chapter or Database to the Search List

DESCRIPTION:

Adds an S chapter or other object to the S-PLUS search list.

USAGE:

attach(what=NULL, pos = -1, name = "") 

OPTIONAL ARGUMENTS:

what
a character string giving a chapter directory or S-PLUS object to use as a database, usually an object of a database class (that is, a class including the virtual class database). If what is a chapter directory, the S chapter is attached. This can contain a database directory, documentation, class/method definitions, and/or an object library compiled from C or Fortran. This directory should have been prepared for use with S-PLUS using the CHAPTER utility. See the section Side Effects below for special actions taken when attaching a chapter. If what is a S-PLUS object, methods should exist for the fundamental database operations (see dbobjects). Class designers have complete freedom in defining these operations, as long as they provide consistent ways to perform the basic operations of getting, assigning, and removing named objects. It is also possible to attach ordinary S named lists, or S structures whose data vector is a named list. In this case, the named elements of the list become the objects in the attached database, with the same names they had in the list. Objects of class "data.frame" are frequently used in this way.

If what is omitted, attach creates and attached to the search list an empty table database that persists throughout the session, unless detached.
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 data (you must have write permission on the corresponding object or directory). If pos is a large number ( .Machine$integer.max is guaranteed big enough), the new database is attached at the end of the search path. The position can be given as that of an attached database, either by name or as an attached object; the new database is then inserted just in front of the specified database.
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:

the attached database, as an object of class "attached". This uniquely identifies the database. This is the best object to use to specify the database as the where argument to get, exists, etc. Only the attached value is guaranteed to identify the database correctly regardless of what other attach and detach operations have occurred. For directory databases, the value uses the file and file system serial identification. For all other databases, an identifier is constructed that is unique for all attachments. For example, attaching a list as a database on two occasions produces two distinct identifications.

ACTIONS ON ATTACHING:

If a chapter or database contains a function named .on.attach, this function will be called, with no arguments, immediately after attaching the database. If you're writing a chapter and need to do something when attaching it (such as calling library to ensure some S-PLUS library is available), write an .on.attach function to do this.

SIDE EFFECTS:

The internal search list maintained by the S-PLUS evaluator is modified to include the attached database. 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 occurring before the synchronize call.

If the object attached is the name of an S chapter, some additional side-effects occur. Object libraries are linked automatically to the S-PLUS session; that is, if the chapter included some compiled routines such as C functions, these will be automatically available for calling from S-PLUS. Assignments to an attached object are allowed in any position, provided you have write permission. The underlying object is not updated until the object itself is removed from the search list, either through detach or by quitting S-PLUS. At that time, the revised object is saved as an object with a default or specified name (or discarded), as determined by detach . The search list is valid only for the current S-PLUS session, that is, it does not persist from session to session.

INITIAL SEARCH LIST:

At the beginning of a S-PLUS session, the internal search list normally contains the working directory and libraries containing S-PLUS functions and data sets. The working directory is taken to be the current directory, if that appears to be a chapter and you have permission to write into the data directory there. If not, your home directory is tried. If both fail, S-PLUS tries to initialize the home directory as a chapter. Changes to the initial search list can be made by including calls to attach, library, module , and detach in the .S.init file in your home directory, or by specifying directories in your .S.chapters file.

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.

If you set options(report.assign.masking=T) then attach will warn when you attach a directory that contains objects with the same name as objects further back on the search list.

SEE ALSO:

, , , , , .

EXAMPLES:

attach("/usr/joe/testdata")  # attach Joe's testdata directory in position 2 
attach("/usr/joe/testdata", pos = 1)  
# attach Joe's testdata directory as the working directory 
attach(wafer) # attach a data frame