blob: dc49c0992bd2331db39be854a273c009064badf9 [file] [log] [blame]
Bram Moolenaar68563932017-01-10 13:31:15 +01001*develop.txt* For Vim version 8.0. Last change: 2017 Jan 05
Bram Moolenaar071d4272004-06-13 20:20:40 +00002
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.
Bram Moolenaar531da592013-05-06 05:58:55 +020022Also see http://vim.wikia.com/wiki/How_to_make_and_submit_a_patch.
Bram Moolenaar071d4272004-06-13 20:20:40 +000023
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
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010067 obscure features, or at least add hints in documentation that they exist.
Bram Moolenaar071d4272004-06-13 20:20:40 +000068- 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|.
Bram Moolenaarae5bce12005-08-15 21:41:48 +0000126- Use comments in a useful way! Quoting the function name and argument names
127 is NOT useful. Do explain what they are for.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000128- 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. ;-)"
Bram Moolenaareca15752006-03-10 21:35:45 +0000152 To use Vim with gdb see: http://www.agide.org and http://clewn.sf.net.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000153- 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:
Bram Moolenaar13d5aee2016-01-21 23:36:05 +01001691. Get the code from github. That makes it easier to keep your changed
170 version in sync with the main code base (it may be a while before your
171 changes will be included). You do need to spend some time learning git,
172 it's not the most user friendly tool.
1732. Adjust the documentation. Doing this first gives you an impression of how
Bram Moolenaar071d4272004-06-13 20:20:40 +0000174 your changes affect the user.
Bram Moolenaar13d5aee2016-01-21 23:36:05 +01001753. Make the source code changes.
1764. Check ../doc/todo.txt if the change affects any listed item.
1775. Make a patch with "git diff". You can also create a pull request on
178 github, but it's the diff that matters.
1796. Make a note about what changed, preferably mentioning the problem and the
Bram Moolenaar68563932017-01-10 13:31:15 +0100180 solution. Send an email to the |vim-dev| maillist with an explanation and
Bram Moolenaar13d5aee2016-01-21 23:36:05 +0100181 include the diff. Or create a pull request on github.
182
183
184C COMPILER *style-compiler*
185
186The minimal C compiler version supported is C89, also known as ANSI C.
187Later standards don't add much and C89 is the widest supported.
188
189One restriction that this implies: no // comments, only /* comments */.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000190
191
192USE OF COMMON FUNCTIONS *style-functions*
193
194Some functions that are common to use, have a special Vim version. Always
195consider using the Vim version, because they were introduced with a reason.
196
197NORMAL NAME VIM NAME DIFFERENCE OF VIM VERSION
198free() vim_free() Checks for freeing NULL
199malloc() alloc() Checks for out of memory situation
200malloc() lalloc() Like alloc(), but has long argument
201strcpy() STRCPY() Includes cast to (char *), for char_u * args
202strchr() vim_strchr() Accepts special characters
203strrchr() vim_strrchr() Accepts special characters
204isspace() vim_isspace() Can handle characters > 128
Bram Moolenaar9e368db2007-05-12 13:25:01 +0000205iswhite() vim_iswhite() Only TRUE for tab and space
Bram Moolenaar36fc5352006-03-04 21:49:37 +0000206memcpy() mch_memmove() Handles overlapped copies
207bcopy() mch_memmove() Handles overlapped copies
Bram Moolenaar071d4272004-06-13 20:20:40 +0000208memset() vim_memset() Uniform for all systems
209
210
211NAMES *style-names*
212
213Function names can not be more than 31 characters long (because of VMS).
214
Bram Moolenaar13d5aee2016-01-21 23:36:05 +0100215Don't use "delete" or "this" as a variable name, C++ doesn't like it.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000216
217Because of the requirement that Vim runs on as many systems as possible, we
218need to avoid using names that are already defined by the system. This is a
219list of names that are known to cause trouble. The name is given as a regexp
220pattern.
221
222is.*() POSIX, ctype.h
223to.*() POSIX, ctype.h
224
225d_.* POSIX, dirent.h
226l_.* POSIX, fcntl.h
227gr_.* POSIX, grp.h
228pw_.* POSIX, pwd.h
229sa_.* POSIX, signal.h
230mem.* POSIX, string.h
231str.* POSIX, string.h
232wcs.* POSIX, string.h
233st_.* POSIX, stat.h
234tms_.* POSIX, times.h
235tm_.* POSIX, time.h
236c_.* POSIX, termios.h
237MAX.* POSIX, limits.h
238__.* POSIX, system
239_[A-Z].* POSIX, system
240E[A-Z0-9]* POSIX, errno.h
241
Bram Moolenaar9964e462007-05-05 17:54:07 +0000242.*_t POSIX, for typedefs. Use .*_T instead.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000243
244wait don't use as argument to a function, conflicts with types.h
245index shadows global declaration
246time shadows global declaration
247new C++ reserved keyword
248try Borland C++ doesn't like it to be used as a variable.
249
Bram Moolenaar6be7f872012-01-20 21:08:56 +0100250clear Mac curses.h
251echo Mac curses.h
252instr Mac curses.h
253meta Mac curses.h
254newwin Mac curses.h
255nl Mac curses.h
256overwrite Mac curses.h
257refresh Mac curses.h
258scroll Mac curses.h
259typeahead Mac curses.h
260
Bram Moolenaar071d4272004-06-13 20:20:40 +0000261basename() GNU string function
262dirname() GNU string function
263get_env_value() Linux system function
264
265
266VARIOUS *style-various*
267
Bram Moolenaare344bea2005-09-01 20:46:49 +0000268Typedef'ed names should end in "_T": >
269 typedef int some_T;
Bram Moolenaar071d4272004-06-13 20:20:40 +0000270Define'ed names should be uppercase: >
271 #define SOME_THING
272Features always start with "FEAT_": >
273 #define FEAT_FOO
274
275Don't use '\"', some compilers can't handle it. '"' works fine.
276
277Don't use:
278 #if HAVE_SOME
279Some compilers can't handle that and complain that "HAVE_SOME" is not defined.
280Use
281 #ifdef HAVE_SOME
282or
283 #if defined(HAVE_SOME)
284
285
286STYLE *style-examples*
287
288General rule: One statement per line.
289
290Wrong: if (cond) a = 1;
291
292OK: if (cond)
293 a = 1;
294
295Wrong: while (cond);
296
297OK: while (cond)
298 ;
299
300Wrong: do a = 1; while (cond);
301
302OK: do
303 a = 1;
304 while (cond);
305
Bram Moolenaar13d5aee2016-01-21 23:36:05 +0100306Wrong: if (cond) {
307 cmd;
308 cmd;
309 } else {
310 cmd;
311 cmd;
312 }
313
314OK: if (cond)
315 {
316 cmd;
317 cmd;
318 }
319 else
320 {
321 cmd;
322 cmd;
323 }
Bram Moolenaar071d4272004-06-13 20:20:40 +0000324
Bram Moolenaar5e9b2fa2016-02-01 22:37:05 +0100325Use ANSI (new style) function declarations with the return type on a separate
326indented line.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000327
328Wrong: int function_name(int arg1, int arg2)
329
330OK: /*
331 * Explanation of what this function is used for.
332 *
333 * Return value explanation.
334 */
335 int
Bram Moolenaar13d5aee2016-01-21 23:36:05 +0100336 function_name(
337 int arg1, /* short comment about arg1 */
338 int arg2) /* short comment about arg2 */
Bram Moolenaar071d4272004-06-13 20:20:40 +0000339 {
340 int local; /* comment about local */
341
342 local = arg1 * arg2;
343
Bram Moolenaar071d4272004-06-13 20:20:40 +0000344
345
346SPACES AND PUNCTUATION *style-spaces*
347
348No space between a function name and the bracket:
349
350Wrong: func (arg);
351OK: func(arg);
352
353Do use a space after if, while, switch, etc.
354
355Wrong: if(arg) for(;;)
356OK: if (arg) for (;;)
357
358Use a space after a comma and semicolon:
359
360Wrong: func(arg1,arg2); for (i = 0;i < 2;++i)
361OK: func(arg1, arg2); for (i = 0; i < 2; ++i)
362
363Use a space before and after '=', '+', '/', etc.
364
365Wrong: var=a*5;
366OK: var = a * 5;
367
368In general: Use empty lines to group lines of code together. Put a comment
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100369just above the group of lines. This makes it easier to quickly see what is
Bram Moolenaar071d4272004-06-13 20:20:40 +0000370being done.
371
372OK: /* Prepare for building the table. */
373 get_first_item();
374 table_idx = 0;
375
376 /* Build the table */
377 while (has_item())
378 table[table_idx++] = next_item();
379
380 /* Finish up. */
381 cleanup_items();
382 generate_hash(table);
383
384==============================================================================
3853. Design decisions *design-decisions*
386
387Folding
388
389Several forms of folding should be possible for the same buffer. For example,
390have one window that shows the text with function bodies folded, another
391window that shows a function body.
392
393Folding is a way to display the text. It should not change the text itself.
394Therefore the folding has been implemented as a filter between the text stored
395in a buffer (buffer lines) and the text displayed in a window (logical lines).
396
397
398Naming the window
399
400The word "window" is commonly used for several things: A window on the screen,
401the xterm window, a window inside Vim to view a buffer.
402To avoid confusion, other items that are sometimes called window have been
403given another name. Here is an overview of the related items:
404
405screen The whole display. For the GUI it's something like 1024x768
406 pixels. The Vim shell can use the whole screen or part of it.
407shell The Vim application. This can cover the whole screen (e.g.,
408 when running in a console) or part of it (xterm or GUI).
409window View on a buffer. There can be several windows in Vim,
410 together with the command line, menubar, toolbar, etc. they
411 fit in the shell.
412
413
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000414Spell checking *develop-spell*
415
416When spell checking was going to be added to Vim a survey was done over the
417available spell checking libraries and programs. Unfortunately, the result
418was that none of them provided sufficient capabilities to be used as the spell
419checking engine in Vim, for various reasons:
420
421- Missing support for multi-byte encodings. At least UTF-8 must be supported,
422 so that more than one language can be used in the same file.
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000423 Doing on-the-fly conversion is not always possible (would require iconv
424 support).
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000425- For the programs and libraries: Using them as-is would require installing
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000426 them separately from Vim. That's mostly not impossible, but a drawback.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000427- Performance: A few tests showed that it's possible to check spelling on the
428 fly (while redrawing), just like syntax highlighting. But the mechanisms
Bram Moolenaar4770d092006-01-12 23:22:24 +0000429 used by other code are much slower. Myspell uses a hashtable, for example.
430 The affix compression that most spell checkers use makes it slower too.
Bram Moolenaar51485f02005-06-04 21:55:20 +0000431- For using an external program like aspell a communication mechanism would
432 have to be setup. That's complicated to do in a portable way (Unix-only
433 would be relatively simple, but that's not good enough). And performance
434 will become a problem (lots of process switching involved).
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000435- Missing support for words with non-word characters, such as "Etten-Leur" and
436 "et al.", would require marking the pieces of them OK, lowering the
437 reliability.
438- Missing support for regions or dialects. Makes it difficult to accept
439 all English words and highlight non-Canadian words differently.
440- Missing support for rare words. Many words are correct but hardly ever used
441 and could be a misspelled often-used word.
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000442- For making suggestions the speed is less important and requiring to install
443 another program or library would be acceptable. But the word lists probably
444 differ, the suggestions may be wrong words.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000445
Bram Moolenaar4770d092006-01-12 23:22:24 +0000446
447Spelling suggestions *develop-spell-suggestions*
448
449For making suggestions there are two basic mechanisms:
4501. Try changing the bad word a little bit and check for a match with a good
451 word. Or go through the list of good words, change them a little bit and
452 check for a match with the bad word. The changes are deleting a character,
453 inserting a character, swapping two characters, etc.
4542. Perform soundfolding on both the bad word and the good words and then find
455 matches, possibly with a few changes like with the first mechanism.
456
457The first is good for finding typing mistakes. After experimenting with
458hashtables and looking at solutions from other spell checkers the conclusion
459was that a trie (a kind of tree structure) is ideal for this. Both for
460reducing memory use and being able to try sensible changes. For example, when
461inserting a character only characters that lead to good words need to be
462tried. Other mechanisms (with hashtables) need to try all possible letters at
463every position in the word. Also, a hashtable has the requirement that word
464boundaries are identified separately, while a trie does not require this.
465That makes the mechanism a lot simpler.
466
467Soundfolding is useful when someone knows how the words sounds but doesn't
468know how it is spelled. For example, the word "dictionary" might be written
469as "daktonerie". The number of changes that the first method would need to
470try is very big, it's hard to find the good word that way. After soundfolding
471the words become "tktnr" and "tkxnry", these differ by only two letters.
472
473To find words by their soundfolded equivalent (soundalike word) we need a list
474of all soundfolded words. A few experiments have been done to find out what
475the best method is. Alternatives:
4761. Do the sound folding on the fly when looking for suggestions. This means
477 walking through the trie of good words, soundfolding each word and
478 checking how different it is from the bad word. This is very efficient for
479 memory use, but takes a long time. On a fast PC it takes a couple of
480 seconds for English, which can be acceptable for interactive use. But for
481 some languages it takes more than ten seconds (e.g., German, Catalan),
482 which is unacceptable slow. For batch processing (automatic corrections)
Bram Moolenaar82038d72007-05-10 17:15:45 +0000483 it's too slow for all languages.
Bram Moolenaar4770d092006-01-12 23:22:24 +00004842. Use a trie for the soundfolded words, so that searching can be done just
485 like how it works without soundfolding. This requires remembering a list
486 of good words for each soundfolded word. This makes finding matches very
487 fast but requires quite a lot of memory, in the order of 1 to 10 Mbyte.
488 For some languages more than the original word list.
4893. Like the second alternative, but reduce the amount of memory by using affix
490 compression and store only the soundfolded basic word. This is what Aspell
491 does. Disadvantage is that affixes need to be stripped from the bad word
492 before soundfolding it, which means that mistakes at the start and/or end
493 of the word will cause the mechanism to fail. Also, this becomes slow when
494 the bad word is quite different from the good word.
495
496The choice made is to use the second mechanism and use a separate file. This
497way a user with sufficient memory can get very good suggestions while a user
498who is short of memory or just wants the spell checking and no suggestions
499doesn't use so much memory.
500
501
502Word frequency
503
504For sorting suggestions it helps to know which words are common. In theory we
505could store a word frequency with the word in the dictionary. However, this
506requires storing a count per word. That degrades word tree compression a lot.
507And maintaining the word frequency for all languages will be a heavy task.
508Also, it would be nice to prefer words that are already in the text. This way
509the words that appear in the specific text are preferred for suggestions.
510
511What has been implemented is to count words that have been seen during
512displaying. A hashtable is used to quickly find the word count. The count is
513initialized from words listed in COMMON items in the affix file, so that it
514also works when starting a new file.
515
516This isn't ideal, because the longer Vim is running the higher the counts
Bram Moolenaar82038d72007-05-10 17:15:45 +0000517become. But in practice it is a noticeable improvement over not using the word
Bram Moolenaar4770d092006-01-12 23:22:24 +0000518count.
519
Bram Moolenaar071d4272004-06-13 20:20:40 +0000520==============================================================================
5214. Assumptions *design-assumptions*
522
523Size of variables:
524char 8 bit signed
525char_u 8 bit unsigned
Bram Moolenaar4770d092006-01-12 23:22:24 +0000526int 32 or 64 bit signed (16 might be possible with limited features)
527unsigned 32 or 64 bit unsigned (16 as with ints)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000528long 32 or 64 bit signed, can hold a pointer
529
530Note that some compilers cannot handle long lines or strings. The C89
531standard specifies a limit of 509 characters.
532
533 vim:tw=78:ts=8:ft=help:norl: