API.md

Table of contents

• babashka.process - Shell out in Clojure with simplicity and ease.
  • $ - Convenience macro around process.
  • *defaults* - Dynamic var containing overridable default options.
  • alive? - Returns true if the process is still running and false otherwise.
  • check - Takes a process, waits until is finished and throws if exit code is non-zero.
  • destroy - Destroys the process and returns the input arg.
  • destroy-tree - Same as destroy but also destroys all descendants.
  • exec - Replaces the current process image with the process image specified by the given path invoked with the given args.
  • parse-args - Parses arguments to process to map with: * :prev: a (previous) process whose input is piped into the current process * :cmd: a vector of command line argument strings * :opts: options map.
  • pb - Returns a process builder (as record).
  • pipeline - Returns the processes for one pipe created with -> or creates pipeline from multiple process builders.
  • process - Creates a child process.
  • process* - Same as with process but called with parsed arguments (the result from parse-args).
  • sh - Convenience function similar to clojure.java.shell/sh that sets :out and :err to :string by default and blocks.
  • shell - Convenience function around process that was originally in babashka.tasks.
  • start - Takes a process builder, calls start and returns a process (as record).
  • tokenize - Tokenize string to list of individual space separated arguments.

---

babashka.process

Shell out in Clojure with simplicity and ease. If you are not yet familiar with the API, start reading the docstrings for process and shell.

$ 📃

($ opts? & args)

Macro.

Convenience macro around process. Takes command as varargs. Options can be passed via metadata on the form or as a first map arg. Supports interpolation via ~

*defaults* 📃

Dynamic var containing overridable default options. Use alter-var-root to change permanently or binding to change temporarily.

alive? 📃

(alive? p)

Returns true if the process is still running and false otherwise.

check 📃

(check proc)

Takes a process, waits until is finished and throws if exit code is non-zero.

destroy 📃

(destroy proc)

Destroys the process and returns the input arg. Takes process or map with :proc (java.lang.ProcessBuilder).

destroy-tree 📃

(destroy-tree proc)

Same as [destroy](#babashka.process/destroy) but also destroys all descendants. JDK9+ only. Falls back to [destroy](#babashka.process/destroy) on older JVM versions.

exec 📃

(exec opts? & args)

Replaces the current process image with the process image specified by the given path invoked with the given args. Works only in GraalVM native images. Override the first argument using :arg0.

parse-args 📃

(parse-args args)

Parses arguments to process to map with:

• :prev: a (previous) process whose input is piped into the current process
• :cmd: a vector of command line argument strings
• :opts: options map

pb 📃

(pb & args)

Returns a process builder (as record).

pipeline 📃

(pipeline proc)
(pipeline pb & pbs)

Returns the processes for one pipe created with -> or creates pipeline from multiple process builders.

• When passing a process, returns a vector of processes of a pipeline created with -> or pipeline.
• When passing two or more process builders created with pb: creates a pipeline as a vector of processes (JDK9+ only).

Also see Pipelines.

process 📃

(process opts? & args)

Creates a child process. Takes a command (vector of strings or objects that will be turned into strings) and optionally a map of options.

Returns: a record with:

• :proc: an instance of java.lang.Process
• :in, :err, :out: the process's streams. To obtain a string from :out or :err you will typically use slurp or use the :string option (see below). Slurping those streams will block the current thread until the process is finished.
• :cmd: the command that was passed to create the process.
• :prev: previous process record in case of a pipeline.

The returned record can be passed to deref. Doing so will cause the current thread to block until the process is finished and will populate :exit with the exit code.

Supported options:

• :in, :out, :err: objects compatible with clojure.java.io/copy that will be copied to or from the process's corresponding stream. May be set to :inherit for redirecting to the parent process's corresponding stream. Optional :in-enc, :out-enc and :err-enc values will be passed along to clojure.java.io/copy. For redirecting to Clojure's *in*, *out* or *err* stream, set the corresponding option accordingly. The :out and :err options support :string for writing to a string output. You will need to deref the process before accessing the string via the process's :out. For writing output to a file, you can set :out and :err to a java.io.File object, or a keyword:
  • :write + an additional :out-file/:err-file + file to write to the file.
  • :append + an additional :out-file/:err-file + file to append to the file.
• :inherit: if true, sets :in, :out and :err to :inherit.
• :dir: working directory.
• :env, :extra-env: a map of environment variables. See Add environment.
• :escape: function that will applied to each stringified argument. On Windows this defaults to prepending a backslash before a double quote. On other operating systems it defaults to identity.
• :pre-start-fn: a one-argument function that, if present, gets called with a map of process info just before the process is started. Can be useful for debugging or reporting. Any return value from the function is discarded. Map contents:
  • :cmd - a vector of the tokens of the command to be executed (e.g. ["ls" "foo"])
• :shutdown: shutdown hook, defaults to nil. Takes process map. Typically used with destroy or destroy-tree to ensure long running processes are cleaned up on shutdown.
• :exit-fn: a function which is executed upon exit. Receives process map as argument. Only supported in JDK11+.

process* 📃

(process* {:keys [prev cmd opts]})

Same as with process but called with parsed arguments (the result from parse-args)

sh 📃

(sh opts? & args)

Convenience function similar to clojure.java.shell/sh that sets :out and :err to :string by default and blocks. Similar to cjs/sh it does not check the exit code (this can be done with check).

shell 📃

(shell opts? & args)

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 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.

Examples:

• (shell "ls -la")
• (shell {:out "/tmp/log.txt"} "git commit -m" "WIP")

Also see the shell entry in the babashka book here.

start 📃

(start pb)

Takes a process builder, calls start and returns a process (as record).

tokenize 📃

(tokenize s)

Tokenize string to list of individual space separated arguments. If argument contains space you can wrap it with ' or ".