[Rd] Questions about name space directives

[Prof Brian Ripley]

On Tue, 1 May 2007, Seth Falcon wrote:

> Hi,
>
> I'm hoping to get some clarification of the intent of some of
> directives used in NAMESPACE files.

For 'intent' you would have to get a response from the authors.
Pending that, here are some comments on what they implemented.

> 1. Is import(somePkg) also intended to import all classes and methods
>   that are exported via exportClasses and exportMethods in somePkg?
>   I think import pulls in classes and methods, but it isn't clear
>   from the docs whether this is as intended.

`Import' and `export' are not being used in the everyday sense.  export() 
in a name space is to do with whether objects in the name space are in the 
package environment (as distinct from the name space environment). 
import() imports the name space and not the package environment.  As the 
classes, methods and any created generics are in the name space, they are 
_all_ imported by import(somePkg) (whether exported or not).

However, for methods on generics not in the same package you need to do 
more than import them: you need to tell the S4 dispatch mechanisms about 
them.  At that point there seem to be some differences between import() 
and importMethodsFrom() that I do not currently understand, relating to 
importing methods from more than one namespace and merging the methods 
tables.  (I suspect that the differences, if real, are unintentional.)

Using importMethods() also imports the corresponding generics if they are 
in the namespace being imported from, but that is best thought of as an 
implementation detail.


> 2. What is exportMethods intended to do?  I'm confused about when/if
>   exportMethods deals with a generic function vs method(s) for a
>   generic function.
>
>   a) In a package that defines a generic function "foo" via
>      setGeneric, it seems to be sufficient to use
>      exportMethods("foo") to export the generic (and any methods
>      defined).  Is this as intended or should the author add an
>      export("foo") directive to explicitly export the generic
>      function?

Naming a generic in exportMethods() will export the generic if it is in 
the namespace.  Conversely, exporting a generic will export its methods
(namespace.R:406).

>   b) In a package that only sets methods on generic "foo", an
>      exportMethods("foo") directive does not re-export the "foo"
>      generic.  I find it confusing that exportMethods sometimes
>      exports the generic and sometimes not.  The generic can be
>      re-exported using export().

I don't know what you mean by 're-export' here, but I think that relates 
to using these terms in the everyday sense.  I guess you are saying that 
if you import a generic (which need not have been exported) from another 
name space, that is not exported by exportMethods.  That is correct 
according to my previous para: that generic was never 'in' the name space 
but in its enclosing environment.  As export() works not just on the name 
space but also its imports, you can explicitly export a generic you 
imported.  (All you need in order to be able to export an object is for it 
to be visible from the name space when the latter is loaded.)

I'll look into adding a bit more to `Writing R Extensions', but some of 
this is implementation detail that we do not necessarily wish to enshrine 
in the API.  (OTOH, changing it is likely to break things nowadays.)

Brian

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