rotate_rds: Serialize R objects to disk (with backup)

In s-fleck/rtdr: Log Rotation and Conditional Backups

Serialize R objects to disk (with backup)

Description

The rotate_rds*() functions are wrappers around base::saveRDS() that create a backup of the destination file (if it exists) instead of just overwriting it.

Usage

rotate_rds(
  object,
  file = "",
  ascii = FALSE,
  version = NULL,
  compress = TRUE,
  refhook = NULL,
  ...,
  on_change_only = FALSE
)

rotate_rds_date(
  object,
  file = "",
  ascii = FALSE,
  version = NULL,
  compress = TRUE,
  refhook = NULL,
  ...,
  age = -1L,
  on_change_only = FALSE
)

rotate_rds_time(
  object,
  file = "",
  ascii = FALSE,
  version = NULL,
  compress = TRUE,
  refhook = NULL,
  ...,
  age = -1L,
  on_change_only = FALSE
)

Arguments

object	R object to serialize.
file	a connection or the name of the file where the R object is saved to or read from.
ascii	a logical. If TRUE or NA, an ASCII representation is written; otherwise (default), a binary one is used. See the comments in the help for save.
version	the workspace format version to use. NULL specifies the current default version (3). The only other supported value is 2, the default from R 1.4.0 to R 3.5.0.
compress	a logical specifying whether saving to a named file is to use "gzip" compression, or one of "gzip", "bzip2" or "xz" to indicate the type of compression to be used. Ignored if file is a connection.
refhook	a hook function for handling reference objects.
...	Arguments passed on to rotate, rotate_date, rotate_time max_backups maximum number of backups to keep an integer scalar: Maximum number of backups to keep In addition for timestamped backups the following value are supported: a Date scalar: Remove all backups before this date a character scalar representing a Date in ISO format (e.g. "2019-12-31") a character scalar representing an Interval in the form "<number> <interval>" (see below for more info) size scalar integer, character or Inf. Backup/rotate only if file is larger than this size. Integers are interpreted as bytes. You can pass character vectors that contain a file size suffix like 1k (kilobytes), 3M (megabytes), 4G (gigabytes), 5T (terabytes). Instead of these short forms you can also be explicit and use the IEC suffixes KiB, MiB, GiB, TiB. In Both cases 1 kilobyte is 1024 bytes, 1 megabyte is 1024 kilobytes, etc... . (if age and size are provided, both criteria must be TRUE to trigger rotation) dir character scalar. The directory in which the backups of file are stored (defaults to dirname(file)) compression Whether or not backups should be compressed FALSE for uncompressed backups, TRUE for zip compression; uses zip() a scalar integer between 1 and 9 to specify a compression level (requires the zip package, see its documentation for details) the character scalars "utils::zip()" or "zip::zipr" to force a specific zip command dry_run logical scalar. If TRUE no changes are applied to the file system (no files are created or deleted) verbose logical scalar. If TRUE additional informative messages are printed create_file logical scalar. If TRUE create an empty file in place of file after rotating. format a scalar character that can be a subset of of valid strftime() formatting strings. The default setting is "%Y-%m-%d--%H-%M-%S". You can use an arbitrary number of dashes anywhere in the format, so "%Y-%m-%d--%H-%M-%S" and "%Y%m%d%H%M%S" are both legal. T and _ can also be used as separators. For example, the following datetime formats are also possible: %Y-%m-%d_%H-%M-%S (Python logging default), %Y%m%dT%H%M%S (ISO 8601) All datetime components except %Y are optional. If you leave out part of the timestamp, the first point in time in the period is assumed. For example (assuming the current year is 2019) %Y is identical to 2019-01-01--00-00-00. The timestamps must be lexically sortable, so "%Y-%m-%d" is legal, "%m-%d-%Y" and %Y-%d are not. now The current Date or time (POSIXct) as a scalar. You can pass a custom value here to to override the real system time. As a convenience you can also pass in character strings that follow the guidelines outlined above for format, but please note that these differ from the formats understood by as.POSIXct() or as.Date(). overwrite logical scalar. If TRUE overwrite backups if a backup of the same name (usually due to timestamp collision) exists.
on_change_only	logical scalaror a list. Rotate only if object is different from the object saved in file. If a list, arguments that will be passed on to data.table::all.equal (only when both obects are data.tables)
age	minimum age after which to backup/rotate a file; can be a character scalar representing an Interval in the form "<number> <interval>" (e.g. "2 months", see Intervals section below). a Date or a character scalar representing a Date for a fixed point in time after which to backup/rotate. See format for which Date/Datetime formats are supported by rotor. (if age and size are provided, both criteria must be TRUE to trigger rotation)

Value

the path to file (invisibly)

Note

The default value for age is different for rotate_rds_date() (-1) than for rotate_date() (1) to make it a bit safer. This means if you execute rotate_date() twice on the same file on a given day it will silently not rotate the file, while rotate_rds_date() will throw an error.

Examples

dest <- tempfile()
rotate_rds(iris, dest)
rotate_rds(iris, dest)
rotate_rds(iris, dest)

list_backups(dest)

# cleanup
unlink(list_backups(dest))
unlink(dest)

s-fleck/rtdr documentation built on Oct. 18, 2022, 12:26 a.m.