▼File:   Racket File and Format Libraries
On this page:
unzip
call-with-unzip
make-filesystem-entry-reader
read-zip-directory
zip-directory?
zip-directory-entries
zip-directory-contains?
zip-directory-includes-directory?
unzip-entry
call-with-unzip-entry
path->zip-path
exn:  fail:  unzip:  no-such-entry
  top  ← prev  up  next → 

5 zip File Extraction

David Herman

 (require file/unzip) package: base
The file/unzip library provides a function to extract items from a zip archive.

procedure

(unzip in    
  [entry-reader    
  #:preserve-timestamps? preserve-timestamps?    
  #:utc-timestamps? utc-timestamps?]) → void?
  in : (or/c path-string? input-port?)
  entry-reader : 
(if preserve-timestamps?
    (bytes? boolean? input-port? (or/c #f exact-integer?)
     . -> . any)
    (bytes? boolean? input-port? . -> . any))
   = (make-filesystem-entry-reader)
  preserve-timestamps? : any/c = #f
  utc-timestamps? : any/c = #f
Unzips an entire zip archive from in.

For each entry in the archive, the entry-reader procedure is called with three or four arguments: the byte string representing the entry name, a boolean flag indicating whether the entry represents a directory, an input port containing the inflated contents of the entry, and (if preserve-timestamps?) #f or a timestamp for a file. The default entry-reader unpacks entries to the filesystem; call make-filesystem-entry-reader to configure aspects of the unpacking, such as the destination directory.

Normally, zip archives record modification dates in local time, but if utc-timestamps? is true, then the time in the archive is interpreted as UTC.

Changed in version 6.0.0.3 of package base: Added the #:preserve-timestamps? argument. Changed in version 6.0.1.12: Added the #:utc-timestamps? argument.

procedure

(call-with-unzip in proc) → any

  in : (or/c path-string? input-port?)
  proc : (-> path-string? any)
Unpacks in to a temporary directory, calls proc on the temporary directory’s path, and then deletes the temporary directory while returning the result of proc.

Added in version 6.0.1.6 of package base.

procedure

(make-filesystem-entry-reader [#:dest dest-path 
  #:strip-count strip-count 
  #:permissive? permissive? 
  #:exists exists]) 
 → 
((bytes? boolean? input-port?) ((or/c #f exact-integer?))
 . ->* . any)
  dest-path : (or/c path-string? #f) = #f
  strip-count : exact-nonnegative-integer? = 0
  permissive? : any/c = #f
  exists : 
(or/c 'skip 'error 'replace 'truncate
      'truncate/replace 'append 'update
      'can-update 'must-truncate)
 = 'error
Creates a zip entry reader that can be used with either unzip or unzip-entry and whose behavior is to save entries to the local filesystem. Intermediate directories are always created if necessary before creating files. Directory entries are created as directories in the filesystem, and their entry contents are ignored.

If dest-path is not #f, every path in the archive is prefixed to determine the destination path of the extracted entry.

If strip-count is positive, then strip-count path elements are removed from the entry path from the archive (before prefixing the path with dest-path); if the item’s path contains strip-count elements, then it is not extracted.

Unless permissive? is true, then entries with paths containing an up-directory indicator are disallowed, and a link entry whose target is an absolute path or contains an up-directory indicator is also disallowed. Absolute paths are always disallowed. A disallowed path triggers an exception.

If exists is 'skip and the file for an entry already exists, then the entry is skipped. Otherwise, exists is passed on to open-output-file for writing the entry’s inflated content.

Changed in version 6.0.0.3 of package base: Added support for the optional timestamp argument in the result function. Changed in version 6.3: Added the #:permissive? argument.

procedure

(read-zip-directory in) → zip-directory?

  in : (or/c path-string? input-port?)
Reads the central directory of a zip file and generates a zip directory representing the zip file’s contents. If in is an input port, it must support position setting via file-position.

This procedure performs limited I/O: it reads the list of entries from the zip file, but it does not inflate any of their contents.

procedure

(zip-directory? v) → boolean?

  v : any/c
Returns #t if v is a zip directory, #f otherwise.

procedure

(zip-directory-entries zipdir) → (listof bytes?)

  zipdir : zip-directory?
Extracts the list of entries for a zip archive.

procedure

(zip-directory-contains? zipdir name) → boolean?

  zipdir : zip-directory?
  name : (or/c bytes? path-string?)
Determines whether the given entry name occurs in the given zip directory. If name is not a byte string, it is converted using path->zip-path.

Directory entries match with or without trailing slashes.

procedure

(zip-directory-includes-directory? zipdir    
  name) → boolean?
  zipdir : zip-directory?
  name : (or/c bytes? path-string?)
Determines whether the given name is included anywhere in the given zip directory as a filesystem directory, either as an entry itself or as the containing directory of other entries. If name is not a byte string, it is converted using path->zip-path.

procedure

(unzip-entry in 
  zipdir 
  entry 
  [entry-reader 
  #:preserve-timestamps? preserve-timestamps? 
  #:utc-timestamps? utc-timestamps?]) 
 → void?
  in : (or/c path-string? input-port?)
  zipdir : zip-directory?
  entry : (or/c bytes? path-string?)
  entry-reader : 
(if preserve-timestamps?
    (bytes? boolean? input-port? (or/c #f exact-integer?)
     . -> . any)
    (bytes? boolean? input-port? . -> . any))
   = (make-filesystem-entry-reader)
  preserve-timestamps? : any/c = #f
  utc-timestamps? : any/c = #f
Unzips a single entry from a zip archive based on a previously read zip directory, zipdir, from read-zip-directory. If in is an input port, it must support position setting via file-position.

The entry parameter is a byte string whose name must be found in the zip file’s central directory. If entry is not a byte string, it is converted using path->zip-path.

The read-entry argument is used to read the contents of the zip entry in the same way as for unzip.

If entry is not in zipdir, an exn:fail:unzip:no-such-entry exception is raised.

Changed in version 6.0.0.3 of package base: Added the #:preserve-timestamps? argument. Changed in version 6.0.1.12: Added the #:utc-timestamps? argument.

procedure

(call-with-unzip-entry [in] entry proc) → any

  in : path-string? = input-port
  entry : path-string?
  proc : (-> path-string? any)
Unpacks entry within in to a temporary directory, calls proc on the unpacked file’s path, and then deletes the temporary directory while returning the result of proc.

Added in version 6.0.1.6 of package base.

procedure

(path->zip-path path) → bytes?

  path : path-string?
Converts a file name potentially containing path separators in the current platform’s format to use path separators recognized by the zip file format: /.

struct

(struct exn:fail:unzip:no-such-entry exn:fail (entry)
    #:extra-constructor-name make-exn:fail:unzip:no-such-entry)
  entry : bytes?
Raised when a requested entry cannot be found in a zip archive. The entry field is a byte string representing the requested entry name.

  top  ← prev  up  next →