[Rd] Writing R-extensions

[Prof Brian Ripley]

On Sat, 27 Aug 2005, Berwin A Turlach wrote:

> G'day all,
>
> After reading through "Writing R Extensions", Version 2.1.1
> (2005-06-20), I thought the the following points might need
> clarifications or corrections.  (I checked that these comments also
> hold for "Writing R Extensions", Version 2.2.0.)
>
> 1) When I ran "package.skeleton" recently, I noticed that the
>   DESCRIPTION file and an entry `type'.  This surprised me a bit
>   since I did not remember reading about it in the description of the
>   DESCRIPTION file.  I realised that package types are described in
>   the last section of Chapter 1 of "Writing R Extensions", but would
>   it be possible to add at the end of Section 1.1.1 (The
>   `DESCRIPTION' file) something like:
>
> The optional @samp{Type} field specifies the type of the package:
> @pxref{Package types}.

Added.  Note that section 1.1.1 is not exhaustive: other fields are 
allowed.

> 3) The final sentence in the section on `Registering S3 methods' is:
>
>        Any methods for a generic defined in a package that does not
>        use a name space should be exported, and the package defining
>        and exporting the method should be attached to the search path
>        if the methods are to be found.
>
>   I wonder whether this should actually be:
>
>        Any methods for a generic defined in a package that does not
>        use a name space should be exported, and the package defining
>        and exporting the generic should be attached to the search path
>                          ^^^^^^^
>        if the methods are to be found.
>
>   Or is the implication of that sentence that if I have a package
>   with a name space which defines a method for a generic defined in
>   another package that does not use a name space, then this method
>   is only found if my package is attached to the search path and
>   mere loading of the namespace is not sufficient?

I think we need to check with the author (Luke, r23430).  If the generic 
is not visible there is no dispatch and so this would be irrelevant. 
Assuming a typo, your implication is what the svn log entry says and how I 
read the text.

r23430 | luke | 2003-03-02 18:52:13 +0000 (Sun, 02 Mar 2003) | 3 lines

Added wording to clarify that S3method registration should only be used if
the generic is defined in a work space.
                             name?


> 4) This could be nit-picking (or just the fact that English is not my
>   native language), but the section on `Load hooks' states
>
>      Packages with name spaces do not use the @code{.First.lib}
>      function.  Since loading and attaching are distinct operations
>      when a name space is used, separate hooks are provided for each.
>      These hook functions are called @code{.onLoad} and
>      @code{.onAttach}.
>
>   I interpreted this as "o.k., loading and attaching are distinct
>   operations, if I load a package .onLoad (and only .onLoad) is run,
>   if I attach a package then .onAttach (and only .onAttach) is run".
>   But the manual continues a bit further down with
>
>      Packages are not likely to need @code{.onAttach} (except perhaps
>      for a start-up banner); code to set options and load shared
>      objects should be placed in a @code{.onLoad} function, or use
>      made of the @code{useDynLib} directive described next.
>
>   This seems to imply to me that the .onLoad is executed also if I
>   attach a package.  So should may understanding rather be "attaching
>   a package implies loading it and, hence, if I attach a package,
>   then .onLoad and .onAttach are both run (with .onLoad presumably
>   run first?)"?

Yes.  But not quite the whole story.  You cannot attach a package without 
loading the namespace, and so .onLoad is run when the namespace is loaded.
Possibly some time later the package can be attached and then .onAttach is 
run.

That section is about how to write load hooks: it is not intended to be a 
tutorial on namespaces.  But earlier we do have

   Like other packages, packages with name spaces are loaded and attached
   to the search path by calling @code{library}.

and library() is the only way to attach package with a name space.  (In 
case anyone thinks differently, require() etc all call library.)

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