GNU bug report logs - #3098
23.0.92; improving documentation of process filter functions

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 3098 in the body.
You can then email your comments to 3098 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Markus Triska <markus.triska <at> gmx.at>
To: emacs-pretest-bug <at> gnu.org
Subject: 23.0.92; improving documentation of process filter functions
Date: Fri, 24 Apr 2009 19:04:42 +0200

The documentation of process filter functions states:

   The expression `(buffer-name (process-buffer PROCESS))' returns
   `nil' if the buffer is dead.

Instead of `buffer-name', it seems better to use `buffer-live-p' here:
For one thing, it will also work when process-buffer is `nil', whereas
`buffer-name' would then evaluate to the name of the current buffer.

And, although the documentation also says:

   A filter function that writes the output into the buffer of the
   process should check whether the buffer is still alive.

the `ordinary-insertion-filter' example does not heed this advice.

Suggestion:

2009-04-24  Markus Triska  <markus.triska <at> gmx.at>

	* processes.texi (Filter Functions): Use `buffer-live-p' instead
	of `buffer-name' in the main text as well as in the example.

diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 64d2d7d..6f54eb6 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -1249,25 +1249,28 @@ filter function.  @xref{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 @code{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:
+filter.  Such filter functions need to use @code{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.  Such filter functions should also check whether
+the buffer is still alive, since inserting into a dead buffer will
+raise an error. They should also update the process marker, and in
+some cases update the value of point.  Here is how to do these things:
 
 @smallexample
 @group
 (defun ordinary-insertion-filter (proc string)
-  (with-current-buffer (process-buffer proc)
-    (let ((moving (= (point) (process-mark proc))))
+  (when (buffer-live-p (process-buffer proc))
+    (with-current-buffer (process-buffer proc)
+      (let ((moving (= (point) (process-mark proc))))
 @end group
 @group
-      (save-excursion
-        ;; @r{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))))))
+        (save-excursion
+          ;; @r{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)))))))
 @end group
 @end smallexample
 
@@ -1294,12 +1297,6 @@ 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.  @xref{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
-@code{(buffer-name (process-buffer @var{process}))} returns @code{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


In GNU Emacs 23.0.92.2 (i386-apple-darwin9.6.1, GTK+ Version 2.14.7)
 of 2009-04-05 on mt-imac.local
Windowing system distributor `The X.Org Foundation', version 11.0.10402000
configured using `configure  '--with-tiff=no''

Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: en.UTF-8
  value of $XMODIFIERS: nil
  locale-coding-system: utf-8-unix
  default-enable-multibyte-characters: t

Message #12 received at 3098 <at> debbugs.gnu.org (full text, mbox):

From: Chong Yidong <cyd <at> stupidchicken.com>
To: Markus Triska <markus.triska <at> gmx.at>
Cc: 3098 <at> debbugs.gnu.org
Subject: Re: 23.0.92; improving documentation of process filter functions
Date: Tue, 24 Aug 2010 16:44:07 -0400

> 2009-04-24  Markus Triska  <markus.triska <at> gmx.at>
>
> * processes.texi (Filter Functions): Use `buffer-live-p' instead
> of `buffer-name' in the main text as well as in the example.

Thanks, committed.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.