About Lectures Research Software Blog
Musical Site
MySpace
Facebook

Moods Blog

Dojo Shin Kaï

RSS Feed
Thank you!

XHTML 1.0 conformant
CSS 2.0 conformant
Didier Verna's scientific blog: Lisp, Emacs, LaTeX and random stuff.

Tag - text editing

Entries feed - Comments feed

Wednesday, July 20 2011

One more indentation hack

Here's yet another indentation hack that I came up with recently.

All the work done by Nikodemus on the Slime indentation contrib is pretty cool, especially the notion of indentation style (though I wish the styles were Custom variables, but that is another story). I tend to use indentation styles for global, maybe collaborative preferences, but on several occasions however, I find that this approach has a couple of drawbacks.

  • One of them is that the indentation information is far away from the corresponding symbol, in a separate file. If you change a function's prototype for instance, you may also need to load the file(s) in which the corresponding style(s) is (are) defined and edit them.
  • The other problem is that if you want to let other people edit your source code and honor your indentation style, you also need to provide them with the style definition, and they need to load it separately.

For those reasons, I tend to think that the indentation style approach is not very well suited for project-specific indentation settings. What I would like is to provide indentation information close to the function definition, and also to have that information automatically available when anyone loads the project into Slime. Here's a way to do it.

The key to success here is the function swank:eval-in-emacs which, as its name suggests, sends some Emacs Lisp code to your (X)Emacs session for evaluation. This function effectively allows you to trigger some Emacs Lisp computation from a Common Lisp file. Remember that indentation information is stored in the common-lisp-indent-function property of a symbol. The function clindent below does this:

(defun clindent (symbol indent)
  "Set SYMBOL's indentation to INDENT in (X)Emacs.
This function sets SYMBOL's common-lisp-indent-function property.
If INDENT is a symbol, use its indentation definition.
Otherwise, INDENT is considered as an indentation definition."
  (when (and (member :swank *features*)
	     (let ((configuration
		     (find-symbol "MY.PACKAGE.CONFIGURATION" :cl-user)))
	       (when (and configuration (boundp configuration))
		 (getf (symbol-value configuration) :swank-eval-in-emacs))))
    (funcall (intern "EVAL-IN-EMACS" :swank)
	     `(put ',symbol 'common-lisp-indent-function
		   ,(if (symbolp indent)
			`(get ',indent 'common-lisp-indent-function)
		      `',indent))
	     t)))

As explained in the docstring, this function will ask (X)Emacs to put SYMBOL's common-lisp-indent-function property to a definition, either provided directly, or retrieved from another symbol. For example, if your package defines an econd macro, you may want to call it like this:

(clindent 'econd 'cond)

This function ensures that Swank is actually available before using it (first condition in the and clause). I will explain the other weird bits later on.

The next question is when exactly do we want to call this function? The answer is: pretty much on all occasions. Your code might be loaded from source and interpreted, or it might be compiled. But then, it might be compiled within or outside a Slime environment. In any case, you want your indentation information to be sent to (X)Emacs everytime it's possible. So obviously, we're gonna wrap this function in an eval-when form thanks to a macro. This is also a good opportunity to save some quoting.

(defmacro defindent (symbol indent)
  "Set SYMBOL's indentation to INDENT in (X)Emacs.
SYMBOL and INDENT need not be quoted.
See CLINDENT for more information."
  `(eval-when (:compile-toplevel :execute :load-toplevel)
     (clindent ',symbol ',indent)))

And now, right on top of your econd definition, you can just say this:

(defindent econd cond)

Now here's one final step. If your package uses its own readtable, it's even more convenient to define a reader-macro for indentation information. I choose #i:

(defun i-reader (stream subchar arg)
  "Read an argument list for the DEFINDENT macro."
  (declare (ignore subchar arg))
  (cons 'defindent (read stream)))
 
(set-dispatch-macro-character #\# #\i #'i-reader *readtable*)

And now, the code in my package will look like this:

#i(econd cond)
(defmacro econd #|...|#)

Pretty cool, eh?

All right. We still have two weirdos to explain in the clindent function.

First, you noticed that the function's computation is conditionalized on the existence of a cl-user::my.package.configuration variable, which actually stores a property list of various compiling or loading options for this package. The option we're interested in is :swank-eval-in-emacs, which must be set to non-nil. Here's why. The execution of Emacs Lisp code from Swank is (rightfully) considered as a security risk so it is disabled by default. If you want to authorize that, you need to set the (Emacs) variable slime-enable-evaluate-in-emacs to t. Otherwise, calling swank:evaluate-in-emacs is like calling 911. So we have a chicken-and-egg problem here: if we want to avoid an error in clindent, we would need to check the value of this variable, but in order to do that, we would need to evaluate something in (X)Emacs ;-)

The solution I choose is hence to disable the functionality by default, and document the fact that if people want to use my indentation information, they need to set both the Slime variable and my package-specific option to non-nil before loading the package (possibly setting them back to nil afterwards). They also need to trust that I'm not going to inject anything suspicious into their (X)Emacs session at the same time...

The last bit we need to explain is the final t argument passed to swank:eval-in-emacs. The corresponding parameter is called nowait in the function's prototype. It has something to do with asynchronous computation, and in fact, I don't really know what's going on under the hood, but what I do know is that if you set it to t, Swank doesn't care about the return value of your form anymore, which is fine because we're only doing a side effect. On the other hand, if you omit that parameter, Swank will try to interpret the return value in some way, and you will most probably get a serialization error. Indeed, the return value is the indentation definition itself, so for example, (&rest (&whole 2 &rest 1)) doesn't make (Common Lisp) sense.

That's it. Happy indenting!

Friday, May 6 2011

Common Lisp indentation in XEmacs

UPDATE: since the original publication of this blog entry, Nikodemus Siivola and I have done some more work on various other aspects of Common Lisp indentation, and I must say that the result is pretty satisfactory. Nikodemus has merged all the changes into Slime, and I have done so for XEmacs. If you're an XEmacs user, you don't need to use the slime-indentation contrib to get these improvements. Simply upgrade the "prog-modes" package and load cl-indent.el.

I have just modified XEmacs to improve the indentation of Common Lisp code. This change involves two things: the support for multiple method qualifiers in a call to defmethod and, much more importantly, a cleaner and more flexible scheme for indenting lambda lists. The patch has also been submitted to the GNU Emacs developers. Below is a more detailed description of what you get with these changes.

Method qualifiers

Until now, only one method qualifier was understood. Below are some examples demonstrating that the one method qualifier and the argument list are indented by 4 characters, and the method's body only by 2:

(defmethod foo :around ()        (defmethod foo :around
  do-this)                           ()
                                   do-this)
(defmethod foo
    :around ()                   (defmethod foo
  do-this)                           :around
                                     ()
                                   do-this)

Now let's add a second method qualifier:

(defmethod foo comb :around ()        (defmethod foo	    
	   do-this)			  comb :around () 
					  do-this)

Woops. Neither is correct. But now, you get this instead:

(defmethod foo comb :around ()        (defmethod foo	    
  do-this)				  comb :around () 
					do-this)

Three more examples to show how confused we were:

(defmethod foo comb :around     (defmethod foo comb     (defmethod foo 
  ()				    :around		    comb       
  do-this)			  ()			    :around    
				  do-this)		  ()	       
							  do-this)

And how better we just got:

(defmethod foo comb :around     (defmethod foo comb     (defmethod foo
    ()				    :around		    comb      
  do-this)			    ()			    :around   
				  do-this)		    ()	      
							  do-this)

Indeed, you can see that everything between the method's name and its body is now correctly indented by 4.

Lambda Lists

The next round of changes deals with the formatting of lambda-lists. As such, this will apply everywhere a lambda-list is expected, such as defun, defgeneric, defmethod etc. First of all, here are two examples showing that we were not very clever before:

(defun foo (mand1 mand2
	    &optional opt1
	    opt2
	    &rest args
	    &key key1 key2
	    (key3 val3) &aux aux1
	    aux2)
  do-this)

(defun foo (mand1 mand2 &optional opt1
	    opt2
	    &rest args
	    &key key1 key2
	    (key3 val3) &aux aux1
	    aux2)
  do-this)

Basically, everything was blindly aligned at the beginning of the lambda-list. Here is what you get now:

(defun foo (mand1 mand2
	    &optional opt1
	      opt2
	    &rest args
	    &key key1 key2
	      (key3 val3) &aux aux1
			    aux2)
  do-this)

(defun foo (mand1 mand2 &optional opt1
			  opt2
	    &rest args
	    &key key1 key2
	      (key3 val3) &aux aux1
			    aux2)
  do-this)

The difference is that keyword parameters are indented with respect to their corresponding keyword. The amount of indentation is provided by a new customizable user option named lisp-lambda-list-keyword-parameter-indentation (oh boy, what a mouthful). If you prefer, you can also have the parameters vertically aligned with each other. Set the new customizable user option named lisp-lambda-list-keyword-parameter-alignment to t and you will get this instead:

(defun foo (mand1 mand2
	    &optional opt1
		      opt2
	    &rest args
	    &key key1 key2
		 (key3 val3) &aux aux1
				  aux2)
  do-this)

(defun foo (mand1 mand2 &optional opt1
				  opt2
	    &rest args
	    &key key1 key2
		 (key3 val3) &aux aux1
				  aux2)
  do-this)

Finally, just as you could align keyword parameters together, you can also align the keywords together. Set the new customizable user option named lisp-lambda-list-keyword-alignment to t, and you will get this (only the second example differs):

(defun foo (mand1 mand2 &optional opt1
				  opt2
			&rest args
			&key key1 key2
			     (key3 val3) &aux aux1
					      aux2)
  do-this)

These are in fact my preferred settings, although both alignment options default to nil. Here is a final example demonstrating how you could format a long lambda-list with plenty of arguments:

(defun foo (mand1 mand2
	    &optional
	      opt1 opt2 opt3
	    &key
	      key1 key2 key3
	    &aux
	      aux1 aux2 aux3)
  do-this)

These indentation problems have been a huge peeve of mine for quite a long time. I hope you will find the changes useful!

French Flag English Flag
Copyright (C) 2008 -- 2018 Didier Verna didier@lrde.epita.fr