ReactiveObject.S3: Class: ReactiveObject.S3
In rappster/reactr: Reactive object bindings with built-in caching and push functionality

Description Usage Arguments Details Value Fields Intended use of this class Author(s) References See Also Examples

Class representing the system state (S3) and its constructor function.

ReactiveObject.S3(.x, pull_refs_list = character(), id = character(),
  uid = character(), value = NULL, where = parent.frame(),
  checksum = character(), cl = class(value), exists_visible = FALSE,
  cache = TRUE, has_cached = FALSE, is_invalid = FALSE,
  registry = getRegistry(), refs_pull = new.env(parent = emptyenv()),
  refs_push = new.env(parent = emptyenv()), refs_checksum = new.env(parent =
  emptyenv()), has_pull_refs = FALSE, has_push_refs = FALSE,
  must_push = FALSE, has_pushed = FALSE, is_running_push = FALSE,
  func = NULL, condition = NULL)

`.x`	`ANY`. An object of an arbitrary class whose class attribute should be updated so that it becomes an instance of class `ReactiveObject.S3`. Mainly intended for rapid prototyping purposes
`pull_refs_list`	`list`. List of pull references as returned by functions that identify pull references (e.g. `processYaml`.

Instances of this class are implicitly created when calling setReactive and stored in the registry. Objects of this class can be thought of as the "invisible parts" of the reactive objects of whom actually only field .value is visible to the user or other functions consuming the reactive object.

Instance of class ReactiveObject.S3.

.id: character. Object ID. Initial: character().
.uid: character. Object ID. Initial: character(). Automatically computed once .id is specified: digest::digest(list(id = .id, where = capture.output(eval(.where)))).
.value: ANY. Actual object value / cached value. Initial: NULL.
.where: environment. Environment of reactive object. Initial: parent.frame().
.checksum: character. Checksum of visible value. Initial: character().
.class: character. Class of visible object (.value). If strongly typed (argument typed = TRUE in setReactive, then this field is used to determine if an assignment value is valid or not. Initial: character().
.exists_visible: logical. Field for tracking if the visible object value actually exists already or if this is a mere "empty container" in the registry. It is set to TRUE when the visible object is actually set/created via setReactive. Initial: FALSE.
.has_cached: logical. Field for tracking if the instance already has a cached value or not. If FALSE, the binding function (if there is any) is executed and after that the field is set to TRUE to signal that a cached value exists. Initial: FALSE.
.is_modcycle_complete: logical. TRUE: modification cycle complete; FALSE: modification cycle not complete yet. Only relevant for bi-directional bindings and in case of explicitly changing visible object values via <- or assign. Very important to determine the scope of object updates. Initial: TRUE.
.is_invalid: logical. Field for propagating the invalidity of referenced objects to its dependees. It is set to TRUE when an reactive object is unset or removed. Initial: FALSE.
.cache: logical. TRUE: use caching mechanism and everything associated with it; FALSE: no caching. Initial: TRUE.
.registry: environment. Reference to the registry environment (see getRegistry. Important for retrieving and comparing checksum values, enabling push and other useful things (integrity checks etc.) Initial: getRegistry().
.refs_pull: environment. Environment for storing information of inbound/pull references. Initial: new.env(parent = emptyenv()).
.refs_push: environment. Environment for storing information of outbound/push references. Initial: new.env(parent = emptyenv()).
.has_pull_refs: logical. TRUE: object has inbound/pull references; FALSE: object has no inbound/pull references Initial: FALSE.
.has_push_refs: logical. TRUE: object has outbound/push references; FALSE: object has no outbound/push references Initial: FALSE.
.must_push: logical. Field that controls if push is enabled. TRUE: push changes to outbound references; FALSE: changes need to be pulled by references, no push. Initial: FALSE.
.has_pushed: logical. TRUE: change has been pushed to all push references; FALSE: change has not been pushed to push references yet. Initial: FALSE.
.is_running_push: logical. TRUE: push process is currently running; FALSE: no push process is currently running. Initial: FALSE.
.func: function. Binding function. Initial: NULL.
.refs_checksum: environment. Environment for caching checksums of referenced objects. Initial: new.env(parent = emptyenv()).
condition: condition (at least by inheritance). If a condition has been signaled, this field is assigned a respective custom condition object that is triggered when the visible object value (or self$.value) is requested. Also see signalCondition and signalCondition Initial: NULL.

This S3 class, or to be more precise its constructor function, exists mainly for rapid prototyping purposes. This is mainly reflected in the fact, that when specifying .x, this constructor function will simply update the class attribute of whatever object has been provided.

However, it also allows for a more formal OOP-style of rapid prototyping by offering explicit class fields (all arguments except .x). Nevertheless, it is probably advisable to switch to an explicit formal approach such as S4 and/or Reference Classes once the package or application has reached a certain state of maturity.

Janko Thyson janko.thyson@rappster.de

http://github.com/Rappster/reactr

setReactive

## Not run: 

## Informal use (intended mainly for rapid prototyping) //
## Takes *any* object and simply changes the class attributes
ReactiveObject.S3(
  list(
    id = "x_1",
    value = 10
  )
)  
ReactiveObject.S3(TRUE)  

## Formal use (explicitly using 'fields') //
res <- ReactiveObject.S3()
ls(res, all.names = TRUE)
res <- ReactiveObject.S3(
  id = "x_1",
  value = 10
)
res$.id
res$.uid
## --> automatically computed; important for handling checksum values

## Recommended: include namespace //
## Regardless if you plan on using this class in an informal or formal way
reactr::ReactiveObject.S3(
  id = "x_1",
  value = 10
)

##------------------------------------------------------------------------------
## Methods //
##------------------------------------------------------------------------------

obj <- reactr::ReactiveObject.S3(
  id = "x_1",
  value = 10
)

## Compute checksum //
digest::digest(x_1)
obj$.checksum
obj$.value <- x_1 <- 100
digest::digest(x_1)
obj$.computeChecksum()

## Compute UID //
x_1_uid <- computeObjectUid(id = "x_1")
x_1_uid
obj$.uid
obj$.computeUid()
## --> automatically executed in constructor based on 'obj$.id' and 'obj$.where'

## Copy //
obj$.copy(id = "x_1_copied")
x_1_copied
x_1 <- 100
x_1
x_1_copied
## --> independent
getFromRegistry("x_1")
getFromRegistry("x_1_copied")
## --> independent

## References //
obj$.hasPullReferences()
obj$.hasPushReferences()
## --> difficult to illustrate "stand-alone"; these methods are executed 
## when calling `setReactive()`

## Register and unregister //
exists(obj$.uid, getRegistry())
## --> actually, the object is already registered through call to 'setReactive()' 
## but we overwrite the existing value here for illustration:
obj$.register(overwrite = TRUE)

obj$.unregister()
exists(obj$.uid, getRegistry())
obj$.register()
exists(obj$.uid, getRegistry())

## Remove //
## Remove visible object from its associated environment and invisible object 
## from the registry
obj$.remove()
try(x_1)
## --> removed 


## End(Not run)