babashka.process — babashka/process 0.5.22

Clojure library for shelling out / spawning sub-processes. If you are not yet familiar with the API, start reading the docstrings for process and shell.

$ clj macro

($ opts? & args)

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* clj

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

alive? clj

(alive? p)

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

check clj

(check proc)

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

destroy clj

(destroy proc)

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

destroy-tree clj

(destroy-tree proc)

Same as destroy but also destroys all descendants. JDK9+ only. Falls back to destroy on older JVM versions.

exec clj

(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 (which includes babashka).

Supported opts

• :arg0: override first argument (the executable). No-op on Windows.
• :cmd, :env,:extra-env, :escape,:pre-start-fn : see process.

parse-args clj

(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

Note that this function bridges the legacy [cmds ?opts] syntax to the newer recommended syntax [?opts & args] and therefore looks unnecessarily complex.

pb clj

(pb & args)

Returns a process builder (as record).

pipeline clj

(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 clj

(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:

• :cmd: a vector of strings. A single string can be tokenized into a vector of strings with tokenize. Overrides the variadic args argument.
• :in, :out, :err: objects compatible with clojure.java.io/copy that will be copied to 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 and :bytes for writing to a byte array. You will need to deref the process before accessing the string or byte array via the process's :out. To redirect :err to :out, specify :err :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.
• :prev: output from :prev will be piped to the input of this process. Overrides :in.
• :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* clj

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

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

sh clj

(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 clj

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

Examples:

• (shell "ls -la") ;; "ls -la" is tokenized as ["ls" "-la"]
• (shell {:out "/tmp/log.txt"} "git commit -m" "WIP") ;; "git commit -m" is tokenized as ["git" "commit" "-m"] and "WIP" is an additional argument

Also see the shell entry in the babashka book here.

start clj

(start pb)

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

tokenize clj

(tokenize s)

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