Commit | Line | Data |
---|---|---|
2c9bd776 RW |
1 | \input texinfo @c -*- texinfo -*- |
2 | ||
322ddc7f GM |
3 | @setfilename ../../info/vhdl-mode |
4 | @settitle VHDL Mode, an Emacs mode for editing VHDL code | |
2c9bd776 | 5 | |
322ddc7f GM |
6 | @c Adapted from the VHDL Mode texinfo manual version 2 by Rodney J. Whitby. |
7 | @c Adapted from the CC Mode texinfo manual by Barry A. Warsaw. | |
2c9bd776 | 8 | |
322ddc7f GM |
9 | @copying |
10 | This file documents VHDL Mode, an Emacs mode for editing VHDL code. | |
2c9bd776 | 11 | |
322ddc7f GM |
12 | Copyright @copyright{} 1995--2008, 2010, 2012, 2014 Free Software |
13 | Foundation, Inc. | |
2c9bd776 | 14 | |
322ddc7f GM |
15 | @quotation |
16 | Permission is granted to copy, distribute and/or modify this document | |
17 | under the terms of the GNU Free Documentation License, Version 1.3 or | |
18 | any later version published by the Free Software Foundation; with no | |
19 | Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' | |
20 | and with the Back-Cover Texts as in (a) below. A copy of the license | |
21 | is included in the section entitled ``GNU Free Documentation License.'' | |
22 | ||
23 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and | |
24 | modify this GNU manual.'' | |
25 | @end quotation | |
26 | @end copying | |
2c9bd776 | 27 | |
322ddc7f GM |
28 | @dircategory Emacs editing modes |
29 | @direntry | |
30 | * VHDL Mode: (vhdl-mode). Emacs mode for editing VHDL code. | |
31 | @end direntry | |
2c9bd776 | 32 | |
322ddc7f GM |
33 | @finalout |
34 | ||
35 | @titlepage | |
36 | @title VHDL Mode | |
37 | @sp 2 | |
38 | @subtitle A GNU Emacs mode for editing VHDL code. | |
39 | @sp 2 | |
40 | @author Reto Zimmermann | |
41 | @author @email{reto@@gnu.org} | |
42 | @author Rod Whitby | |
43 | @author @email{software.vhdl-mode@@rwhitby.net} | |
2c9bd776 RW |
44 | |
45 | @page | |
46 | @vskip 0pt plus 1filll | |
322ddc7f | 47 | @insertcopying |
2c9bd776 RW |
48 | @end titlepage |
49 | ||
322ddc7f | 50 | @contents |
2c9bd776 | 51 | |
322ddc7f GM |
52 | @ifnottex |
53 | @node Top | |
54 | @top VHDL Mode, an Emacs mode for editing VHDL code | |
2c9bd776 | 55 | |
322ddc7f GM |
56 | @insertcopying |
57 | @end ifnottex | |
2c9bd776 RW |
58 | |
59 | @menu | |
60 | * Introduction:: | |
61 | * Getting Connected:: | |
62 | * New Indentation Engine:: | |
63 | * Customizing Indentation:: | |
64 | * Syntactic Symbols:: | |
2c9bd776 RW |
65 | * Frequently Asked Questions:: |
66 | * Getting the latest VHDL Mode release:: | |
67 | * Sample .emacs File:: | |
322ddc7f | 68 | * Limitations and Known Bugs:: |
2c9bd776 | 69 | * Mailing Lists and Submitting Bug Reports:: |
322ddc7f | 70 | * GNU Free Documentation License:: The license for this documentation. |
2c9bd776 RW |
71 | * Concept Index:: |
72 | * Command Index:: Command Index | |
73 | * Key Index:: Key Index | |
74 | * Variable Index:: Variable Index | |
75 | @end menu | |
76 | ||
322ddc7f | 77 | @node Introduction |
2c9bd776 RW |
78 | @chapter Introduction |
79 | @cindex Introduction | |
80 | ||
322ddc7f GM |
81 | Welcome to VHDL Mode. This is a GNU Emacs mode for editing files |
82 | containing VHDL code. | |
2c9bd776 RW |
83 | |
84 | This manual will describe the following: | |
85 | ||
86 | @itemize @bullet | |
87 | @item | |
88 | How to get started using VHDL Mode. | |
89 | ||
90 | @item | |
91 | How the indentation engine works. | |
92 | ||
93 | @item | |
94 | How to customize the indentation engine. | |
95 | ||
96 | @end itemize | |
97 | ||
98 | @findex vhdl-version | |
99 | The major version number was incremented to 3 with the addition of | |
100 | many new features for editing VHDL code to the new indentation engine, | |
101 | which was introduced in major version 2. To find the minor revision | |
102 | number of this release, use @kbd{M-x vhdl-version RET}. | |
103 | ||
104 | A special word of thanks goes to Rod Whitby, who wrote the | |
105 | VHDL Mode indentation engine, and to Barry Warsaw, who wrote | |
106 | the CC Mode indentation engine that formed the basis | |
107 | thereof. Their manuals were also the basis for this manual. | |
108 | ||
109 | This manual is not very up-to-date. It basically contains the | |
110 | indentation machine documentation by Rod Whitby with only minor | |
111 | adaptions. A short documentation of the entire VHDL Mode is available | |
112 | within the mode itself by typing @kbd{C-c C-h}. Also, all commands and | |
113 | customization of most variables are available through the menu, which | |
114 | makes everything highly self-explaining. | |
115 | ||
322ddc7f | 116 | @node Getting Connected |
2c9bd776 RW |
117 | @chapter Getting Connected |
118 | @cindex Getting Connected | |
119 | ||
322ddc7f GM |
120 | To get started, simply visit a @file{.vhd} file in Emacs; or type |
121 | @kbd{M-x vhdl-mode RET}. | |
2c9bd776 | 122 | |
322ddc7f | 123 | @node New Indentation Engine |
2c9bd776 RW |
124 | @chapter New Indentation Engine |
125 | @cindex New Indentation Engine | |
126 | ||
2c9bd776 RW |
127 | VHDL Mode has a new indentation engine, providing a simplified, yet |
128 | flexible and general mechanism for customizing indentation. It breaks | |
129 | indentation calculation into two steps. First for the line of code being | |
130 | indented, VHDL Mode analyzes what kind of language construct it's | |
131 | looking at, then it applies user defined offsets to the current line | |
132 | based on this analysis. | |
133 | ||
134 | This section will briefly cover how indentation is calculated in | |
135 | VHDL Mode. It is important to understand the indentation model | |
136 | being used so that you will know how to customize VHDL Mode for | |
137 | your personal coding style. | |
138 | ||
2c9bd776 RW |
139 | @menu |
140 | * Syntactic Analysis:: Step 1 -- Syntactic Analysis | |
141 | * Indentation Calculation:: Step 2 -- Indentation Calculation | |
142 | @end menu | |
2c9bd776 | 143 | |
322ddc7f | 144 | @node Syntactic Analysis |
2c9bd776 RW |
145 | @section Syntactic Analysis |
146 | @cindex Syntactic Analysis | |
2c9bd776 RW |
147 | |
148 | @vindex vhdl-offsets-alist | |
149 | @vindex offsets-alist (vhdl-) | |
150 | @cindex relative buffer position | |
151 | @cindex syntactic symbol | |
152 | @cindex syntactic component | |
153 | @cindex syntactic component list | |
154 | @cindex relative buffer position | |
155 | The first thing VHDL Mode does when indenting a line of code, is | |
156 | to analyze the line, determining the @dfn{syntactic component list} of | |
157 | the construct on that line. A @dfn{syntactic component} consists of a | |
158 | pair of information (in lisp parlance, a @emph{cons cell}), where the | |
159 | first part is a @dfn{syntactic symbol}, and the second part is a | |
160 | @dfn{relative buffer position}. Syntactic symbols describe elements of | |
161 | VHDL code, e.g. @code{statement}, @code{comment}, @code{block-open}, | |
162 | @code{block-close}, etc. @xref{Syntactic Symbols}, for a complete list | |
163 | of currently recognized syntactic symbols and their semantics. Also, | |
164 | the variable @code{vhdl-offsets-alist} contains the list of currently | |
165 | supported syntactic symbols. | |
166 | ||
167 | Conceptually, a line of VHDL code is always indented relative to the | |
168 | indentation of some line higher up in the buffer. This is represented | |
169 | by the relative buffer position in the syntactic component. | |
170 | ||
171 | It might help to see an example. Suppose we had the following code as | |
172 | the only thing in a VHDL Mode buffer @footnote{The line numbers | |
173 | in this and future examples don't actually appear in the buffer.}: | |
174 | @example | |
175 | @group | |
176 | ||
177 | 1: inverter : process | |
178 | 2: begin | |
179 | 3: q <= not d; | |
180 | 4: wait on d; | |
181 | 5: end inverter; | |
182 | ||
183 | @end group | |
184 | @end example | |
185 | ||
186 | @kindex C-c C-x | |
187 | @findex vhdl-show-syntactic-information | |
188 | @findex show-syntactic-information (vhdl-) | |
189 | We can use the command @kbd{C-c C-x} | |
190 | (@code{vhdl-show-syntactic-information}) to simply report what the | |
191 | syntactic analysis is for the current line. Running this command on | |
192 | line 4 of example 1, we'd see in the echo area: | |
193 | @example | |
194 | ||
195 | ((statement . 28)) | |
196 | ||
197 | @end example | |
198 | ||
199 | This tells us that the line is a statement and it is indented relative | |
200 | to buffer position 28, which happens to be the @samp{q} on line 3. If | |
201 | you were to move point to line 3 and hit @kbd{C-c C-x}, you would see: | |
202 | @example | |
203 | ||
204 | ((statement-block-intro . 20)) | |
205 | ||
206 | @end example | |
207 | ||
208 | This indicates that line 3 is the first statement in a block, and is | |
209 | indented relative to buffer position 20, which is the @samp{b} in the | |
210 | @code{begin} keyword on line 2. | |
211 | ||
212 | @cindex comment only line | |
213 | Syntactic component lists can contain more than one component, and | |
214 | individual syntactic compenents need not have relative buffer positions. | |
215 | The most common example of this is a line that contains a @dfn{comment | |
216 | only line}. | |
217 | @example | |
218 | @group | |
219 | ||
220 | %%% TBD %%% | |
221 | ||
222 | @end group | |
223 | @end example | |
224 | ||
225 | @noindent | |
226 | Hitting @kbd{C-c C-x} on line 3 of the example gives us: | |
227 | @example | |
228 | ||
229 | ((comment-intro) (block-intro . 46)) | |
230 | ||
231 | @end example | |
232 | ||
233 | @noindent | |
234 | so you can see that the syntactic component list contains two syntactic | |
235 | components. Also notice that the first component, | |
236 | @samp{(comment-intro)} has no relative buffer position. | |
237 | ||
322ddc7f | 238 | @node Indentation Calculation |
2c9bd776 RW |
239 | @section Indentation Calculation |
240 | @cindex Indentation Calculation | |
2c9bd776 RW |
241 | |
242 | @vindex vhdl-offsets-alist | |
243 | @vindex offsets-alist (vhdl-) | |
244 | Indentation for the current line is calculated using the syntactic | |
245 | component list derived in step 1 above (see @ref{Syntactic | |
246 | Analysis}). Each component contributes to the final total indentation | |
247 | of the line in two ways. | |
248 | ||
249 | First, the syntactic symbols are looked up in the @code{vhdl-offsets-alist} | |
250 | variable, which is an association list of syntactic symbols and the | |
251 | offsets to apply for those symbols. These offsets are added to the | |
252 | running total. | |
253 | ||
254 | Second, if the component has a relative buffer position, VHDL Mode | |
255 | adds the column number of that position to the running total. By adding | |
256 | up the offsets and columns for every syntactic component on the list, | |
257 | the final total indentation for the current line is computed. | |
258 | ||
259 | Let's use our code example above to see how this works. Here is our | |
260 | example again. | |
261 | @example | |
262 | @group | |
263 | ||
264 | 1: inverter : process | |
265 | 2: begin | |
266 | 3: q <= not d; | |
267 | 4: wait on d; | |
268 | 5: end inverter; | |
269 | ||
270 | @end group | |
271 | @end example | |
272 | ||
273 | @kindex TAB | |
274 | Let's say point is on line 3 and we hit the @key{TAB} key to re-indent | |
275 | the line. Remember that the syntactic component list for that | |
276 | line is: | |
277 | @example | |
278 | ||
279 | ((statement-block-intro . 20)) | |
280 | ||
281 | @end example | |
282 | ||
283 | @noindent | |
284 | VHDL Mode looks up @code{statement-block-intro} in the | |
285 | @code{vhdl-offsets-alist} variable. Let's say it finds the value @samp{2}; | |
286 | it adds this to the running total (initialized to zero), yielding a | |
287 | running total indentation of 2 spaces. | |
288 | ||
289 | Next VHDL Mode goes to buffer position 20 and asks for the | |
290 | current column. Since the @code{begin} keyword at buffer position 20 is | |
291 | in column zero, it adds @samp{0} to the running total. Since there is | |
292 | only one syntactic component on the list for this line, indentation | |
293 | calculation is complete, and the total indentation for the line is 2 | |
294 | spaces. | |
295 | Simple, huh? | |
296 | ||
297 | Actually, the mode usually just does The Right Thing without you having | |
298 | to think about it in this much detail. But when customizing | |
299 | indentation, it's helpful to understand the general indentation model | |
300 | being used. | |
301 | ||
302 | @vindex vhdl-echo-syntactic-information-p | |
303 | @vindex echo-syntactic-information-p (vhdl-) | |
304 | @cindex TAB | |
305 | To help you configure VHDL Mode, you can set the variable | |
306 | @code{vhdl-echo-syntactic-information-p} to non-@code{nil} so that the | |
307 | syntactic component list and calculated offset will always be echoed in | |
308 | the minibuffer when you hit @kbd{TAB}. | |
309 | ||
310 | ||
322ddc7f GM |
311 | @ignore |
312 | @node Indentation Commands | |
2c9bd776 RW |
313 | @chapter Indentation Commands |
314 | @cindex Indentation Commands | |
2c9bd776 RW |
315 | |
316 | @strong{<TBD>} | |
322ddc7f | 317 | @end ignore |
2c9bd776 | 318 | |
2c9bd776 | 319 | |
322ddc7f | 320 | @node Customizing Indentation |
2c9bd776 RW |
321 | @chapter Customizing Indentation |
322 | @cindex Customizing Indentation | |
2c9bd776 RW |
323 | |
324 | @cindex vhdl-set-offset | |
325 | @cindex set-offset (vhdl-) | |
326 | The @code{vhdl-offsets-alist} variable is where you customize all your | |
327 | indentations. You simply need to decide what additional offset you want | |
328 | to add for every syntactic symbol. You can use the command @kbd{C-c | |
329 | O} (@code{vhdl-set-offset}) as the way to set offsets, both | |
330 | interactively and from your mode hook. Also, you can set up | |
331 | @emph{styles} of indentation. Most likely, you'll find one of the | |
332 | pre-defined styles will suit your needs, but if not, this section will | |
322ddc7f | 333 | describe how to set up basic editing configurations. @xref{Styles}, for |
2c9bd776 RW |
334 | an explanation of how to set up named styles. |
335 | ||
336 | @cindex vhdl-basic-offset | |
337 | @cindex basic-offset (vhdl-) | |
338 | As mentioned previously, the variable @code{vhdl-offsets-alist} is an | |
339 | association list between syntactic symbols and the offsets to be applied | |
340 | for those symbols. In fact, these offset values can be an integer, a | |
341 | function or variable name, or one of the following symbols: @code{+}, | |
342 | @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}. The symbol | |
343 | values have the following meanings: | |
344 | ||
345 | @itemize @bullet | |
346 | ||
347 | @item | |
348 | @code{+} -- 1 x @code{vhdl-basic-offset} | |
349 | @item | |
350 | @code{-} -- -1 x @code{vhdl-basic-offset} | |
351 | @item | |
352 | @code{++} -- 2 x @code{vhdl-basic-offset} | |
353 | @item | |
354 | @code{--} -- -2 x @code{vhdl-basic-offset} | |
355 | @item | |
356 | @code{*} -- 0.5 x @code{vhdl-basic-offset} | |
357 | @item | |
358 | @code{/} -- -0.5 x @code{vhdl-basic-offset} | |
359 | ||
360 | @end itemize | |
361 | ||
362 | @noindent | |
363 | So, for example, because most of the default offsets are defined in | |
364 | terms of @code{+}, @code{-}, and @code{0}, if you like the general | |
365 | indentation style, but you use 2 spaces instead of 4 spaces per level, | |
366 | you can probably achieve your style just by changing | |
367 | @code{vhdl-basic-offset} like so (in your @file{.emacs} file): | |
368 | @example | |
369 | ||
370 | (setq vhdl-basic-offset 2) | |
371 | ||
372 | @end example | |
373 | ||
374 | To change indentation styles more radically, you will want to change the | |
375 | value associated with the syntactic symbols in the | |
376 | @code{vhdl-offsets-alist} variable. First, I'll show you how to do that | |
377 | interactively, then I'll describe how to make changes to your | |
378 | @file{.emacs} file so that your changes are more permanent. | |
379 | ||
380 | @menu | |
381 | * Interactive Customization:: | |
382 | * Permanent Customization:: | |
383 | * Styles:: | |
384 | * Advanced Customizations:: | |
385 | @end menu | |
386 | ||
322ddc7f | 387 | @node Interactive Customization |
2c9bd776 RW |
388 | @section Interactive Customization |
389 | @cindex Interactive Customization | |
2c9bd776 RW |
390 | |
391 | As an example of how to customize indentation, let's change the | |
392 | style of the example above from: | |
393 | @example | |
394 | @group | |
395 | ||
396 | 1: inverter : process | |
397 | 2: begin | |
398 | 3: q <= not d; | |
399 | 4: wait on d; | |
400 | 5: end inverter; | |
401 | ||
402 | @end group | |
403 | @end example | |
404 | @noindent | |
405 | to: | |
406 | @example | |
407 | @group | |
408 | ||
409 | 1: inverter : process | |
410 | 2: begin | |
411 | 3: q <= not d; | |
412 | 4: wait on d; | |
413 | 5: end inverter; | |
414 | ||
415 | @end group | |
416 | @end example | |
417 | ||
418 | In other words, we want to change the indentation of the statments | |
419 | inside the inverter process. Notice that the construct we want to | |
420 | change starts on line 3. To change the indentation of a line, we need | |
421 | to see which syntactic component affect the offset calculations for that | |
422 | line. Hitting @kbd{C-c C-x} on line 3 yields: | |
423 | @example | |
424 | ||
425 | ((statement-block-intro . 20)) | |
426 | ||
427 | @end example | |
428 | ||
429 | @findex vhdl-set-offset | |
430 | @findex set-offset (vhdl-) | |
431 | @kindex C-c O | |
432 | @noindent | |
433 | So we know that to change the offset of the first signal assignment, we need to | |
434 | change the indentation for the @code{statement-block-intro} syntactic | |
435 | symbol. To do this interactively, just hit @kbd{C-c O} | |
436 | (@code{vhdl-set-offset}). This prompts you for the syntactic symbol to | |
437 | change, providing a reasonable default. In this case, the default is | |
438 | @code{statement-block-intro}, which is just the syntactic symbol we want to | |
439 | change! | |
440 | ||
441 | After you hit return, VHDL Mode will then prompt you for the new | |
442 | offset value, with the old value as the default. The default in this | |
443 | case is @samp{+}, so hit backspace to delete the @samp{+}, then hit | |
444 | @samp{++} and @kbd{RET}. This will associate an offset of twice the | |
445 | basic indent with the syntactic symbol @code{statement-block-intro} in | |
446 | the @code{vhdl-offsets-alist} variable. | |
447 | ||
448 | @findex vhdl-indent-defun | |
449 | @findex indent-defun (vhdl-) | |
450 | To check your changes quickly, just enter @kbd{M-x vhdl-indent-defun} to | |
451 | reindent the entire function. The example should now look like: | |
452 | @example | |
453 | @group | |
454 | ||
455 | 1: inverter : process | |
456 | 2: begin | |
457 | 3: q <= not d; | |
458 | 4: wait on d; | |
459 | 5: end inverter; | |
460 | ||
461 | @end group | |
462 | @end example | |
463 | ||
464 | Notice how just changing the offset on line 3 is all we needed to do. | |
465 | Since the other affected lines are indented relative to line 3, they are | |
466 | automatically indented the way you'd expect. For more complicated | |
467 | examples, this may not always work. The general approach to take is to | |
468 | always start adjusting offsets for lines higher up in the file, then | |
469 | re-indent and see if any following lines need further adjustments. | |
470 | ||
322ddc7f | 471 | @node Permanent Customization |
2c9bd776 RW |
472 | @section Permanent Indentation |
473 | @cindex Permanent Indentation | |
2c9bd776 RW |
474 | |
475 | @vindex vhdl-mode-hook | |
476 | @cindex hooks | |
477 | To make this change permanent, you need to add some lisp code to your | |
478 | @file{.emacs} file. VHDL Mode provides a @code{vhdl-mode-hook} | |
479 | that you can use to customize your language editing styles. This hook | |
480 | gets run as the last thing when you enter VHDL Mode. | |
481 | ||
482 | Here's a simplified example of what you can add to your @file{.emacs} | |
483 | file to make the changes described in the previous section | |
484 | (@ref{Interactive Customization}) more permanent. See the Emacs | |
485 | manuals for more information on customizing Emacs via hooks. | |
322ddc7f GM |
486 | @xref{Sample .emacs File}, for a more complete sample @file{.emacs} file. |
487 | ||
2c9bd776 RW |
488 | @example |
489 | @group | |
490 | ||
491 | (defun my-vhdl-mode-hook () | |
492 | ;; my customizations for all of vhdl-mode | |
493 | (vhdl-set-offset 'statement-block-intro '++) | |
494 | ;; other customizations can go here | |
495 | ) | |
496 | (add-hook 'vhdl-mode-hook 'my-vhdl-mode-hook) | |
497 | ||
498 | @end group | |
499 | @end example | |
500 | ||
501 | For complex customizations, you will probably want to set up a | |
502 | @emph{style} that groups all your customizations under a single | |
322ddc7f | 503 | name. @xref{Styles}. |
2c9bd776 RW |
504 | |
505 | The offset value can also be a function, and this is how power users | |
322ddc7f GM |
506 | gain enormous flexibility in customizing indentation. @xref{Advanced |
507 | Customizations}. | |
2c9bd776 | 508 | |
322ddc7f | 509 | @node Styles |
2c9bd776 RW |
510 | @section Styles |
511 | @cindex Styles | |
2c9bd776 RW |
512 | |
513 | Most people only need to edit code formatted in just a few well-defined | |
514 | and consistent styles. For example, their organization might impose a | |
515 | ``blessed'' style that all its programmers must conform to. Similarly, | |
516 | people who work on GNU software will have to use the GNU coding style on | |
517 | C code. Some shops are more lenient, allowing some variety of coding | |
518 | styles, and as programmers come and go, there could be a number of | |
519 | styles in use. For this reason, VHDL Mode makes it convenient for | |
520 | you to set up logical groupings of customizations called @dfn{styles}, | |
521 | associate a single name for any particular style, and pretty easily | |
522 | start editing new or existing code using these styles. This chapter | |
523 | describes how to set up styles and how to edit your C code using styles. | |
524 | ||
525 | @menu | |
526 | * Built-in Styles:: | |
527 | * Adding Styles:: | |
528 | * File Styles:: | |
529 | @end menu | |
530 | ||
531 | ||
322ddc7f | 532 | @node Built-in Styles |
2c9bd776 RW |
533 | @subsection Built-in Styles |
534 | @cindex Built-in Styles | |
2c9bd776 RW |
535 | |
536 | If you're lucky, one of VHDL Mode's built-in styles might be just | |
537 | what you're looking for. Some of the most common VHDL styles are | |
538 | already built-in. These include: | |
539 | ||
540 | @itemize @bullet | |
541 | @item | |
542 | @cindex IEEE style | |
543 | @code{GNU} -- the coding style in the IEEE Language Reference Manual. | |
544 | ||
545 | @end itemize | |
546 | ||
547 | @findex vhdl-set-style | |
548 | @findex set-style (vhdl-) | |
549 | If you'd like to experiment with these built-in styles you can simply | |
322ddc7f | 550 | type @kbd{M-x vhdl-set-style RET} in a VHDL Mode buffer. |
2c9bd776 | 551 | |
2c9bd776 RW |
552 | You will be prompted for one of the above styles (with completion). |
553 | Enter one of the styles and hit @kbd{RET}. Note however that setting a | |
554 | style in this way does @emph{not} automatically re-indent your file. | |
322ddc7f | 555 | @ignore |
2c9bd776 RW |
556 | For commands that you can use to view the effect of your changes, see |
557 | @ref{Indentation Commands}. | |
322ddc7f | 558 | @end ignore |
2c9bd776 RW |
559 | |
560 | Once you find a built-in style you like, you can make the change | |
561 | permanent by adding a call to your @file{.emacs} file. Let's say for | |
562 | example that you want to use the @code{IEEE} style in all your | |
563 | files. You would add this: | |
564 | @example | |
565 | @group | |
566 | ||
567 | (defun my-vhdl-mode-hook () | |
568 | ;; use IEEE style for all VHDL code | |
569 | (vhdl-set-style "IEEE") | |
570 | ;; other customizations can go here | |
571 | ) | |
572 | (add-hook 'vhdl-mode-hook 'my-vhdl-mode-hook) | |
573 | ||
574 | @end group | |
575 | @end example | |
576 | ||
577 | @noindent | |
578 | @xref{Permanent Customization}. | |
579 | ||
322ddc7f | 580 | @node Adding Styles |
2c9bd776 RW |
581 | @subsection Adding Styles |
582 | @cindex Adding Styles | |
2c9bd776 RW |
583 | |
584 | @vindex vhdl-style-alist | |
585 | @vindex style-alist (vhdl-) | |
586 | @findex vhdl-add-style | |
587 | @findex add-style (vhdl-) | |
588 | If none of the built-in styles is appropriate, you'll probably want to | |
589 | add a new style definition. Styles are kept in the @code{vhdl-style-alist} | |
590 | variable, but you probably won't want to modify this variable directly. | |
591 | VHDL Mode provides a function, called @code{vhdl-add-style}, that you | |
592 | can use to easily add new styles or update existing styles. This | |
593 | function takes two arguments, a @var{stylename} string, and an | |
594 | association list @var{description} of style customizations. If | |
595 | @var{stylename} is not already in @code{vhdl-style-alist}, the new style is | |
596 | added, otherwise the style already associated with @var{stylename} is | |
597 | changed to the new @var{description}. This function also takes an | |
598 | optional third argument, which if non-@code{nil}, automatically | |
599 | institutes the new style in the current buffer. | |
600 | ||
601 | The sample @file{.emacs} file provides a concrete example of how a new | |
602 | style can be added and automatically set. @xref{Sample .emacs File}. | |
603 | ||
322ddc7f | 604 | @node File Styles |
2c9bd776 RW |
605 | @subsection File Styles |
606 | @cindex File Styles | |
2c9bd776 RW |
607 | |
608 | @cindex local variables | |
609 | The Emacs manual describes how you can customize certain variables on a | |
610 | per-file basis by including a @dfn{Local Variable} block at the end of | |
611 | the file. So far, you've only seen a functional interface to | |
612 | VHDL Mode, which is highly inconvenient for use in a Local Variable | |
613 | block. VHDL Mode provides two variables that make it easier for | |
614 | you to customize your style on a per-file basis. | |
615 | ||
616 | @vindex vhdl-file-style | |
617 | @vindex file-style (vhdl-) | |
618 | @vindex vhdl-file-offsets | |
619 | @vindex file-offsets (vhdl-) | |
620 | ||
621 | The variable @code{vhdl-file-style} can be set to a style name string as | |
622 | described in @ref{Built-in Styles}. When the file is visited, | |
623 | VHDL Mode will automatically set the file's style to this style | |
624 | using @code{vhdl-set-style}. | |
625 | ||
626 | @vindex vhdl-offsets-alist | |
627 | @vindex offsets-alist (vhdl-) | |
628 | @findex vhdl-set-offset | |
629 | @findex set-offset (vhdl-) | |
630 | Another variable, @code{vhdl-file-offsets}, takes an association list | |
631 | similar to what is allowed in @code{vhdl-offsets-alist}. When the file is | |
632 | visited, VHDL Mode will automatically institute these offets using | |
633 | @code{vhdl-set-offset}. @xref{Customizing Indentation}. | |
634 | ||
635 | Note that file style settings (i.e. @code{vhdl-file-style}) are applied | |
636 | before file offset settings (i.e. @code{vhdl-file-offsets}). | |
637 | ||
638 | ||
322ddc7f | 639 | @node Advanced Customizations |
2c9bd776 RW |
640 | @section Advanced Customizations |
641 | @cindex Advanced Customizations | |
2c9bd776 RW |
642 | |
643 | @vindex vhdl-style-alist | |
644 | @vindex style-alist (vhdl-) | |
645 | @vindex vhdl-basic-offset | |
646 | @vindex basic-offset (vhdl-) | |
647 | For most users, VHDL Mode will support their coding styles with | |
648 | very little need for customizations. Usually, one of the standard | |
649 | styles defined in @code{vhdl-style-alist} will do the trick. Sometimes, | |
650 | one of the syntactic symbol offsets will need to be tweeked slightly, or | |
651 | perhaps @code{vhdl-basic-offset} will need to be changed. However, some | |
652 | styles require a more advanced ability for customization, and one of the | |
653 | real strengths of VHDL Mode is that the syntactic analysis model | |
654 | provides a very flexible framework for customizing indentation. This | |
655 | allows you to perform special indentation calculations for situations | |
656 | not handled by the mode directly. | |
657 | ||
658 | @menu | |
659 | * Custom Indentation Functions:: | |
660 | * Other Special Indentations:: | |
661 | @end menu | |
662 | ||
322ddc7f | 663 | @node Custom Indentation Functions |
2c9bd776 RW |
664 | @subsection Custom Indentation Functions |
665 | @cindex Custom Indentation Functions | |
2c9bd776 RW |
666 | |
667 | @cindex custom indentation functions | |
668 | One of the most common ways to customize VHDL Mode is by writing | |
669 | @dfn{custom indentation functions} and associating them with specific | |
670 | syntactic symbols (see @ref{Syntactic Symbols}). VHDL Mode itself | |
671 | uses custom indentation functions to provide more sophisticated | |
672 | indentation, for example when lining up selected signal assignments: | |
673 | @example | |
674 | @group | |
675 | ||
676 | %%% TBD %%% | |
677 | ||
678 | @end group | |
679 | @end example | |
680 | ||
681 | In this example, the @code{statement-cont} syntactic symbol has an | |
682 | offset of @code{+}, and @code{vhdl-basic-offset} is 2, so lines 4 | |
683 | through 6 are simply indented two spaces to the right of line 3. But | |
684 | perhaps we'd like VHDL Mode to be a little more intelligent so | |
685 | that it offsets the waveform descriptions relative to the signal | |
686 | assignment operator in line 3. To do this, we have to write a custom | |
687 | indentation function which finds the column of signal assignment | |
688 | operator on the first line of the statement. Here is the lisp code | |
689 | (from the @file{vhdl-mode.el} source file) that implements this: | |
690 | @example | |
691 | @group | |
692 | ||
693 | (defun vhdl-lineup-statement-cont (langelem) | |
694 | ;; line up statement-cont after the assignment operator | |
695 | (save-excursion | |
696 | (let* ((relpos (cdr langelem)) | |
697 | (assignp (save-excursion | |
698 | (goto-char (vhdl-point 'boi)) | |
699 | (and (re-search-forward "\\(<\\|:\\)=" | |
700 | (vhdl-point 'eol) t) | |
701 | (- (point) (vhdl-point 'boi))))) | |
702 | (curcol (progn | |
703 | (goto-char relpos) | |
704 | (current-column))) | |
705 | foundp) | |
706 | (while (and (not foundp) | |
707 | (< (point) (vhdl-point 'eol))) | |
708 | (re-search-forward "\\(<\\|:\\)=\\|(" (vhdl-point 'eol) 'move) | |
709 | (if (vhdl-in-literal (cdr langelem)) | |
710 | (forward-char) | |
711 | (if (= (preceding-char) ?\() | |
712 | ;; skip over any parenthesized expressions | |
713 | (goto-char (min (vhdl-point 'eol) | |
714 | (scan-lists (point) 1 1))) | |
715 | ;; found an assignment operator (not at eol) | |
716 | (setq foundp (not (looking-at "\\s-*$")))))) | |
717 | (if (not foundp) | |
718 | ;; there's no assignment operator on the line | |
719 | vhdl-basic-offset | |
720 | ;; calculate indentation column after assign and ws, unless | |
721 | ;; our line contains an assignment operator | |
722 | (if (not assignp) | |
723 | (progn | |
724 | (forward-char) | |
725 | (skip-chars-forward " \t") | |
726 | (setq assignp 0))) | |
727 | (- (current-column) assignp curcol)) | |
728 | ))) | |
729 | ||
730 | @end group | |
731 | @end example | |
732 | @noindent | |
733 | Custom indent functions take a single argument, which is a syntactic | |
734 | component cons cell (see @ref{Syntactic Analysis}). The | |
735 | function returns an integer offset value that will be added to the | |
736 | running total indentation for the lne. Note that what actually gets | |
737 | returned is the difference between the column that the signal assignment | |
738 | operator is on, and the column of the buffer relative position passed in | |
739 | the function's argument. Remember that VHDL Mode automatically | |
740 | adds in the column of the component's relative buffer position and we | |
741 | don't want that value added into the final total twice. | |
742 | ||
743 | @cindex statement-cont syntactic symbol | |
744 | @findex vhdl-lineup-statement-cont | |
745 | @findex lineup-statement-cont (vhdl-) | |
746 | Now, to associate the function @code{vhdl-lineup-statement-cont} with the | |
747 | @code{statement-cont} syntactic symbol, we can add something like the | |
748 | following to our @code{vhdl-mode-hook}: | |
749 | @example | |
750 | ||
751 | (vhdl-set-offset 'statement-cont 'vhdl-lineup-statement-cont) | |
752 | ||
753 | @end example | |
754 | ||
755 | @findex vhdl-indent-defun | |
756 | Now the function looks like this after re-indenting (using @kbd{M-x | |
757 | vhdl-indent-defun}): | |
758 | @example | |
759 | @group | |
760 | ||
761 | %%% TBD %%% | |
762 | ||
763 | @end group | |
764 | @end example | |
765 | ||
766 | @vindex vhdl-offsets-alist | |
767 | @vindex offsets-alist (vhdl-) | |
768 | Custom indentation functions can be as simple or as complex as you like, | |
769 | and any syntactic symbol that appears in @code{vhdl-offsets-alist} can have | |
770 | a custom indentation function associated with it. Note however that | |
771 | using many custom indentation functions may have a performance impact on | |
772 | VHDL Mode. | |
773 | ||
322ddc7f | 774 | @node Other Special Indentations |
2c9bd776 RW |
775 | @subsection Other Special Indentations |
776 | @cindex Other Special Indentations | |
2c9bd776 RW |
777 | |
778 | @vindex vhdl-special-indent-hook | |
779 | @vindex special-indent-hook (vhdl-) | |
780 | One other variable is available for you to customize VHDL Mode: | |
781 | @code{vhdl-special-indent-hook}. This is a standard hook variable that | |
782 | is called after every line is indented by VHDL Mode. You can use | |
783 | it to do any special indentation or line adjustments your style | |
784 | dictates, such as adding extra indentation to the port map clause in a | |
785 | component instantiation, etc. Note however, that you should not change | |
786 | @code{point} or @code{mark} inside your @code{vhdl-special-indent-hook} | |
787 | functions. | |
788 | ||
789 | ||
322ddc7f | 790 | @node Syntactic Symbols |
2c9bd776 RW |
791 | @chapter Syntactic Symbols |
792 | @cindex Syntactic Symbols | |
2c9bd776 RW |
793 | |
794 | @vindex vhdl-offsets-alist | |
795 | The complete list of recognized syntactic symbols is described in the | |
796 | @code{vhdl-offsets-alist} variable. This chapter will provide some | |
797 | examples to help clarify these symbols. | |
798 | ||
799 | @cindex -open syntactic symbols | |
800 | @cindex -close syntactic symbols | |
801 | Most syntactic symbol names follow a general naming convention. When a | |
802 | line begins with a @code{begin} or @code{end} keyword, the syntactic | |
803 | symbol will contain the suffix @code{-open} or @code{-close} | |
804 | respectively. | |
805 | ||
806 | @cindex -intro syntactic symbols | |
807 | @cindex -cont syntactic symbols | |
808 | @cindex -block-intro syntactic symbols | |
809 | Usually, a distinction is made between the first line that introduces a | |
810 | construct and lines that continue a construct, and the syntactic symbols | |
811 | that represent these lines will contain the suffix @code{-intro} or | |
812 | @code{-cont} respectively. As a sub-classification of this scheme, a | |
813 | line which is the first of a particular block construct will contain the | |
814 | suffix @code{-block-intro}. | |
815 | ||
816 | @strong{<TBD> include the name and a brief example of every syntactic | |
817 | symbol currently recognized} | |
818 | ||
322ddc7f | 819 | @node Frequently Asked Questions |
2c9bd776 RW |
820 | @chapter Frequently Asked Questions |
821 | @cindex Frequently Asked Questions | |
2c9bd776 RW |
822 | |
823 | @kindex C-x h | |
824 | @kindex ESC C-\ | |
825 | @kindex ESC C-q | |
826 | @kindex ESC C-u | |
827 | @kindex RET | |
828 | @kindex LFD | |
829 | @findex newline-and-indent | |
830 | @quotation | |
831 | ||
832 | @strong{Q.} @emph{How do I re-indent the whole file?} | |
833 | ||
834 | @strong{A.} Visit the file and hit @kbd{C-x h} to mark the whole | |
835 | buffer. Then hit @kbd{@key{ESC} C-\} to re-indent the entire region | |
836 | which you've just marked. Or just enter @kbd{M-x vhdl-indent-buffer}. | |
837 | @sp 2 | |
838 | ||
839 | @strong{Q.} @emph{How do I re-indent the entire function?} | |
840 | ||
841 | @strong{A.} Hit @kbd{@key{ESC} C-h} to mark the entire function. Then | |
842 | hit @kbd{@key{ESC} C-\} to re-indent the entire region which you've just | |
843 | marked. | |
844 | @sp 2 | |
845 | ||
846 | @strong{Q.} @emph{How do I re-indent the current block?} | |
847 | ||
848 | @strong{A.} First move to the brace which opens the block with | |
849 | @kbd{@key{ESC} C-u}, then re-indent that expression with | |
850 | @kbd{@key{ESC} C-q}. | |
851 | @sp 2 | |
852 | ||
853 | @strong{Q.} @emph{How do I re-indent the current statement?} | |
854 | ||
855 | @strong{A.} First move to the beginning of the statement with | |
856 | @kbd{@key{ESC} a}, then re-indent that expression with @kbd{@key{ESC} | |
857 | C-q}. | |
858 | @sp 2 | |
859 | ||
2c9bd776 RW |
860 | @strong{Q.} @emph{I put @code{(vhdl-set-offset 'statement-cont 0)} |
861 | in my @file{.emacs} file but I get an error saying that | |
862 | @code{vhdl-set-offset}'s function definition is void.} | |
863 | ||
864 | @strong{A.} This means that VHDL Mode wasn't loaded into your | |
865 | Emacs session by the time the @code{vhdl-set-offset} call was reached, | |
866 | mostly likely because VHDL Mode is being autoloaded. Instead | |
867 | of putting the @code{vhdl-set-offset} line in your top-level | |
868 | @file{.emacs} file, put it in your @code{vhdl-mode-hook}, or | |
869 | simply add the following to the top of your @file{.emacs} file: | |
870 | @example | |
871 | ||
872 | (require 'vhdl-mode) | |
873 | ||
874 | @end example | |
875 | ||
876 | See the sample @file{.emacs} file @ref{Sample .emacs File} for | |
877 | details. | |
878 | ||
879 | @end quotation | |
880 | ||
881 | ||
322ddc7f | 882 | @node Getting the latest VHDL Mode release |
2c9bd776 RW |
883 | @chapter Getting the latest VHDL Mode release |
884 | @cindex Getting the latest VHDL Mode release | |
2c9bd776 RW |
885 | |
886 | The best way to be sure you always have the latest VHDL Mode release | |
887 | is to join the @code{vhdl-mode-announce} mailing list. If you are a | |
888 | brave soul, and wish to participate in beta testing of new releases of | |
889 | VHDL Mode, you may also join the @code{vhdl-mode-victims} mailing | |
322ddc7f | 890 | list. Send email to the maintainer @email{reto@@gnu.org} to join |
2c9bd776 RW |
891 | either of these lists. |
892 | ||
893 | The official Emacs VHDL Mode Home Page can be found at | |
322ddc7f | 894 | @uref{http://www.iis.ee.ethz.ch/~zimmi/emacs/vhdl-mode.html}. |
2c9bd776 | 895 | |
322ddc7f | 896 | @node Sample .emacs File |
2c9bd776 RW |
897 | @chapter Sample @file{.emacs} file |
898 | @cindex Sample @file{.emacs} file | |
2c9bd776 RW |
899 | |
900 | Most customizations can be done using the `Customize' entry in the | |
901 | VHDL Mode menu, which requires no editing of the .emacs file. | |
902 | If you want to customize indentation, here you go: | |
903 | ||
904 | @example | |
905 | ;; Here's a sample .emacs file that might help you along the way. Just | |
906 | ;; copy this region and paste it into your .emacs file. You may want to | |
907 | ;; change some of the actual values. | |
908 | ||
909 | (defconst my-vhdl-style | |
910 | '((vhdl-tab-always-indent . t) | |
911 | (vhdl-comment-only-line-offset . 4) | |
912 | (vhdl-offsets-alist . ((arglist-close . vhdl-lineup-arglist) | |
913 | (statement-cont . 0) | |
914 | (case-alternative . 4) | |
915 | (block-open . 0))) | |
916 | (vhdl-echo-syntactic-information-p . t) | |
917 | ) | |
918 | "My VHDL Programming Style") | |
919 | ||
920 | ;; Customizations for vhdl-mode | |
921 | (defun my-vhdl-mode-hook () | |
922 | ;; add my personal style and set it for the current buffer | |
923 | (vhdl-add-style "PERSONAL" my-vhdl-style t) | |
924 | ;; offset customizations not in my-vhdl-style | |
925 | (vhdl-set-offset 'statement-case-intro '++) | |
926 | ;; other customizations | |
927 | (setq tab-width 8 | |
928 | ;; this will make sure spaces are used instead of tabs | |
929 | indent-tabs-mode nil) | |
930 | ;; keybindings for VHDL are put in vhdl-mode-map | |
931 | (define-key vhdl-mode-map "\C-m" 'newline-and-indent) | |
932 | ) | |
933 | ||
2c9bd776 RW |
934 | (add-hook 'vhdl-mode-hook 'my-vhdl-mode-hook) |
935 | @end example | |
936 | ||
322ddc7f | 937 | @node Limitations and Known Bugs |
2c9bd776 RW |
938 | @chapter Limitations and Known Bugs |
939 | @cindex Limitations and Known Bugs | |
2c9bd776 RW |
940 | |
941 | @itemize @bullet | |
942 | @item | |
943 | Re-indenting large regions or expressions can be slow. | |
944 | ||
322ddc7f | 945 | @ignore |
2c9bd776 RW |
946 | @item |
947 | The index menu does not work on my XEmacs installation (don't know why). | |
322ddc7f | 948 | @end ignore |
2c9bd776 RW |
949 | |
950 | @end itemize | |
951 | ||
322ddc7f | 952 | @node Mailing Lists and Submitting Bug Reports |
2c9bd776 RW |
953 | @chapter Mailing Lists and Submitting Bug Reports |
954 | @cindex Mailing Lists and Submitting Bug Reports | |
2c9bd776 RW |
955 | |
956 | @kindex C-c C-b | |
957 | @findex vhdl-submit-bug-report | |
958 | @findex submit-bug-report (vhdl-) | |
959 | @cindex beta testers mailing list | |
960 | @cindex announcement mailing list | |
961 | To report bugs, use the @kbd{C-c C-b} (@code{vhdl-submit-bug-report}) | |
962 | command. This provides vital information I need to reproduce your | |
963 | problem. Make sure you include a concise, but complete code example. | |
964 | Please try to boil your example down to just the essential code needed | |
965 | to reproduce the problem, and include an exact recipe of steps needed to | |
966 | expose the bug. Be especially sure to include any code that appears | |
967 | @emph{before} your bug example. | |
968 | ||
322ddc7f | 969 | For other help or suggestions, send a message to @email{reto@@gnu.org}. |
2c9bd776 | 970 | |
322ddc7f | 971 | Send an add message to @email{reto@@gnu.org} to get on the |
2c9bd776 RW |
972 | @code{vhdl-mode-victims} beta testers list where beta releases of |
973 | VHDL Mode are posted. Note that you shouldn't expect beta | |
974 | releases to be as stable as public releases. | |
975 | ||
976 | There is also an announce only list where the latest public releases | |
977 | of VHDL Mode are posted. Send an add message to | |
322ddc7f GM |
978 | @email{reto@@gnu.org} to be added to this list. |
979 | ||
2c9bd776 | 980 | |
322ddc7f GM |
981 | @node GNU Free Documentation License |
982 | @appendix GNU Free Documentation License | |
983 | @include doclicense.texi | |
984 | ||
985 | ||
986 | @node Concept Index | |
2c9bd776 | 987 | @unnumbered Concept Index |
2c9bd776 RW |
988 | |
989 | @printindex cp | |
990 | ||
991 | ||
322ddc7f | 992 | @node Command Index |
2c9bd776 | 993 | @unnumbered Command Index |
2c9bd776 | 994 | |
2c9bd776 RW |
995 | Since all VHDL Mode commands are prepended with the string |
996 | @samp{vhdl-}, each appears under its @code{vhdl-<thing>} name and its | |
997 | @code{<thing> (vhdl-)} name. | |
998 | @iftex | |
999 | @sp 2 | |
1000 | @end iftex | |
1001 | @printindex fn | |
1002 | ||
1003 | ||
322ddc7f | 1004 | @node Key Index |
2c9bd776 | 1005 | @unnumbered Key Index |
2c9bd776 RW |
1006 | |
1007 | @printindex ky | |
1008 | ||
1009 | ||
322ddc7f | 1010 | @node Variable Index |
2c9bd776 | 1011 | @unnumbered Variable Index |
2c9bd776 | 1012 | |
2c9bd776 RW |
1013 | Since all VHDL Mode variables are prepended with the string |
1014 | @samp{vhdl-}, each appears under its @code{vhdl-<thing>} name and its | |
1015 | @code{<thing> (vhdl-)} name. | |
1016 | @iftex | |
1017 | @sp 2 | |
1018 | @end iftex | |
1019 | @printindex vr | |
322ddc7f | 1020 | |
2c9bd776 | 1021 | @bye |