new_property {S7}

Define a new property

Description

A property defines a named component of an object. Properties are typically used to store (meta) data about an object, and are often limited to a data of a specific class.

By specifying a getter and/or setter, you can make the property "dynamic" so that it's computed when accessed or has some non-standard behaviour when modified.

Usage

new_property(
  class = class_any,
  getter = NULL,
  setter = NULL,
  validator = NULL,
  default = NULL,
  name = NULL
)

Arguments

class

Class that the property must be an instance of. See as_class() for details.

getter

An optional function used to get the value. The function should take self as its sole argument and return the value. If you supply a getter, you are responsible for ensuring that it returns an object of the correct class; it will not be validated automatically.

If a property has a getter but doesn't have a setter, it is read only.

setter

An optional function used to set the value. The function should take self and value and return a modified object.

validator

A function taking a single argument, value, the value to validate.

The job of a validator is to determine whether the property value is valid. It should return NULL if the object is valid, or if it's not valid, a single string describing the problem. The message should not include the name of the property as this will be automatically appended to the beginning of the message.

The validator will be called after the class has been verified, so your code can assume that value has known type.

default

When an object is created and the property is not supplied, what should it default to? If NULL, defaults to the "empty" instance of class.

name

Property name, primarily used for error messages. Used primrarily for testing as it is set automatically when using a list of properties.

Value

An S7 property, i.e. a list with class S7_property.

Examples

# Simple properties store data inside an object
pizza <- new_class("pizza", properties = list(
  slices = new_property(class_numeric, default = 10)
))
my_pizza <- pizza(slices = 6)
my_pizza@slices
my_pizza@slices <- 5
my_pizza@slices

your_pizza <- pizza()
your_pizza@slices

# Dynamic properties can compute on demand
clock <- new_class("clock", properties = list(
  now = new_property(getter = function(self) Sys.time())
))
my_clock <- clock()
my_clock@now; Sys.sleep(1)
my_clock@now
# This property is read only
try(my_clock@now <- 10)

# These can be useful if you want to deprecate a property
person <- new_class("person", properties = list(
  first_name = class_character,
  firstName = new_property(
     getter = function(self) {
       warning("@firstName is deprecated; please use @first_name instead", call. = FALSE)
       self@first_name
     },
     setter = function(self, value) {
       warning("@firstName is deprecated; please use @first_name instead", call. = FALSE)
       self@first_name <- value
       self
     }
   )
))
hadley <- person(first_name = "Hadley")
hadley@firstName
hadley@firstName <- "John"
hadley@first_name