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