[Rd] namespaces and S4 methods/classes

[John Chambers]

The current version of the methods package now has a namespace. Packages
using S4 methods and classes can have NAMESPACE files.  New directives
can be included in NAMESPACE files to import and export classes and
methods.

Namespaces allow cleaner definition of the API for packages, and are
needed for future improvements to R.

NOTE: This is a major revision.  In principle, it should be back
compatible, and it passes the checks (on linux).  But approach with
caution, namespaces do change the language semantics, and we will likely
encounter some surprises.

The new directives, in addition to those described in Luke Tierney's
article in the June, 2003 R News, are:

exportClasses(...)
exportMethods(...)

importClassesFrom(package, ...)
importMethodsFrom(package, ...)

The `...' arguments are the names of classes or of generic functions
as appropriate.  The exportClasses and exportMethods directives export
the corresponding class definitions and all the methods for the
functions.  Similarly, the importClassesFrom and importMethodsFrom
import the class definitions and all the methods defined for the
functions.

This is a preliminary version, with several known deficiencies.  Here
are some points to note.

1.  Currently, NAMESPACE files  using methods must explicitly import
    the methods package, via the `import(methods)' directive.

2.  Private (i.e., non-exported) methods for primitive functions don't
    currently really work.  They don't appear explicitly, but are
    defined internally.  (This will be fixed, but needs a change in
    the way methods are dispatched for primitives.)

3.  Methods are exported all-or-nothing; it is not possible to export
    some of the methods for a function.  (Again, this will require a
    different mechanism than is currently used.)

    A related point is that the exported methods are only the methods
    defined in this package, not methods imported for the same
    function.  (As a result, it may still be necessary to require() a
    package even if there is an import() directive for it, so users
    will see all the methods.  This will probably change.)

4.  The NAMESPACE mechanism should work with or without a saved image
    from the INSTALL, but there may be subtleties not uncovered.  (As
    always with classes and methods, there is an efficiency advantage
    to using saved images.)

5.  The exported names from the methods package are quite liberal, but
    there may be some currently used functions that come up missing; let
    us know.  In the future the exports from the methods package will
    probably shrink, to make the API cleaner.

6.  An important change required by namespaces is that classes be
    directly identifiable as objects, not just the class name as a
    string.  The current version takes a first step by including the
    package name as an attribute in the class() value for objects with
    formal classes.  A better mechanism may be used later.

7.  There are some problems with debugging using namespaces.  At the
    moment, the trace() function has been instrumented to override
    locked bindings, but we don't guarantee this in the future.
    (However, some mechanism will be needed--it certainly was in
    debugging the changes so far.)

8.  In case of serious problems, you should be able to go back to a
    non-namespace version of the methods package by moving the
    NAMESPACE file in $R_HOME/src/library/methods, removing all.R and
    running make.  (At least, it works here.)


Here are examples of two package NAMESPACE files:  withNamespace and
withNamespace2, the latter using the former:

withNamespace/NAMESPACE:

import(methods)
export(f1, ng1)
exportMethods("[", initialize)
exportClasses(c1)

-----------------------
withNamespace2/NAMESPACE:

import(methods)
importFrom(withNamespace, ng1)
importClassesFrom(withNamespace, c1)
importMethodsFrom(withNamespace, f1, "[")
export(f4, f5, f1)
exportMethods(f6, "[", f1)
exportClasses(c1, c2)


-- 
John M. Chambers                  jmc at bell-labs.com
Bell Labs, Lucent Technologies    office: (908)582-2681
700 Mountain Avenue, Room 2C-282  fax:    (908)582-3340
Murray Hill, NJ  07974            web: http://www.cs.bell-labs.com/~jmc