Serialization utilities — blockr

Blocks are serialized by writing out information on the constructor used to create the object, combining this with block state information, which constitutes values such that when passed to the constructor the original object can be re-created.

Usage

blockr_ser(x, ...)

# S3 method for class 'block'
blockr_ser(x, state = NULL, ...)

# S3 method for class 'blocks'
blockr_ser(x, blocks = NULL, ...)

# S3 method for class 'board_options'
blockr_ser(x, options = NULL, ...)

# S3 method for class 'blockr_ctor'
blockr_ser(x, ...)

# S3 method for class 'board_option'
blockr_ser(x, option = NULL, ...)

# S3 method for class 'llm_model_option'
blockr_ser(x, option = NULL, ...)

# S3 method for class 'board'
blockr_ser(x, board_id = NULL, ...)

# S3 method for class 'link'
blockr_ser(x, ...)

# S3 method for class 'links'
blockr_ser(x, ...)

# S3 method for class 'stack'
blockr_ser(x, ...)

# S3 method for class 'stacks'
blockr_ser(x, ...)

blockr_deser(x, ..., on_error = NULL)

# S3 method for class 'list'
blockr_deser(x, ...)

# S3 method for class 'block'
blockr_deser(x, data, ...)

# S3 method for class 'blocks'
blockr_deser(x, data, ..., on_error = NULL)

# S3 method for class 'board'
blockr_deser(x, data, ..., on_error = NULL)

# S3 method for class 'link'
blockr_deser(x, data, ...)

# S3 method for class 'links'
blockr_deser(x, data, ...)

# S3 method for class 'stack'
blockr_deser(x, data, ...)

# S3 method for class 'stacks'
blockr_deser(x, data, ...)

# S3 method for class 'board_options'
blockr_deser(x, data, ...)

# S3 method for class 'blockr_ctor'
blockr_deser(x, data, ...)

# S3 method for class 'board_option'
blockr_deser(x, data, ...)

Arguments

x: Object to (de)serialize
...: Generic consistency
state: Object state (as returned from an expr_server)
blocks: Block states keyed by block ID. A block that is NULL, or omitted from blocks altogether, defaults to values from its constructor scope. A partial snapshot is therefore valid: under deferred construction off-screen blocks are never built and carry no live state, so blocks may cover only the built subset – the rest serialize from their constructors rather than aborting the save.
options: Board option values (NULL uses values provided by x)
option: Board option value (NULL uses values provided by x)
board_id: Board ID
on_error: How to handle a block that cannot be deserialized – its constructor (or the package providing it) is unavailable, its payload cannot be reconstructed, or the re-created object is not a block. "abort" (the default) propagates the error, while "drop" omits the offending block (emitting a warning) and continues; board deserialization then prunes any links and stacks that reference a dropped block, so a board referencing a since-retired or no-longer-installed block type still loads. Board deserialization resolves on_error once and threads it to the contained blocks. The default is sourced from blockr_option("deser_on_error", "abort"), letting a deployment opt into dropping via options(blockr.deser_on_error = "drop") or the BLOCKR_DESER_ON_ERROR environment variable.
data: List valued data (converted from JSON)

Value

Serialization helper function blockr_ser() returns lists, which for most objects contain slots object and payload, where object contains a class vector which is used by blockr_deser() to instantiate an empty object of that class and use S3 dispatch to identify the correct method that, given the content in payload, can re-create the original object.

Details

Helper functions blockr_ser() and blockr_deser() are implemented as generics and perform most of the heavy lifting for (de-)serialization: representing objects as easy-to-serialize (nested) lists containing mostly strings and no objects which are hard/impossible to truthfully re-create in new sessions (such as environments).

During deserialization, blockr_deser() forwards ... to the dispatched per-class method. This lets callers (and outer methods deserializing nested objects) thread additional context down to inner deserializers.

The class vector written to object selects the blockr_deser() method, but the re-created object only has to keep the kind of object it names: the last class with a blockr_deser() method of its own, such as block for any block. Classes in front of it may differ from the ones written, so a package can rename or drop classes of its blocks without breaking saved boards. An object re-created as another kind raises an error of class block_deser_class_error.

Examples

blk <- new_dataset_block("iris")

blockr_ser(blk)
#> $object
#> [1] "dataset_block" "data_block"    "block"         "vctrs_vctr"   
#> [5] "list"         
#> 
#> $payload
#> $payload$dataset
#> [1] "iris"
#> 
#> $payload$package
#> [1] "datasets"
#> 
#> $payload$block_name
#> [1] "Dataset"
#> 
#> 
#> $constructor
#> $constructor$object
#> [1] "blockr_ctor"
#> 
#> $constructor$constructor
#> [1] "new_dataset_block"
#> 
#> $constructor$package
#> [1] "blockr.core"
#> 
#> $constructor$version
#> [1] "0.1.4"
#> 
#> 

all.equal(blk, blockr_deser(blockr_ser(blk)), check.environment = FALSE)
#> [1] TRUE