#lang scribble/manual

@(require (for-label package-zipper
                     racket/base
                     racket/contract/base))

@title{Package Zipper}
@author{Hans Dijkema}

@defmodule[package-zipper]

@defproc[(zip-package [directory path-string? (current-directory)]
                      [#:exclude exclude
                       (listof (or/c string? path? regexp? byte-regexp?))
                       null])
         path?]{

Reads @filepath{info.rkt} in @racket[directory], obtains its
@racket['version] value, and creates a ZIP archive in the parent directory.

The output filename is formed from the package directory name and version. For
example, package directory @filepath{racket-upnp} with version @tt{5.0} produces
@filepath{racket-upnp-5.0.zip}.

The directory is archived recursively. The following paths are omitted:

@itemlist[
 @item{@filepath{.git} directories and files}
 @item{@filepath{compiled} directories and files}
 @item{names ending in @tt{~}}
 @item{names ending in @tt{.bak}, without regard to case}
 @item{@tt{.html}, @tt{.js}, and @tt{.css} files below directories named
       @filepath{scribblings}, @filepath{scribbles}, or @filepath{scrbl},
       without regard to case}
]

The optional @racket[exclude] list adds exclusions. A string matches an equal
file or directory name anywhere in the relative path. A relative path value
matches that path and everything below it. A regular expression is applied to
the complete relative path, with @litchar{/} as the path separator. Custom
string and path comparisons are case-sensitive.

For example:

@racketblock[
(zip-package
 #:exclude
 (list "tmp"
       (string->path "examples/generated")
       #rx"^tests/data/"))
]

The package files are stored at the root of the archive. An existing archive
with the same name is replaced. The resulting complete path is returned.
}