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"))
	  return(FALSE)
	}
	if (!quietly) cat("Autoloading required library:",name"\n")
	sys.source(file)
	assign(".Libraries", c(name, .Libraries), NULL)
      }
      return(TRUE)
    }
}

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

TITLE(library @@ Load libraries of user code. )
USAGE(
library(name)
require(name,quietly=FALSE)
.Libraries
library.dynam("name.so")
)
ALIAS(require)
ALIAS(library.dynam)
ALIAS(.Libraries)
ARGUMENTS(
ARG(name@@)
The name of a library. With no argument LANG(library) will print out a list of
available libraries.
ARG(quietly@@)
With LANG(quietly=TRUE) a warning will not be printed if the library cannot be 
found.
)
PARA BOLD(VALUE)
LANG(library) returns the list of loaded libraries; LANG(require) returns 
a boolean value indicating whether the required library is available.
PARA BOLD(DESCRIPTION)
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. 
PARA
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. 
PARA
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.  
PARA
 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). 
PARA
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. 
PARA
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. 
PARA
The LANG(man) subdirectory should contain R help files for the functions
in the library. 
PARA
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. 
EXAMPLES(
library(eda)
require(eda)
require(nonexistent)
)




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