Comment boxes for R scripts within Emacs
Some people like to insert nice comment boxes in their R scripts. Using Emacs and ESS, this is easy to achieve thanks to the lisp function
A first example
Without any customization, here is an example of how
comment-box can help you:
comment-box inserts a comment box around the desired region; and the box width corresponds to the region width.
Some additional customization may be useful.
A possible keybinding
First, it would be convenient to define a keybinding for this function :
M-x comment-box is quite a long instruction (and you have also to set the region manually, which adds another operation).
Automatically adjust the number of # in the left margin of the comment box
ESS handles comments in a particular way, according to the number of
# that introduce them. According to the manual:
By default, comments beginning with ‘###’ are aligned to the beginning of the line. Comments beginning with ‘##’ are aligned to the current level of indentation for the block containing the comment. Finally, comments beginning with ‘#’ are aligned to a column on the right
This behavior may be modified, but I find it really useful (and natural since it is consistent with Lisp conventions).
comment-box inserts two
# in the left margin of the comment box, so that the box may be indented depending on its position within the R script. But you may want a simple rule such as:
- if the comment box corresponds to a 0-level of indentation, then it should start with three
- otherwise, the comment box should start with two
#only, and will be indented accordingly
This allows to distinguish different levels of information within the R script. Of course, you can provide a prefix argument to the
comment-box function to adjust manually the number of
# that are required, but this is quite cumbersome. A piece of Lisp code that handles that automatically is given below.
A proposition of Lisp code
The following Emacs Lisp code might help.
(defun ess-r-comment-box-line () "Insert a comment box around the text of the current line of an R script. If the current line indentation is 0, the comment box begins with ###. Otherwise, it begins with ## and is indented accordingly." (interactive) (save-excursion (let ((beg (progn (back-to-indentation) (point))) (end (line-end-position))) (comment-box beg end (if (> (current-indentation) 0) 1 2))))) ;; A keybinding specific to ESS-R mode: (add-hook 'ess-r-mode-hook '(lambda () (local-set-key (kbd "\C-cb") #'ess-r-comment-box-line)))
This code allows three things to facilitate and standardize the use of comment boxes into an R script:
- there is no need to set the region anymore: the comment box is inserted around the text of the current line, automatically
- the number is
#is adjusted according to the level of identation
- the keybinding
C-c bis proposed to trigger the function in ESS-R mode.
Here is an example of its use:
Of course, all this is only an illustration of a possible use and customization of
comment-box, and the present example is mainly a matter of personal taste.
Happy comment boxing!