1*develop.txt* For Vim version 7.3. Last change: 2008 Dec 17 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7Development of Vim. *development* 8 9This text is important for those who want to be involved in further developing 10Vim. 11 121. Design goals |design-goals| 132. Coding style |coding-style| 143. Design decisions |design-decisions| 154. Assumptions |design-assumptions| 16 17See the file README.txt in the "src" directory for an overview of the source 18code. 19 20Vim is open source software. Everybody is encouraged to contribute to help 21improving Vim. For sending patches a context diff "diff -c" is preferred. 22Also see http://www.vim.org/tips/tip.php?tip_id=618. 23 24============================================================================== 251. Design goals *design-goals* 26 27Most important things come first (roughly). 28 29Note that quite a few items are contradicting. This is intentional. A 30balance must be found between them. 31 32 33VIM IS... VI COMPATIBLE *design-compatible* 34 35First of all, it should be possible to use Vim as a drop-in replacement for 36Vi. When the user wants to, he can use Vim in compatible mode and hardly 37notice any difference with the original Vi. 38 39Exceptions: 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 55VIM IS... IMPROVED *design-improved* 56 57The IMproved bits of Vim should make it a better Vi, without becoming a 58completely 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 exist. 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 76VIM IS... MULTI PLATFORM *design-multi-platform* 77 78Vim 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 95VIM 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 105VIM IS... HIGH SPEED AND SMALL IN SIZE *design-speed-size* 106 107Using Vim must not be a big attack on system resources. Keep it small and 108fast. 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 122VIM 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|. 126- Use comments in a useful way! Quoting the function name and argument names 127 is NOT useful. Do explain what they are for. 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 134VIM IS... FLEXIBLE *design-flexible* 135 136Vim should make it easy for users to work in their preferred styles rather 137than coercing its users into particular patterns of work. This can be for 138items with a large impact (e.g., the 'compatible' option) or for details. The 139defaults are carefully chosen such that most users will enjoy using Vim as it 140is. Commands and options can be used to adjust Vim to the desire of the user 141and its environment. 142 143 144VIM 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. ;-)" 152 To use Vim with gdb see: http://www.agide.org and http://clewn.sf.net. 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============================================================================== 1582. Coding style *coding-style* 159 160These are the rules to use when making changes to the Vim source code. Please 161stick to these rules, to keep the sources readable and maintainable. 162 163This list is not complete. Look in the source code for more examples. 164 165 166MAKING CHANGES *style-changes* 167 168The basic steps to make changes to the code: 1691. Adjust the documentation. Doing this first gives you an impression of how 170 your changes affect the user. 1712. Make the source code changes. 1723. Check ../doc/todo.txt if the change affects any listed item. 1734. Make a patch with "diff -c" against the unmodified code and docs. 1745. Make a note about what changed and include it with the patch. 175 176 177USE OF COMMON FUNCTIONS *style-functions* 178 179Some functions that are common to use, have a special Vim version. Always 180consider using the Vim version, because they were introduced with a reason. 181 182NORMAL NAME VIM NAME DIFFERENCE OF VIM VERSION 183free() vim_free() Checks for freeing NULL 184malloc() alloc() Checks for out of memory situation 185malloc() lalloc() Like alloc(), but has long argument 186strcpy() STRCPY() Includes cast to (char *), for char_u * args 187strchr() vim_strchr() Accepts special characters 188strrchr() vim_strrchr() Accepts special characters 189isspace() vim_isspace() Can handle characters > 128 190iswhite() vim_iswhite() Only TRUE for tab and space 191memcpy() mch_memmove() Handles overlapped copies 192bcopy() mch_memmove() Handles overlapped copies 193memset() vim_memset() Uniform for all systems 194 195 196NAMES *style-names* 197 198Function names can not be more than 31 characters long (because of VMS). 199 200Don't use "delete" as a variable name, C++ doesn't like it. 201 202Because of the requirement that Vim runs on as many systems as possible, we 203need to avoid using names that are already defined by the system. This is a 204list of names that are known to cause trouble. The name is given as a regexp 205pattern. 206 207is.*() POSIX, ctype.h 208to.*() POSIX, ctype.h 209 210d_.* POSIX, dirent.h 211l_.* POSIX, fcntl.h 212gr_.* POSIX, grp.h 213pw_.* POSIX, pwd.h 214sa_.* POSIX, signal.h 215mem.* POSIX, string.h 216str.* POSIX, string.h 217wcs.* POSIX, string.h 218st_.* POSIX, stat.h 219tms_.* POSIX, times.h 220tm_.* POSIX, time.h 221c_.* POSIX, termios.h 222MAX.* POSIX, limits.h 223__.* POSIX, system 224_[A-Z].* POSIX, system 225E[A-Z0-9]* POSIX, errno.h 226 227.*_t POSIX, for typedefs. Use .*_T instead. 228 229wait don't use as argument to a function, conflicts with types.h 230index shadows global declaration 231time shadows global declaration 232new C++ reserved keyword 233try Borland C++ doesn't like it to be used as a variable. 234 235basename() GNU string function 236dirname() GNU string function 237get_env_value() Linux system function 238 239 240VARIOUS *style-various* 241 242Typedef'ed names should end in "_T": > 243 typedef int some_T; 244Define'ed names should be uppercase: > 245 #define SOME_THING 246Features always start with "FEAT_": > 247 #define FEAT_FOO 248 249Don't use '\"', some compilers can't handle it. '"' works fine. 250 251Don't use: 252 #if HAVE_SOME 253Some compilers can't handle that and complain that "HAVE_SOME" is not defined. 254Use 255 #ifdef HAVE_SOME 256or 257 #if defined(HAVE_SOME) 258 259 260STYLE *style-examples* 261 262General rule: One statement per line. 263 264Wrong: if (cond) a = 1; 265 266OK: if (cond) 267 a = 1; 268 269Wrong: while (cond); 270 271OK: while (cond) 272 ; 273 274Wrong: do a = 1; while (cond); 275 276OK: do 277 a = 1; 278 while (cond); 279 280 281Functions start with: 282 283Wrong: int function_name(int arg1, int arg2) 284 285OK: /* 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 299NOTE: Don't use ANSI style function declarations. A few people still have to 300use a compiler that doesn't support it. 301 302 303SPACES AND PUNCTUATION *style-spaces* 304 305No space between a function name and the bracket: 306 307Wrong: func (arg); 308OK: func(arg); 309 310Do use a space after if, while, switch, etc. 311 312Wrong: if(arg) for(;;) 313OK: if (arg) for (;;) 314 315Use a space after a comma and semicolon: 316 317Wrong: func(arg1,arg2); for (i = 0;i < 2;++i) 318OK: func(arg1, arg2); for (i = 0; i < 2; ++i) 319 320Use a space before and after '=', '+', '/', etc. 321 322Wrong: var=a*5; 323OK: var = a * 5; 324 325In general: Use empty lines to group lines of code together. Put a comment 326just above the group of lines. This makes it easier to quickly see what is 327being done. 328 329OK: /* 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============================================================================== 3423. Design decisions *design-decisions* 343 344Folding 345 346Several forms of folding should be possible for the same buffer. For example, 347have one window that shows the text with function bodies folded, another 348window that shows a function body. 349 350Folding is a way to display the text. It should not change the text itself. 351Therefore the folding has been implemented as a filter between the text stored 352in a buffer (buffer lines) and the text displayed in a window (logical lines). 353 354 355Naming the window 356 357The word "window" is commonly used for several things: A window on the screen, 358the xterm window, a window inside Vim to view a buffer. 359To avoid confusion, other items that are sometimes called window have been 360given another name. Here is an overview of the related items: 361 362screen 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. 364shell The Vim application. This can cover the whole screen (e.g., 365 when running in a console) or part of it (xterm or GUI). 366window 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 371Spell checking *develop-spell* 372 373When spell checking was going to be added to Vim a survey was done over the 374available spell checking libraries and programs. Unfortunately, the result 375was that none of them provided sufficient capabilities to be used as the spell 376checking 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. 380 Doing on-the-fly conversion is not always possible (would require iconv 381 support). 382- For the programs and libraries: Using them as-is would require installing 383 them separately from Vim. That's mostly not impossible, but a drawback. 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 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. 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). 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. 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. 402 403 404Spelling suggestions *develop-spell-suggestions* 405 406For making suggestions there are two basic mechanisms: 4071. 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. 4112. 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 414The first is good for finding typing mistakes. After experimenting with 415hashtables and looking at solutions from other spell checkers the conclusion 416was that a trie (a kind of tree structure) is ideal for this. Both for 417reducing memory use and being able to try sensible changes. For example, when 418inserting a character only characters that lead to good words need to be 419tried. Other mechanisms (with hashtables) need to try all possible letters at 420every position in the word. Also, a hashtable has the requirement that word 421boundaries are identified separately, while a trie does not require this. 422That makes the mechanism a lot simpler. 423 424Soundfolding is useful when someone knows how the words sounds but doesn't 425know how it is spelled. For example, the word "dictionary" might be written 426as "daktonerie". The number of changes that the first method would need to 427try is very big, it's hard to find the good word that way. After soundfolding 428the words become "tktnr" and "tkxnry", these differ by only two letters. 429 430To find words by their soundfolded equivalent (soundalike word) we need a list 431of all soundfolded words. A few experiments have been done to find out what 432the best method is. Alternatives: 4331. 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 too slow for all languages. 4412. 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. 4463. 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 453The choice made is to use the second mechanism and use a separate file. This 454way a user with sufficient memory can get very good suggestions while a user 455who is short of memory or just wants the spell checking and no suggestions 456doesn't use so much memory. 457 458 459Word frequency 460 461For sorting suggestions it helps to know which words are common. In theory we 462could store a word frequency with the word in the dictionary. However, this 463requires storing a count per word. That degrades word tree compression a lot. 464And maintaining the word frequency for all languages will be a heavy task. 465Also, it would be nice to prefer words that are already in the text. This way 466the words that appear in the specific text are preferred for suggestions. 467 468What has been implemented is to count words that have been seen during 469displaying. A hashtable is used to quickly find the word count. The count is 470initialized from words listed in COMMON items in the affix file, so that it 471also works when starting a new file. 472 473This isn't ideal, because the longer Vim is running the higher the counts 474become. But in practice it is a noticeable improvement over not using the word 475count. 476 477============================================================================== 4784. Assumptions *design-assumptions* 479 480Size of variables: 481char 8 bit signed 482char_u 8 bit unsigned 483int 32 or 64 bit signed (16 might be possible with limited features) 484unsigned 32 or 64 bit unsigned (16 as with ints) 485long 32 or 64 bit signed, can hold a pointer 486 487Note that some compilers cannot handle long lines or strings. The C89 488standard specifies a limit of 509 characters. 489 490 vim:tw=78:ts=8:ft=help:norl: 491