myStartupUtilities

0th

Percentile

Example functions to utilities for start-up messages

Illustration of package 'startupmsg'

Keywords
utilities
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

  • 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

See Also

Mail "[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

Aliases
  • mystartupMessage
  • mySMHandler
  • buildStartupMessage
Examples
# NOT RUN {
## 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")

# }
Documentation reproduced from package startupmsg, version 0.9.6, License: LGPL-3

Community examples

Looks like there are no examples yet.