archive_write {archive}

Create a writable connection to a file in an archive.

Description

Create a writable connection to a file in an archive.

Usage

archive_write(
  archive,
  file,
  mode = "w",
  format = NULL,
  filter = NULL,
  options = character()
)

Arguments

archive

character(1) The archive filename or an archive object.

file

character(1) || integer(1) The filename within the archive, specified either by filename or by position.

mode

character(1) A description of how to open the connection (if it should be opened initially). See section ‘Modes’ in base::connections() for possible values.

format

character(1) default: NULL The archive format, one of ‘7zip’, ‘cab’, ‘cpio’, ‘iso9660’, ‘lha’, ‘mtree’, ‘shar’, ‘rar’, ‘raw’, ‘tar’, ‘xar’, ‘zip’, ‘warc’.

filter

character(1) default: NULL The archive filter, one of ‘none’, ‘gzip’, ‘bzip2’, ‘compress’, ‘lzma’, ‘xz’, ‘uuencode’, ‘lzip’, ‘lrzip’, ‘lzop’, ‘grzip’, ‘lz4’, ‘zstd’.

options

character() default: character(0) Options to pass to the filter or format. The list of available options are documented in options can have one of the following forms:

• option=value The option/value pair will be provided to every module. Modules that do not accept an option with this name will ignore it.

• option The option will be provided to every module with a value of "1".

• !option The option will be provided to every module with a NULL value.

• module:option=value, module:option, module:!option As above, but the corresponding option and value will be provided only to modules whose name matches module. See read options for available read options See write options for available write options

Details

If format and filter are NULL, they will be set automatically based on the file extension given in file when writing and automatically detected using Robust automatic format detection when reading.

For traditional zip archives archive_write() creates a connection which writes the data to the specified file directly. For other archive formats the file size must be known when the archive is created, so the data is first written to a scratch file on disk and then added to the archive. This scratch file is automatically removed when writing is complete.

Value

An 'archive_write' connection to the file within the archive to be written.

Examples

# Archive format and filters can be set automatically from the file extensions.
f1 <- tempfile(fileext = ".tar.gz")

write.csv(mtcars, archive_write(f1, "mtcars.csv"))
archive(f1)
unlink(f1)

# They can also be specified explicitly
f2 <- tempfile()
write.csv(mtcars, archive_write(f2, "mtcars.csv", format = "tar", filter = "bzip2"))
archive(f2)
unlink(f2)

# You can also pass additional options to control things like compression level
f3 <- tempfile(fileext = ".tar.gz")
write.csv(mtcars, archive_write(f3, "mtcars.csv", options = "compression-level=2"))
archive(f3)
unlink(f3)