R6Class: Create an R6 reference object generator

Description

R6 objects are essentially environments, structured in a way that makes them
look like an object in a more typical object-oriented language than R. They
support public and private members, as well as inheritance across different
packages.

Arguments

classname

Name of the class. The class name is useful primarily for S3
method dispatch.

public

A list of public members, which can be functions (methods) and
non-functions (fields).

private

An optional list of private members, which can be functions
and non-functions.

active

An optional list of active binding functions.

inherit

A R6ClassGenerator object to inherit from; in other words, a
superclass. This is captured as an unevaluated expression which is
evaluated in parent_env each time an object is instantiated.

lock_objects

Should the environments of the generated objects be
locked? If locked, new members can't be added to the objects.

class

Should a class attribute be added to the object? Default is
TRUE. If FALSE, the objects will simply look like
environments, which is what they are.

portable

If TRUE (the default), this class will work with
inheritance across different packages. Note that when this is enabled,
fields and members must be accessed with self$x or
private$x; they can't be accessed with just x.

lock_class

If TRUE, it won't be possible to add more members to
the generator object with $set. If FALSE (the default), then
it will be possible to add more members with $set. The methods
$is_locked, $lock, and $unlock can be used to query
and change the locked state of the class.

cloneable

If TRUE (the default), the generated objects will
have method named $clone, which makes a copy of the object.

parent_env

An environment to use as the parent of newly-created
objects.

lock

Deprecated as of version 2.1; use lock_class instead.

Details

An R6 object consists of a public environment, and may also contain a private
environment, as well as environments for superclasses. In one sense, the
object and the public environment are the same; a reference to the object is
identical to a reference to the public environment. But in another sense, the
object also consists of the fields, methods, private environment and so on.

The active argument is a list of active binding functions. These
functions take one argument. They look like regular variables, but when
accessed, a function is called with an optional argument. For example, if
obj$x2 is an active binding, then when accessed as obj$x2, it
calls the x2() function that was in the active list, with no
arguments. However, if a value is assigned to it, as in obj$x2 <- 50,
then the function is called with the right-side value as its argument, as in
x2(50). See makeActiveBinding for more information.

If the public or private lists contain any items that have reference
semantics (for example, an environment), those items will be shared across
all instances of the class. To avoid this, add an entry for that item with a
NULL initial value, and then in the initialize method,
instantiate the object and assign it.

The print method

R6 object generators and R6 objects have a default print method to
show them on the screen: they simply list the members and parameters (e.g.
lock_objects, portable, etc., see above) of the object.

The default print method of R6 objects can be redefined, by
supplying a public print method. (print members that are not
functions are ignored.) This method is automatically called whenever the
object is printed, e.g. when the object's name is typed at the command
prompt, or when print(obj) is called. It can also be called directly
via obj$print(). All extra arguments from a print(obj, ...)
call are passed on to the obj$print(...) method.

Portable and non-portable classes

When R6 classes are portable (the default), they can be inherited across
packages without complication. However, when in portable mode, members must
be accessed with self and private, as in self$x and
private$y.

When used in non-portable mode, R6 classes behave more like reference
classes: inheritance across packages will not work well, and self
and private are not necessary for accessing fields.

Cloning objects

R6 objects have a method named clone by default. To disable this,
use cloneable=FALSE. Having the clone method present will
slightly increase the memory footprint of R6 objects, but since the method
will be shared across all R6 objects, the memory use will be negligible.

By default, calling x$clone() on an R6 object will result in a
shallow clone. That is, if any fields have reference semantics
(environments, R6, or reference class objects), they will not be copied;
instead, the clone object will have a field that simply refers to the same
object.

To make a deep copy, you can use x$clone(deep=TRUE). With this
option, any fields that are R6 objects will also be cloned; however,
environments and reference class objects will not be.

If you want different deep copying behavior, you can supply your own
private method called deep_clone. This method will be called for
each field in the object, with two arguments: name, which is the
name of the field, and value, which is the value. Whatever the
method returns will be used as the value for the field in the new clone
object. You can write a deep_clone method that makes copies of
specific fields, whether they are environments, R6 objects, or reference
class objects.

S3 details

Normally the public environment will have two classes: the one supplied in
the classname argument, and "R6". It is possible to get the
public environment with no classes, by using class=FALSE. This will
result in faster access speeds by avoiding class-based dispatch of
$. The benefit is is negligible in most cases.

If a class is a subclass of another, the object will have as its classes
the classname, the superclass's classname, and "R6"

The primary difference in behavior when class=FALSE is that, without
a class attribute, it won't be possible to use S3 methods with the objects.
So, for example, pretty printing (with print.R6Class) won't be used.