Utilities for start-up messages

Description

several utilities to produce start-up messages

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
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

See Also

buildStartupMessage for some illustration; for the ideas taken up in this package, see mails "[Rd] Wishlist: 'quietly' argument for .onAttach() / .First.lib() " on r-devel by Brian Ripley, https://stat.ethz.ch/pipermail/r-devel/2006-April/037281.html, by Andy Liaw, https://stat.ethz.ch/pipermail/r-devel/2006-April/037286.html, by Seth Falcon, https://stat.ethz.ch/pipermail/r-devel/2006-April/037317.html, and again by Seth Falcon, https://stat.ethz.ch/pipermail/r-devel/2006-April/037367.html, and by the author, https://stat.ethz.ch/pipermail/r-devel/2006-April/037382.html

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
## 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

Want to suggest features or report bugs for rdrr.io? Use the GitHub issue tracker.