ELisp macros for MINOS coding conventions

1. Introduction.
2. Overview
3. Procurement, Installation and setup.
4. Usage.
5. Customization.
6. Modification guide.

See also how to doxygenate your code.

1. Introduction

   When I got to the section in the MINOS coding convention document regarding the formatting of source code it reminded me of some simple, kludgy emacs lisp code I had used in the past to save me typing time when starting a new file. I figured I might be able to extend them for MINOS. Luckily before I got very far on this I stumbled onto tempo.el which I had unwittingly used before as the underlining engine of the very nice html-helper-mode.el.

   I started looking at the tempo.info file and realized it is a really easy package to use so I started fooling around with trying to codify the conventions which relate to formatting. A few hours later I had something which actually worked. The major time was spent in learning elisp. After this initial coding it should be very trivial for me and others how have a passing understanding of lisp to add in other and modify existing rules.

   This code mainly exists for my own benefit, but I would be very happy if others found it useful and ecstatic if people actually wanted to improve on them.

   Finally, this documentation is almost longer than the actual code.

2. Overview

   This set of macros will allow you to greatly reduce the number of keystrokes you must use when starting a new header (.h) or implementation (.cxx) file. It will also help you adhere to MINOS coding conventions.

   The macros work by prompting you for the salient information about the Class, Method or other language constructs you are working on. From this a skeleton or template of code is constructed and inserted into your buffer following the coding conventions. You can then traverse the skeleton to various ``hot points'' and fill in the details.

3. Procurement, installation and setup

   Procurement:

   • tempo.el (local copy), (original authors site) This file may already be on your system. It comes with GNU emacs and may come with your installation of XEmacs as well (on Debian GNU/Linux it is part of xemacs21-basesupport package). It is also needed in html-helper-mode.el so if you happen to already be using this you will have it. Don't worry about versions, it is an old package. If you don't have it installed, just download it.

   • minos-conventions.el (Obviously.)
   • minos.el

   Installation:

   1. Place the minos-conventions.el and minos.el files (and tempo.el file if you had to download it) somewhere in your emacs lisp load-path.
   2. If you don't know what ``emacs lisp load-path'' means then do something like the following:

            mkdir ~/.elisp
            

      And add the line:

            (setq load-path (cons (expand-file-name "~/.elisp") load-path))
            

      to your .emacs file. Now place the required files in this directory.

   Setup:

   • Setup is simple (note the above step), just add:

           (load "minos.el") 
           

     to your .emacs file.

4. Usage

   Usage is very simple. By default anything you do is initiated by the keystrokes:

       C-cmc
       

   that is, typing a `Control-c' followed by an `m' and a `c' (short for Minos Conventions). These keys are only bound locally (ie. only in c++-mode). You will then be prompted for the name of the block of code which should be inserted into the current buffer. If you don't know what the name is, just hit the TAB key and you will be given a list of possibilities which look something like:

       C-cmc
       Block name: TAB
       

       Possible completions are: 
       header-file     implementation-file 
       

   See below for how to turn on more functionality

   File name completion works, so typing ``imp-TAB'' will complete to ``implementation-file''. After a block type is chosen you will be prompted for various pieces of info such as name of Class (which defaults to be the same as the file's name).

   If a prompted input is caught as not fitting the convention you will warned and given a chance to quit the current macro or just accept the unconventional format.

   Once a template has been inserted into your buffer you can traverse key points which need further filling in by using the the ``M-]'' and ``M-['' keys. (Unfortunately, these hot points are not saved after closing the file.) These will jump the cursor forward and backward, respectively, among the points which may need further editing.

5. Customization

   By default, minos-convention.el will be in a novice and verbose mode. This means not all functionality will be present and that verbose comments will be inserted into your buffer. In general, these comments should be deleted. They give examples or other helpful comments.

   Increased functionality will make more templates available and is turned on by putting the following in your .emacs file:

       (setq minos-convention-expert t)
       

   To turn off the ``helpful'' comments you can use:

       (setq minos-convention-verbose nil)
       

   Other customizations can be made by directly editing the minos.el file. If you wish, take a look at this file, however, it is not necessary in order to use these macros.

   If there is some manner of customization which is required and is not readily obvious how to implement, contact me.

6. Modification Guide

   There is not a whole lot to this package. There are two files:

   • minos.el will load the main file as well as set up CC mode (the mode implementing c++-mode) so that you don't need to. This is done because parts of minos-conventions.el rely on the user's c++-mode being correctly configured and it can be dificult for some people to learn how to do this.

   • minos-conventions.el holds the main body of the code which produces the templates. It is described below.

   The minos-conventions.el is split into 4 parts:

   1. Definition of the function and related variables which gets hooked into the c-mode and the c++-mode. This function binds the keys discussed above and initializes tempo.el.

   2. The template definition section is next. The templates are written in a special elisp language that the tempo.el engine interprets. It is very simple and essentially you just write what looks like C++ with some mark-up tags. You are able to prompt the user for values, but not able to do a lot general elisp.

      Since the template syntax is so simple and fairly well described in the tempo.info it won't be described here.

   3. Then comes some local helper functions. This consists largely of routines which prompt the user for something (ie the Class name) and do some checks against the conventions.

   4. Finally, the minos-convention- routines are defined. These are often just light wrappers around the corresponding tempo-template-minos- functions. The reason to wrap this is if some programming functionality is needed for a particular wrapper, it usually can not be done in the context of the template definition.

      For each minos-convention- function, one must put a entry in the read statement in the minos-convention function so as to allow completion. The entry must match the name of the function as the function call is actually built from this name.

   To add a new convention implementation, roughly follow these steps:
   1. Add a template (or templates) in the template section. Any info that the user gives which should be checked against conventions should be read directly from the mini-buffer. For examples see the get-* and *-okay-p functions in the helper function section. If the info doesn't need to be checked, then you can use tempo.el's input mechanism. If parts of your template can be used in multiple contexts break it up into multiple templates.

   2. Write a minos-convention-* function which is responsible for calling any get/check info functions and calling the one or more tempo-template-minos-* functions. If you do use the get/check mechanism, choose variable names which are the same as pre-existing ones if possible (ie, classname when prompting for the name of the class, so as to make it easy to mix and match different templates.

   3. Add the appropriate entry to the comp-list alist in the minos-convention function. If it is an ``expert'' function, set it inside the if-statement, o.w., set it in the let-statement.