loadObject.Rd
Load an object from its metadata, based on the loading function specified in its schema.
loadObject(info, project, ...)
customloadObjectHelper(
info,
project,
...,
.locations,
.memory,
.fallback = NULL
)
Named list containing the metadata for this object.
Any argument accepted by the acquisition functions, see ?acquireFile
.
By default, this should be a string containing the path to a staging directory.
Further arguments to pass to the specific loading function listed in the schema.
Character vector of package names containing application-specific schemas.
An environment used to cache the loading functions, to avoid extra schema file reads on subsequent calls.
Function that accepts a schema string (e.g., "data_frame/v1.json"
) and returns the path to a schema.
If NULL
, no fallback is used and an error is raised if the schema cannot be found.
An object corresponding to info
, as defined by the loading function.
The loadObject
function loads an object from file into memory based on the schema specified in info
,
effectively reversing the activity of the corresponding stageObject
method.
It does so by extracting the name of the appropriate loading function from the _attributes.restore.R
property of the schema;
this should be a string that contains a namespaced function, which can be parsed and evaluated to obtain said function.
loadObject
will then call the loading function with the supplied arguments.
Application developers can override the behavior of loadObject
by specifying a custom function in .altLoadObject
.
This is typically used to point to a different set of application-specific schemas,
which in turn point to (potentially custom) loading functions in their _application.restore.R
properties.
In most applications, the override should be defined with customloadObjectHelper
, which simplifies the process of specifying a different set of schemas.
# Same example as stageObject, but reversed.
library(S4Vectors)
df <- DataFrame(A=1:10, B=LETTERS[1:10])
# First staging it:
tmp <- tempfile()
dir.create(tmp)
out <- stageObject(df, tmp, path="coldata")
# Loading it:
loadObject(out, tmp)
#> DataFrame with 10 rows and 2 columns
#> A B
#> <integer> <character>
#> 1 1 A
#> 2 2 B
#> 3 3 C
#> 4 4 D
#> 5 5 E
#> 6 6 F
#> 7 7 G
#> 8 8 H
#> 9 9 I
#> 10 10 J
Comments for extension developers
When writing alabaster extensions, developers may need to load child objects inside the loading functions for their classes. In such cases, developers should use
.loadObject
rather than callingloadObject
directly. This ensures that any application-level overrides of the loading functions are respected. Once in memory, the child objects can then be assembled into more complex objects by the developer's loading function.By default,
loadObject
will look through the schemas in alabaster.schemas to find the schema specified ininfo$`$schema`
. Developers of alabaster extensions can temporarily add extra packages to the schema search path by supplying package names in thealabaster.schema.locations
option; schema files are expected to be stored in theschemas
subdirectory of each package's installation directory. In the long term, extension developers should request the addition of their packages toloadObject
's default search path.