Shared Functions and Data Sets

DESCRIPTION:

Attaches a section of a S-PLUS library. A library section is a way of packaging a collection of S-PLUS functions, data sets, documentation, and compiled code.

USAGE:

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>>) 

OPTIONAL ARGUMENTS:

section
a character string or name giving the name of the section of the library. The section must be a valid S-PLUS chapter. If omitted, S-PLUS returns a help message describing the libraries in lib.loc (see below).
first
a logical flag. If 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
a character string or name of a section on which help is desired. In most cases, this gives a list of objects in the section with brief descriptions. Once you attach a section, you can use the help function directly to see documentation on particular objects in the section.
pos
the position in the search list the library section should occupy. The databases originally in position 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
a character vector containing the names of library directories. If you do not include the directory $SHOME/library here, S-PLUS appends it to the list. If you omit 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
a logical value. If 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.
sep
a character string giving the directory separator for the platform the library section runs on. For example, by default this is equal to "\\" on most Windows machines, but can also be set to "/".
library
a character string or name giving the name of the library where 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.
.data
a character string naming the trailing component of the directory attached to the search path by library. Typically, this is set to ".Data". This argument applies only to the .Last.lib function.
where
the position in the search path where the library was attached. This argument applies only to the .Last.lib function.
dependencies
if TRUE (the default), then packages required by the package you are loading are loaded before the requested package is loaded. (This is done recursively.) If FALSE, the required packages are not loaded. In this case, expect errors running the code in the library. (The required packages are listed in the'Depends:' line of the DESCRIPTION file for the package.)
warn.conflicts
added for R compatibility. This argument does nothing.

VALUE:

The 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.

SIDE EFFECTS:

In most situations, 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.

DETAILS:

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.

BACKGROUND:

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.

SEE ALSO:

, , , , , , .

EXAMPLES:

# 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