[Rd] Recommended way to call/import functions from a Suggested package

[Berwin A Turlach]

G'day David,

On Fri, 22 Feb 2013 18:50:07 -0800
David Winsemius <dwinsemius at comcast.net> wrote:

> On Feb 22, 2013, at 6:39 PM, David Winsemius wrote:
[...]
> > I've always wondered: How does lattice manage to use grid functions
> > without putting them on the search path?

Because lattice imports the grid package and has a NAMESPACE (as have
all packages nowadays):

R> packageDescription("lattice")
Package: lattice
Version: 0.20-10
Date: 2012/08/21
[...]
Suggests: grid, KernSmooth, MASS
Imports: grid, grDevices, graphics, stats, utils, methods
[...]

And the relevant information is not in the "Writing R Extensions"
manual but in section 3.5.4 of the "R Language Definition" manual:

	Packages which have a @emph{namespace} have a different search
	path. When a search for an @R{} object is started from an
	object in such a package, the package itself is searched first,
	then its imports, then the base namespace and finally the
	global environment and the rest of the regular search path.
	The effect is that references to other objects in the same
	package will be resolved to the package, and objects cannot be
	masked by objects of the same name in the global environment or
	in other packages.

Thus, as grid is imported by lattice, it is loaded but not attached
(i.e. does not appear in the search path).  However, function in the
lattice package will find functions in the grid package as the imports
are searched.

> Neither can the R interpreter find it. But it's clearly available if
> you ask nicely:
> 
> > grid::grid.text

This will always work, whether the grid package is loaded/attached or
not:

R> sessionInfo()
R version 2.15.2 (2012-10-26)
Platform: x86_64-unknown-linux-gnu/64 (64-bit)

locale:
[1] C

attached base packages:
[1] stats     graphics  grDevices utils     dataset  methods base     

loaded via a namespace (and not attached):
[1] tools_2.15.2
R> grid::grid.text
function (label, x = unit(0.5, "npc"), y = unit(0.5, "npc"), 
    just = "centre", hjust = NULL, vjust = NULL, rot = 0, check.overlap = FALSE, 
    default.units = "npc", name = NULL, gp = gpar(), draw = TRUE, 
    vp = NULL) 
{
    tg <- textGrob(label = label, x = x, y = y, just = just, 
        hjust = hjust, vjust = vjust, rot = rot, check.overlap = check.overlap, 
        default.units = default.units, name = name, gp = gp, 
        vp = vp)
    if (draw) 
        grid.draw(tg)
    invisible(tg)
}
<bytecode: 0x2507c80>
<environment: namespace:grid>


You specifically asked R to get object grid.text from the grid
package, so R obliges to do so.  For the help system to find the help
pages on an object, the package that contains the help pages has to be
on the search path AFAIK.

Cheers,

	Berwin