README

   1 INFERIOR-SHELL
   2
   3 This CL library allows you to spawn local or remote processes and shell pipes.
   4 It lets me use CL in many cases where I would previously write shell scripts.
   5 The name is a pun, in that this library can both
   6 let you spawn inferior (children processes) shells, and
   7 serve itself as an inferior (not so featureful) shell.
   8 Because so many features of a shell are missing,
   9 inferior-shell only brings down the low-hanging fruits of shell scripting;
  10 yet CL is such a better programming language than the shell
  11 (or other "scripting" languages) that it is already a great pleasure
  12 to be able to write things in CL rather than in these languages.
  13 More features will come, and/or you can use other CL libraries as a complement.
  14
  15 Inferior-shell recognizes a small domain-specific language to describe
  16 commands or pipelines of commands, and some functions to actually run
  17 these pipelines either locally or remotely (via ssh).
  18 It will implicitly invoke ssh when asked to run a command on a remote host;
  19 for best results, be sure to have passphrase-less access to these hosts
  20 via e.g. ssh-agent.
  21
  22 The name inferior-shell was suggested by Michael Livshin,
  23 as inspired by the equivalent notion in GNU Emacs.
  24
  25 Example use of inferior-shell, from the rpm system:
  26 (defun rpms-installed (&key (packagenames t) host)
  27   (run/lines
  28    `(pipe (rpm -qa)
  29           ,@(unless (eq packagenames t)
  30               `((egrep ("^(" ,@(loop :for (name . more) :on packagenames
  31                                  :collect name :when more :collect "|")
  32                              ")-[^-]+(-[^-]+)?$")))))
  33    :host host))
  34
  35
  36 ==== Limitations ====
  37
  38 By default, inferior-shell uses asdf-driver:run-program
  39 as its universal execution backend, and has its limitations,
  40 which are as follows.
  41
  42 First, inferior-shell at this point only supports
  43 synchronous execution of sub-processes.
  44 For asynchronous execution, please use IOlib or executor.
  45 IOlib requires C compilation and linking, and may or may not support Windows.
  46 executor only supports select implementations.
  47 A future extension to inferior-shell may use IOlib as a backend.
  48
  49 Second, there is currently limited support for input redirection.
  50 The only possible input redirection is from /dev/null
  51 or by inheriting the parent's standard input
  52 when running in :interactive mode.
  53 However, using shell redirection, you can also redirect input from a file,
  54 or from a numbered file descriptor (except 0, 1, 2).
  55
  56 Finally, supported platforms at this time include:
  57 ABCL, Allegro, CLISP, ClozureCL, CMUCL, ECL, LispWorks, RMCL, SBCL, SCL, XCL.
  58 Platforms NOT (yet) supported include:
  59 CormanLisp (untested), GCL (untested), Genera (unimplemented), MKCL (untested).
  60 On supported platforms, inferior-shell works on both Unix and Windows.
  61
  62
  63 ==== Exported Functionality ====
  64
  65 The inferior-shell library creates a package INFERIOR-SHELL,
  66 that exports the following macros and functions:
  67
  68 PARSE-PROCESS-SPEC SPEC
  69   parse an expression in the process-spec mini-language into
  70   objects specifying a pipeline of processes to be executed.
  71   See the PROCESS-SPEC mini-language below.
  72
  73 PRINT-PROCESS-SPEC SPEC &OPTIONAL OUTPUT
  74   print a process specification to given OUTPUT
  75   into a portable form usable by a Unix shell.
  76   OUTPUT is as per FORMAT's stream output argument,
  77   defaults to NIL for returning the result as a string.
  78   SPEC can be a parsed PROCESS-SPEC object,
  79   a CONS to be parsed by PARSE-PROCESS-SPEC,
  80   or a string for a process-spec that has already been formatted.
  81
  82 *CURRENT-HOST-NAMES*
  83   a variable, a list of strings, the aliases for the localhost.
  84
  85 CURRENT-HOST-NAME-P X
  86   a function, returns true if X is a string member of *CURRENT-HOST-NAMES*
  87
  88 INITIALIZE-CURRENT-HOST-NAMES
  89   function that initializes the *CURRENT-HOST-NAMES*
  90   with "localhost" and the results from $(hostname -s) and $(hostname -f).
  91
  92 RUN CMD &KEY ON-ERROR TIME SHOW HOST OUTPUT
  93   RUN will execute the given command CMD, which can be
  94   a CONS to be parsed by PARSE-PROCESS-SPEC,
  95   a PROCESS-SPEC object already parsed,
  96   or a string to be passed to a Unix shell.
  97   ON-ERROR specifies behavior in case the command doesn't successfully exit
  98   with exit code 0, as per FARE-UTILS's ERROR-BEHAVIOR provided with
  99   (if a function, invoke it, if a string, issue an error with it,
 100   otherwise return it as is).
 101   TIME is a boolean which if true causes the execution to be timed as per TIME.
 102   SHOW is a boolean which if true causes a message to be sent
 103   to the *TRACE-OUTPUT* before execution.
 104   HOST is either NIL (execute on localhost) or a string specifying a host
 105   on which to run the command using ssh if
 106   it's not an alias for localhost as recognized by CURRENT-HOST-NAME-P
 107   (be sure to have passphraseless  login using ssh-agent).
 108   OUTPUT is one of
 109   NIL (default) for inheriting the parent process's stdout,
 110   :LINES for returning one result per line,
 111   :STRING for returning the output as one big string,
 112   :STRING/STRIPPED is like :STRING
 113   but strips any line-ending at the end of the results,
 114   just like a shell's `cmd` or $(cmd) would do,
 115   more options are accepted and you can define your own, as per
 116   asdf-driver's slurp-input-stream protocol.
 117   On Windows, RUN will not succeed for pipes, only for simple commands.
 118   On Unix, simple commands on localhost are executed directly, but
 119   remote commands and pipes are executed by spawning a shell.
 120
 121 RUN/S CMD &KEY ON-ERROR TIME SHOW HOST
 122   RUN/S is a shorthand for RUN :OUTPUT 'STRING,
 123   returning as a string what the inferior command sent to its standard output.
 124
 125 RUN/SS CMD &KEY ON-ERROR TIME SHOW HOST
 126   RUN/S is a shorthand for RUN :OUTPUT :STRING/STRIPPED,
 127   just like a shell's `cmd` or $(cmd) would do.
 128
 129 RUN/LINES CMD &KEY ON-ERROR TIME SHOW HOST
 130   run/lines is a shorthand for RUN :OUTPUT :LINES,
 131   returning as a list of one string per line (stripped of line-ending)
 132   what the inferior command sent to its standard output.
 133
 134 *BACKEND*
 135   a variable to choose between backends. Currently, only supported are
 136   :AUTO (the default, using asdf-driver:run-program, and
 137   spawning a shell unless it's a simple process), and
 138   :SBCL (only available on #+(and sbcl sb-thread unix),
 139   doesn't need a shell but has some limitations such as
 140   only supporting redirection of stdin, stdout, stderr).
 141
 142
 143 ==== THE PROCESS-SPEC MINI-LANGUAGE ====
 144
 145 This library offers a SEXP syntax to specify processes
 146 and pipelines of processes in the manner of Unix shells,
 147 including support for file descriptor redirection.
 148 Process specifications can be printed,
 149 to be executed by a local or remote shell,
 150 or directly executed by your Lisp implementation,
 151 depending on its capabilities and on the complexity of the pipeline.
 152
 153 SEXP mini-language
 154
 155 ;; A process is a pipe or a command
 156 process := pipe | or | and | progn | fork | command
 157
 158 ;; A pipe is a list of processes, each of whose output is connected to the next one's input.
 159 pipe := ( pipe process* )
 160
 161 ;; OR is a list of processes which will be executed in sequence until one returns exit code 0.
 162 or := ( or processes )
 163
 164 ;; AND is a list of processes which will be executed in sequence until one does not return exit code 0.
 165 and := ( and processes )
 166
 167 ;; PROGN is a list of processes which will be executed sequentially.
 168 progn := ( progn processes )
 169
 170 ;; FORK is a list of processes which will be forked and executed in parallel.
 171 fork := ( fork processes )
 172
 173 ;; A command is a list of tokens and redirections.
 174 ;; Tokens specify the argv, redirections specify modifications of the inherited file descriptors.
 175 command := ( [redirection|token|tokens]* )
 176
 177 ;; A token is a string, to be used literally,
 178 ;; a keyword, to be downcased and prefixed with -- as in :foo ==> "--foo"
 179 ;; a symbol, to be downcased, or a list of tokens to be concatenated.
 180 token := string | keyword | symbol | (token*)
 181
 182 ;; A list starting with * is actually to be spliced in the token stream.
 183 tokens := (\* [token|tokens]*)
 184
 185 ;; Redirections mimic those redirections available to a shell, for instance zsh.
 186 redirection := (
 187  ! fd pathname flags |   ;; open a file with given flags redirect to specified fd
 188  < fd? pathname | ;; open a file for input, redirect to specified fd (default: 0)
 189  [>|>>|<>|>!|>>!] fd? pathname | ;; open a file for (respectively) output, append, io, output clobbering, append clobbering, redirect to specified fd (default: 1)
 190  - fd | <& fd - | >& fd - | ;; close a fd
 191  <& - | >& - | ;; close fd 0, respectively fd 1.
 192  <& fd fd | >& fd fd | ;; redirect fds: the left one is the new number, the right one the old number.
 193  >& pn | >&! | ;; redirect both fd 1 and 2 to pathname (respectively, clobbering)
 194  >>& pn | >>&! ) ;; redirect both fd 1 and 2 to append to pathname (respectively, clobbering)
 195
 196 Note that these are all exported symbols from the INFERIOR-SHELL package,
 197 except that a few of them are also inherited from COMMON-LISP: < > -
 198 Therefore the other ones will only work if you either
 199 use the INFERIOR-SHELL package or
 200 use a package prefix INFERIOR-SHELL: where appropriate.
 201
 202 A SEXP in the minilanguage can be parsed with parse-process-spec,
 203 into an object of class process-spec.
 204 print-process-spec will print a process-spec object;
 205 in this context, a string represents itself (assuming it's already a printed process spec),
 206 and a cons is a specification in the minilanguage to be parsed with parse-process-spec first.
 207
 208
 209 ==== TO DO ====
 210
 211 Document it.
 212
 213 Have a complementary inferior-shell-watcher library that uses iolib to spawn
 214 pipes locally, and watch the subprocesses as part of the iolib event loop.