adding error checking for null lists in execute, improving (chibi process) docs

lib/chibi/process.scm

@@ -47,11 +47,20 @@
              (not (car o))
              (equal? (car o) (car cmdline))))))
 
+;;> Replaces the current process with a new image running the program
+;;> \var{cmd}, with arguments in the list \var{args}.  The first
+;;> argument, by convention, should be the file name being executed -
+;;> an error is signaled if \var{args} is null.  The command and
+;;> arguments may be symbols or numbers in addition to strings for
+;;> convenience.  Equivalent to \ccode{execvp}.
 (define (execute cmd args)
   (define (->string x)
     (cond ((symbol? x) (symbol->string x))
+          ((eqv? -i x) "-i")
           ((number? x) (number->string x))
           (else x)))
+  (if (null? args)
+      (error "execute requires a non-empty argument list (command-name comes first)"))
   (execvp (->string cmd) (map ->string args)))
 
 (define (execute-returned cmd)
@@ -64,6 +73,33 @@
       (newline (current-error-port))))
     (exit 1)))
 
+;;> Runs the given command \var{cmd} in a subprocess, with arguments
+;;> \var{args}.  Uses a flat representation of arguments to avoid
+;;> duplicates, so unlike \scheme{execute} automatically includes
+;;> \var{cmd} as the first argument program name.  As a convenience,
+;;> \var{cmd} itself may be a list which is appended to any arguments.
+;;>
+;;> The \ccode{stdin}, \ccode{stdout} and \ccode{stderr} will be
+;;> inherited from the current process.  Use
+;;> \scheme{call-with-process-io} if you need to capture or manipulate
+;;> the subprocess IO.
+;;>
+;;> \emph{Examples:}
+;;>
+;;> \schemeblock{
+;;> (system "date")
+;;> Mon Aug 28 23:25:11 JST 2017
+;;> }
+;;>
+;;> \schemeblock{
+;;> (system "ls" "/usr/")
+;;> bin  games  include  lib  local  sbin  share  src
+;;> }
+;;>
+;;> \schemeblock{
+;;> (system '(dc -e "2 2 + p"))
+;;> 4
+;;> }
 (define (system cmd . args)
   (let ((pid (fork)))
     (cond
@@ -74,10 +110,18 @@
      (else
       (waitpid pid 0)))))
 
+;;> Equivalent to \scheme{system}, but returns \scheme{#t} on success
+;;> and \scheme{#f} on failure.
 (define (system? cmd . args)
   (let ((res (apply system cmd args)))
     (and (pair? res) (zero? (cadr res)))))
 
+;;> Runs the program \var{command} in a subprocess and calls
+;;> \var{proc} on 4 arguments: the \var{pid}, \var{stdin},
+;;> \var{stdout} and \var{stderr} of the subprocess.  \var{command}
+;;> should be a list beginning with the program name followed by any
+;;> args, which may be symbols or numbers for convenience as with
+;;> \scheme{system}, or a string which is split on white-space.
 (define (call-with-process-io command proc)
   (define (set-non-blocking! fd)
     (cond-expand
@@ -120,6 +164,8 @@
                    (open-input-file-descriptor (car out-pipe))
                    (open-input-file-descriptor (car err-pipe)))))))))
 
+;;> Utility to run \var{command} and return the accumulated output as
+;;> a bytevector.
 (define (process->bytevector command)
   (call-with-process-io
    command
@@ -129,6 +175,8 @@
        (waitpid pid 0)
        res))))
 
+;;> Utility to run \var{command} and return the accumulated output as
+;;> a string.
 (define (process->string command)
   (call-with-process-io
    command
@@ -138,9 +186,14 @@
        (waitpid pid 0)
        res))))
 
+;;> Utility to run \var{command} and return the accumulated output as
+;;> a sexp, as from \scheme{read}.
 (define (process->sexp command)
   (call-with-input-string (process->string command) read))
 
+;;> Utility to run \var{command} and return a list of three values:
+;;> the accumulated output as a string, the error output as a string,
+;;> and the exit status as an integer.
 (define (process->output+error+status command)
   (call-with-process-io
    command
@@ -151,10 +204,14 @@
             (res (waitpid pid 0)))
        (list out err (cadr res))))))
 
+;;> Utility to run \var{command} and return a list of two values:
+;;> the accumulated output as a string, the error output as a string.
 (define (process->output+error command)
   (let ((res (process->output+error+status command)))
     (list (car res) (cadr res))))
 
+;;> Utility to run \var{command} and return the output as a list of
+;;> strings, one for each line (trailing newlines not included).
 (define (process->string-list command)
   (call-with-process-io
    command