GNU Info

(elisp)Filter Functions

---

Next: Accepting Output Prev: Process Buffers Up: Output from Processes

---

Enter node , (file) or (file)node

Process Filter Functions
------------------------

   A process "filter function" is a function that receives the standard
output from the associated process.  If a process has a filter, then
_all_ output from that process is passed to the filter.  The process
buffer is used directly for output from the process only when there is
no filter.

   The filter function can only be called when Emacs is waiting for
something, because process output arrives only at such times.  Emacs
waits when reading terminal input, in `sit-for' and `sleep-for' (Note:
Waiting), and in `accept-process-output' (Note: Accepting Output).

   A filter function must accept two arguments: the associated process
and a string, which is output just received from it.  The function is
then free to do whatever it chooses with the output.

   Quitting is normally inhibited within a filter function--otherwise,
the effect of typing `C-g' at command level or to quit a user command
would be unpredictable.  If you want to permit quitting inside a filter
function, bind `inhibit-quit' to `nil'.  Note: Quitting.

   If an error happens during execution of a filter function, it is
caught automatically, so that it doesn't stop the execution of whatever
program was running when the filter function was started.  However, if
`debug-on-error' is non-`nil', the error-catching is turned off.  This
makes it possible to use the Lisp debugger to debug the filter
function.  Note: Debugger.

   Many filter functions sometimes or always insert the text in the
process's buffer, mimicking the actions of Emacs when there is no
filter.  Such filter functions need to use `set-buffer' in order to be
sure to insert in that buffer.  To avoid setting the current buffer
semipermanently, these filter functions must save and restore the
current buffer.  They should also update the process marker, and in some
cases update the value of point.  Here is how to do these things:

     (defun ordinary-insertion-filter (proc string)
       (with-current-buffer (process-buffer proc)
         (let ((moving (= (point) (process-mark proc))))
           (save-excursion
             ;; Insert the text, advancing the process marker.
             (goto-char (process-mark proc))
             (insert string)
             (set-marker (process-mark proc) (point)))
           (if moving (goto-char (process-mark proc))))))

The reason to use `with-current-buffer', rather than using
`save-excursion' to save and restore the current buffer, is so as to
preserve the change in point made by the second call to `goto-char'.

   To make the filter force the process buffer to be visible whenever
new text arrives, insert the following line just before the
`with-current-buffer' construct:

     (display-buffer (process-buffer proc))

   To force point to the end of the new output, no matter where it was
previously, eliminate the variable `moving' and call `goto-char'
unconditionally.

   In earlier Emacs versions, every filter function that did regular
expression searching or matching had to explicitly save and restore the
match data.  Now Emacs does this automatically for filter functions;
they never need to do it explicitly.  Note: Match Data.

   A filter function that writes the output into the buffer of the
process should check whether the buffer is still alive.  If it tries to
insert into a dead buffer, it will get an error.  The expression
`(buffer-name (process-buffer PROCESS))' returns `nil' if the buffer is
dead.

   The output to the function may come in chunks of any size.  A program
that produces the same output twice in a row may send it as one batch of
200 characters one time, and five batches of 40 characters the next.  If
the filter looks for certain text strings in the subprocess output, make
sure to handle the case where one of these strings is split across two
or more batches of output.

 - Function: set-process-filter process filter
     This function gives PROCESS the filter function FILTER.  If FILTER
     is `nil', it gives the process no filter.

 - Function: process-filter process
     This function returns the filter function of PROCESS, or `nil' if
     it has none.

   Here is an example of use of a filter function:

     (defun keep-output (process output)
        (setq kept (cons output kept)))
          => keep-output
     (setq kept nil)
          => nil
     (set-process-filter (get-process "shell") 'keep-output)
          => keep-output
     (process-send-string "shell" "ls ~/other\n")
          => nil
     kept
          => ("lewis@slug[8] % "
     "FINAL-W87-SHORT.MSS    backup.otl              kolstad.mss~
     address.txt             backup.psf              kolstad.psf
     backup.bib~             david.mss               resume-Dec-86.mss~
     backup.err              david.psf               resume-Dec.psf
     backup.mss              dland                   syllabus.mss
     "
     "#backups.mss#          backup.mss~             kolstad.mss
     ")