library(section=<<see below>>, first=F, help=NULL, pos, lib.loc=<<see below>>, sep=<<see below>>, character.only=FALSE, dependencies = TRUE, warn.conflicts = TRUE) .First.lib(library=<<see below>>, section=<<see below>>) .Last.lib(library=<<see below>>, section=<<see below>>, .data=<<see below>>, where=<<see below>>)
lib.loc
(see below).
first=TRUE
, the
library
function attaches the data
directory for the library section before the system functions and
data, in position 2 of the search list. Otherwise, it attaches the
section near the end of the search list, just before library
"main"
. If you want more control
over exactly where the library is loaded, use the
pos
argument (see below). Some libraries may
move themselves (see details below)
help
function directly to see
documentation on particular objects in the section.
pos
or
beyond are moved down the list. The position can also be given as that
of an attached database, either by name or an object of class
"attached"
; the library section is then
inserted just above the specified database.
lib.loc
and there is an object on
database 0 named
lib.loc
, the
library
function uses that object for the
lib.loc
argument. You can initialize
lib.loc
from
getenv("S_LIBS")
to set the list of locations where
library sections (or packages) may be installed.
character.only
is
FALSE
(the default) then
library(mylib)
(without quotes) is equivalent to
library("mylib")
. If
character.only
is
TRUE
then
mylib
is expected to be the name of a variable containing a character string.
The same goes for the
help
argument.
section
is located (i.e., the element of
lib.loc
containing the library
section). This argument applies only to the
.First.lib
and
.Last.lib
functions.
library
. Typically, this is set to
".Data"
. This argument applies only to
the
.Last.lib
function.
.Last.lib
function.
library
function invisibly returns an object of class
"attached"
. If saved, this object can be
used for the duration of the S-PLUS session to refer to the attached
database. If you call
library
to see help on a section,
library
returns
NULL
. The
library
function will not attach the same library section twice.
library
either prints
documentation or attaches a data directory. If you give no arguments
to
library
, it prints a brief description
of each available section for each library in
lib.loc
. If you provide the
help
argument,
library
prints information on the
contents of the section specified by
help
. Otherwise,
library
attaches the data directory for
the section.
If the library section contains a
shared object file S.so,
the file is automatically loaded when the library is attached. Thus,
you no longer need to include any loading commands in
.First.lib
.
If the functions
.on.attach
and
.on.detach
exist in the library database,
they are called when the library database is attached and detached,
respectively.
The libraries that come standard with S-PLUS are:
chron
Functions to handle dates and times.
example5
Examples for S-PLUS 5.x and later.
examples
Examples from The New S
Language.
maps
Display of maps with projections.
missing
Model-based methods and multiple
imputation for missing data.
nlme2
Older mixed-effects models functions. Note that
library(nlme2)
is deprecated;
please use
library(nlme3)
instead.
robust
Cutting-edge robust model fitting
and outlier detection.
spjava
CONNECT/Java, an interface between
S-PLUS and Java.
The functions, data objects, and compiled code accessed by
library
are often user-contributed or
experimental and are not an official part of S-PLUS. You should use
them with caution.
The default library to use when calling
library
with no
lib.loc
argument is the library
subdirectory of the S-PLUS home directory. For example, if your S-PLUS
home directory is
/usr/splus,
the
examples
section corresponds to directory
/usr/splus/library/examples.
You can specify a list of libraries, some of them outside your S-PLUS
home directory, with the
lib.loc
argument.
You may want to assign your own default to
lib.loc
on database 0 in your
.First
function to make it easy to share
S-PLUS functions or data with coworkers. For example, including the command
assign(where=0, "lib.loc", "/users/project_1")
in
.First
tells
library
to search for library sections in the
directory /users/project_1 before searching $SHOME/library.
If a function named
.First.lib
exists in the
library section,
library
executes this
function whenever the library section is attached. The
.First.lib
function can be called with two
arguments: the name of the library directory (i.e., the element of
lib.loc
used for this library section) and
the name of the section. A typical use for
.First.lib
is to record information in the
session frame, such as the location of auxiliary data files required by
functions in the library.
If a function named
.Last.lib
exists in the
library section, it is executed when the library is detached or when S-PLUS
shuts down. Its first two arguments are the same as those of
.First.lib
. In addition, it accepts a
.data
argument which is generally equal to
".Data"
, the trailing component of the
directory attached by
library
. The
.Last.lib
argument also has a
where
argument to specify which position in
the search path the directory was attached.
The
.Last.lib
function is actually called
when any database is detached, not just those attached with the
library
function. Conversely,
.First.lib
is called only when using
library
.
Some libraries need to be loaded early in the search list to
work correctly, because they contain different versions of functions than
are otherwise used in S-PLUS. The usual practice is to
use
first=T
when loading the library to ensure this. Some libraries,
including the
bigdata
library, will even move themselves
if you do not load them early in the search list.
The function
.libPaths(new)
returns a vector of directory names,
and if
new
is supplied, it adds that directory
to the list of places to look for libraries when calling
library()
or
system.file()
. If the argument
new
is supplied then
.libPaths
has the side affect of modifying the value
of the variable
lib.loc
that is stored in database 0.
a S-PLUS library is structured in the manner described below. If you
create libraries for use with the
library
function, they must follow this model.
A library is a directory. This directory contains one or more subdirectories, each of which is a section of the library and must be a valid S-PLUS chapter. It must also contain a file named README which should have one-line descriptions of each of the sections of the library. Each section must include a subdirectory named .Data containing S-PLUS functions and data sets. The .Data directory must include a subdirectory __Meta containing meta information such as class and method definitions for use with S-PLUS 5.x and later.
If the library section contains help, there should be source SGML files
in the top-level section directory, and __Shelp and
__Hhelp directories under the .Data directory. See the
S-PLUS Programmer's Guide for complete details on creating and
installing help files. The
prompt
function
is useful for generating skeleton help files for your functions.
A section may contain source files, a make file, and a shared object or
DLL for any compiled code used by the functions in the data directory.
When source code is present in a section, there should also be a
makefile or Makefile that makes the required object
files. The utility CHAPTER is useful for generating a
makefile with targets that create a section of the appropriate
form for
library
; you must create your own
README
file for the section. See the
CHAPTER help file for more information on how to maintain the
directories this utility prepares.
# Print a list of sections. library() # Documentation on examples section. library(help="examples") # Attach examples data directory. library(examples) # See how .First.lib for the examples section works. .First.lib