3. New Indentation Engine

VHDL Mode has a new indentation engine, providing a simplified, yet flexible and general mechanism for customizing indentation. It breaks indentation calculation into two steps. First for the line of code being indented, VHDL Mode analyzes what kind of language construct it's looking at, then it applies user defined offsets to the current line based on this analysis.

This section will briefly cover how indentation is calculated in VHDL Mode. It is important to understand the indentation model being used so that you will know how to customize VHDL Mode for your personal coding style.

3.1 Syntactic Analysis

The first thing VHDL Mode does when indenting a line of code, is to analyze the line, determining the syntactic component list of the construct on that line. A syntactic component consists of a pair of information (in lisp parlance, a cons cell), where the first part is a syntactic symbol, and the second part is a relative buffer position. Syntactic symbols describe elements of VHDL code, e.g. statement, comment, block-open, block-close, etc. See section 6. Syntactic Symbols, for a complete list of currently recognized syntactic symbols and their semantics. Also, the variable vhdl-offsets-alist contains the list of currently supported syntactic symbols.

Conceptually, a line of VHDL code is always indented relative to the indentation of some line higher up in the buffer. This is represented by the relative buffer position in the syntactic component.

It might help to see an example. Suppose we had the following code as the only thing in a VHDL Mode buffer (1):

  1: inverter : process
  2: begin
  3:   q <= not d;
  4:   wait on d;
  5: end inverter;

We can use the command C-c C-x (vhdl-show-syntactic-information) to simply report what the syntactic analysis is for the current line. Running this command on line 4 of example 1, we'd see in the echo area:

((statement . 28))

This tells us that the line is a statement and it is indented relative to buffer position 28, which happens to be the `q' on line 3. If you were to move point to line 3 and hit C-c C-x, you would see:

((statement-block-intro . 20))

This indicates that line 3 is the first statement in a block, and is indented relative to buffer position 20, which is the `b' in the begin keyword on line 2.

Syntactic component lists can contain more than one component, and individual syntactic compenents need not have relative buffer positions. The most common example of this is a line that contains a comment only line.

%%% TBD %%%

Hitting C-c C-x on line 3 of the example gives us:

((comment-intro) (block-intro . 46))

so you can see that the syntactic component list contains two syntactic components. Also notice that the first component, `(comment-intro)' has no relative buffer position.

3.2 Indentation Calculation

Indentation for the current line is calculated using the syntactic component list derived in step 1 above (see 3.1 Syntactic Analysis). Each component contributes to the final total indentation of the line in two ways.

First, the syntactic symbols are looked up in the vhdl-offsets-alist variable, which is an association list of syntactic symbols and the offsets to apply for those symbols. These offsets are added to the running total.

Second, if the component has a relative buffer position, VHDL Mode adds the column number of that position to the running total. By adding up the offsets and columns for every syntactic component on the list, the final total indentation for the current line is computed.

Let's use our code example above to see how this works. Here is our example again.

  1: inverter : process
  2: begin
  3:   q <= not d;
  4:   wait on d;
  5: end inverter;

Let's say point is on line 3 and we hit the TAB key to re-indent the line. Remember that the syntactic component list for that line is:

((statement-block-intro . 20))

VHDL Mode looks up statement-block-intro in the vhdl-offsets-alist variable. Let's say it finds the value `2'; it adds this to the running total (initialized to zero), yielding a running total indentation of 2 spaces.

Next VHDL Mode goes to buffer position 20 and asks for the current column. Since the begin keyword at buffer position 20 is in column zero, it adds `0' to the running total. Since there is only one syntactic component on the list for this line, indentation calculation is complete, and the total indentation for the line is 2 spaces. Simple, huh?

Actually, the mode usually just does The Right Thing without you having to think about it in this much detail. But when customizing indentation, it's helpful to understand the general indentation model being used.

To help you configure VHDL Mode, you can set the variable vhdl-echo-syntactic-information-p to non-nil so that the syntactic component list and calculated offset will always be echoed in the minibuffer when you hit TAB.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.