myStartupUtilities: Example functions to utilities for start-up messages
In startupmsg: Utilities for Start-Up Messages

myStartupUtilities

R Documentation

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)

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

a start-up message of condition StartupMessage with type "version" as to the version information.
additional messages of class StartupMessage and of type "notabene" according to the ... argument
a message of class StartupMessage and of type "information" mentioning
- ?"}<pkg-name>\code{" – according to argument packageHelp,
- 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:

options("StartupBanner" = "off") switches off all start-up messages
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
from pkg version 1.0.0 on, the default of this option value is "no-version" (respectively "no - version"), which suppresses version information to avoid unnecessary cascade of pkg submissions to CRAN triggered by startup messages showing changed version information of attached/loaded packages up-stream.

Also, from version 1.0.0 on, we show a hint on how to obtain version information of all attached packages, regardless of whether these use start-up messages managed by this packages; i.e.; through sessionInfo(). This hint is only shown once per session, but can also be switched on and off through options("StartupShowHint_sessionInfo") set to TRUE or FALSE, respectively.

Author(s)

Peter Ruckdeschel peter.ruckdeschel@uni-oldenburg.de

Examples

#----------------------------
### save old option values
( oldOptionStartupBanner <- getOption("StartupBanner") )
( oldOptionStartupShowHint_sessionInfo <- getOption("StartupShowHint_sessionInfo") )
###
#----------------------------


## a set of test messages

options("StartupBanner" = "complete")
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")

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")
###

#----------------------------
### options switching on and off hints and details of start-up messages
#----------------------------

buildStartupMessage(pkg = "stats", msg)

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

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

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

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

options("StartupBanner" = "no-version") ## default
buildStartupMessage(pkg = "stats", msg)

options("StartupBanner" = "no - version")
options("StartupShowHint_sessionInfo" = FALSE)
buildStartupMessage(pkg = "startupmsg", packageHelp = TRUE)

options("StartupBanner" = "no - version")
options("StartupShowHint_sessionInfo" = TRUE)
buildStartupMessage(pkg = "startupmsg", packageHelp = TRUE)

options("StartupBanner" = "no-version")
buildStartupMessage(pkg = "startupmsg", packageHelp = TRUE)

options("StartupBanner" = "complete")
buildStartupMessage(pkg = "startupmsg", packageHelp = TRUE)

## restore old values 
options("StartupBanner" = oldOptionStartupBanner)
options("StartupShowHint_sessionInfo" = oldOptionStartupShowHint_sessionInfo)
rm(oldOptionStartupBanner, oldOptionStartupShowHint_sessionInfo)

startupmsg documentation built on April 3, 2025, 10:37 p.m.