updateSerializedObjects: Update the serialized objects contained in a directory

In Bioconductor/updateObject: Find/fix old serialized S4 instances

Update the serialized objects contained in a directory

Description

Use updateSerializedObjects() to find and update all the serialized objects contained in a directory. This is the workhorse behind higher-level functions updatePackageObjects() and family (updateAllPackageObjects(), updateBiocPackageRepoObjects(), and updateAllBiocPackageRepoObjects()).

collect_rds_files(), collect_rda_files(), update_rds_file(), and update_rda_file() are the low-level utilities used internally by updateSerializedObjects() to do the job.

Usage

updateSerializedObjects(dirpath=".", recursive=FALSE,
                        filter=NULL, dry.run=FALSE)

## Low-level utilities upon which updateSerializedObjects() is built:
collect_rds_files(dirpath=".", recursive=FALSE)
collect_rda_files(dirpath=".", recursive=FALSE)
update_rds_file(filepath, filter=NULL, dry.run=FALSE)
update_rda_file(filepath, filter=NULL, dry.run=FALSE)

Arguments

dirpath	The path (as a single string) to an arbitrary directory.
recursive	TRUE or FALSE. Should the directory be searched recursively to find the objects to update? By default the directory is not searched recursively.
filter	NULL (the default) or a single string containing a regular expression. When filter is set, only objects for which there is a match in the output of updateObject(object, check=FALSE, verbose=TRUE) actually get replaced with the object returned by the updateObject call. See Details section below for more on this. Note that the pattern matching is case sensitive.
dry.run	TRUE or FALSE. By default, updated objects are written back to their original file. Set dry.run to TRUE to perform a trial run with no changes made.
filepath	The path (as a single string) to a file containing serialized objects. This must be an RDS file (for update_rds_file) or RDA file (for update_rda_file).

Details

update_rds_file() and update_rds_file() use updateObject() internally to update individual R objects.

If no filter is specified (the default), each object is updated with object <- updateObject(object, check=FALSE). If that turns out to be a no-op, then code 0 ("nothing to update") is returned. Otherwise 1 is returned.

If a filter is specified (via the filter argument) then updateObject(object, check=FALSE, verbose=TRUE) is called on each object and the output of the call is captured with capture.output(). Only if the output contains a match for filter is the object replaced with the object returned by the call. If this replacement turns out to be a no-op, or if the output contained no match for filter, then code 0 ("nothing to update") is returned. Otherwise 1 is returned.

The pattern matching is case sensitive.

Note that determining whether a call to updateObject() is a no-op or not is done by calling digest::digest() on the original object and object returned by updateObject(), and by comparing the 2 hash values. This is a LOT MORE reliable than using identical() which is notoriously unreliable!

Value

updateSerializedObjects() returns a single integer which is the number of updated files or a negative error code (-2 if loading an RDS or RDA file failed, -1 if updateObject() returned an error).

collect_rds_files() and collect_rda_files() return a character vector of (relative) file paths.

update_rds_file() and update_rda_file() return a single integer which is one of the following codes:

• -2 if loading the RDS or RDA file failed;

• -1 if updateObject() returned an error;

• 0 if there was nothing to update in the file;

• 1 if the file got updated.

See Also

• The updatePackageObjects function which is just a thin wrapper around updateSerializedObjects.

• The updateObject generic function in the BiocGenerics package.

• The capture.output function in the utils package.

• The digest function in the digest package.

Examples

dirpath <- system.file("extdata", package="updateObject")

## ---------------------------------------------------------------------
## WITHOUT A FILTER
## ---------------------------------------------------------------------

## updateSerializedObjects() prints one line per processed file:
updateSerializedObjects(dirpath, recursive=TRUE, dry.run=TRUE)

## Note that updateSerializedObjects() needs to attach/load the packages
## in which the classes of the objects to update are defined. These
## packages are: GenomicRanges for GRanges objects, SummarizedExperiment
## for SummarizedExperiment objects, and InteractionSet for GInteractions
## objects. This means that sessionInfo() will typically report more
## attached and loaded packages after a updateSerializedObjects() run
## than before:
sessionInfo()

## Also updateSerializedObjects() will raise an error if it fails to
## attach or load a package (typically because the package is missing).
## It will NOT try to install the package.

## ---------------------------------------------------------------------
## WITH A FILTER
## ---------------------------------------------------------------------

## We want to filter on the presence of the **word** "DataFrame" in
## the output of 'updateObject( , check=FALSE, verbose=TRUE)'. We can't
## just set 'filter' to '"DataFrame" for that as this would also produce
## matches in the presence of strings like "AnnotatedDataFrame":
filter <- "\bDataFrame\b"

updateSerializedObjects(dirpath, recursive=TRUE, filter=filter,
                        dry.run=TRUE)

Bioconductor/updateObject documentation built on Oct. 30, 2024, 12:15 p.m.