myStartupUtilities: Example functions to utilities for start-up messages

Description

Illustration of package 'startupmsg'

Usage

mySMHandler(c)
mystartupMessage(..., domain = NULL, pkg = "", type="version", 
                 SMHandler=mySMHandler, endline = FALSE)
buildStartupMessage(..., pkg, library=NULL, domain=NULL, 
                    packageHelp=FALSE, MANUAL = NULL, VIGNETTE = NULL,
                    SMHandler=mySMHandler)

Arguments

c: an object of class StartupMessage
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
domain: see gettext. If NA, messages will not be translated.
type: character -- the type part of an S3-object of class StartupMessage; currently, type should be in c("version","notabene","information").
SMHandler: function to handle the output of an object of class StartupMessage, defaults to mySMHandler; btw: SMHandler stands for /S/tartup/M/essage/Handler/
endline: logical: shall there be an empty line (TRUE) or a line with linestarter in the end?
packageHelp: logical: is there help available as ?<pkg-name> ?
MANUAL: character or NULL if !is.null(MANUAL) the name of a manual distributed together with the package (with relative path within the library) or an URL
VIGNETTE: character or NULL if !is.null(VIGNETTE) an indication of one or more vignettes available to this package
...: character vectors (which are pasted together with no separator)

Author

Peter Ruckdeschel peter.ruckdeschel@uni-oldenburg.de

Details

mystartupMessage redirects the output of startupMessage to have a particular output function SMHandler issue the message; to see how such a function may be defined, have a look at code of the default function mySMHandler:


mySMHandler <- function(c) {
    pkg <- startupPackage(c) # get the package slot of c
    #prefix a starter for each new line of the message:
    linestarterN <- paste(":",pkg,"> ", sep ="")                              
    linestarterN <- paste("\n",linestarter, sep ="")
    linestarterE <- paste(linestarterN,"$",sep="")
    writeLines(paste(linestarter, sub(linestarterE,"\n", 
               gsub("\n",linestarterN,conditionMessage(c))),
                    sep=""),stderr())}

Just like for startupMessage, for mystartupMessage, too, restarts muffleMessage(), onlytypeMessage(c0,atypes), custom(c,f) are available (confer startupmsg).

To generate a complete start-up message, we provide buildStartupMessage: this function automatically generates

additional messages of class StartupMessage and of type "notabene" according to the ... argument
a message of class StartupMessage and of type "information" mentioning
- NEWS("}<pkg-name>\code{"), if there is a NEWS file,
- URL, if there is a URL mentioned in the DESCRIPTION file,
- if there is a MANUAL argument, the file / the URL to this manual
- if there is a VIGNETTE argument, VIGNETTE is printed out indicating a vignette location

The user may suppress the start-up messages produced by buildStartupMessages in two ways: Either by suppressStartupMessages(expr) and onlyversionStartupMessages(expr, atypes="version") as for startupmessage (confer startupmsg), or -- as proposed by Brian Ripley -- by options; let us describe the latter possibility here:

if option "StartupBanner" is not defined (default) or setting options("StartupBanner"=NULL) or options("StartupBanner"="complete") the complete start-up banner is displayed
for any other value of option "StartupBanner" (i.e., not in c(NULL,"off","complete")) only the version information is displayed

Examples

Run this code

## a set of test messages

msg <- "Note that you may set global options by options() --- cf. ?\"options\"."

## issuing of messages controlled by options()
buildStartupMessage(pkg="stats", msg) 
suppressStartupMessages(buildStartupMessage(pkg="stats", msg) )
suppressMessages(buildStartupMessage(pkg="stats", msg))
onlytypeStartupMessages(buildStartupMessage(pkg="stats", msg),
          atypes="version")

getOption("StartupBanner")
buildStartupMessage(pkg="stats", msg)

options("StartupBanner"="off");getOption("StartupBanner")
buildStartupMessage(pkg="stats", msg)

options("StartupBanner"="complete");getOption("StartupBanner")
buildStartupMessage(pkg="stats", msg)

options("StartupBanner"="something else");getOption("StartupBanner")
buildStartupMessage(pkg="stats", msg)

options("StartupBanner"=NULL);getOption("StartupBanner")
buildStartupMessage(pkg="stats", msg)


MNH <- "https://www.r-project.org/"
buildStartupMessage(pkg="stats", msg, packageHelp=TRUE, MANUAL=MNH)
## not quite a manual, but to illustrate the principle:
## "demo/nlm.R" as a "manual": to be system-independent the 
## first call is to be preferred 
buildStartupMessage(pkg="stats", msg, packageHelp=TRUE, MANUAL=c("demo","nlm.R"))
###  works, too, (i.e. is equivalent) under Linux and Windows (at least):
buildStartupMessage(pkg="stats", msg, packageHelp=TRUE, MANUAL="demo/nlm.R")