Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the cmd Reference Manual, version 0.0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Dec 22 13:07:37 2020 GMT+0.
| • Introduction | What cmd is all about | |
| • Systems | The systems documentation | |
| • Files | The files documentation | |
| • Packages | The packages documentation | |
| • Definitions | The symbols documentation | |
| • Indexes | Concepts, functions, variables and data types |
A utility for running external programs, built on UIOP.
Cmd is designed to:
Arguments to cmd are never passed to a shell for interpretation.
Arguments are handled as follows:
A string is tokenized (using cl-shlex) and added to the list of arguments.
(cmd "ls -al")
≡ (uiop:run-program '("ls" "-al"))
(cmd "echo 'hello world'")
≡ (uiop:run-program '("echo" "hello world"))
A list of strings is added directly to the list of arguments (not tokenized). (Putting a string in a list is “escaping” it.)
(cmd "bash -c 'exit 1'")
≡ (cmd "bash -c" '("exit 1"))
A literal keyword, along with the next value, is passed through as a keyword argument to UIOP.
(cmd "bash -c 'exit 1'" :ignore-error-status t)
≡ (cmd :ignore-error-status t "bash -c 'exit 1'")
≡ (cmd "bash -c" :ignore-error-status t '("exit 1"))
≡ (uiop:run-program '("bash" "-c" "exit 1") :ignore-error-status t)
Note that unlike normal Lisp functions, keyword arguments can appear anywhere, not just at the end.
Any other string, integer, or pathname is directly added to the list
of arguments. (It is an error if a pathname begins with -.)
Cmd is designed with multi-threaded programs in mind. It always runs
programs with their working directory relative to
*default-pathname-defaults*. This is because the OS-level
working directory a program, on both Windows and Unix, is the working
directory of the entire process, not the individual thread, and
changing it changes it for all threads.
You can also specify the directory for a particular command with the
keyword argument :in:
(cmd "ls" :in #p"/")
(cmd :in #p"/" "ls")
=> /bin /home /tmp /usr ...
The cmd package offers several entry points:
cmd runs an external program synchronously, returning the exit
code. By default, on a non-zero exit it signals an error.
(cmd "cat /etc/os-release")
NAME="Ubuntu" [...]
=> 0
$cmd returns the output of the external program as a string,
stripping any trailing newline. (Much like $(cmd) in a shell.)
($cmd "date")
=> "Sun Sep 27 15:43:01 CDT 2020"
cmd? returns t if the external program returned 0, and nil
otherwise, with the exit code as a second value. As other variants
by default signal an error if the process exists non-zero, cmd? is
useful for programs that are expected to fail.
(cmd? "kill -0" pid)
=> T # PID is a live process
=> NIL # PID is not a live process
cmd& runs an external program asynchronously (with
uiop:launch-program) and returns a UIOP process-info object.
(cmd& "cp -a" src dest)
=> #<PROCESS-INFO ...>
Redirection is accomplished via keyword arguments. These should be self-explanatory to anyone who has used a shell.
(cmd "echo 'hello world'" :> #p"hello.txt")
(cmd "cat" #p"hello.txt")
=> hello world
;; Append
(cmd "echo 'goodbye world'" :>> #p"hello.txt")
(cmd "cat" #p"hello.txt")
=> hello world
goodbye world
(cmd "tar cf -" #p"hello.txt" :> #p"hello.tar")
(cmd "rm" #p"hello.txt")
(cmd "tar xf" #p"hello.tar")
(cmd "cat" #p"hello.txt")
=> hello world
goodbye world
Supported directions are:
:< Redirect stdin.:>, :1> Redirect stdout.:>>, :1>> Append stdout.:2> Redirect stderr.:2>> Append stderr.:&>, :>& Redirect stdout and stderr.:&>>, :>>& Append stdout and stderr.There are two hooks you can use to control cmd. These are exported from the cmd/hooks package (so you can :use :cmd without having to worry about them.) Both hooks expect a list of functions of one argument.
The hook *message-hook* is called with the external program and its arguments, quoted as a shell command line. This can be useful for logging commands as they are run.
The hook *proc-hook* is called with the process object (as returned by uiop:launch-program). This can be useful if you want to be able to track what is being run in a particular dynamic extent.
On Windows only, the first argument (the program name) has .exe appended to it automatically if it doesn’t already have a file extension.
While cmd does not use a shell to interpret its arguments, it does still have to run a shell (sh on Unix, cmd.exe on Windows) in order to change the working directory of the program.
How inefficient this is depends on what your distribution uses as a shell; it is faster when sh is, say, dash, than when it is bash.
Recent versions of GNU env support a -C switch to do this directly. When that is supported (support is detected dynamically) then env -C is used in place of a shell and overhead is negligible.
Cmd is a spinoff of Overlord, a Common Lisp build system, and was inspired by the cmd function in Shake, a Haskell build system.
I plan to support at least inline redirection (e.g. (cmd "sth file > other-file")) and pipelines.
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The cmd system | ||
| • The cmd/cmd system | ||
| • The cmd/hooks system |
Next: The cmd/cmd system, Previous: Systems, Up: Systems [Contents][Index]
Paul M. Rodriguez <pmr@ruricolist.com>
MIT
A utility for running external programs
0.0.1
cmd/cmd (system)
cmd.asd (file)
cmd.lisp (file)
Next: The cmd/hooks system, Previous: The cmd system, Up: Systems [Contents][Index]
Paul M. Rodriguez <pmr@ruricolist.com>
MIT
cmd.asd (file)
lisp.lisp (file)
Previous: The cmd/cmd system, Up: Systems [Contents][Index]
Paul M. Rodriguez <pmr@ruricolist.com>
MIT
cmd.asd (file)
lisp.lisp (file)
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files |
| • The cmd.asd file | ||
| • The cmd/cmd.lisp file | ||
| • The cmd/cmd/lisp.lisp file | ||
| • The cmd/hooks/lisp.lisp file |
Next: The cmd/cmd․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
Next: The cmd/cmd/lisp․lisp file, Previous: The cmd․asd file, Up: Lisp files [Contents][Index]
cmd (system)
cmd.lisp
Next: The cmd/hooks/lisp․lisp file, Previous: The cmd/cmd․lisp file, Up: Lisp files [Contents][Index]
cmd/cmd (system)
cmd.lisp
Previous: The cmd/cmd/lisp․lisp file, Up: Lisp files [Contents][Index]
cmd/hooks (system)
hooks.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The cmd/cmd package | ||
| • The cmd/hooks package |
Next: The cmd/hooks package, Previous: Packages, Up: Packages [Contents][Index]
cmd.lisp (file)
cmd
Previous: The cmd/cmd package, Up: Packages [Contents][Index]
lisp.lisp (file)
Definitions are sorted by export status, category, package, and then by lexicographic order.
| • Exported definitions | ||
| • Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
| • Exported special variables | ||
| • Exported macros | ||
| • Exported compiler macros | ||
| • Exported functions |
Next: Exported macros, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
Next: Exported compiler macros, Previous: Exported special variables, Up: Exported definitions [Contents][Index]
Next: Exported functions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
Previous: Exported compiler macros, Up: Exported definitions [Contents][Index]
Return the results of CMD as a string, stripping any trailing
newlines, like $(cmd) would in a shell.
By default stderr is discarded.
Run a program.
CMD should be a string naming a program. This command will be run with
its current directory set to the value of the current directory in a
thread-safe manner.
The current directory is based on ‘*default-pathname-defaults*’, not on the OS-level working directory, as the OS-level directory is useless for multi-threaded programs.
A list of strings or pathnames is added to the list of arguments.
A string in ARGS is split into a list of tokens using shell-style
tokenization rules. (To protect a string with spaces, either add
quotation marks, or enclose it in a singleton list.)
A pathname in ARGS is translated to a native namestring and passed as
an argument to the command. The native namestring is not permitted to
start with a dash.
A property list is treated as a list of keyword arguments to
‘uiop:run-program’. Certain keywords are treated as abbreviations:
e.g. ‘:>’ is an abbreviation for ‘:output’. Abbreviations can be
compound: e.g. ‘:>>’ affects both ‘:output’ and ‘:if-exists’.
By default, standard output is sent to ‘*standard-output*’, and error
output is sent to ‘*message-stream*’.
On Windows, the .exe suffix may be omitted from the name of the
executable.
Run CMD purely for its side effects, discarding all output and returning nothing.
Like ‘cmd’, but run asynchronously and return a handle on the process (as from ‘launch-program’).
Run a program, returning T if it passed, nil otherwise. By default the output is discarded.
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal special variables | ||
| • Internal macros | ||
| • Internal functions | ||
| • Internal types |
Next: Internal macros, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
Next: Internal functions, Previous: Internal special variables, Up: Internal definitions [Contents][Index]
Next: Internal types, Previous: Internal macros, Up: Internal definitions [Contents][Index]
Wait for PROC to finish.
Run a program (with uiop:run-program) in the current base directory.
Wrap TOKENS with the necessary code to run the process in DIR.
The OS-level current directory is per-process, not per thread. Using ‘chdir’ could lead to race conditions. Instead, we arrange for the new process to change its own working directory.
Previous: Internal functions, Up: Internal definitions [Contents][Index]
Previous: Definitions, Up: Top [Contents][Index]
| • Concept index | ||
| • Function index | ||
| • Variable index | ||
| • Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
| Jump to: | C F L |
|---|
| Jump to: | C F L |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | $
A C D E F L M P S U W |
|---|
| Jump to: | $
A C D E F L M P S U W |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | *
S |
|---|
| Jump to: | *
S |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | C P S T |
|---|
| Jump to: | C P S T |
|---|