37.9.2 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 (see section 21.9 Waiting for Elapsed Time or Input), and in accept-process-output (see section 37.9.3 Accepting Output from Processes).

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. See section 21.10 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. See section 18.1 The Lisp 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. See section 34.6 The 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 ")