[Rd] declaring package dependencies

[John Fox]

Dear Duncan and Michael,

> -----Original Message-----
> From: r-devel-bounces at r-project.org [mailto:r-devel-bounces at r-
> project.org] On Behalf Of Duncan Murdoch
> Sent: Friday, September 13, 2013 9:51 AM
> To: Michael Friendly
> Cc: r-devel
> Subject: Re: [Rd] declaring package dependencies
> 
> On 13/09/2013 8:31 AM, Michael Friendly wrote:
> > On 9/12/2013 1:37 PM, Duncan Murdoch wrote:
> > >
> > > I think this one would be fine if you had library(MASS) or
> > > require(MASS) or (probably best) used MASS::loglm explicitly.  It
> may
> > > be that in the past some other package put MASS on the search list,
> > > and that's why it worked before.
> > >
> > > The distinction is between "loading" and "attaching" a package.
> > > Loading it (which would be done if you had MASS::loglm, or imported
> > > it) guarantees that the package is initialized and in memory, but
> > > doesn't make it visible to the user without the explicit MASS::
> > > prefix.  Attaching it first loads it, then modifies the user's
> search
> > > list so the user can see it.
> > >
> > > Loading is less intrusive, so it's preferred over attaching.  Both
> > > library() and require() would attach it.
> > >
> > Thanks for this explanation, but I'm still confused about how to
> avoid
> > the wrath of the CRAN-devel
> > daemon, whose appetite for new morsels of developer flesh seems ever
> > increasing and makes
> > keeping even a stable package up-to-date a moving target.  Perhaps
> such
> > changes in R devel
> > should be announced on this list for public comment before they are
> > enforced in R CMD check.
> Changes are generally announced in the NEWS.Rd file long before
> release,
> but R-devel is an unreleased version, so you won't see the news until
> it
> is there.  Announcing things that nobody can try leads to fewer useful
> comments than putting them into R-devel where at least people can see
> what is really happening.
> >
> > In vcdExtra, I use MASS::loglm in ~ 6 .Rd examples, a vignette, and
> also
> > provide R code that
> > extends *.loglm methods.  All of this previously worked by including
> > Suggests: MASS, ...
> > Changing this to Imports: MASS seems rather heavy-handed; I don't
> really
> > want/need all of MASS
> > in my namespace, and using MASS::loglm in examples seems ugly.  For
> now,
> > I'll use
> > require(MASS) in each example.
> 
> If you need a small number of things from MASS in your package code,
> then importing them explicitly is definitely the way to go, e.g.
> importFrom(MASS, loglm).  If you only use them in examples, I wouldn't
> do that, I'd recommend Suggests and use the MASS:: prefix. Whether that
> is ugly is a matter of taste:  it makes it clear to a user where that
> function came from, and doesn't potentially hide objects from other
> packages later in the search path.
> 

If I understand this thread, Michael's package doesn't use loglm() -- it
provides methods for objects produced by loglm() and hence "Enhances" the
package.

> On the other hand, require(pkg) is really simple; we have no equivalent
> function that only does the loading, without attaching.
> So it's hard to write
> 
> if (requireLoadable(MASS)) {
>    MASS::loglm( ... )
> }
> 

I understand why one would want to do this sort of thing (say, using
requireNamespace), to avoid attaching the MASS package to the search path
and possibly shadowing objects on the path, but I think that most users --
as opposed to R developers -- will find the package::function( ... ) syntax
in examples not so much ugly as cryptic. I think that we have ample recent
evidence on this list that even developers (I don't exempt myself) are
confused by namespace issues. On balance, I prefer

	if (require(MASS)) {
		loglm( ...)
	}

which tells the user that it's necessary to load MASS before using loglm(). 

It would be nice if examples ran in a "sandbox," so that an example could
read something like

	library(MASS)
	loglm( ... )
	. . .

without affecting the path in the current session, and fail gracefully if
the MASS package weren't available (unlikely, of course, in the case of
MASS, but not more generally).

Best,
 John

> >
> > > Attaching it first loads it, then modifies the user's search list
> so
> > > the user can see it.
> > Which directive does this?
> 
> library() and require() both do it.
> 
> Duncan Murdoch
> >
> 
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel