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 agetter
, you are responsible for ensuring that it returns an object of the correctclass
; 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
andvalue
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 thatvalue
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 ofclass
.- name
Property name, primarily used for error messages. Generally don't need to set this here, as it's more convenient to supply as a the element name when defining a list of properties. If both
name
and a list-name are supplied, the list-name will be used.
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
#> [1] 6
my_pizza@slices <- 5
my_pizza@slices
#> [1] 5
your_pizza <- pizza()
your_pizza@slices
#> [1] 10
# 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)
#> [1] "2024-01-09 17:25:53 UTC"
my_clock@now
#> [1] "2024-01-09 17:25:54 UTC"
# This property is read only
try(my_clock@now <- 10)
#> Error : Can't set read-only property <clock>@now
# 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
#> Warning: @firstName is deprecated; please use @first_name instead
#> [1] "Hadley"
hadley@firstName <- "John"
#> Warning: @firstName is deprecated; please use @first_name instead
hadley@first_name
#> [1] "John"