874
|
1 *develop.txt* For Vim version 7.0. Last change: 2006 Mar 09
|
7
|
2
|
|
3
|
|
4 VIM REFERENCE MANUAL by Bram Moolenaar
|
|
5
|
|
6
|
|
7 Development of Vim. *development*
|
|
8
|
|
9 This text is important for those who want to be involved in further developing
|
|
10 Vim.
|
|
11
|
|
12 1. Design goals |design-goals|
|
|
13 2. Coding style |coding-style|
|
|
14 3. Design decisions |design-decisions|
|
|
15 4. Assumptions |design-assumptions|
|
|
16
|
|
17 See the file README.txt in the "src" directory for an overview of the source
|
|
18 code.
|
|
19
|
|
20 Vim is open source software. Everybody is encouraged to contribute to help
|
|
21 improving Vim. For sending patches a context diff "diff -c" is preferred.
|
|
22 Also see http://www.vim.org/tips/tip.php?tip_id=618.
|
|
23
|
|
24 ==============================================================================
|
|
25 1. Design goals *design-goals*
|
|
26
|
|
27 Most important things come first (roughly).
|
|
28
|
|
29 Note that quite a few items are contradicting. This is intentional. A
|
|
30 balance must be found between them.
|
|
31
|
|
32
|
|
33 VIM IS... VI COMPATIBLE *design-compatible*
|
|
34
|
|
35 First of all, it should be possible to use Vim as a drop-in replacement for
|
|
36 Vi. When the user wants to, he can use Vim in compatible mode and hardly
|
|
37 notice any difference with the original Vi.
|
|
38
|
|
39 Exceptions:
|
|
40 - We don't reproduce obvious Vi bugs in Vim.
|
|
41 - There are different versions of Vi. I am using Version 3.7 (6/7/85) as a
|
|
42 reference. But support for other versions is also included when possible.
|
|
43 The Vi part of POSIX is not considered a definitive source.
|
|
44 - Vim adds new commands, you cannot rely on some command to fail because it
|
|
45 didn't exist in Vi.
|
|
46 - Vim will have a lot of features that Vi doesn't have. Going back from Vim
|
|
47 to Vi will be a problem, this cannot be avoided.
|
|
48 - Some things are hardly ever used (open mode, sending an e-mail when
|
|
49 crashing, etc.). Those will only be included when someone has a good reason
|
|
50 why it should be included and it's not too much work.
|
|
51 - For some items it is debatable whether Vi compatibility should be
|
|
52 maintained. There will be an option flag for these.
|
|
53
|
|
54
|
|
55 VIM IS... IMPROVED *design-improved*
|
|
56
|
|
57 The IMproved bits of Vim should make it a better Vi, without becoming a
|
|
58 completely different editor. Extensions are done with a "Vi spirit".
|
|
59 - Use the keyboard as much as feasible. The mouse requires a third hand,
|
|
60 which we don't have. Many terminals don't have a mouse.
|
|
61 - When the mouse is used anyway, avoid the need to switch back to the
|
|
62 keyboard. Avoid mixing mouse and keyboard handling.
|
|
63 - Add commands and options in a consistent way. Otherwise people will have a
|
|
64 hard time finding and remembering them. Keep in mind that more commands and
|
|
65 options will be added later.
|
|
66 - A feature that people do not know about is a useless feature. Don't add
|
|
67 obscure features, or at least add hints in documentation that they exists.
|
|
68 - Minimize using CTRL and other modifiers, they are more difficult to type.
|
|
69 - There are many first-time and inexperienced Vim users. Make it easy for
|
|
70 them to start using Vim and learn more over time.
|
|
71 - There is no limit to the features that can be added. Selecting new features
|
|
72 is one based on (1) what users ask for, (2) how much effort it takes to
|
|
73 implement and (3) someone actually implementing it.
|
|
74
|
|
75
|
|
76 VIM IS... MULTI PLATFORM *design-multi-platform*
|
|
77
|
|
78 Vim tries to help as many users on as many platforms as possible.
|
|
79 - Support many kinds of terminals. The minimal demands are cursor positioning
|
|
80 and clear-screen. Commands should only use key strokes that most keyboards
|
|
81 have. Support all the keys on the keyboard for mapping.
|
|
82 - Support many platforms. A condition is that there is someone willing to do
|
|
83 Vim development on that platform, and it doesn't mean messing up the code.
|
|
84 - Support many compilers and libraries. Not everybody is able or allowed to
|
|
85 install another compiler or GUI library.
|
|
86 - People switch from one platform to another, and from GUI to terminal
|
|
87 version. Features should be present in all versions, or at least in as many
|
|
88 as possible with a reasonable effort. Try to avoid that users must switch
|
|
89 between platforms to accomplish their work efficiently.
|
|
90 - That a feature is not possible on some platforms, or only possible on one
|
|
91 platform, does not mean it cannot be implemented. [This intentionally
|
|
92 contradicts the previous item, these two must be balanced.]
|
|
93
|
|
94
|
|
95 VIM IS... WELL DOCUMENTED *design-documented*
|
|
96
|
|
97 - A feature that isn't documented is a useless feature. A patch for a new
|
|
98 feature must include the documentation.
|
|
99 - Documentation should be comprehensive and understandable. Using examples is
|
|
100 recommended.
|
|
101 - Don't make the text unnecessarily long. Less documentation means that an
|
|
102 item is easier to find.
|
|
103
|
|
104
|
|
105 VIM IS... HIGH SPEED AND SMALL IN SIZE *design-speed-size*
|
|
106
|
|
107 Using Vim must not be a big attack on system resources. Keep it small and
|
|
108 fast.
|
|
109 - Computers are becoming faster and bigger each year. Vim can grow too, but
|
|
110 no faster than computers are growing. Keep Vim usable on older systems.
|
|
111 - Many users start Vim from a shell very often. Startup time must be short.
|
|
112 - Commands must work efficiently. The time they consume must be as small as
|
|
113 possible. Useful commands may take longer.
|
|
114 - Don't forget that some people use Vim over a slow connection. Minimize the
|
|
115 communication overhead.
|
|
116 - Items that add considerably to the size and are not used by many people
|
|
117 should be a feature that can be disabled.
|
|
118 - Vim is a component among other components. Don't turn it into a massive
|
|
119 application, but have it work well together with other programs.
|
|
120
|
|
121
|
|
122 VIM IS... MAINTAINABLE *design-maintain*
|
|
123
|
|
124 - The source code should not become a mess. It should be reliable code.
|
|
125 - Use the same layout in all files to make it easy to read |coding-style|.
|
481
|
126 - Use comments in a useful way! Quoting the function name and argument names
|
|
127 is NOT useful. Do explain what they are for.
|
7
|
128 - Porting to another platform should be made easy, without having to change
|
|
129 too much platform-independent code.
|
|
130 - Use the object-oriented spirit: Put data and code together. Minimize the
|
|
131 knowledge spread to other parts of the code.
|
|
132
|
|
133
|
|
134 VIM IS... FLEXIBLE *design-flexible*
|
|
135
|
|
136 Vim should make it easy for users to work in their preferred styles rather
|
|
137 than coercing its users into particular patterns of work. This can be for
|
|
138 items with a large impact (e.g., the 'compatible' option) or for details. The
|
|
139 defaults are carefully chosen such that most users will enjoy using Vim as it
|
|
140 is. Commands and options can be used to adjust Vim to the desire of the user
|
|
141 and its environment.
|
|
142
|
|
143
|
|
144 VIM IS... NOT *design-not*
|
|
145
|
|
146 - Vim is not a shell or an Operating System. You will not be able to run a
|
|
147 shell inside Vim or use it to control a debugger. This should work the
|
|
148 other way around: Use Vim as a component from a shell or in an IDE.
|
|
149 A satirical way to say this: "Unlike Emacs, Vim does not attempt to include
|
|
150 everything but the kitchen sink, but some people say that you can clean one
|
|
151 with it. ;-)"
|
722
|
152 To use Vim with gdb see: http://www.agide.org and http://clewn.sf.net.
|
7
|
153 - Vim is not a fancy GUI editor that tries to look nice at the cost of
|
|
154 being less consistent over all platforms. But functional GUI features are
|
|
155 welcomed.
|
|
156
|
|
157 ==============================================================================
|
|
158 2. Coding style *coding-style*
|
|
159
|
|
160 These are the rules to use when making changes to the Vim source code. Please
|
|
161 stick to these rules, to keep the sources readable and maintainable.
|
|
162
|
|
163 This list is not complete. Look in the source code for more examples.
|
|
164
|
|
165
|
|
166 MAKING CHANGES *style-changes*
|
|
167
|
|
168 The basic steps to make changes to the code:
|
|
169 1. Adjust the documentation. Doing this first gives you an impression of how
|
|
170 your changes affect the user.
|
|
171 2. Make the source code changes.
|
|
172 3. Check ../doc/todo.txt if the change affects any listed item.
|
|
173 4. Make a patch with "diff -c" against the unmodified code and docs.
|
|
174 5. Make a note about what changed and include it with the patch.
|
|
175
|
|
176
|
|
177 USE OF COMMON FUNCTIONS *style-functions*
|
|
178
|
|
179 Some functions that are common to use, have a special Vim version. Always
|
|
180 consider using the Vim version, because they were introduced with a reason.
|
|
181
|
|
182 NORMAL NAME VIM NAME DIFFERENCE OF VIM VERSION
|
|
183 free() vim_free() Checks for freeing NULL
|
|
184 malloc() alloc() Checks for out of memory situation
|
|
185 malloc() lalloc() Like alloc(), but has long argument
|
|
186 strcpy() STRCPY() Includes cast to (char *), for char_u * args
|
|
187 strchr() vim_strchr() Accepts special characters
|
|
188 strrchr() vim_strrchr() Accepts special characters
|
|
189 isspace() vim_isspace() Can handle characters > 128
|
|
190 iswhite() vim_iswhite() Only TRUE for Tab and space
|
711
|
191 memcpy() mch_memmove() Handles overlapped copies
|
|
192 bcopy() mch_memmove() Handles overlapped copies
|
7
|
193 memset() vim_memset() Uniform for all systems
|
|
194
|
|
195
|
|
196 NAMES *style-names*
|
|
197
|
|
198 Function names can not be more than 31 characters long (because of VMS).
|
|
199
|
|
200 Don't use "delete" as a variable name, C++ doesn't like it.
|
|
201
|
|
202 Because of the requirement that Vim runs on as many systems as possible, we
|
|
203 need to avoid using names that are already defined by the system. This is a
|
|
204 list of names that are known to cause trouble. The name is given as a regexp
|
|
205 pattern.
|
|
206
|
|
207 is.*() POSIX, ctype.h
|
|
208 to.*() POSIX, ctype.h
|
|
209
|
|
210 d_.* POSIX, dirent.h
|
|
211 l_.* POSIX, fcntl.h
|
|
212 gr_.* POSIX, grp.h
|
|
213 pw_.* POSIX, pwd.h
|
|
214 sa_.* POSIX, signal.h
|
|
215 mem.* POSIX, string.h
|
|
216 str.* POSIX, string.h
|
|
217 wcs.* POSIX, string.h
|
|
218 st_.* POSIX, stat.h
|
|
219 tms_.* POSIX, times.h
|
|
220 tm_.* POSIX, time.h
|
|
221 c_.* POSIX, termios.h
|
|
222 MAX.* POSIX, limits.h
|
|
223 __.* POSIX, system
|
|
224 _[A-Z].* POSIX, system
|
|
225 E[A-Z0-9]* POSIX, errno.h
|
|
226
|
|
227 *_t POSIX, for typedefs. Use *_T instead.
|
|
228
|
|
229 wait don't use as argument to a function, conflicts with types.h
|
|
230 index shadows global declaration
|
|
231 time shadows global declaration
|
|
232 new C++ reserved keyword
|
|
233 try Borland C++ doesn't like it to be used as a variable.
|
|
234
|
|
235 basename() GNU string function
|
|
236 dirname() GNU string function
|
|
237 get_env_value() Linux system function
|
|
238
|
|
239
|
|
240 VARIOUS *style-various*
|
|
241
|
502
|
242 Typedef'ed names should end in "_T": >
|
|
243 typedef int some_T;
|
7
|
244 Define'ed names should be uppercase: >
|
|
245 #define SOME_THING
|
|
246 Features always start with "FEAT_": >
|
|
247 #define FEAT_FOO
|
|
248
|
|
249 Don't use '\"', some compilers can't handle it. '"' works fine.
|
|
250
|
|
251 Don't use:
|
|
252 #if HAVE_SOME
|
|
253 Some compilers can't handle that and complain that "HAVE_SOME" is not defined.
|
|
254 Use
|
|
255 #ifdef HAVE_SOME
|
|
256 or
|
|
257 #if defined(HAVE_SOME)
|
|
258
|
|
259
|
|
260 STYLE *style-examples*
|
|
261
|
|
262 General rule: One statement per line.
|
|
263
|
|
264 Wrong: if (cond) a = 1;
|
|
265
|
|
266 OK: if (cond)
|
|
267 a = 1;
|
|
268
|
|
269 Wrong: while (cond);
|
|
270
|
|
271 OK: while (cond)
|
|
272 ;
|
|
273
|
|
274 Wrong: do a = 1; while (cond);
|
|
275
|
|
276 OK: do
|
|
277 a = 1;
|
|
278 while (cond);
|
|
279
|
|
280
|
|
281 Functions start with:
|
|
282
|
|
283 Wrong: int function_name(int arg1, int arg2)
|
|
284
|
|
285 OK: /*
|
|
286 * Explanation of what this function is used for.
|
|
287 *
|
|
288 * Return value explanation.
|
|
289 */
|
|
290 int
|
|
291 function_name(arg1, arg2)
|
|
292 int arg1; /* short comment about arg1 */
|
|
293 int arg2; /* short comment about arg2 */
|
|
294 {
|
|
295 int local; /* comment about local */
|
|
296
|
|
297 local = arg1 * arg2;
|
|
298
|
|
299 NOTE: Don't use ANSI style function declarations. A few people still have to
|
|
300 use a compiler that doesn't support it.
|
|
301
|
|
302
|
|
303 SPACES AND PUNCTUATION *style-spaces*
|
|
304
|
|
305 No space between a function name and the bracket:
|
|
306
|
|
307 Wrong: func (arg);
|
|
308 OK: func(arg);
|
|
309
|
|
310 Do use a space after if, while, switch, etc.
|
|
311
|
|
312 Wrong: if(arg) for(;;)
|
|
313 OK: if (arg) for (;;)
|
|
314
|
|
315 Use a space after a comma and semicolon:
|
|
316
|
|
317 Wrong: func(arg1,arg2); for (i = 0;i < 2;++i)
|
|
318 OK: func(arg1, arg2); for (i = 0; i < 2; ++i)
|
|
319
|
|
320 Use a space before and after '=', '+', '/', etc.
|
|
321
|
|
322 Wrong: var=a*5;
|
|
323 OK: var = a * 5;
|
|
324
|
|
325 In general: Use empty lines to group lines of code together. Put a comment
|
|
326 just above the group of lines. This makes it more easy to quickly see what is
|
|
327 being done.
|
|
328
|
|
329 OK: /* Prepare for building the table. */
|
|
330 get_first_item();
|
|
331 table_idx = 0;
|
|
332
|
|
333 /* Build the table */
|
|
334 while (has_item())
|
|
335 table[table_idx++] = next_item();
|
|
336
|
|
337 /* Finish up. */
|
|
338 cleanup_items();
|
|
339 generate_hash(table);
|
|
340
|
|
341 ==============================================================================
|
|
342 3. Design decisions *design-decisions*
|
|
343
|
|
344 Folding
|
|
345
|
|
346 Several forms of folding should be possible for the same buffer. For example,
|
|
347 have one window that shows the text with function bodies folded, another
|
|
348 window that shows a function body.
|
|
349
|
|
350 Folding is a way to display the text. It should not change the text itself.
|
|
351 Therefore the folding has been implemented as a filter between the text stored
|
|
352 in a buffer (buffer lines) and the text displayed in a window (logical lines).
|
|
353
|
|
354
|
|
355 Naming the window
|
|
356
|
|
357 The word "window" is commonly used for several things: A window on the screen,
|
|
358 the xterm window, a window inside Vim to view a buffer.
|
|
359 To avoid confusion, other items that are sometimes called window have been
|
|
360 given another name. Here is an overview of the related items:
|
|
361
|
|
362 screen The whole display. For the GUI it's something like 1024x768
|
|
363 pixels. The Vim shell can use the whole screen or part of it.
|
|
364 shell The Vim application. This can cover the whole screen (e.g.,
|
|
365 when running in a console) or part of it (xterm or GUI).
|
|
366 window View on a buffer. There can be several windows in Vim,
|
|
367 together with the command line, menubar, toolbar, etc. they
|
|
368 fit in the shell.
|
|
369
|
|
370
|
236
|
371 Spell checking *develop-spell*
|
|
372
|
|
373 When spell checking was going to be added to Vim a survey was done over the
|
|
374 available spell checking libraries and programs. Unfortunately, the result
|
|
375 was that none of them provided sufficient capabilities to be used as the spell
|
|
376 checking engine in Vim, for various reasons:
|
|
377
|
|
378 - Missing support for multi-byte encodings. At least UTF-8 must be supported,
|
|
379 so that more than one language can be used in the same file.
|
323
|
380 Doing on-the-fly conversion is not always possible (would require iconv
|
|
381 support).
|
236
|
382 - For the programs and libraries: Using them as-is would require installing
|
323
|
383 them separately from Vim. That's mostly not impossible, but a drawback.
|
236
|
384 - Performance: A few tests showed that it's possible to check spelling on the
|
|
385 fly (while redrawing), just like syntax highlighting. But the mechanisms
|
625
|
386 used by other code are much slower. Myspell uses a hashtable, for example.
|
|
387 The affix compression that most spell checkers use makes it slower too.
|
300
|
388 - For using an external program like aspell a communication mechanism would
|
|
389 have to be setup. That's complicated to do in a portable way (Unix-only
|
|
390 would be relatively simple, but that's not good enough). And performance
|
|
391 will become a problem (lots of process switching involved).
|
236
|
392 - Missing support for words with non-word characters, such as "Etten-Leur" and
|
|
393 "et al.", would require marking the pieces of them OK, lowering the
|
|
394 reliability.
|
|
395 - Missing support for regions or dialects. Makes it difficult to accept
|
|
396 all English words and highlight non-Canadian words differently.
|
|
397 - Missing support for rare words. Many words are correct but hardly ever used
|
|
398 and could be a misspelled often-used word.
|
323
|
399 - For making suggestions the speed is less important and requiring to install
|
|
400 another program or library would be acceptable. But the word lists probably
|
|
401 differ, the suggestions may be wrong words.
|
7
|
402
|
625
|
403
|
|
404 Spelling suggestions *develop-spell-suggestions*
|
|
405
|
|
406 For making suggestions there are two basic mechanisms:
|
|
407 1. Try changing the bad word a little bit and check for a match with a good
|
|
408 word. Or go through the list of good words, change them a little bit and
|
|
409 check for a match with the bad word. The changes are deleting a character,
|
|
410 inserting a character, swapping two characters, etc.
|
|
411 2. Perform soundfolding on both the bad word and the good words and then find
|
|
412 matches, possibly with a few changes like with the first mechanism.
|
|
413
|
|
414 The first is good for finding typing mistakes. After experimenting with
|
|
415 hashtables and looking at solutions from other spell checkers the conclusion
|
|
416 was that a trie (a kind of tree structure) is ideal for this. Both for
|
|
417 reducing memory use and being able to try sensible changes. For example, when
|
|
418 inserting a character only characters that lead to good words need to be
|
|
419 tried. Other mechanisms (with hashtables) need to try all possible letters at
|
|
420 every position in the word. Also, a hashtable has the requirement that word
|
|
421 boundaries are identified separately, while a trie does not require this.
|
|
422 That makes the mechanism a lot simpler.
|
|
423
|
|
424 Soundfolding is useful when someone knows how the words sounds but doesn't
|
|
425 know how it is spelled. For example, the word "dictionary" might be written
|
|
426 as "daktonerie". The number of changes that the first method would need to
|
|
427 try is very big, it's hard to find the good word that way. After soundfolding
|
|
428 the words become "tktnr" and "tkxnry", these differ by only two letters.
|
|
429
|
|
430 To find words by their soundfolded equivalent (soundalike word) we need a list
|
|
431 of all soundfolded words. A few experiments have been done to find out what
|
|
432 the best method is. Alternatives:
|
|
433 1. Do the sound folding on the fly when looking for suggestions. This means
|
|
434 walking through the trie of good words, soundfolding each word and
|
|
435 checking how different it is from the bad word. This is very efficient for
|
|
436 memory use, but takes a long time. On a fast PC it takes a couple of
|
|
437 seconds for English, which can be acceptable for interactive use. But for
|
|
438 some languages it takes more than ten seconds (e.g., German, Catalan),
|
|
439 which is unacceptable slow. For batch processing (automatic corrections)
|
|
440 it's to slow for all languages.
|
|
441 2. Use a trie for the soundfolded words, so that searching can be done just
|
|
442 like how it works without soundfolding. This requires remembering a list
|
|
443 of good words for each soundfolded word. This makes finding matches very
|
|
444 fast but requires quite a lot of memory, in the order of 1 to 10 Mbyte.
|
|
445 For some languages more than the original word list.
|
|
446 3. Like the second alternative, but reduce the amount of memory by using affix
|
|
447 compression and store only the soundfolded basic word. This is what Aspell
|
|
448 does. Disadvantage is that affixes need to be stripped from the bad word
|
|
449 before soundfolding it, which means that mistakes at the start and/or end
|
|
450 of the word will cause the mechanism to fail. Also, this becomes slow when
|
|
451 the bad word is quite different from the good word.
|
|
452
|
|
453 The choice made is to use the second mechanism and use a separate file. This
|
|
454 way a user with sufficient memory can get very good suggestions while a user
|
|
455 who is short of memory or just wants the spell checking and no suggestions
|
|
456 doesn't use so much memory.
|
|
457
|
|
458
|
|
459 Word frequency
|
|
460
|
|
461 For sorting suggestions it helps to know which words are common. In theory we
|
|
462 could store a word frequency with the word in the dictionary. However, this
|
|
463 requires storing a count per word. That degrades word tree compression a lot.
|
|
464 And maintaining the word frequency for all languages will be a heavy task.
|
|
465 Also, it would be nice to prefer words that are already in the text. This way
|
|
466 the words that appear in the specific text are preferred for suggestions.
|
|
467
|
|
468 What has been implemented is to count words that have been seen during
|
|
469 displaying. A hashtable is used to quickly find the word count. The count is
|
|
470 initialized from words listed in COMMON items in the affix file, so that it
|
|
471 also works when starting a new file.
|
|
472
|
|
473 This isn't ideal, because the longer Vim is running the higher the counts
|
|
474 become. But in practice it is a noticable improvement over not using the word
|
|
475 count.
|
|
476
|
7
|
477 ==============================================================================
|
|
478 4. Assumptions *design-assumptions*
|
|
479
|
|
480 Size of variables:
|
|
481 char 8 bit signed
|
|
482 char_u 8 bit unsigned
|
625
|
483 int 32 or 64 bit signed (16 might be possible with limited features)
|
|
484 unsigned 32 or 64 bit unsigned (16 as with ints)
|
7
|
485 long 32 or 64 bit signed, can hold a pointer
|
|
486
|
|
487 Note that some compilers cannot handle long lines or strings. The C89
|
|
488 standard specifies a limit of 509 characters.
|
|
489
|
|
490 vim:tw=78:ts=8:ft=help:norl:
|