R devel - Apr 2006 - Wishlist: 'quietly' argument for .onAttach() / .First.lib()

Hi R-devels,

in "Writing R extensions" as well as in the help
to .onAttach(), you mention that one could
use this function to issue a start-up message/banner
for the package.

My little wish for Easter:

a 'quietly'-type argument for .onAttach() / .First.lib()
which is passed through by functions
require() and library() respectively,
and by means of which one could optionally
suppress this start-up message/banner .

Is this hard to do?

Thank you already
Peter

On Thu, 13 Apr 2006, Peter Ruckdeschel wrote:
> Hi R-devels,
>
> in "Writing R extensions" as well as in the help
> to .onAttach(), you mention that one could
> use this function to issue a start-up message/banner
> for the package.
>
> My little wish for Easter:
>
> a 'quietly'-type argument for .onAttach() / .First.lib()
> which is passed through by functions
> require() and library() respectively,
> and by means of which one could optionally
> suppress this start-up message/banner .
>
> Is this hard to do?
I believe so (and think we have been here before).  The documented call 
sequence is

      .onLoad(libname, pkgname)
      .onAttach(libname, pkgname)

the same as .First.lib.  There is no way to add an argument here, as many 
existing packages do not support it.  Beyond that, how would you pass the 
argument in?  Namespaces and packages are often loaded/attached implicitly 
as a result of loading other packages.

I did think you could make use of an option to decide whether to the print 
the message or not, but I have always assumed that those who did want a 
banner probably did not want it suppressed.

-- 
Brian D. Ripley,                  ripley at stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595

Andy Liaw wrote:
> From: Prof Brian Ripley
> >/ 
> />/ On Thu, 13 Apr 2006, Peter Ruckdeschel wrote:
> />/ 
> />/ > Hi R-devels,
> />/ >
> />/ > in "Writing R extensions" as well as in the help
> />/ > to .onAttach(), you mention that one could
> />/ > use this function to issue a start-up message/banner
> />/ > for the package.
> />/ >
> />/ > My little wish for Easter:
> />/ >
> />/ > a 'quietly'-type argument for .onAttach() /
.First.lib() which is
> />/ > passed through by functions
> />/ > require() and library() respectively,
> />/ > and by means of which one could optionally
> />/ > suppress this start-up message/banner .
> />/ >
> />/ > Is this hard to do?
> />/ 
> />/ I believe so (and think we have been here before). /
sorry, but I did not find anything on it ---
probably I searched for the wrong keywords.
> /> The //documented call //sequence is
> />/ 
> />/       .onLoad(libname, pkgname)
> />/       .onAttach(libname, pkgname)
> />/ 
> />/ the same as .First.lib.  There is no way to add an argument 
> />/ here, as many //existing packages do not support it.  
> /
Couldn't a reasonable default value (probably FALSE ) catch
this?
> /> Beyond that, how would / /you pass the 
> />/ argument in?  Namespaces and packages are often 
> />/ loaded/attached implicitly //as a result of loading other packages.
> /
oK this is an issue --- no idea for this.
> >/ I did think you could make use of an option to decide whether 
> />/ to the print //the message or not, 
> /
This is probably the cleanest solution.
> /> but I have always assumed that those who 
> />/ did want a //banner probably did not want it suppressed.
> /
> That certainly is the case with randomForest, speaking for myself
> here.  The banner I put in contains the version number of the 
> package and a reminder to see what's been changed/fixed.  I have 
> not seen a compelling reason why suppressing such information is 
> necessary (as opposed to "desirable").  I believe reporting 
> version number upon startup is a Good Thing, as all too often 
> people ask questions or report problems about packages without
> mentioning the version of the packages they used.  I see this as
> a way of reminding the users.
>   
I completely agree as to package version information
and pointers to NEWS / more information on the package.

My wish is motivated by something else ---  call it
 
           /"scalable start-up message"/

In a discussion with Martin Maechler, he proposed to alert/warn
the user in some prominent place about the interpretation of
arithmetics operating on distributions in our package "distr".

I have been thinking about this "prominent place" for some time
and found that an .onAttach() message might be the right place.

A user, however, who is already used to this interpretation, will soon
find this (extended) start-up message annoying and will want to
suppress it.

I could do this with a "hand-made" option but thought this might
be of more general interest.

Thank you for your attention,
Peter

Summing up the discussions in this thread, I have built a package
'startupmsg' available (in a first version) for the moment at

http://www.uni-bayreuth.de/departments/math/org/mathe7/R-devel/startupmsg_0.1.tar.gz

(see documentation within)

In particular, I took up suggestions from Seth Falcon's mail as to the
condition system
in R as well as a  suggestion by Brian Ripley in some earlier reply in
this thread
to use options() to control start-up messages.

Any comments/suggestions are welcome.

If you find 'startupmsg' useful, you might decide to integrate (parts
of) it to the
'utils' package  (or some yet to be built package
"packageutils" ) later
on ---
for the moment, I would simply submit it to CRAN in the next days.

Best,
Peter

Seth Falcon <sfalcon at fhcrc.org> writes:
>Paul Roebuck <roebuck at mdanderson.org> writes:
>>Prof Brian Ripley <ripley at stats.ox.ac.uk> writes:
>>> Similarly for Bill Dunlap's proposal: suppressMessages would
squelch all
>>> messages from the call, not just the one from your package's
startup
code.
>>> Now, at present there may not be any, but that could well change as
>>> message() gets more widely used.
>>
>> I found Bill's suggestion a bit scary myself; suppressing messages
>> when dealing with loading packages seems a bit like disabling the
>> compiler's warning messages - a bad idea. But it was a novel
>> approach.
>
>What's the use case where this would be scary?  suppressMessages
>doesn't supress warnings or errors, just messages.  If the info to be
>communicated to the user is important enough that it would be
"scary"
>to not see it, then shouldn't it sent as a a warning or an error?
>
>> Given what you said above, do you favor the suggestion to use
>> message() instead of cat() for the purpose of .onAttach() startup
>> messages? I've seen message() before in the manpages but never saw
>> any documentation on how or when it might be considered appropriate
>> to use.
[...]
>>>>>> On Thu, 13 Apr 2006, Prof Brian Ripley wrote:
>>>>>>> I did think you could make use of an option to
decide whether to
>>>>>>> the print the message or not, [snip]
[...]
>> Why would one want to represent a simple non-error message as a
>> condition in the first place?
>
>Because it allows another developer to have control over those
>messages.  That's the beauty of the condition system in R.  
>
>Right now, developers can choose to allow or suppress messages sent
>via message().  With a small change, developers could have a lot more
>control.  The message code could define a restart that would allow a
>developer-specified function to handle the message.  This could be
>useful, for example, to log all messages to a file.
[snip]
>For anyone still with me:
>
>* If there was much concern about squelching "important" messages
by
>  accident, then one could define a new subclass of simpleMessage, say
>  startupMessage or blatherMessage, and then suppress just those.
>
>* This use case of handling messages could also be addressed with a
>  logging system like Python's logging module.  Basically, it would
>  allow users to install log handlers, set priorities, etc.

Dear Seth,

thank you very much for your helpful comments:
>I had a quick look and for what it's worth, a few comments...
>
>* Seems a bit more code than I would expect.
Arguable, yes...
>  I think you have some use cases that I don't have ;-).
hopefully I'm not the only one to have these cases :-)
>  In terms of general use, I would suggest making a stab at a
>  simplified version.
I have tried to do something in that direction:

* files startUpMessage.R / StartupUtilities.Rd now gather the code
  addressing a more general audience; (?"startupmsg")

* files illustration.R / myStartupUtilities.Rd
  [ with mySMHandler, mystartupMessage, buildStartupMessage ]
   (?"mySMHandler") may be thought of an illustration of the concept
  (and hence should not enter general packages, I suppose)

the revised code is available again under

  
http://www.uni-bayreuth.de/departments/math/org/mathe7/R-devel/startupmsg_0.2.tar.gz
>  For example, what's the difference between startupMessage and
>  startupVersionMessage; are both needed?
I guessed so: the idea is to have more than one type of
StartupMessage, and suppressing should be done according to the type;

I have rethought this now: instead of two (or more) subclasses
of StartupMessage, I now have endowed class StartupMessage with an
extra slot type, which currently is supposed to take one of the tree
values

  + "version":     version and title information from the DESCRIPTION
file
  + "notabene":   "nota bene"s on the package to be given at
                   this prominent place
  + "information": (starting) pointers for more information on the
                   package:
                   -howto call the package help file,
                   -howto inspect the NEWS file,
                   -additional manuals/vignettes
                   -URLs

(but the code already supports arbitrarily many type values)
>  And linestarter?
I agree: this should better be dealt with in a more general/flexible way
by allowing  + the developper using 'startupMessages'
               to use his own SMHandler (for /S/tartup/M/essage/Handler/)
               as illustrated in 'mystartupMessages'
             + the user of a package with 'startupMessages'
               to specify a suitable custom restart
               (see examples in ?"startupmsg")
               --- is achieved using your code example
>* Consider adding a customizable restart.  As it stands, startupmsg
>  doesn't give a user more control than message().
Now it does; I admit, I should have integrated your proposed elegant
code right from the beginning.
> That is, you can either muffle the messages or not.  If I want to write
> them to a file or prefix them with funny characters, doing so by grabbing
> hold of the message before it is emitted via the restart seems like a
> nice approach (although one could argue for a more general system
> logging system that probably would not need the fancy condition
> system use).
Thank you again
Peter