R-alpha: libraries

Thomas Lumley (thomas@biostat.washington.edu)
Sun, 2 Feb 1997 18:00:39 -0800 (PST)

Date: Sun, 2 Feb 1997 18:00:39 -0800 (PST)
From: Thomas Lumley <thomas@biostat.washington.edu>
To: r-testers@stat.math.ethz.ch
Subject: R-alpha: libraries
In-Reply-To: <199701221423.PAA08462@galadriel.ci.tuwien.ac.at>

At the end of this message is code for require(), a variant of library(). 
It differs in that it returns a boolean success/failure value and
optionally prints a warning, rather than stopping with an error, if the
library is unavailable.  This is designed for use inside other functions,
where it may be inappropriate to crash if a library is missing.  It has a
help file that also documents the library() command and related things.
The mixed capitalisation of TITLE in the help file is deliberate - R won't
let you use the word TITLE in a help file. 

Thomas Lumley
"require" <-function (name,quietly=FALSE) 
  if (missing(name)) return(TRUE);
  if (!exists(".Libraries", inherits = TRUE)) 
    assign(".Libraries", character(0), NULL)
    else {
      name <- substitute(name)
      if (!is.character(name)) 
	name <- deparse(name)
      if (is.na(match(name, .Libraries))) {
	file <- system.file("library", name)
	if (file == ""){ 
	  if (!quietly) warning(paste("Required library ", name," not found.\n"))
	if (!quietly) cat("Autoloading required library:",name"\n")
	assign(".Libraries", c(name, .Libraries), NULL)

----------------------help file---------------------

TITLE(library @@ Load libraries of user code. )
The name of a library. With no argument LANG(library) will print out a list of
available libraries.
With LANG(quietly=TRUE) a warning will not be printed if the library cannot be 
LANG(library) returns the list of loaded libraries; LANG(require) returns 
a boolean value indicating whether the required library is available.
LANG(library) and LANG(require) both load a library.  LANG(require) is designed 
for use inside other functions; it returns LANG(FALSE) and optionally gives a 
warning, rather than giving an error, if the library does not exist.  Both 
functions check and update the list of currently loaded libraries stored in 
LANG(.Libraries) and do not reload code that is already loaded. 
LANG(library.dynam("name")) loads the specified object file from
LANG(RHOME/lib) if it has not been loaded already. It is designed to be
used inside a library rather than at the command line. 
LANG(help(library(name))) prints a list of functions in library "name".
PARA BOLD(CREATING LIBRARIES) Libraries provide a mechanism for loading
optional code and its documentation as needed. Libraries are compiled and
installed from subdirectories of LANG(RHOME/src/library); LANG(eda) and
LANG(mva) are provided as examples.  
 A library consists of a subdirectory containing a LANG(TITLe) and
LANG(INDEX) file, and subdirectories LANG(funs), LANG(man), LANG(src) and
LANG(src-c).  The LANG(TiTLE) file contains a line giving the name of the
library and a brief description. LANG(INDEX) contains a line for each
sufficiently interesting function in the library, giving its name and a
description (functions such as print methods not usually called explicitly
might not be included). 
The LANG(funs) subdirectory contains R code files with names beginning
with lowercase letters. One of these files should use
LANG(library.dynam()) to load any necessary compiled code. 
Source and a Makefile for the compiled code is in LANG(src), and a pure
LANG(C) version of the source should be in LANG(src-c). In the common case
when all the source is in LANG(C) it may be convenient to make one of
these directories a symbolic link to t he other. The Makefile will be
passed various machine-dependent compile and link flags, examples of which
can be seen in the LANG(eda) library. 
The LANG(man) subdirectory should contain R help files for the functions
in the library. 
To install a library run LANG(make libs) in LANG(RHOME/src/library) and
then run LANG(etc/lib-installhelp) in LANG(RHOME). This will reinstall all
the libraries. 

r-testers mailing list -- For info or help, send "info" or "help",
To [un]subscribe, send "[un]subscribe"
(in the "body", not the subject !)  To: r-testers-request@stat.math.ethz.ch