From ade19c13fd05018fa2441c164471223ca5f490ac Mon Sep 17 00:00:00 2001 From: "Robert P. Goldman" <rpgoldman@gmail.com> Date: Tue, 6 Aug 2013 19:55:40 -0500 Subject: [PATCH] Document the multiple different methods of SLURP-STREAM-STRING. --- uiop/run-program.lisp | 33 +++++++++++++++++++++++++++------ 1 file changed, 27 insertions(+), 6 deletions(-) diff --git a/uiop/run-program.lisp b/uiop/run-program.lisp index d7f3f364..143e20f8 100644 --- a/uiop/run-program.lisp +++ b/uiop/run-program.lisp @@ -136,7 +136,28 @@ by /bin/sh in POSIX" ;;;; Slurping a stream, typically the output of another program (with-upgradability () - (defgeneric slurp-input-stream (processor input-stream &key &allow-other-keys)) + (defgeneric slurp-input-stream (processor input-stream &key &allow-other-keys) + (:documentation + "SLURP-INPUT-STREAM is a generic function with two positional arguments +PROCESSOR and INPUT-STREAM and additional keyword arguments, that consumes (slurps) +the contents of the INPUT-STREAM and processes them according to a method +specified by PROCESSOR. + +Built-in methods include the following: +* if PROCESSOR is a function, it is called with the INPUT-STREAM as its argument +* if PROCESSOR is a list, its first element should be a function. It will be applied to a cons of the + INPUT-STREAM and the rest of the list. That is (x . y) will be treated as + \(APPLY x <stream> y\) +* if PROCESSOR is an output-stream, the contents of INPUT-STREAM is copied to the output-stream, + per copy-stream-to-stream, with appropriate keyword arguments. +* if PROCESSOR is the symbol CL:STRING or the keyword :STRING, then the contents of INPUT-STREAM + are returned as a string, as per SLURP-STREAM-STRING. +* if PROCESSOR is the keyword :LINES then the INPUT-STREAM will be handled by SLURP-STREAM-LINES. +* if PROCESSOR is the keyword :LINE then the INPUT-STREAM will be handled by SLURP-STREAM-LINE. +* if PROCESSOR is the keyword :FORMS then the INPUT-STREAM will be handled by SLURP-STREAM-FORMS. +* if PROCESSOR is the keyword :FORM then the INPUT-STREAM will be handled by SLURP-STREAM-FORM. + +Programmers are encouraged to define their own methods for this generic function.")) #-(or gcl2.6 genera) (defmethod slurp-input-stream ((function function) input-stream &key &allow-other-keys) @@ -248,12 +269,12 @@ if it was NIL, the output is discarded; if it was :INTERACTIVE, the output and the input are inherited from the current process. Otherwise, OUTPUT should be a value that is a suitable first argument to -SLURP-INPUT-STREAM. In this case, RUN-PROGRAM will create a temporary stream +SLURP-INPUT-STREAM (qv.). In this case, RUN-PROGRAM will create a temporary stream for the program output. The program output, in that stream, will be processed -by SLURP-INPUT-STREAM, according to the using OUTPUT as the first argument. -RUN-PROGRAM will return whatever SLURP-INPUT-STREAM returns. E.g., using -:OUTPUT :STRING will have it return the entire output stream as a string. Use -ELEMENT-TYPE and EXTERNAL-FORMAT for the stream passed to the OUTPUT processor." +by SLURP-INPUT-STREAM, using OUTPUT as the first argument. RUN-PROGRAM will +return whatever SLURP-INPUT-STREAM returns. E.g., using :OUTPUT :STRING will +have it return the entire output stream as a string. Use ELEMENT-TYPE and +EXTERNAL-FORMAT for the stream passed to the OUTPUT processor." ;; TODO: The current version does not honor :OUTPUT NIL on Allegro. Setting ;; the :INPUT and :OUTPUT arguments to RUN-SHELL-COMMAND on ACL actually do -- GitLab