Skip to contents

A class specifies the properties (data) that each of its objects will possess. The class, and its parent, determines which method will be used when an object is passed to a generic.

Usage

new_class(
  name,
  parent = R7_object,
  package = NULL,
  properties = list(),
  abstract = FALSE,
  constructor = NULL,
  validator = NULL
)

new_object(.parent, ...)

Arguments

name

The name of the class, as a string. The result of calling new_class() should always be assigned to a variable with this name, i.e. foo <- new_class("foo").

parent

The parent class to inherit behavior from. There are three options:

package

Package name. It is good practice to set the package name when exporting an R7 class from a package because it includes the package name in the class name when it's used for dispatch. This allows different packages to use the same name to refer to different classes. If you see package, you must export the constructor.

properties

A named list specifying the properties (data) that belong to each instance of the class. Each element of the list can either be a type specification (processed by as_class()) or a full property specification created new_property().

abstract

Is this an abstract class? An abstract class can not be instantiated.

constructor

The constructor function. Advanced use only.

A custom constructor should call new_object() to create the R7 object. The first argument, .data, should an instance of the parent class. The subsequent arguments are used to set the properties.

validator

A function taking a single argument, self, the object to validate.

The job of a validator is to determine whether the object is valid, i.e. if the current property values form an allowed combination. The types of the properties are always automatically validated so the job of the validator is to verify that the values of individual properties are ok (i.e. maybe a property should have length 1, or should always be positive), or that the combination of values of multiple properties is ok. It is called after construction and whenever any property is set.

The validator should return NULL if the object is valid. If not, it should return a character vector where each element describes a single problem, using @prop_name to describe where the problem lies.

See validate() for more details, examples, and how to temporarily suppress validation when needed.

.parent, ...

Parent object and named properties used to construct the object.

Value

A object constructor, a function that can be used to create objects of the given class.

Examples

# Create an class that represents a range using a numeric start and end
range <- new_class("range",
  properties = list(
    start = class_numeric,
    end = class_numeric
  )
)
r <- range(start = 10, end = 20)
r
#> <range>
#>  @ start: num 10
#>  @ end  : num 20
# get and set properties with @
r@start
#> [1] 10
r@end <- 40
r@end
#> [1] 40

# R7 automatically ensures that properties are of the declared types:
try(range(start = "hello", end = 20))
#> Error : <range> object properties are invalid:
#> - @start must be <integer> or <double>, not <character>

# But we might also want to use a validator to ensure that start and end
# are length 1, and that start is < end
range <- new_class("range",
  properties = list(
    start = class_numeric,
    end = class_numeric
  ),
  validator = function(self) {
    if (length(self@start) != 1) {
      "@start must be a single number"
    } else if (length(self@end) != 1) {
      "@end must be a single number"
    } else if (self@end < self@start) {
      "@end must be great than or equal to @start"
    }
  }
)
try(range(start = c(10, 15), end = 20))
#> Error : <range> object is invalid:
#> - @start must be a single number
try(range(start = 20, end = 10))
#> Error : <range> object is invalid:
#> - @end must be great than or equal to @start

r <- range(start = 10, end = 20)
try(r@start <- 25)
#> Error : <range> object is invalid:
#> - @end must be great than or equal to @start