     [file docstyle.texi not included]

VHDL Mode, an Emacs mode for editing VHDL code
**********************************************

This file documents VHDL Mode, an Emacs mode for editing VHDL code.

Copyright © 1995--2008, 2010, 2012, 2015--2020 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover Texts as in (a) below.  A copy of the license is included in the section entitled ``GNU Free Documentation License.''

     (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and modify this GNU manual.''

Introduction
************

Welcome to VHDL Mode. This is a GNU Emacs mode for editing files containing VHDL code.

This manual will describe the following:

  * How to get started using VHDL Mode.

  * How the indentation engine works.

  * How to customize the indentation engine.

The major version number was incremented to 3 with the addition of many new features for editing VHDL code to the new indentation engine, which was introduced in major version 2. To find the minor revision number of this release, use M-x vhdl-version RET.

A special word of thanks goes to Rod Whitby, who wrote the VHDL Mode indentation engine, and to Barry Warsaw, who wrote the CC Mode indentation engine that formed the basis thereof. Their manuals were also the basis for this manual.

This manual is not very up-to-date. It basically contains the indentation machine documentation by Rod Whitby with only minor adaptions. A short documentation of the entire VHDL Mode is available within the mode itself by typing C-c C-h. Also, all commands and customization of most variables are available through the menu, which makes everything highly self-explaining.

Getting Connected
*****************

To get started, simply visit a .vhd file in Emacs; or type M-x vhdl-mode RET.

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.

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 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  (The line numbers in this and future examples don't actually appear in the buffer.):

       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 components 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.

Indentation Calculation
=======================

Indentation for the current line is calculated using the syntactic component list derived in step 1 above (see 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.

Customizing Indentation
***********************

The vhdl-offsets-alist variable is where you customize all your indentations.  You simply need to decide what additional offset you want to add for every syntactic symbol.  You can use the command C-c O (vhdl-set-offset) as the way to set offsets, both interactively and from your mode hook.  Also, you can set up styles of indentation.  Most likely, you'll find one of the pre-defined styles will suit your needs, but if not, this section will describe how to set up basic editing configurations.  See Styles, for an explanation of how to set up named styles.

As mentioned previously, the variable vhdl-offsets-alist is an association list between syntactic symbols and the offsets to be applied for those symbols.  In fact, these offset values can be an integer, a function or variable name, or one of the following symbols: +, -, ++, --, *, or /.  The symbol values have the following meanings:

  * +  --  1 x vhdl-basic-offset

  * -  --  -1 x vhdl-basic-offset

  * ++ --  2 x vhdl-basic-offset

  * -- --  -2 x vhdl-basic-offset

  * *  --  0.5 x vhdl-basic-offset

  * /  --  -0.5 x vhdl-basic-offset

So, for example, because most of the default offsets are defined in terms of +, -, and 0, if you like the general indentation style, but you use 2 spaces instead of 4 spaces per level, you can probably achieve your style just by changing vhdl-basic-offset like so (in your .emacs file):

     (setq vhdl-basic-offset 2)

To change indentation styles more radically, you will want to change the value associated with the syntactic symbols in the vhdl-offsets-alist variable.  First, I'll show you how to do that interactively, then I'll describe how to make changes to your .emacs file so that your changes are more permanent.

Interactive Customization
=========================

As an example of how to customize indentation, let's change the style of the example above from:

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

to:

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

In other words, we want to change the indentation of the statements inside the inverter process.  Notice that the construct we want to change starts on line 3.  To change the indentation of a line, we need to see which syntactic component affect the offset calculations for that line.  Hitting C-c C-x on line 3 yields:

     ((statement-block-intro . 20))

So we know that to change the offset of the first signal assignment, we need to change the indentation for the statement-block-intro syntactic symbol.  To do this interactively, just hit C-c O (vhdl-set-offset).  This prompts you for the syntactic symbol to change, providing a reasonable default.  In this case, the default is statement-block-intro, which is just the syntactic symbol we want to change!

After you hit return, VHDL Mode will then prompt you for the new offset value, with the old value as the default.  The default in this case is +, so hit backspace to delete the +, then hit ++ and RET.  This will associate an offset of twice the basic indent with the syntactic symbol statement-block-intro in the vhdl-offsets-alist variable.

To check your changes quickly, just enter M-x vhdl-indent-defun to reindent the entire function.  The example should now look like:

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

Notice how just changing the offset on line 3 is all we needed to do. Since the other affected lines are indented relative to line 3, they are automatically indented the way you'd expect.  For more complicated examples, this may not always work.  The general approach to take is to always start adjusting offsets for lines higher up in the file, then re-indent and see if any following lines need further adjustments.

Permanent Indentation
=====================

To make this change permanent, you need to add some lisp code to your .emacs file.  VHDL Mode provides a vhdl-mode-hook that you can use to customize your language editing styles.  This hook gets run as the last thing when you enter VHDL Mode.

Here's a simplified example of what you can add to your .emacs file to make the changes described in the previous section (Interactive Customization) more permanent.  See the Emacs manuals for more information on customizing Emacs via hooks. See Sample Init File, for a more complete sample .emacs file.

     (defun my-vhdl-mode-hook ()
       ;; my customizations for all of vhdl-mode
       (vhdl-set-offset 'statement-block-intro '++)
       ;; other customizations can go here
       )
     (add-hook 'vhdl-mode-hook 'my-vhdl-mode-hook)

For complex customizations, you will probably want to set up a style that groups all your customizations under a single name.  See Styles.

The offset value can also be a function, and this is how power users gain enormous flexibility in customizing indentation.  See Advanced Customizations.

Styles
======

Most people only need to edit code formatted in just a few well-defined and consistent styles.  For example, their organization might impose a ``blessed'' style that all its programmers must conform to.  Similarly, people who work on GNU software will have to use the GNU coding style on C code.  Some shops are more lenient, allowing some variety of coding styles, and as programmers come and go, there could be a number of styles in use.  For this reason, VHDL Mode makes it convenient for you to set up logical groupings of customizations called styles, associate a single name for any particular style, and pretty easily start editing new or existing code using these styles.  This chapter describes how to set up styles and how to edit your C code using styles.

Built-in Styles
---------------

If you're lucky, one of VHDL Mode's built-in styles might be just what you're looking for.  Some of the most common VHDL styles are already built-in.  These include:

  * GNU -- the coding style in the IEEE Language Reference Manual.

If you'd like to experiment with these built-in styles you can simply type M-x vhdl-set-style RET in a VHDL Mode buffer.

You will be prompted for one of the above styles (with completion). Enter one of the styles and hit RET.  Note however that setting a style in this way does not automatically re-indent your file.

Once you find a built-in style you like, you can make the change permanent by adding a call to your .emacs file.  Let's say for example that you want to use the IEEE style in all your files.  You would add this:

     (defun my-vhdl-mode-hook ()
       ;; use IEEE style for all VHDL code
       (vhdl-set-style "IEEE")
       ;; other customizations can go here
       )
     (add-hook 'vhdl-mode-hook 'my-vhdl-mode-hook)

See Permanent Customization.

Adding Styles
-------------

If none of the built-in styles is appropriate, you'll probably want to add a new style definition.  Styles are kept in the vhdl-style-alist variable, but you probably won't want to modify this variable directly. VHDL Mode provides a function, called vhdl-add-style, that you can use to easily add new styles or update existing styles.  This function takes two arguments, a STYLENAME string, and an association list DESCRIPTION of style customizations.  If STYLENAME is not already in vhdl-style-alist, the new style is added, otherwise the style already associated with STYLENAME is changed to the new DESCRIPTION.  This function also takes an optional third argument, which if non-nil, automatically institutes the new style in the current buffer.

The sample .emacs file provides a concrete example of how a new style can be added and automatically set.  See Sample Init File.

File Styles
-----------

The Emacs manual describes how you can customize certain variables on a per-file basis by including a Local Variable block at the end of the file.  So far, you've only seen a functional interface to VHDL Mode, which is highly inconvenient for use in a Local Variable block.  VHDL Mode provides two variables that make it easier for you to customize your style on a per-file basis.

The variable vhdl-file-style can be set to a style name string as described in Built-in Styles.  When the file is visited, VHDL Mode will automatically set the file's style to this style using vhdl-set-style.

Another variable, vhdl-file-offsets, takes an association list similar to what is allowed in vhdl-offsets-alist.  When the file is visited, VHDL Mode will automatically institute these offsets using vhdl-set-offset.  See Customizing Indentation.

Note that file style settings (i.e., vhdl-file-style) are applied before file offset settings (i.e., vhdl-file-offsets).

Advanced Customizations
=======================

For most users, VHDL Mode will support their coding styles with very little need for customizations.  Usually, one of the standard styles defined in vhdl-style-alist will do the trick.  Sometimes, one of the syntactic symbol offsets will need to be tweaked slightly, or perhaps vhdl-basic-offset will need to be changed.  However, some styles require a more advanced ability for customization, and one of the real strengths of VHDL Mode is that the syntactic analysis model provides a very flexible framework for customizing indentation. This allows you to perform special indentation calculations for situations not handled by the mode directly.

Custom Indentation Functions
----------------------------

One of the most common ways to customize VHDL Mode is by writing custom indentation functions and associating them with specific syntactic symbols (see Syntactic Symbols).  VHDL Mode itself uses custom indentation functions to provide more sophisticated indentation, for example when lining up selected signal assignments:

     %%% TBD %%%

In this example, the statement-cont syntactic symbol has an offset of +, and vhdl-basic-offset is 2, so lines 4 through 6 are simply indented two spaces to the right of line 3.  But perhaps we'd like VHDL Mode to be a little more intelligent so that it offsets the waveform descriptions relative to the signal assignment operator in line 3.  To do this, we have to write a custom indentation function which finds the column of signal assignment operator on the first line of the statement.  Here is the lisp code (from the vhdl-mode.el source file) that implements this:

     (defun vhdl-lineup-statement-cont (langelem)
       ;; line up statement-cont after the assignment operator
       (save-excursion
         (let* ((relpos (cdr langelem))
     	   (assignp (save-excursion
     		     (goto-char (vhdl-point 'boi))
     		     (and (re-search-forward "\\(<\\|:\\)="
     					     (vhdl-point 'eol) t)
     			  (- (point) (vhdl-point 'boi)))))
     	   (curcol (progn
     		     (goto-char relpos)
     		     (current-column)))
     	   foundp)
           (while (and (not foundp)
     		  (< (point) (vhdl-point 'eol)))
     	(re-search-forward "\\(<\\|:\\)=\\|(" (vhdl-point 'eol) 'move)
     	(if (vhdl-in-literal (cdr langelem))
     	    (forward-char)
     	  (if (= (preceding-char) ?\()
     	      ;; skip over any parenthesized expressions
     	      (goto-char (min (vhdl-point 'eol)
     			      (scan-lists (point) 1 1)))
     	    ;; found an assignment operator (not at eol)
     	    (setq foundp (not (looking-at "\\s-*$"))))))
           (if (not foundp)
     	  ;; there's no assignment operator on the line
     	  vhdl-basic-offset
     	;; calculate indentation column after assign and ws, unless
     	;; our line contains an assignment operator
     	(if (not assignp)
     	    (progn
     	      (forward-char)
     	      (skip-chars-forward " \t")
     	      (setq assignp 0)))
     	(- (current-column) assignp curcol))
           )))

Custom indent functions take a single argument, which is a syntactic component cons cell (see Syntactic Analysis).  The function returns an integer offset value that will be added to the running total indentation for the line.  Note that what actually gets returned is the difference between the column that the signal assignment operator is on, and the column of the buffer relative position passed in the function's argument.  Remember that VHDL Mode automatically adds in the column of the component's relative buffer position and we don't want that value added into the final total twice.

Now, to associate the function vhdl-lineup-statement-cont with the statement-cont syntactic symbol, we can add something like the following to our vhdl-mode-hook:

     (vhdl-set-offset 'statement-cont 'vhdl-lineup-statement-cont)

Now the function looks like this after re-indenting (using M-x vhdl-indent-defun):

     %%% TBD %%%

Custom indentation functions can be as simple or as complex as you like, and any syntactic symbol that appears in vhdl-offsets-alist can have a custom indentation function associated with it.  Note however that using many custom indentation functions may have a performance impact on VHDL Mode.

Other Special Indentations
--------------------------

One other variable is available for you to customize VHDL Mode: vhdl-special-indent-hook.  This is a standard hook variable that is called after every line is indented by VHDL Mode.  You can use it to do any special indentation or line adjustments your style dictates, such as adding extra indentation to the port map clause in a component instantiation, etc.  Note however, that you should not change point or mark inside your vhdl-special-indent-hook functions.

Syntactic Symbols
*****************

The complete list of recognized syntactic symbols is described in the vhdl-offsets-alist variable.  This chapter will provide some examples to help clarify these symbols.

Most syntactic symbol names follow a general naming convention.  When a line begins with a begin or end keyword, the syntactic symbol will contain the suffix -open or -close respectively.

Usually, a distinction is made between the first line that introduces a construct and lines that continue a construct, and the syntactic symbols that represent these lines will contain the suffix -intro or -cont respectively.  As a sub-classification of this scheme, a line which is the first of a particular block construct will contain the suffix -block-intro.

<TBD> include the name and a brief example of every syntactic symbol currently recognized

Frequently Asked Questions
**************************

     Q. How do I re-indent the whole file?

     A. Visit the file and hit C-x h to mark the whole buffer. Then hit ESC C-\ to re-indent the entire region which you've just marked. Or just enter M-x vhdl-indent-buffer.

     Q. How do I re-indent the entire function?

     A. Hit ESC C-h to mark the entire function. Then hit ESC C-\ to re-indent the entire region which you've just marked.

     Q. How do I re-indent the current block?

     A. First move to the brace which opens the block with ESC C-u, then re-indent that expression with ESC C-q.

     Q. How do I re-indent the current statement?

     A. First move to the beginning of the statement with ESC a, then re-indent that expression with ESC C-q.

     Q. I put (vhdl-set-offset 'statement-cont 0) in my .emacs file but I get an error saying that vhdl-set-offset's function definition is void.

     A. This means that VHDL Mode wasn't loaded into your Emacs session by the time the vhdl-set-offset call was reached, mostly likely because VHDL Mode is being autoloaded.  Instead of putting the vhdl-set-offset line in your top-level .emacs file, put it in your vhdl-mode-hook, or simply add the following to the top of your .emacs file:

          (require 'vhdl-mode)

     See the sample .emacs file Sample Init File for details.

Getting the latest VHDL Mode release
************************************

The best way to be sure you always have the latest VHDL Mode release is to join the vhdl-mode-announce mailing list.  If you are a brave soul, and wish to participate in beta testing of new releases of VHDL Mode, you may also join the vhdl-mode-victims mailing list.  Send email to the maintainer reto@gnu.org to join either of these lists.

The official Emacs VHDL Mode Home Page can be found at http://www.iis.ee.ethz.ch/~zimmi/emacs/vhdl-mode.html.

Sample Init File
****************

Most customizations can be done using the ``Customize'' entry in the VHDL Mode menu, which requires no editing of the .emacs file. If you want to customize indentation, here you go:

     ;; Here's a sample .emacs file that might help you along the way.  Just
     ;; copy this region and paste it into your .emacs file.  You may want to
     ;; change some of the actual values.

     (defconst my-vhdl-style
       '((vhdl-tab-always-indent        . t)
         (vhdl-comment-only-line-offset . 4)
         (vhdl-offsets-alist            . ((arglist-close    . vhdl-lineup-arglist)
                                           (statement-cont   . 0)
                                           (case-alternative . 4)
                                           (block-open       . 0)))
         (vhdl-echo-syntactic-information-p . t)
         )
       "My VHDL Programming Style")

     ;; Customizations for vhdl-mode
     (defun my-vhdl-mode-hook ()
       ;; add my personal style and set it for the current buffer
       (vhdl-add-style "PERSONAL" my-vhdl-style t)
       ;; offset customizations not in my-vhdl-style
       (vhdl-set-offset 'statement-case-intro '++)
       ;; other customizations
       (setq tab-width 8
             ;; this will make sure spaces are used instead of tabs
             indent-tabs-mode nil)
       ;; keybindings for VHDL are put in vhdl-mode-map
       (define-key vhdl-mode-map "\C-m" 'newline-and-indent)
       )

     (add-hook 'vhdl-mode-hook 'my-vhdl-mode-hook)

Limitations and Known Bugs
**************************

  * Re-indenting large regions or expressions can be slow.

Mailing Lists and Submitting Bug Reports
****************************************

To report bugs, use the C-c C-b (vhdl-submit-bug-report) command.  This provides vital information I need to reproduce your problem.  Make sure you include a concise, but complete code example. Please try to boil your example down to just the essential code needed to reproduce the problem, and include an exact recipe of steps needed to expose the bug.  Be especially sure to include any code that appears before your bug example.

For other help or suggestions, send a message to reto@gnu.org.

Send an add message to reto@gnu.org to get on the vhdl-mode-victims beta testers list where beta releases of VHDL Mode are posted.  Note that you shouldn't expect beta releases to be as stable as public releases.

There is also an announce only list where the latest public releases of VHDL Mode are posted.  Send an add message to reto@gnu.org to be added to this list.

GNU Free Documentation License
******************************

     [file doclicense.texi not included]

Command Index
*************

Since all VHDL Mode commands are prepended with the string vhdl-, each appears under its vhdl-<thing> name and its <thing> (vhdl-) name.

Variable Index
**************

Since all VHDL Mode variables are prepended with the string vhdl-, each appears under its vhdl-<thing> name and its <thing> (vhdl-) name.