Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the inferior-shell Reference Manual, version 2.0.5, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Oct 13 11:15:45 2021 GMT+0.
| • Introduction | What inferior-shell 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 |
This CL library allows you to spawn local or remote processes and shell pipes. It lets me use CL in many cases where I would previously write shell scripts. The name is a pun, in that this library can both let you spawn inferior (children processes) shells, and serve itself as an inferior (not so featureful) shell. Because so many features of a shell are missing, inferior-shell only brings down the low-hanging fruits of shell scripting; yet CL is such a better programming language than the shell (or other "scripting" languages) that it is already a great pleasure to be able to write things in CL rather than in these languages. More features will come, and/or you can use other CL libraries as a complement.
Inferior-shell recognizes a small domain-specific language to describe commands or pipelines of commands, and some functions to actually run these pipelines either locally or remotely (via ssh). It will implicitly invoke ssh when asked to run a command on a remote host; for best results, be sure to have passphrase-less access to these hosts via e.g. ssh-agent.
The name inferior-shell was suggested by Michael Livshin, as inspired by the equivalent notion in GNU Emacs.
Example use of inferior-shell, from the rpm system:
(defun rpms-installed (&key (packagenames t) host)
(run/lines
`(pipe (rpm -qa)
,@(unless (eq packagenames t)
`((egrep ("^(" ,@(loop :for (name . more) :on packagenames
:collect name :when more :collect "|")
")-[^-]+(-[^-]+)?$")))))
:host host))
By default, inferior-shell uses uiop:run-program as its universal execution backend, and has its limitations, which are as follows.
First, inferior-shell at this point only supports synchronous execution of sub-processes. For asynchronous execution, please use IOlib or executor. IOlib requires C compilation and linking, and may or may not support Windows. executor only supports select implementations. A future extension to inferior-shell may use IOlib as a backend.
Second, supported platforms at this time include: ABCL, Allegro, CLISP, ClozureCL, CMUCL, ECL, LispWorks, RMCL, SBCL, SCL, XCL. Platforms NOT (yet) supported include: CormanLisp (untested), GCL (untested), Genera (unimplemented), MKCL (untested). On supported platforms, inferior-shell works on both Unix and Windows.
The inferior-shell library creates a package INFERIOR-SHELL, that exports the following macros and functions:
PARSE-PROCESS-SPEC SPEC
parse an expression in the process-spec mini-language into objects specifying a pipeline of processes to be executed. See the PROCESS-SPEC mini-language below.
PRINT-PROCESS-SPEC SPEC &OPTIONAL OUTPUT
print a process specification to given OUTPUT into a portable form usable by a Unix shell. OUTPUT is as per FORMAT's stream output argument, defaults to NIL for returning the result as a string. SPEC can be a parsed PROCESS-SPEC object, a CONS to be parsed by PARSE-PROCESS-SPEC, or a string for a process-spec that has already been formatted.
*CURRENT-HOST-NAMES*
a variable, a list of strings, the aliases for the localhost. You may need to initialize it if the defaults don't suffice.
CURRENT-HOST-NAME-P X
a function, returns true if X is a string member of CURRENT-HOST-NAMES
INITIALIZE-CURRENT-HOST-NAMES
function that initializes the CURRENT-HOST-NAMES with "localhost" and the results from $(hostname -s) and $(hostname -f).
RUN CMD &KEY ON-ERROR TIME SHOW HOST OUTPUT
RUN will execute the given command CMD, which can be
a CONS to be parsed by PARSE-PROCESS-SPEC,
a PROCESS-SPEC object already parsed,
or a string to be passed to a Unix shell.
ON-ERROR specifies behavior in case the command doesn't successfully exit
with exit code 0. NIL means continue and return the error code;
T (default) means signal the error (same as :ON-ERROR 'SIGNAL);
any other value is called as by UIOP:CALL-FUNCTION with the condition as argument,
and if it returns, its return values are returned by RUN.
TIME is a boolean which if true causes the execution to be timed as per TIME.
SHOW is a boolean which if true causes a message to be sent
to the *TRACE-OUTPUT* before execution.
HOST is either NIL (execute on localhost) or a string specifying a host
on which to run the command using ssh if
it's not an alias for localhost as recognized by CURRENT-HOST-NAME-P
(be sure to have passphraseless login using ssh-agent).
The INPUT, OUTPUT and ERROR-OUTPUT arguments are as for UIOP:RUN-PROGRAM,
except that they default to NIL, T, T respectively instead of NIL, NIL, NIL.
In particular, OUTPUT is as per UIOP:SLURP-OUTPUT-STREAM one of
NIL for no output (redirect to /dev/null),
a stream for itself,
T (default) for the current *standard-output*,
:INTERACTIVE for inheriting the parent process's stdout,
:LINES for returning one result per line,
:STRING for returning the output as one big string,
:STRING/STRIPPED is like :STRING
but strips any line-ending at the end of the results,
just like a shell's cmd or $(cmd) would, and
more options are accepted and you can define your own, as per
uiop's slurp-input-stream protocol.
On Windows, RUN will not succeed for pipes, only for simple commands.
On Unix, simple commands on localhost are executed directly, but
remote commands and pipes are executed by spawning a shell.
RUN/NIL CMD &KEY ON-ERROR TIME SHOW HOST
RUN/NIL is a shorthand for RUN with :INPUT :OUTPUT :ERROR-OUTPUT bound to NIL.
RUN/S CMD &KEY ON-ERROR TIME SHOW HOST
RUN/S is a shorthand for RUN with :OUTPUT bound to :STRING,
returning as a string what the inferior command sent to its standard output.
RUN/SS CMD &KEY ON-ERROR TIME SHOW HOST
RUN/S is a shorthand for RUN :OUTPUT :STRING/STRIPPED,
just like a shell's cmd or $(cmd) would do.
RUN/INTERACTIVE CMD &KEY ON-ERROR TIME SHOW HOST
RUN/INTERACTIVE is a shorthand for RUN with :INPUT :OUTPUT :ERROR-OUTPUT
all bound to :INTERACTIVE, so you may run commands that interact with users,
inheritting the stdin, stdout and stderr of the current process.
RUN/I CMD &KEY KEYS
RUN/I is a shorthand alias for RUN/INTERACTIVE
RUN/LINES CMD &KEY ON-ERROR TIME SHOW HOST
RUN/LINES is a shorthand for RUN :OUTPUT :LINES,
returning as a list of one string per line (stripped of line-ending)
what the inferior command sent to its standard output.
This library offers a SEXP syntax to specify processes and pipelines of processes in the manner of Unix shells, including support for file descriptor redirection. Process specifications can be printed, to be executed by a local or remote shell, or directly executed by your Lisp implementation, depending on its capabilities and on the complexity of the pipeline.
SEXP mini-language
;; A process is a pipe or a command
process := pipe | or | and | progn | fork | command
;; A pipe is a list of processes, each of whose output is connected to the next one's input.
pipe := ( pipe process* )
;; OR is a list of processes which will be executed in sequence until one returns exit code 0.
or := ( or processes )
;; AND is a list of processes which will be executed in sequence until one does not return exit code 0.
and := ( and processes )
;; PROGN is a list of processes which will be executed sequentially.
progn := ( progn processes )
;; FORK is a list of processes which will be forked and executed in parallel.
fork := ( fork processes )
;; A command is a list of tokens and redirections.
;; Tokens specify the argv, redirections specify modifications of the inherited file descriptors.
command := ( [redirection|token|tokens]* )
;; A token is a string, to be used literally,
;; a keyword, to be downcased and prefixed with -- as in :foo ==> "--foo"
;; a symbol, to be downcased, or a list of tokens to be concatenated.
token := string | keyword | symbol | (token*)
;; A list starting with * is actually to be spliced in the token stream.
tokens := (\* [token|tokens]*)
;; Redirections mimic those redirections available to a shell, for instance zsh.
redirection := (
! fd pathname flags | ;; open a file with given flags redirect to specified fd
< fd? pathname | ;; open a file for input, redirect to specified fd (default: 0)
[>|>>|<>|>!|>>!] fd? pathname | ;; open a file for (respectively) output, append, io, output clobbering, append clobbering, redirect to specified fd (default: 1)
- fd | <& fd - | >& fd - | ;; close a fd
<& - | >& - | ;; close fd 0, respectively fd 1.
<& fd fd | >& fd fd | ;; redirect fds: the left one is the new number, the right one the old number.
>& pn | >&! | ;; redirect both fd 1 and 2 to pathname (respectively, clobbering)
>>& pn | >>&! ) ;; redirect both fd 1 and 2 to append to pathname (respectively, clobbering)
Note that these are all exported symbols from the INFERIOR-SHELL package, except that a few of them are also inherited from COMMON-LISP: < > - Therefore the other ones will only work if you either use the INFERIOR-SHELL package or use a package prefix INFERIOR-SHELL: where appropriate.
A SEXP in the minilanguage can be parsed with parse-process-spec, into an object of class process-spec. print-process-spec will print a process-spec object; in this context, a string represents itself (assuming it's already a printed process spec), and a cons is a specification in the minilanguage to be parsed with parse-process-spec first.
Better document it.
Have a complementary inferior-shell-watcher library that uses iolib to spawn pipes locally, and watch the subprocesses as part of the iolib event loop.
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The inferior-shell system |
Francois-Rene Rideau
MIT
spawn local or remote processes and shell pipes
2.0.5
inferior-shell.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files |
Next: The inferior-shell/pkgdcl․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
inferior-shell.asd
inferior-shell (system)
Next: The inferior-shell/process-spec․lisp file, Previous: The inferior-shell․asd file, Up: Lisp files [Contents][Index]
inferior-shell (system)
pkgdcl.lisp
Next: The inferior-shell/utilities․lisp file, Previous: The inferior-shell/pkgdcl․lisp file, Up: Lisp files [Contents][Index]
pkgdcl.lisp (file)
inferior-shell (system)
process-spec.lisp
Next: The inferior-shell/macros․lisp file, Previous: The inferior-shell/process-spec․lisp file, Up: Lisp files [Contents][Index]
pkgdcl.lisp (file)
inferior-shell (system)
utilities.lisp
Next: The inferior-shell/host․lisp file, Previous: The inferior-shell/utilities․lisp file, Up: Lisp files [Contents][Index]
pkgdcl.lisp (file)
inferior-shell (system)
macros.lisp
with-directory (macro)
Next: The inferior-shell/run․lisp file, Previous: The inferior-shell/macros․lisp file, Up: Lisp files [Contents][Index]
pkgdcl.lisp (file)
inferior-shell (system)
host.lisp
Previous: The inferior-shell/host․lisp file, Up: Lisp files [Contents][Index]
inferior-shell (system)
run.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The inferior-shell package |
pkgdcl.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 macros | ||
| • Exported functions | ||
| • Exported generic functions | ||
| • Exported classes | ||
| • Exported types |
Next: Exported functions, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
utilities.lisp (file)
Next: Exported generic functions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
process-spec.lisp (file)
run command CMD. Unless otherwise specified, copy the subprocess’s output to *standard-output* and its error-output to *error-output*. Return values for the output, error-output and exit-code.
The command specified by COMMAND can be a list as parsed by PARSE-PROCESS-SPEC, or a string
to execute with a shell (/bin/sh on Unix, CMD.EXE on Windows).
Signal a continuable SUBPROCESS-ERROR if the process wasn’t successful (exit-code 0),
unless ON-ERROR is specified, which if NIL means ignore the error (and return the three values).
If OUTPUT is a pathname, a string designating a pathname, or NIL designating the null device,
the file at that path is used as output.
If it’s :INTERACTIVE, output is inherited from the current process;
beware that this may be different from your *STANDARD-OUTPUT*,
and under SLIME will be on your *inferior-lisp* buffer.
If it’s T, output goes to your current *STANDARD-OUTPUT* stream.
Otherwise, OUTPUT should be a value that is a suitable first argument to
SLURP-INPUT-STREAM (qv.), or a list of such a value and keyword arguments.
In this case, RUN-PROGRAM will create a temporary stream for the program output;
the program output, in that stream, will be processed by a call to SLURP-INPUT-STREAM,
using OUTPUT as the first argument (or the first element of OUTPUT, and the rest as keywords).
The primary value resulting from that call (or NIL if no call was needed)
will be the first value returned by RUN-PROGRAM.
E.g., using :OUTPUT :STRING will have it return the entire output stream as a string.
And using :OUTPUT ’(:STRING :STRIPPED T) will have it return the same string
stripped of any ending newline.
ERROR-OUTPUT is similar to OUTPUT, except that the resulting value is returned
as the second value of RUN-PROGRAM. T designates the *ERROR-OUTPUT*.
Also :OUTPUT means redirecting the error output to the output stream,
in which case NIL is returned.
INPUT is similar to OUTPUT, except that VOMIT-OUTPUT-STREAM is used,
no value is returned, and T designates the *STANDARD-INPUT*.
Use ELEMENT-TYPE and EXTERNAL-FORMAT are passed on
to your Lisp implementation, when applicable, for creation of the output stream.
One and only one of the stream slurping or vomiting may or may not happen
in parallel with the subprocess, depending on options and implementation,
and with priority being given to output processing.
Other streams are completely produced or consumed
before or after the subprocess is spawned, using temporary files.
RUN returns 3 values:
0- the result of the OUTPUT slurping if any, or NIL
1- the result of the ERROR-OUTPUT slurping if any, or NIL
2- either 0 if the subprocess exited with success status,
or an indication of failure via the EXIT-CODE of the process
run.lisp (file)
alias for run/interactive
run.lisp (file)
run command CMD interactively, connecting the subprocess’s input, output and error-output
to the same file descriptors as the current process
See the documentation for INFERIOR-SHELL:RUN for other keyword arguments.
run.lisp (file)
run command CMD, return its standard output results as a list of strings, one per line,
discarding line terminators. Unless otherwise specified, discard error-output.
See the documentation for INFERIOR-SHELL:RUN for other keyword arguments.
run.lisp (file)
run command CMD. Unless otherwise specified, discard the subprocess’s output and error-output. See the documentation for INFERIOR-SHELL:RUN for other keyword arguments.
run.lisp (file)
run command CMD, return its standard output results as a string.
Unless otherwise specified, discard its error-output.
See the documentation for INFERIOR-SHELL:RUN for other keyword arguments.
run.lisp (file)
run command CMD, return its standard output results as a string like run/s,
but strips the line ending off the result string very much like ‘cmd‘ or $(cmd) at the shell
See the documentation for INFERIOR-SHELL:RUN for other keyword arguments.
run.lisp (file)
process-spec.lisp (file)
utilities.lisp (file)
utilities.lisp (file)
Next: Exported classes, Previous: Exported functions, Up: Exported definitions [Contents][Index]
automatically generated reader method
process-spec.lisp (file)
automatically generated reader method
process-spec.lisp (file)
Print a process specification in a way suitable for consumption by a shell
process-spec.lisp (file)
Next: Exported types, Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
process-spec.lisp (file)
sequence-spec (class)
print-process-spec (method)
process-spec.lisp (file)
redirection (class)
integer
:old-fd
redirection-old-fd (generic function)
process-spec.lisp (file)
process-spec (class)
list
:arguments
command-arguments (generic function)
list
:redirections
command-redirections (generic function)
process-spec.lisp (file)
redirection (class)
integer
:old-fd
redirection-old-fd (generic function)
integer
:new-fd
redirection-new-fd (generic function)
process-spec.lisp (file)
redirection (class)
integer
:fd
redirection-fd (generic function)
symbol
:symbol
redirection-symbol (generic function)
list
:flags
redirection-flags (generic function)
(or string pathname)
:pathname
redirection-pathname (generic function)
process-spec.lisp (file)
sequence-spec (class)
print-process-spec (method)
process-spec.lisp (file)
sequence-spec (class)
print-process-spec (method)
process-spec.lisp (file)
sequence-spec (class)
print-process-spec (method)
process-spec.lisp (file)
simple-print-object-mixin (class)
process-spec.lisp (file)
sequence-spec (class)
print-process-spec (method)
process-spec.lisp (file)
simple-print-object-mixin (class)
Previous: Exported classes, Up: Exported definitions [Contents][Index]
process-spec.lisp (file)
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal special variables | ||
| • Internal macros | ||
| • Internal functions | ||
| • Internal generic functions | ||
| • Internal classes | ||
| • Internal types |
Next: Internal macros, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
host.lisp (file)
Next: Internal functions, Previous: Internal special variables, Up: Internal definitions [Contents][Index]
macros.lisp (file)
Next: Internal generic functions, Previous: Internal macros, Up: Internal definitions [Contents][Index]
utilities.lisp (file)
process-spec.lisp (file)
host.lisp (file)
run.lisp (file)
utilities.lisp (file)
utilities.lisp (file)
host.lisp (file)
process-spec.lisp (file)
utilities.lisp (file)
process-spec.lisp (file)
process-spec.lisp (file)
utilities.lisp (file)
run.lisp (file)
process-spec.lisp (file)
process-spec.lisp (file)
process-spec.lisp (file)
utilities.lisp (file)
process-spec.lisp (file)
Similar to READ-LINE, this function also returns as additional values the state about
whether CR or LF were read. CR, LF and CR+LF are accepted only.
Partial state accepted as input, too, for parsing in chunks.
utilities.lisp (file)
run.lisp (file)
run.lisp (file)
utilities.lisp (file)
utilities.lisp (file)
utilities.lisp (file)
utilities.lisp (file)
process-spec.lisp (file)
Next: Internal classes, Previous: Internal functions, Up: Internal definitions [Contents][Index]
process-spec.lisp (file)
process-spec.lisp (file)
automatically generated reader method
process-spec.lisp (file)
automatically generated writer method
process-spec.lisp (file)
automatically generated reader method
process-spec.lisp (file)
automatically generated writer method
process-spec.lisp (file)
automatically generated reader method
process-spec.lisp (file)
automatically generated writer method
process-spec.lisp (file)
process-spec.lisp (file)
process-spec.lisp (file)
process-spec.lisp (file)
process-spec.lisp (file)
process-spec.lisp (file)
automatically generated reader method
process-spec.lisp (file)
automatically generated reader method
process-spec.lisp (file)
automatically generated reader method
process-spec.lisp (file)
automatically generated reader method
process-spec.lisp (file)
automatically generated reader method
process-spec.lisp (file)
automatically generated reader method
process-spec.lisp (file)
automatically generated reader method
process-spec.lisp (file)
automatically generated reader method
process-spec.lisp (file)
Next: Internal types, Previous: Internal generic functions, Up: Internal definitions [Contents][Index]
process-spec.lisp (file)
standard-object (class)
list
clps-arguments-r (generic function)
(setf clps-arguments-r) (generic function)
list
clps-redirections-r (generic function)
(setf clps-redirections-r) (generic function)
(or null stream)
clps-current-argument (generic function)
(setf clps-current-argument) (generic function)
process-spec.lisp (file)
process-spec (class)
sequence-processes (method)
list
:processes
sequence-processes (generic function)
Previous: Internal classes, Up: Internal definitions [Contents][Index]
run.lisp (file)
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: | F I L |
|---|
| Jump to: | F I L |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | (
A C D E F G I M N O P R S T W Z |
|---|
| Jump to: | (
A C D E F G I M N O P R S T W Z |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | *
A C F N O P R S |
|---|
| Jump to: | *
A C F N O P R S |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | A C D F I O P R S T |
|---|
| Jump to: | A C D F I O P R S T |
|---|