Irreal

In a comment to my Emacs comment-box Revisited post, Aaron showed me a nice way to deal with the boundaries of expanding regions. Recall that in that post I wanted to pad the first line of a comment out to the fill column so that comment-box would draw the box across the whole width (more or less) of the window. The problem was that adding those blanks increased the size of the region so the character number of the end of the region was no longer correct. In my code that was easily fixed because I could use (point-max) to locate the end of the region since I had narrowed the buffer to the region.

Aaron’s way of handling this is nice because it feels less ad hoc and because it works for any position in the buffer not just the beginning or end. The idea is to use a marker to point at the end of the region. Conceptually, a marker is just like a position (that is a character index into the buffer) but it has the nice property that if you change the size of the buffer, the marker is adjusted when necessary. It’s as if you planted a flag at the position and the flag moves as the buffer expands or contracts.

Here’s what the revised code looks like

(defun jcs-comment-box (b e)
  "Draw a box comment around the region but arrange for the region
to extend to at least the fill column. Place the point after the
comment box."
  (interactive "r")
  (let ((e (copy-marker e t)))
    (goto-char b)
    (end-of-line)
    (insert-char ?  (- fill-column (current-column)))
    (comment-box b e 1)
    (goto-char e)
    (set-marker e nil)))

As you can see, I’ve replaced the with-region-or-buffer macro with the more sensible (interactive "r"). The copy-marker function will make a copy of an existing marker or if its first argument is a position it will make a marker with that offset. The (optional) second argument says that if text is added at the marker then move the marker ahead. A nil would say the leave the marker where it is. The (set-marker e nil) at the end of the function makes the marker point nowhere. It’s not strictly necessary but it lets Emacs stop worrying about keeping it updated as you further edit the buffer. As you can see, you can treat the marker just you would a position: you can use it as a position, move to it, and even do arithmetic on it.

Chapter 31 of the Emacs Lisp Manual explains markers further. It’s short and interesting so it’s worth a read if you like programming in Emacs Lisp.

Last week I wrote about Comment Boxes In Emacs and gave some examples of how the comment-box command provides an easy way to draw a box around a comment. The only problem is that I want the boxes to extend almost to the right hand margin. Instead of

##########################################
# get-cred -- Get the user's credentials #
##########################################
(defun get-cred ()
...)

I want

##########################################################################
# get-cred -- Get the user's credentials                                 #
##########################################################################
(defun get-cred ()
...)

One could argue, I suppose, that this adds nothing except some useless blanks to the file but I’ve always done it that way and as Henry Higgins might say, “I’ve grown accustomed to its face.” So, how to do it?

My idea was simple: pad the first line with blanks out to the fill column, and then call comment-box to draw the actual box. There’s nothing special about using the fill column as the right hand edge but it makes the function behave well for any size window.

I thought I’d knock off a quick bit of Elisp and be done. It didn’t work out that way. I kept getting a mysterious error that appeared to come from save-restriction (see the code below). After that lot of mucking about I discovered that the real problem was the call to comment-box. The documentation says that there’s an optional third argument to add extra space and, indeed, the beginning of the function is

(defun comment-box (beg end &optional arg)
...)

so I didn’t bother specifying the third argument. It turns out, though, that in the comment-box function we have this line

(comment-region beg end (+ comment-add arg))

so that the optional argument is always used. It works OK in the interactive case because the call to interactive is

(interactive "*r\np")

which causes the prefix argument to be passed to arg. When no prefix argument is specified, this results in a 1 being passed to arg so arg is never nil the way it is if you call comment-box from Elisp with only two arguments. That’s obviously a bug but it’s a small one. At least it’s a small one once you figure out what’s happening.

In any event, once I solved that problem it was easy to write the function:

(defun jcs-comment-box ()
  "Draw a box comment around the region but arrange for the region
to extend to at least the fill column. Place the point after the
comment box."
  (interactive)
  (with-region-or-buffer (b e)
    (save-restriction
      (narrow-to-region b e)
      (goto-char b)
      (end-of-line)
      (insert-char ?  (- fill-column (current-column)))
      (comment-box b (point-max) 1)
      (goto-char (point-max)))))

As you can see, we first move to the beginning of the first line, then to its end, and then we pad the line with blanks out to fill-column. A few comments on the rest of the code:

• It would probably be easier to use

  (interactive "r")
  

  rather than the with-region-or-buffer macro but I write that almost automatically when I’m dealing with a possible region so I just kept it.

• insert-char does nothing if the count is not positive so I didn’t have to worry about whether or not the first line already extended to or past the fill column.
• Using the narrow-to-region function makes it really easy to move around the buffer and helps deal with the fact that I’m changing the size of the region as I go. This problem was described by Xah Lee.
• Notice that even the narrow-to-region doesn’t completely insulate me from the effects of changing the buffer size. I have to use (point-max) as the end of the region (instead of b) in the call to comment-box because b no longer points to the end of the region.

Here’s a neat little hack that can save a bit of time. Emacs has the comment-box command that will put a mode-specific comment box around a region. For example, suppose you have the Elisp

A function to do something very profound.
It is called from the top level.
(defun be-profound ()
...)

and that you select the first two lines and call comment-box. You get

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; A function to do something very profound. ;
; It is called from the top level.          ;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(defun be-profound ()
...)

Similarly if you have some C code like

Here is the the main function
that does something or another

int main ( int argc, char **argv)

and select the first two lines and call comment-box you get

/**********************************/
/* Here is the the main function  */
/* that does something or another */
/**********************************/

int main ( int argc, char **argv)

Back when I was writing a lot of C code I used to put a comment box like that in front of every function. I did it by hand so it was sort of pain. I wish I’d had, or known about, something like comment-box to help me out (that was when I was using Vim).