auto-build.os.cmd — org.clojars.hephaistox/auto-build 0.0.2

Execute an external command, called cmd.

cmd are made of a vector of strings like ["ls" "-la"]

There are many flavors to execute this command, the generic one made of create-process, wait-for, ... and the helpers to simplify some typical use cases.

All functions deal with a process, a map describing the command execution and then enriched as the process is going on.

as-string clj

(as-string cmd dir)

(as-string cmd dir max-out-lines max-err-lines)

Returns only data in process, as strings

create-process clj

(create-process cmd
                dir
                on-out
                on-err
                on-end
                delay
                cant-start
                max-out-lines
                max-err-lines)

Starts the execution of the command cmd in directory dir and store command outputs in atoms respectively named in :out-stream and :err-stream. To save resources, if the stream is empty a pause of delay milliseconds is waited before checking again Only max-out-lines and max-err-lines are stored in the atoms, if nil no value is stored at all.

It's a non blocking function, next step could be still-running?, wait-for or kill.

Returns a process with:

• :cmd the command, e.g. ["ls" "-la"]

• :cmd-str the command as a string e.g. ls -la

• :dir the directory as provided by the user, e.g. ""

• :status is a value among :wip, :didnt-start, :success, :fail

• :adir the expanded directory (useful for debug), e.g. "/User/johndoe/hephaistox"

• If the command starts successfully, it returns also

  • :status = :wip
  • :bb-proc the babashka process, normally for internal use only
  • out-stream a fixed size queue of lines to print on out stream
  • err-stream a fixed size queue of lines to print on err stream

• If not - most probably if directory or command does not exist - returns a process with

  • status=:cmd-doesnt-exist
  • and prints an error message

cant-start is executed if the command execution can't start. on-end will be executed once, at the end of an execution

exec-cmd clj

(exec-cmd cmd)

Returns the string of the execution of a command cmd

final-cmd clj

(final-cmd {:keys [status] :as _res}
           {:keys [subtitle title] :as _printers}
           message
           end-message)

Returns the status and print the message if status is successful

kill clj

(kill {:keys [bb-proc cmd-str] :as process} on-out)

Kill process if it is still running

Returns process with killed.

muted clj

(muted cmd dir)

When only exit code is useful.

Print nothing, even errors, is blocking.

muted-non-blocking clj

(muted-non-blocking cmd dir)

When only side effects are important, no feedback on terminal. Most probably elsewhere

parameterize clj

(parameterize cmd)

Turns cmd to a cmd parameter

print-on-error clj

(print-on-error cmd dir on-out on-err delay max-out-lines max-err-lines)

Does not print on the terminal, except if an error occur.

print-verbosely clj

(print-verbosely verbose
                 cmd
                 dir
                 on-out
                 on-err
                 delay
                 max-out-lines
                 max-err-lines)

printing clj

(printing cmd dir on-out on-err delay)

Print the whole command execution on the terminal. Is blocking until the end.

printing-non-blocking clj

(printing-non-blocking cmd dir on-out on-err on-end delay)

When a command should be printed on the terminal, like a REPL, a compilation, ....

This command is non blocking

still-running? clj

(still-running? process)

Returns true if the process is still living?

to-str clj

(to-str cmd)

Turns cmd into an executable command

wait-for clj

(wait-for {:keys [bb-proc cmd out-stream err-stream status] :as process}
          on-out
          on-err)

Block the current thread execution until the end of process.

This function is noop if the status is different from :wip

Otherwise, the process is executed, if it is failing:

• functions out-print-ln and on-err are called with (on-out line). That functions could be nil.

Returns the process with out-stream and err-stream turned into vector of strings.

when-success? clj

(when-success? {:keys [status] :as _res}
               {:keys [subtitle] :as printers}
               message)

Returns printers if res is successful, nil otherwise