get(name, where=<<see below>>, ...)
get.default(name, where=<<see below>>, frame=<<see below>>,
      mode="any", inherit=F, immediate=F)
exists(name, where=<<see below>>, ...)
exists.default(name, where=<<see below>>, frame=<<see below>>,
      mode="any", inherit=F)

name:

character string giving the name of the object.

where:

database from which the object should come. If where is supplied, it can either be a number or an object defining a database. A number implies the corresponding element of the search list, so where=2, for example, gets an object from the second database in the search list. If where is a character string, this is taken as the path name for a directory in the file system which needs not be on the search list. Otherwise, where is interpreted as a database, of any type. This database is accessed, but it is not put on the search list. The object is obtained from the accessed database. Normally, the accessed database is retained for the duration of the current top-level S-PLUS expression, to make repeated explicit access efficient, but see the argument immediate for overriding this.

frame:

which of the current frames in the evaluation should be searched? Frame 0 is a legal argument, meaning to look in the session database, which contains those objects created by assign with frame=0.

It is an error to supply both where and frame.

mode:

character string giving the mode wanted for the object. The default, "any", means that any mode is acceptable.

inherit:

logical flag to cause searching of parent frames. Normally, only the current frame, global frames, and databases are searched for an object. If inherit=TRUE, the parent frame of the current frame, its parent frame, and all further ancestors will also be searched. This is ignored if either where or frame is given.

immediate:

logical flag; if TRUE, access the database named in where only for the immediate request. Do not retain it for future use in the same top-level expression. This is efficient if many objects are to be read once in one top-level expression, in that no space for the objects needs to be set aside in the top-level frame (where it would stay throughout the expression). (See the last example below.) The immediate argument is not meaningful if frame has been specified, since access to frames in the evaluator is always immediate.

exists returns TRUE or FALSE according to whether the search succeeds.

If both where and frame are omitted, the search is done as if name were an ordinary name in an expression. That is, the search is first in the local data frame, then in frame 1, then the session frame, and then in each of the permanent directories in the search list.

If where is an explicit database rather than a position in the search list, and if the type of the database is known, an alternative is to call the appropriate dbread method directly. Most commonly, this will be a call to dbread.default() for access to a standard S-PLUS directory of binary-object files. The advantage of dbread in this case is that the entire database need not be attached, so the directory need not be read in.

Finding an object with exists that fails the mode test returns FALSE and produces a warning message if the search otherwise succeeds. Finding a file name that does not contain an S-PLUS object produces a warning message and returns FALSE.

You can not use get("a$b") to get the b component of object a; rather this will attempt to get an object named "a$b". Use get("a")$b to get the b component of a.

The use of get with a path name is a more efficient way to get a few objects from a known directory than using attach.

get("[[") # get or print an object of a non-standard name
get("abc", mode="function") # get abc, but only if it is a function
joe.x <- get("x", w="/usr/joe/.Data") # get joe's version of x
if(!exists("my.init", frame=0)) # look only in session database
        do.initialize()

# arrange to read a lot of objects from two databases, and check for
# equality, without cluttering up the top-level expression.  Calling
# do.compare in a loop works better than doing the get's at top level

do.compare <- function(name,i,j) all.equal(get(name, w=i, immediate=T),
                get(name, w=j, immediate=T))