attach(what=NULL, pos = -1, name = "")
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.
what
is omitted,
attach
creates and attached to the search list
an empty table database that persists throughout the session, unless detached.
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.
what
argument.
"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.
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.
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.
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.
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.
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