myStartupUtilities {startupmsg} | 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 |
pkg |
a character string with the name of a single package |
library |
a character vector with path names of R libraries, or |
domain |
see |
type |
character – the type part of an S3-object of class |
SMHandler |
function to handle the output of an object of class |
endline |
logical: shall there be an empty line (TRUE) or a line with linestarter in the end? |
packageHelp |
logical: is there help available as |
MANUAL |
character or |
VIGNETTE |
character or |
... |
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 ... argumenta message of class
StartupMessage
and of type"information"
mentioning
-
?"}<pkg-name>\code{"
– according to argumentpackageHelp
, -
NEWS("}<pkg-name>\code{")
, if there is a ‘NEWS’ file, -
URL
, if there is aURL
mentioned in the ‘DESCRIPTION’ file, if there is a
MANUAL
argument, the file / the URL to this manualif 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 settingoptions("StartupBanner" = NULL)
oroptions("StartupBanner" = "complete")
the complete start-up banner is displayedfor any other value of option
"StartupBanner"
(i.e., not inc(NULL, "off", "complete")
) only the version information is displayedfrom 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
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
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)