Support Class to Implement R Objects using Reference Semantics
The software described here is an initial version. The eventual goal is to support reference-style classes with software in R itself or using inter-system interfaces. The current implementation (R version 2.12.0) is preliminary and subject to change, and currently includes only the R-only implementation. Developers are encouraged to experiment with the software, but the description here is more than usually subject to change.
Purpose of the Class
This class implements basic reference-style semantics for R
objects. Objects normally do not come directly from this class, but
from subclasses defined by a call to
The documentation below is technical background describing the implementation, but applications
should use the interface documented under
in particular the
$ operator and field accessor functions as
A Basic Reference Class
The design of reference classes for R divides those classes up
according to the mechanism used for implementing references, fields,
and class methods.
Each version of this mechanism is defined by a basic reference
class, which must implement a set of methods and provide some
further information used by
setRefClass. The required methods are for operators
get and set a field in an object, and for
initialize objects. To support these methods, the basic reference class needs to have some
implementation mechanism to store and retrieve data from fields in the
The mechanism needs to be consistent with reference semantics; that
is, changes made to the contents of an object are global, seen by any
code accessing that object, rather than only local to the function
call where the change takes place.
As described below, class
envRefClass implements reference
semantics through specialized use of environment
Other basic reference classes may use an interface to a language such
as Java or C++ using reference semantics for classes. Usually, the R user will be able to invoke class methods on the
class, using the
$ operator. The basic reference class
$ needs to make this possible. Essentially, the
operator must return an R function corresponding to the object and
the class method name. Class methods may include an implementation of data abstraction, in
the sense that fields are accessed by get and set
methods. The basic reference class provides this facility by setting
"fieldAccessorGenerator" slot in its definition to a
function of one variable.
This function will be called by
setRefClass with the
vector of field names as arguments.
The generator function must return a list of defined accessor
An element corresponding to a get operation is invoked with no
arguments and should extract the corresponding field; an element for a
set operation will be invoked with a single argument, the value to be
assigned to the field.
The implementation needs to supply the object, since that is not an
argument in the method invocation.
The mechanism used currently by
envRefClass is described below.
Two virtual classes are supplied to test for reference objects:
is(x, "refClass") tests whether
x comes from a class
defined using the reference class mechanism described here;
is(x, "refObject") tests whether the object has reference
semantics generally, including the previous classes and also classes
inheriting from the R types with reference semantics, such as
"environment". Installed class methods are
with slots that identify the name of the function as a class method
and the other class methods called from this method.
The latter information is determined heuristically when the class is
defined by using the
codetools recommended package. This
package must be installed when reference classes are defined, but is
not needed in order to use existing reference classes.