Allow alabaster applications to specify an alternative reading function in altReadObject.
altReadObject(...)
altReadObjectFunction(fun)Further arguments to pass to readObject or its equivalent.
Function that can serve as a drop-in replacement for readObject.
For altReadObject, any R object similar to those returned by readObject.
For altReadObjectFunction, the alternative function (if any) is returned if fun is missing.
If fun is provided, it is used to define the alternative, and the previous alternative is returned.
By default, altReadObject is just a wrapper around readObject.
However, if altReadObjectFunction is called, altReadObject calls the replacement fun instead.
This allows alabaster applications to inject wholesale or class-specific customizations into the reading process,
e.g., to add more metadata whenever an instance of a particular class is encountered.
Developers of alabaster extensions should use altReadObject (instead of readObject) to read child objects when writing their own reading functions,
to ensure that application-specific customizations are respected for the children.
To motivate the use of altReadObject, consider the following scenario.
We have created a reading function readX function to read an instance of class X in an alabaster extension.
This function may be called by readObject if instances of X are children of other objects.
An alabaster application Y requires the addition of some custom metadata during the reading process for X.
It defines an alternative reading function readObject2 that, upon encountering a schema for X, redirects to a application-specific reader readX2.
An example implementation for readX2 would involve calling readX and decorating the result with the extra metadata.
When operating in the context of application Y, the readObject2 generic is used to set altReadObjectFunction.
Any calls to altReadObject in Y's context will subsequently call readObject2.
So, when writing a reading function in an alabaster extension for a class that might contain instances of X as children,
we use altReadObject instead of directly using readObject.
This ensures that, if a child instance of X is encountered and we are operating in the context of application Y,
we correctly call readObject2 and then ultimately readX2.
The application-specific fun is free to do anything it wants as long as it understands the representation.
It is usually most convenient to leverage the existing functionality in readObject,
but if the application-specific saver in altSaveObject does something unusual,
then fun is responsible for the correct interpretation of any custom representation.
old <- altReadObjectFunction()
# Setting it to something.
altReadObjectFunction(function(...) {
print("YAY")
readObject(...)
})
# Staging an example DataFrame:
library(S4Vectors)
df <- DataFrame(A=1:10, B=LETTERS[1:10])
tmp <- tempfile()
saveObject(df, tmp)
# And now reading it - this should print our message.
altReadObject(tmp)
#> [1] "YAY"
#> 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
# Restoring the old reader:
altReadObjectFunction(old)