StartupUtilities: Utilities for start-up messages

Description

several utilities to produce start-up messages

Usage

readVersionInformation(pkg, library=NULL)
readURLInformation(pkg, library=NULL)
pointertoNEWS(pkg, library=NULL) 
infoShow(pkg, filename, library=NULL)
NEWS(pkg, library=NULL)
TOBEDONE(pkg, library=NULL)
StartupMessage(message, call = NULL, pkg="", 
               type="version", endline = FALSE) 
startupPackage(startupmessage) 
startupType(startupmessage) 
startupEndline(startupmessage) 
startupMessage(..., domain = NULL, pkg = "", 
               type="version", endline = FALSE)
suppressStartupMessages(expr)
onlytypeStartupMessages(expr,atypes="version")

Arguments

pkg: a character string with the name of a single package
library: a character vector with path names of R libraries, or NULL. The default value of NULL corresponds to all libraries currently known. If the default is used, the loaded packages are searched before the libraries
filename: name of the file which is to be displayed by infoShow (with relative path within the package main folder)
message: a character string -- the message part of an S3-object of class StartupMessage
call: a call expression -- the call part of an S3-object of class StartupMessage
type: character -- the type part of an S3-object of class StartupMessage; currently, type should be in c("version","notabene","information").
endline: a logical -- the decision on the ending of an S3-object of class StartupMessage
startupmessage: the StartupMessage object whose slot package is to be inspected
domain: see gettext. If NA, messages will not be translated.
atypes: a vector of characters -- the types of StartupMessage-objects which onlytypeStartupMessages lets pass through
expr: expression to evaluate.
...: character vectors (which are pasted together with no separator)

Acknowledgement

Thanks to Seth Falcon for his helpful comments.

Author

Peter Ruckdeschel peter.ruckdeschel@uni-oldenburg.de

Details

readVersionInformation and readURLInformation read the DESCRIPTION file of the package. readVersionInformation returns a list with elements ver and title for the version and title to be found in the DESCRIPTION file; if there is a URL entry it is returned by readURLInformation else readURLInformation returns NULL.

If there is a NEWS in the package main folder, pointertoNEWS returns a string with an expression how to retrieve this file from within R, else pointertoNEWS returns NULL.

infoShow displays the file filename in the package main folder using file.show -- if it exists; NEWS in particular displays the NEWS file, and analogously, TOBEDONE in particular displays the TOBEDONE file; takes up an idea by Andy Liaw.

A new sub-condition StartupMessage to message is introduced, with a constructor with the same name.

In addition to the slots of message, it also has slots package (for the package they are for), type (currently in c("version","notabene","information")), and endline (a logical). These slots may be accessed by startupPackage, startupType, and startupEndline, respectively.

startupMessage issues a start-up message which also is represented as a condition. While the start-up message is being processed, the following restarts are available:

onlytypeMessage(c0,atypes) to filter out types not mentioned in atypes of StartupMessages-argument c0,
custom(c,f) to apply the user-defined function f to StartupMessages-argument c0 instead of the usual procedure

The user may suppress the start-up messages produced by these utilities as follows:

suppressPackageStartupMessages(expr): from package version 0.5 on, is the same as suppressStartupMessages for our start-up banners, but more generally suppresses all messages of S3-class packageStartupMessage (from base package)
onlyversionStartupMessages(expr, atypes="version") only shows messages issued by startupMessage in the expression expr within the parentheses, if there slot type is contained in the atypes argument
by the custom restart (see example by Seth Falcon)

Examples

Run this code

## a set of test messages
several.messages<-function() {
startupMessage("this is a type 'version' startup message", pkg="PKG")
startupMessage("this is a type 'information' startup message", 
                pkg="PKG", type="information")
message("this is an ordinary message")}

## issuing of messages with different wrappers
several.messages()
suppressStartupMessages(several.messages())
suppressMessages(several.messages())
onlytypeStartupMessages(several.messages(),atypes=c("version","notabene"))

##Example by Seth Falcon:
## Here is a test function
doit <- function() {
    several.messages()
    return(123)
}

## Here is an example message handler.  Here, you could write messages
## to a file, send them as email to your friends or enemies, etc.
## For the example, we'll just prepend 'MSG:'
msgLogger <- function(m) {
             types<-paste("(", startupType(m),"):", sep="")
             cat(paste("MSG: ",types, conditionMessage(m)), "\n")
             }

## Finally, call the doit function and customize how messages are
## handled.
withCallingHandlers(doit(),
                    StartupMessage=function(m) {
                        invokeRestart("custom", m, msgLogger)
                    })
### reading information file utilities
readVersionInformation("stats")
readURLInformation("stats")
## for packages with URL file see e.g. dse1
pointertoNEWS("stats") ## no NEWS file;
## IGNORE_RDIFF_BEGIN
NEWS("stats") ## no NEWS file; 
## for packages with NEWS file see e.g. randomForest, distr
## IGNORE_RDIFF_END

Run the code above in your browser using DataLab