R: Utilities for start-up messages

StartupUtilities {startupmsg}

R Documentation

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)

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:

muffleMessage() to suppress the StartupMessage,
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:

suppressStartupMessages(expr) suppresses all messages issued by startupMessage in the expression expr within the parentheses
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)

Acknowledgement

Thanks to Seth Falcon for his helpful comments.

Author(s)

Peter Ruckdeschel peter.ruckdeschel@uni-oldenburg.de

Examples

## 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;
NEWS("stats") ## no NEWS file; 
## for packages with NEWS file see e.g. randomForest, distr

[Package startupmsg version 0.9.6.1 Index]