Types

DebugOutputKind = enum dokCommand, dokError, dokOutput, dokRuntime: Source Edit
ShellExecError = ref object of CatchableError cmd*: string ## Command that returned non-zero exit code cwd*: string ## Absolute path of initial command execution directory retcode*: int ## Exit code errstr*: string ## Stderr for command outstr*: string ## Stdout for command: Source Edit

Procs

proc asgnShell(cmd: string; debugConfig: set[DebugOutputKind] = defaultDebugConfig; options: set[ProcessOption] = defaultProcessOptions): tuple[ output, error: string, exitCode: int] {...}{. raises: [OSError, Exception, IOError], tags: [ExecIOEffect, ReadEnvEffect, RootEffect, ReadIOEffect, TimeEffect, WriteIOEffect].}: wrapper around execCmdEx, which returns the output of the shell call as a string (stripped of n) Source Edit
proc execShell(cmd: string; debugConfig: set[DebugOutputKind] = defaultDebugConfig; options: set[ProcessOption] = defaultProcessOptions): tuple[ output, error: string, exitCode: int] {...}{. raises: [OSError, Exception, IOError], tags: [ExecIOEffect, ReadEnvEffect, RootEffect, ReadIOEffect, TimeEffect, WriteIOEffect].}: wrapper around asgnShell, which calls the commands and handles return values. Source Edit

Macros

macro shellVerbose(args: varargs[untyped]): untyped

See the shell macro below for a general explanation.

This macro differs from shell in as such that it

returns a tuple of

output: string <- output of the shell command to stdout

exitCode: int <- the exit code as an integer

allows to customize the error output behavior by handing the

argument debugConfig (see below) as well as the process options with which startProcess is called by using the options argument.

As you notice the macro signature is args: varargs[untyped]. This macro parses the given arguments manually (to allow multiple named arguments in an untyped macro). If the arguments are not named, they are expected in the order as shown below. combineOutAndErr has to be named!

The following arguments are possible:

debug, debugConfig: a set of DebugOutputKind
options, processOptions: a set of ProcessOption (see stdlib.osproc)
combineOutAndErr: a static bool to decide if the macro should return a 2 tuple of (output: string, errCode: int) (stderr is appended to stdout) or a 3 tuple of (output, outerr: string, errCode: int) (stderr separate) The latter can also be had by using the shellVerboseErr overload below.

Example:

let (res, code) = shellVerbose(debug = {dokCommand}, options = {poEvalCommand},
                               combineOutAndErr = true):
  echo "test"

assert res == "test"
assert code == 0

Source Edit

macro shellVerboseErr(args: varargs[untyped]): untyped

Run shell command, return (stdout, stderr, code). This is an overload of shellVerbose with combineOutAndErr = false by default.

Example:

let (res, err, code) = shellVerboseErr {dokCommand}:
  echo "test"

assert res == "test"
assert code == 0

Source Edit

macro shell(cmds: untyped): untyped

A mini DSL to write shell commands in Nim. Some constructs are not implemented. If in doubt, put (parts of) the command into " ".

The command is echoed before it is run. It is prefixed by

shellCmd:

If there is output, the output is echoed. Each successive line of the output is prefixed by

shell>

If multiple commands are run in succession (i.e. multiple statements in the macro body) and one command returns a non-zero exit code, the following commands will not be run. Instead a warning message will be shown.

For usage with NimScript the output can only be echoed after the call has finished.

The exit code of the command is dropped. If you wish to inspect the exit code, use shellVerbose above.

Source Edit

macro shellEcho(cmds: untyped): untyped

a helper macro around the proc that generates the shell commands to check whether the commands are as expected It echoes the commands at compile time (the representation of the command) and also the resulting string (taking into account potential) Nim symbol quoting at run time Source Edit

macro checkShell(cmds: untyped; exp: untyped): untyped

a wrapper around the shell macro, which can calls unittest.check to check whether construction of the commands works as expected Source Edit

macro shellAssign(cmd: untyped): untyped

Source Edit