Title: | Cross-Platform 'zip' Compression |
Version: | 2.3.3 |
Description: | Cross-Platform 'zip' Compression Library. A replacement for the 'zip' function, that does not require any additional external tools on any platform. |
License: | MIT + file LICENSE |
URL: | https://github.com/r-lib/zip, https://r-lib.github.io/zip/ |
BugReports: | https://github.com/r-lib/zip/issues |
Suggests: | covr, pillar, processx, R6, testthat, withr |
Config/Needs/website: | tidyverse/tidytemplate |
Config/testthat/edition: | 3 |
Config/usethis/last-upkeep: | 2025-05-07 |
Encoding: | UTF-8 |
RoxygenNote: | 7.3.2.9000 |
NeedsCompilation: | yes |
Packaged: | 2025-05-13 13:31:44 UTC; gaborcsardi |
Author: | Gábor Csárdi [aut, cre],
Kuba Podgórski [ctb],
Rich Geldreich [ctb],
Posit Software, PBC |
Maintainer: | Gábor Csárdi <csardi.gabor@gmail.com> |
Repository: | CRAN |
Date/Publication: | 2025-05-13 14:10:02 UTC |
zip: Cross-Platform 'zip' Compression
Description
Cross-Platform 'zip' Compression Library. A replacement for the 'zip' function, that does not require any additional external tools on any platform.
Author(s)
Maintainer: Gábor Csárdi csardi.gabor@gmail.com
Other contributors:
Kuba Podgórski [contributor]
Rich Geldreich [contributor]
Posit Software, PBC (ROR) [copyright holder, funder]
See Also
Useful links:
Report bugs at https://github.com/r-lib/zip/issues
Compress a raw GZIP stream
Description
Compress a raw GZIP stream
Usage
deflate(buffer, level = 6L, pos = 1L, size = NULL)
Arguments
buffer |
Raw vector, containing the data to compress. |
level |
Compression level, integer between 1 (fatest) and 9 (best). |
pos |
Start position of data to compress in |
size |
Compressed size estimate, or |
Value
Named list with three entries:
-
output
: raw vector, the compressed data, -
bytes_read
: number of bytes used frombuffer
, -
bytes_written
: number of bytes written to the output buffer.
See Also
base::memCompress()
does the same with type = "gzip"
,
but it does not tell you the number of bytes read from the input.
Examples
data_gz <- deflate(charToRaw("Hello world!"))
inflate(data_gz$output)
Uncompress a raw GZIP stream
Description
Uncompress a raw GZIP stream
Usage
inflate(buffer, pos = 1L, size = NULL)
Arguments
buffer |
Raw vector, containing the data to uncompress. |
pos |
Start position of data to uncompress in |
size |
Uncompressed size estimate, or |
Value
Named list with three entries:
-
output
: raw vector, the uncompressed data, -
bytes_read
: number of bytes used frombuffer
, -
bytes_written
: number of bytes written to the output buffer.
See Also
base::memDecompress()
does the same with type = "gzip"
,
but it does not tell you the number of bytes read from the input.
Examples
data_gz <- deflate(charToRaw("Hello world!"))
inflate(data_gz$output)
Uncompress 'zip' Archives
Description
unzip()
always restores modification times of the extracted files and
directories.
Usage
unzip(zipfile, files = NULL, overwrite = TRUE, junkpaths = FALSE, exdir = ".")
Arguments
zipfile |
Path to the zip file to uncompress. |
files |
Character vector of files to extract from the archive.
Files within directories can be specified, but they must use a forward
slash as path separator, as this is what zip files use internally.
If |
overwrite |
Whether to overwrite existing files. If |
junkpaths |
Whether to ignore all directory paths when creating
files. If |
exdir |
Directory to uncompress the archive to. If it does not exist, it will be created. |
Permissions
If the zip archive stores permissions and was created on Unix, the permissions will be restored.
Examples
## temporary directory, to avoid messing up the user's workspace.
dir.create(tmp <- tempfile())
dir.create(file.path(tmp, "mydir"))
cat("first file", file = file.path(tmp, "mydir", "file1"))
cat("second file", file = file.path(tmp, "mydir", "file2"))
zipfile <- tempfile(fileext = ".zip")
zip::zip(zipfile, "mydir", root = tmp)
## List contents
zip_list(zipfile)
## Extract
tmp2 <- tempfile()
unzip(zipfile, exdir = tmp2)
dir(tmp2, recursive = TRUE)
Class for an external unzip process
Description
unzip_process()
returns an R6 class that represents an unzip process.
It is implemented as a subclass of processx::process.
Usage
unzip_process()
Value
An unzip_process
R6 class object, a subclass of
processx::process.
Using the unzip_process
class
up <- unzip_process()$new(zipfile, exdir = ".", poll_connection = TRUE, stderr = tempfile(), ...)
See processx::process for the class methods.
Arguments:
-
zipfile
: Path to the zip file to uncompress. -
exdir
: Directory to uncompress the archive to. If it does not exist, it will be created. -
poll_connection
: passed to theinitialize
method of processx::process, it allows usingprocessx::poll()
or thepoll_io()
method to poll for the completion of the process. -
stderr
: passed to theinitialize
method of processx::process, by default the standard error is written to a temporary file. This file can be used to diagnose errors if the process failed. -
...
passed to theinitialize
method of processx::process.
Examples
ex <- system.file("example.zip", package = "zip")
tmp <- tempfile()
up <- unzip_process()$new(ex, exdir = tmp)
up$wait()
up$get_exit_status()
dir(tmp)
Compress Files into 'zip' Archives
Description
zip()
creates a new zip archive file.
Usage
zip(
zipfile,
files,
recurse = TRUE,
compression_level = 9,
include_directories = TRUE,
root = ".",
mode = c("mirror", "cherry-pick")
)
zipr(
zipfile,
files,
recurse = TRUE,
compression_level = 9,
include_directories = TRUE,
root = ".",
mode = c("cherry-pick", "mirror")
)
zip_append(
zipfile,
files,
recurse = TRUE,
compression_level = 9,
include_directories = TRUE,
root = ".",
mode = c("mirror", "cherry-pick")
)
zipr_append(
zipfile,
files,
recurse = TRUE,
compression_level = 9,
include_directories = TRUE,
root = ".",
mode = c("cherry-pick", "mirror")
)
Arguments
zipfile |
The zip file to create. If the file exists, |
files |
List of file to add to the archive. See details below about absolute and relative path names. |
recurse |
Whether to add the contents of directories recursively. |
compression_level |
A number between 1 and 9. 9 compresses best, but it also takes the longest. |
include_directories |
Whether to explicitly include directories
in the archive. Including directories might confuse MS Office when
reading docx files, so set this to |
root |
Change to this working directory before creating the archive. |
mode |
Selects how files and directories are stored in
the archive. It can be |
Details
zip_append()
appends compressed files to an existing 'zip' file.
Relative paths
zip()
and zip_append()
can run in two different modes: mirror
mode and cherry picking mode. They handle the specified files
differently.
Mirror mode
Mirror mode is for creating the zip archive of a directory structure,
exactly as it is on the disk. The current working directory will
be the root of the archive, and the paths will be fully kept.
zip changes the current directory to root
before creating the
archive.
E.g. consider the following directory structure:
. |-- foo | |-- bar | | |-- file1 | | `-- file2 | `-- bar2 `-- foo2 `-- file3
Assuming the current working directory is foo
, the following zip
entries are created by zip
:
setwd("foo") zip::zip("../test.zip", c("bar/file1", "bar2", "../foo2")) #> Warning in warn_for_dotdot(data$key): Some paths reference parent directory, #> creating non-portable zip file zip_list("../test.zip")[, "filename", drop = FALSE] #> # A data frame: 4 x 1 #> filename #> <chr> #> 1 bar/file1 #> 2 bar2/ #> 3 ../foo2/ #> 4 ../foo2/file3
Note that zip refuses to store files with absolute paths, and chops
off the leading /
character from these file names. This is because
only relative paths are allowed in zip files.
Cherry picking mode
In cherry picking mode, the selected files and directories will be at the root of the archive. This mode is handy if you want to select a subset of files and directories, possibly from different paths and put all of the in the archive, at the top level.
Here is an example with the same directory structure as above:
zip::zip( "../test2.zip", c("bar/file1", "bar2", "../foo2"), mode = "cherry-pick" ) zip_list("../test2.zip")[, "filename", drop = FALSE] #> # A data frame: 4 x 1 #> filename #> <chr> #> 1 file1 #> 2 bar2/ #> 3 foo2/ #> 4 foo2/file3
From zip version 2.3.0, "."
has a special meaning in the files
argument: it will include the files (and possibly directories) within
the current working directory, but not the working directory itself.
Note that this only applies to cherry picking mode.
Permissions:
zip()
(and zip_append()
, etc.) add the permissions of
the archived files and directories to the ZIP archive, on Unix systems.
Most zip and unzip implementations support these, so they will be
recovered after extracting the archive.
Note, however that the owner and group (uid and gid) are currently omitted, even on Unix.
zipr()
and zipr_append()
These function exist for historical reasons. They are identical
to zip()
and zipr_append()
with a different default for the
mode
argument.
Value
The name of the created zip file, invisibly.
Examples
## Some files to zip up. We will run all this in the R session's
## temporary directory, to avoid messing up the user's workspace.
dir.create(tmp <- tempfile())
dir.create(file.path(tmp, "mydir"))
cat("first file", file = file.path(tmp, "mydir", "file1"))
cat("second file", file = file.path(tmp, "mydir", "file2"))
zipfile <- tempfile(fileext = ".zip")
zip::zip(zipfile, "mydir", root = tmp)
## List contents
zip_list(zipfile)
## Add another file
cat("third file", file = file.path(tmp, "mydir", "file3"))
zip_append(zipfile, file.path("mydir", "file3"), root = tmp)
zip_list(zipfile)
List Files in a 'zip' Archive
Description
List Files in a 'zip' Archive
Usage
zip_list(zipfile)
Arguments
zipfile |
Path to an existing ZIP file. |
Details
Note that crc32
is formatted using as.hexmode()
. offset
refers
to the start of the local zip header for each entry. Following the approach
of seek()
it is stored as a numeric
rather than an integer
vector and
can therefore represent values up to 2^53-1
(9 PB).
Value
A data frame with columns: filename
, compressed_size
,
uncompressed_size
, timestamp
, permissions
, crc32
, offset
and
type
. type
is one of file
, block_device
, character_device
,
directory
, FIFO
, symlink
or socket
.
Class for an external zip process
Description
zip_process()
returns an R6 class that represents a zip process.
It is implemented as a subclass of processx::process.
Usage
zip_process()
Value
A zip_process
R6 class object, a subclass of
processx::process.
Using the zip_process
class
zp <- zip_process()$new(zipfile, files, recurse = TRUE, poll_connection = TRUE, stderr = tempfile(), ...)
See processx::process for the class methods.
Arguments:
-
zipfile
: Path to the zip file to create. -
files
: List of file to add to the archive. Each specified file or directory in is created as a top-level entry in the zip archive. -
recurse
: Whether to add the contents of directories recursively. -
include_directories
: Whether to explicitly include directories in the archive. Including directories might confuse MS Office when reading docx files, so set this toFALSE
for creating them. -
poll_connection
: passed to theinitialize
method of processx::process, it allows usingprocessx::poll()
or thepoll_io()
method to poll for the completion of the process. -
stderr
: passed to theinitialize
method of processx::process, by default the standard error is written to a temporary file. This file can be used to diagnose errors if the process failed. -
...
passed to theinitialize
method of processx::process.
Examples
dir.create(tmp <- tempfile())
write.table(iris, file = file.path(tmp, "iris.ssv"))
zipfile <- tempfile(fileext = ".zip")
zp <- zip_process()$new(zipfile, tmp)
zp$wait()
zp$get_exit_status()
zip_list(zipfile)