diff --git a/README b/README index 72df2a1ec98be573d45bcc9bc31eadd51e2ff4ec..c7ce344157caafd0b3899fe0fba1284483b52da3 100644 --- a/README +++ b/README @@ -29,13 +29,62 @@ that exports the following macros and functions: (TO BE DOCUMENTED. IN THE MEANTIME, CONSULT THE SOURCES) -PARSE-PROCESS-SPEC -PRINT-PROCESS-SPEC -RUN -RUN/LINES -RUN/S -RUN/SS - +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. + +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, as per FARE-UTILS's ERROR-BEHAVIOUR provided with + (if a function, invoke it, if a string, issue an error with it, + otherwise return it as is). + 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). + 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/S CMD &KEY ON-ERROR TIME SHOW HOST + RUN/S is a shorthand for RUN :OUTPUT 'STRING, + returning as a string what the inferior command sent to its standard output. + +RUN/SS CMD &KEY ON-ERROR TIME SHOW HOST + RUN/SS calls RUN/S then strips any line-ending at the end of the results, + just like a shell's `cmd` or $(cmd) would do. + +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. ==== THE PROCESS-SPEC MINI-LANGUAGE ====