Skip to content

Commit

Permalink
docs: minor: update descriptions of :continue (#162)
Browse files Browse the repository at this point in the history
As discussed on Slack: https://clojurians.slack.com/archives/CLX41ASCS/p1718798012312359?thread_ts=1718774256.150799&cid=CLX41ASCS

**me**
> @borkdude, I reviewed the babashka/process docs on this, and they are pretty good, but I guess they could be reworded slightly to be clearer.
Also, I noticed :continue is described in README but not in any docstring.
Would you like a small PR?

**you**
> yes please!
  • Loading branch information
lread authored Jun 25, 2024
1 parent b09c907 commit ae1656b
Show file tree
Hide file tree
Showing 2 changed files with 11 additions and 4 deletions.
9 changes: 6 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,16 +88,16 @@ This is particularly handy when you want to supply commands coming from the comm
(apply shell "ls -la" *command-line-args*)
```

The `shell` function checks the exit code and throws if it is non-zero:
The `shell` function checks the command's exit code and throws if it is non-zero:

``` clojure
user=> (shell "ls nothing")
ls: nothing: No such file or directory
Execution error (ExceptionInfo) at babashka.process/check (process.cljc:113).
```

To avoid throwing, you can use `:continue true`. You will still see the error
being printed to stderr, but no exception will be thrown. That is convenient
To avoid throwing when the command's exit code is non-zero, use `:continue true`.
You will still see the error printed to stderr, but no exception will be thrown. This is convenient
when you want to handle the `:exit` code yourself:

``` clojure
Expand All @@ -106,6 +106,9 @@ ls: nothing: No such file or directory
1
```

> Note that `:continue true` only suppresses throwing an exception when the executed command's exit code is non-zero.
> Other exceptions can throw, for example, when the executable is not found.
To collect output as a `:string`, use the `:out :string` option as the first argument:

``` clojure
Expand Down
6 changes: 5 additions & 1 deletion src/babashka/process.cljc
Original file line number Diff line number Diff line change
Expand Up @@ -638,14 +638,18 @@
(defn shell
"Convenience function around `process` that was originally in `babashka.tasks`.
Defaults to inheriting I/O: input is read and output is printed
while the process runs. Throws on non-zero exit codes. Kills all
while the process runs. Defaults to throwing on non-zero exit codes. Kills all
subprocesses on shutdown. Optional options map can be passed as the
first argument, followed by multiple command line arguments. The
first command line argument is automatically tokenized. Counter to
what the name of this function may suggest, it does not start a
new (bash, etc.) shell, it just shells out to a program. As such, it
does not support bash syntax like `ls *.clj`.
Supported options:
- `:continue`: if `true`, suppresses throwing on non-zero process exit code.
- see `process` for other options
Examples:
- `(shell \"ls -la\")` ;; `\"ls -la\"` is tokenized as `[\"ls\" \"-la\"]`
Expand Down

0 comments on commit ae1656b

Please sign in to comment.