While working on #202, I noticed that the gzip/gunzip API is perhaps a bit awkward.

Let's look at current fn signatures:

(gzip [source-file])
(gzip [source-file options])

options: :dir, :out-file

(gunzip [gz-file])
(gunzip [gz-file dest])
(gunzip [gz-file dest options])

options: :replace-existing

Observation A: If I want to :replace-existing gunzip file, I must also specify dest even if I am OK with the default.

(require '[babashka.fs :as fs])

(spit "foo" "foo")

(fs/gzip "foo")
;; => "./foo.gz"
(fs/gunzip "foo.gz")
;; => Execution error (FileAlreadyExistsException) at sun.nio.fs.UnixException/translateToIOException (UnixException.java:94).
;;    ./foo
(fs/gunzip "foo.gz" "." {:replace-existing true})

Impact: if interesting to address, a bit icky.
We could add a (gunzip [gz-file options]) where options now includes :dir.
I think we'd have to leave in what would now be legacy (gunzip [gz-file dest options]) and (gz-unzip [gz-file dest]) to avoid a breaking change.

Observation B: :replace-existing needed only for gunzip

gzip output file is always replaced.

(spit "foo" "foo")
(fs/gzip "foo")
;; => "./foo.gz"
(fs/gzip "foo")
;; => "./foo.gz"

Impact: if this is not considered a bug, it would be considered a breaking change.
If considered bug: easy fix would be to add :replace-existing to gzip options.

Observation C: The output dir is specified differently for gzip and gunzip

(fs/gzip "foo" {:dir "out"})
(fs/gunzip "out/foo.gz" "out")

Impact: see Observation A impact for one idea.

Observation D: gzip returns the created file, gunzip does not.

(fs/gzip "foo" {:dir "out"})
;; => "out/foo.gz"
(fs/gunzip "out/foo.gz" "./out")
;; => 3

Impact: easy fix.
Could consider return as Path like most other fns do.

Observation E: gzip allows a custom out-file name, gunzip does not.

(fs/gzip "foo" {:out-file "bar.gz"})
;; => "./bar.gz"
;; we can override dest dir for gunzip but not out-file name
(fs/gunzip "foo.gz" "out-dir")

Impact: easy fix by adding :out-file to gunzip options.

Option 0: Do nothing

These are quibbles, let's leave it as is.

Option 1: Tweak docstrings to describe nuances more clearly

Option 2: Cherry-pick easy wins

Observation B - add and honour :replace-existing to gzip options
Observation D - return created file for gunzip.
Observation E - add optional :out-file to options for gunzip

Option 3: Make existing fn args more synchronous

This address Observations A and C.

gzip signature remains the same.

gzunzip perserves:

(gunzip [gz-file])
(gunzip [gz-file dest])
(gunzip [gz-file dest options])

But also adds

(gunzip [gz-file options])

Documentation is removed for dest variants but preserved for backwards compatibility.
(We could document legacy signatures as deprecated, but unsure if individual fn arities can be ^:deprecated?)

options for both gzip and gunzip now both have:
:dir :out-file

Another option is to add a gunzip2 but that's not so nice for usability.

Proposal

Resolve in multiple PRs
Step1) Option 2 - Observation D - return created file for gunzip.
Step2) Option 2 - Observation E - add out-file to gunzip options.
Step3) Option 2 - If ok with what might be considered breaking: Observation B - add/honour replace-existing to gzip options
Step4) Optinally Tackle Option 3, which addresses

• Observation A - specifying options on gunzip means I must specify dest dir
• Observation C - output dir is specified differently for gzip and gunzip.

Whatcha think?