Vim documentation: develop (original) (raw)

main help file

Development of Vim. * development*

This text is important for those who want to be involved in further developing Vim.

  1. Design goals |design-goals|
  2. Coding style |coding-style|
  3. Design decisions |design-decisions|
  4. Assumptions |design-assumptions|

See the file README.txt in the "src" directory for an overview of the source code.

Vim is open source software. Everybody is encouraged to contribute to help improving Vim. For sending patches a context diff "diff -c" is preferred. Also see http://www.vim.org/tips/tip.php?tip_id=618.

==============================================================================

  1. Design goals * design-goals*

Most important things come first (roughly).

Note that quite a few items are contradicting. This is intentional. A balance must be found between them.

VIM IS... VI COMPATIBLE * design-compatible*

First of all, it should be possible to use Vim as a drop-in replacement for Vi. When the user wants to, he can use Vim in compatible mode and hardly notice any difference with the original Vi.

Exceptions:

VIM IS... IMPROVED * design-improved*

The IMproved bits of Vim should make it a better Vi, without becoming a completely different editor. Extensions are done with a "Vi spirit".

VIM IS... MULTI PLATFORM * design-multi-platform*

Vim tries to help as many users on as many platforms as possible.

VIM IS... WELL DOCUMENTED * design-documented*

VIM IS... HIGH SPEED AND SMALL IN SIZE * design-speed-size*

Using Vim must not be a big attack on system resources. Keep it small and fast.

VIM IS... MAINTAINABLE * design-maintain*

VIM IS... FLEXIBLE * design-flexible*

Vim should make it easy for users to work in their preferred styles rather than coercing its users into particular patterns of work. This can be for items with a large impact (e.g., the 'compatible' option) or for details. The defaults are carefully chosen such that most users will enjoy using Vim as it is. Commands and options can be used to adjust Vim to the desire of the user and its environment.

VIM IS... NOT * design-not*

==============================================================================

  1. Coding style * coding-style*

These are the rules to use when making changes to the Vim source code. Please stick to these rules, to keep the sources readable and maintainable.

This list is not complete. Look in the source code for more examples.

MAKING CHANGES * style-changes*

The basic steps to make changes to the code:

  1. Adjust the documentation. Doing this first gives you an impression of how your changes affect the user.
  2. Make the source code changes.
  3. Check ../doc/todo.txt if the change affects any listed item.
  4. Make a patch with "diff -c" against the unmodified code and docs.
  5. Make a note about what changed and include it with the patch.

USE OF COMMON FUNCTIONS * style-functions*

Some functions that are common to use, have a special Vim version. Always consider using the Vim version, because they were introduced with a reason.

NORMAL NAME VIM NAME DIFFERENCE OF VIM VERSION free() vim_free() Checks for freeing NULL malloc() alloc() Checks for out of memory situation malloc() lalloc() Like alloc(), but has long argument strcpy() STRCPY() Includes cast to (char *), for char_u * args strchr() vim_strchr() Accepts special characters strrchr() vim_strrchr() Accepts special characters isspace() vim_isspace() Can handle characters > 128 iswhite() vim_iswhite() Only TRUE for tab and space memcpy() mch_memmove() Handles overlapped copies bcopy() mch_memmove() Handles overlapped copies memset() vim_memset() Uniform for all systems

NAMES * style-names*

Function names can not be more than 31 characters long (because of VMS).

Don't use "delete" as a variable name, C++ doesn't like it.

Because of the requirement that Vim runs on as many systems as possible, we need to avoid using names that are already defined by the system. This is a list of names that are known to cause trouble. The name is given as a regexp pattern.

is.() POSIX, ctype.h to.() POSIX, ctype.h

d_.* POSIX, dirent.h l_.* POSIX, fcntl.h gr_.* POSIX, grp.h pw_.* POSIX, pwd.h sa_.* POSIX, signal.h mem.* POSIX, string.h str.* POSIX, string.h wcs.* POSIX, string.h st_.* POSIX, stat.h tms_.* POSIX, times.h tm_.* POSIX, time.h c_.* POSIX, termios.h MAX.* POSIX, limits.h __.* POSIX, system _[A-Z].* POSIX, system E[A-Z0-9]* POSIX, errno.h

._t POSIX, for typedefs. Use ._T instead.

wait don't use as argument to a function, conflicts with types.h index shadows global declaration time shadows global declaration new C++ reserved keyword try Borland C++ doesn't like it to be used as a variable.

basename() GNU string function dirname() GNU string function get_env_value() Linux system function

VARIOUS * style-various*

Typedef'ed names should end in "T": typedef int some_T; Define'ed names should be uppercase: #define SOME_THING Features always start with "FEAT": #define FEAT_FOO

Don't use '"', some compilers can't handle it. '"'' works fine.

Don't use: #if HAVE_SOME Some compilers can't handle that and complain that "HAVE_SOME" is not defined. Use #ifdef HAVE_SOME or #if defined(HAVE_SOME)

STYLE * style-examples*

General rule: One statement per line.

Wrong: if (cond) a = 1;

OK: if (cond) a = 1;

Wrong: while (cond);

OK: while (cond) ;

Wrong: do a = 1; while (cond);

OK: do a = 1; while (cond);

Functions start with:

Wrong: int function_name(int arg1, int arg2)

OK: /* * Explanation of what this function is used for. * * Return value explanation. / int function_name(arg1, arg2) int arg1; / short comment about arg1 / int arg2; / short comment about arg2 / { int local; / comment about local */

    local = arg1 * arg2;

NOTE: Don't use ANSI style function declarations. A few people still have to use a compiler that doesn't support it.

SPACES AND PUNCTUATION * style-spaces*

No space between a function name and the bracket:

Wrong: func (arg); OK: func(arg);

Do use a space after if, while, switch, etc.

Wrong: if(arg) for(;;) OK: if (arg) for (;;)

Use a space after a comma and semicolon:

Wrong: func(arg1,arg2); for (i = 0;i < 2;++i) OK: func(arg1, arg2); for (i = 0; i < 2; ++i)

Use a space before and after '=', '+', '/', etc.

Wrong: var=a*5; OK: var = a * 5;

In general: Use empty lines to group lines of code together. Put a comment just above the group of lines. This makes it easier to quickly see what is being done.

OK: /* Prepare for building the table. */ get_first_item(); table_idx = 0;

/* Build the table */
while (has_item())
    table[table_idx++] = next_item();

/* Finish up. */
cleanup_items();
generate_hash(table);

==============================================================================

  1. Design decisions * design-decisions*

Folding

Several forms of folding should be possible for the same buffer. For example, have one window that shows the text with function bodies folded, another window that shows a function body.

Folding is a way to display the text. It should not change the text itself. Therefore the folding has been implemented as a filter between the text stored in a buffer (buffer lines) and the text displayed in a window (logical lines).

Naming the window

The word "window" is commonly used for several things: A window on the screen, the xterm window, a window inside Vim to view a buffer. To avoid confusion, other items that are sometimes called window have been given another name. Here is an overview of the related items:

screen The whole display. For the GUI it's something like 1024x768 pixels. The Vim shell can use the whole screen or part of it. shell The Vim application. This can cover the whole screen (e.g., when running in a console) or part of it (xterm or GUI). window View on a buffer. There can be several windows in Vim, together with the command line, menubar, toolbar, etc. they fit in the shell.

Spell checking * develop-spell*

When spell checking was going to be added to Vim a survey was done over the available spell checking libraries and programs. Unfortunately, the result was that none of them provided sufficient capabilities to be used as the spell checking engine in Vim, for various reasons:

Spelling suggestions * develop-spell-suggestions*

For making suggestions there are two basic mechanisms:

  1. Try changing the bad word a little bit and check for a match with a good word. Or go through the list of good words, change them a little bit and check for a match with the bad word. The changes are deleting a character, inserting a character, swapping two characters, etc.
  2. Perform soundfolding on both the bad word and the good words and then find matches, possibly with a few changes like with the first mechanism.

The first is good for finding typing mistakes. After experimenting with hashtables and looking at solutions from other spell checkers the conclusion was that a trie (a kind of tree structure) is ideal for this. Both for reducing memory use and being able to try sensible changes. For example, when inserting a character only characters that lead to good words need to be tried. Other mechanisms (with hashtables) need to try all possible letters at every position in the word. Also, a hashtable has the requirement that word boundaries are identified separately, while a trie does not require this. That makes the mechanism a lot simpler.

Soundfolding is useful when someone knows how the words sounds but doesn't know how it is spelled. For example, the word "dictionary" might be written as "daktonerie". The number of changes that the first method would need to try is very big, it's hard to find the good word that way. After soundfolding the words become "tktnr" and "tkxnry", these differ by only two letters.

To find words by their soundfolded equivalent (soundalike word) we need a list of all soundfolded words. A few experiments have been done to find out what the best method is. Alternatives:

  1. Do the sound folding on the fly when looking for suggestions. This means walking through the trie of good words, soundfolding each word and checking how different it is from the bad word. This is very efficient for memory use, but takes a long time. On a fast PC it takes a couple of seconds for English, which can be acceptable for interactive use. But for some languages it takes more than ten seconds (e.g., German, Catalan), which is unacceptable slow. For batch processing (automatic corrections) it's too slow for all languages.
  2. Use a trie for the soundfolded words, so that searching can be done just like how it works without soundfolding. This requires remembering a list of good words for each soundfolded word. This makes finding matches very fast but requires quite a lot of memory, in the order of 1 to 10 Mbyte. For some languages more than the original word list.
  3. Like the second alternative, but reduce the amount of memory by using affix compression and store only the soundfolded basic word. This is what Aspell does. Disadvantage is that affixes need to be stripped from the bad word before soundfolding it, which means that mistakes at the start and/or end of the word will cause the mechanism to fail. Also, this becomes slow when the bad word is quite different from the good word.

The choice made is to use the second mechanism and use a separate file. This way a user with sufficient memory can get very good suggestions while a user who is short of memory or just wants the spell checking and no suggestions doesn't use so much memory.

Word frequency

For sorting suggestions it helps to know which words are common. In theory we could store a word frequency with the word in the dictionary. However, this requires storing a count per word. That degrades word tree compression a lot. And maintaining the word frequency for all languages will be a heavy task. Also, it would be nice to prefer words that are already in the text. This way the words that appear in the specific text are preferred for suggestions.

What has been implemented is to count words that have been seen during displaying. A hashtable is used to quickly find the word count. The count is initialized from words listed in COMMON items in the affix file, so that it also works when starting a new file.

This isn't ideal, because the longer Vim is running the higher the counts become. But in practice it is a noticeable improvement over not using the word count.

==============================================================================

  1. Assumptions * design-assumptions*

Size of variables: char 8 bit signed char_u 8 bit unsigned int 32 or 64 bit signed (16 might be possible with limited features) unsigned 32 or 64 bit unsigned (16 as with ints) long 32 or 64 bit signed, can hold a pointer

Note that some compilers cannot handle long lines or strings. The C89 standard specifies a limit of 509 characters.

top - main help file