annotate runtime/doc/develop.txt @ 33811:06219b3bdaf3 v9.0.2121

patch 9.0.2121: [security]: use-after-free in ex_substitute Commit: https://github.com/vim/vim/commit/26c11c56888d01e298cd8044caf860f3c26f57bb Author: Christian Brabandt <cb@256bit.org> Date: Wed Nov 22 21:26:41 2023 +0100 patch 9.0.2121: [security]: use-after-free in ex_substitute Problem: [security]: use-after-free in ex_substitute Solution: always allocate memory closes: #13552 A recursive :substitute command could cause a heap-use-after free in Vim (CVE-2023-48706). The whole reproducible test is a bit tricky, I can only reproduce this reliably when no previous substitution command has been used yet (which is the reason, the test needs to run as first one in the test_substitute.vim file) and as a combination of the `:~` command together with a :s command that contains the special substitution atom `~\=` which will make use of a sub-replace special atom and calls a vim script function. There was a comment in the existing :s code, that already makes the `sub` variable allocate memory so that a recursive :s call won't be able to cause any issues here, so this was known as a potential problem already. But for the current test-case that one does not work, because the substitution does not start with `\=` but with `~\=` (and since there does not yet exist a previous substitution atom, Vim will simply increment the `sub` pointer (which then was not allocated dynamically) and later one happily use a sub-replace special expression (which could then free the `sub` var). The following commit fixes this, by making the sub var always using allocated memory, which also means we need to free the pointer whenever we leave the function. Since sub is now always an allocated variable, we also do no longer need the sub_copy variable anymore, since this one was used to indicated when sub pointed to allocated memory (and had therefore to be freed on exit) and when not. Github Security Advisory: https://github.com/vim/vim/security/advisories/GHSA-c8qm-x72m-q53q Signed-off-by: Christian Brabandt <cb@256bit.org>
author Christian Brabandt <cb@256bit.org>
date Wed, 22 Nov 2023 22:15:05 +0100
parents 1e91e26ceebf
children 4635e43f2c6f
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
30547
1e91e26ceebf Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 30377
diff changeset
1 *develop.txt* For Vim version 9.0. Last change: 2022 Sep 20
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
2
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
3
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
4 VIM REFERENCE MANUAL by Bram Moolenaar
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
5
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
6
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
7 Development of Vim. *development*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
8
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
9 This text is important for those who want to be involved in further developing
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
10 Vim.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
11
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
12 1. Design goals |design-goals|
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
13 2. Coding style |coding-style|
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
14 3. Design decisions |design-decisions|
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
15 4. Assumptions |design-assumptions|
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
16
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
17 See the file README.txt in the "src" directory for an overview of the source
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
18 code.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
19
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
20 Vim is open source software. Everybody is encouraged to contribute to help
13857
e751b5c9dff3 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13818
diff changeset
21 improving Vim. For sending patches a unified diff "diff -u" is preferred.
e751b5c9dff3 Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13818
diff changeset
22 You can create a pull request on github, but it's not required.
4358
cf1d93a3914a Updated runtime files.
Bram Moolenaar <bram@vim.org>
parents: 3281
diff changeset
23 Also see http://vim.wikia.com/wiki/How_to_make_and_submit_a_patch.
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
24
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
25 ==============================================================================
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
26 1. Design goals *design-goals*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
27
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
28 Most important things come first (roughly).
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
29
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
30 Note that quite a few items are contradicting. This is intentional. A
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
31 balance must be found between them.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
32
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
33
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
34 VIM IS... VI COMPATIBLE *design-compatible*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
35
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
36 First of all, it should be possible to use Vim as a drop-in replacement for
21676
1b345fb68ae3 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 20115
diff changeset
37 Vi. When the user wants to, Vim can be used in compatible mode and hardly
1b345fb68ae3 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 20115
diff changeset
38 any differences with the original Vi will be noticed.
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
39
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
40 Exceptions:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
41 - We don't reproduce obvious Vi bugs in Vim.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
42 - There are different versions of Vi. I am using Version 3.7 (6/7/85) as a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
43 reference. But support for other versions is also included when possible.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
44 The Vi part of POSIX is not considered a definitive source.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
45 - Vim adds new commands, you cannot rely on some command to fail because it
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
46 didn't exist in Vi.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
47 - Vim will have a lot of features that Vi doesn't have. Going back from Vim
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
48 to Vi will be a problem, this cannot be avoided.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
49 - Some things are hardly ever used (open mode, sending an e-mail when
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
50 crashing, etc.). Those will only be included when someone has a good reason
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
51 why it should be included and it's not too much work.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
52 - For some items it is debatable whether Vi compatibility should be
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
53 maintained. There will be an option flag for these.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
54
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
55
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
56 VIM IS... IMPROVED *design-improved*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
57
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
58 The IMproved bits of Vim should make it a better Vi, without becoming a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
59 completely different editor. Extensions are done with a "Vi spirit".
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
60 - Use the keyboard as much as feasible. The mouse requires a third hand,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
61 which we don't have. Many terminals don't have a mouse.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
62 - When the mouse is used anyway, avoid the need to switch back to the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
63 keyboard. Avoid mixing mouse and keyboard handling.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
64 - Add commands and options in a consistent way. Otherwise people will have a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
65 hard time finding and remembering them. Keep in mind that more commands and
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
66 options will be added later.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
67 - A feature that people do not know about is a useless feature. Don't add
2033
de5a43c5eedc Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents: 1702
diff changeset
68 obscure features, or at least add hints in documentation that they exist.
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
69 - Minimize using CTRL and other modifiers, they are more difficult to type.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
70 - There are many first-time and inexperienced Vim users. Make it easy for
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
71 them to start using Vim and learn more over time.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
72 - There is no limit to the features that can be added. Selecting new features
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
73 is one based on (1) what users ask for, (2) how much effort it takes to
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
74 implement and (3) someone actually implementing it.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
75
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
76
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
77 VIM IS... MULTI PLATFORM *design-multi-platform*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
78
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
79 Vim tries to help as many users on as many platforms as possible.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
80 - Support many kinds of terminals. The minimal demands are cursor positioning
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
81 and clear-screen. Commands should only use key strokes that most keyboards
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
82 have. Support all the keys on the keyboard for mapping.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
83 - Support many platforms. A condition is that there is someone willing to do
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
84 Vim development on that platform, and it doesn't mean messing up the code.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
85 - Support many compilers and libraries. Not everybody is able or allowed to
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
86 install another compiler or GUI library.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
87 - People switch from one platform to another, and from GUI to terminal
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
88 version. Features should be present in all versions, or at least in as many
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
89 as possible with a reasonable effort. Try to avoid that users must switch
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
90 between platforms to accomplish their work efficiently.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
91 - That a feature is not possible on some platforms, or only possible on one
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
92 platform, does not mean it cannot be implemented. [This intentionally
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
93 contradicts the previous item, these two must be balanced.]
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
94
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
95
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
96 VIM IS... WELL DOCUMENTED *design-documented*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
97
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
98 - A feature that isn't documented is a useless feature. A patch for a new
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
99 feature must include the documentation.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
100 - Documentation should be comprehensive and understandable. Using examples is
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
101 recommended.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
102 - Don't make the text unnecessarily long. Less documentation means that an
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
103 item is easier to find.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
104
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
105
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
106 VIM IS... HIGH SPEED AND SMALL IN SIZE *design-speed-size*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
107
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
108 Using Vim must not be a big attack on system resources. Keep it small and
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
109 fast.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
110 - Computers are becoming faster and bigger each year. Vim can grow too, but
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
111 no faster than computers are growing. Keep Vim usable on older systems.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
112 - Many users start Vim from a shell very often. Startup time must be short.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
113 - Commands must work efficiently. The time they consume must be as small as
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
114 possible. Useful commands may take longer.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
115 - Don't forget that some people use Vim over a slow connection. Minimize the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
116 communication overhead.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
117 - Items that add considerably to the size and are not used by many people
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
118 should be a feature that can be disabled.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
119 - Vim is a component among other components. Don't turn it into a massive
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
120 application, but have it work well together with other programs.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
121
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
122
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
123 VIM IS... MAINTAINABLE *design-maintain*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
124
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
125 - The source code should not become a mess. It should be reliable code.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
126 - Use the same layout in all files to make it easy to read |coding-style|.
481
66080ac5dab7 updated for version 7.0130
vimboss
parents: 323
diff changeset
127 - Use comments in a useful way! Quoting the function name and argument names
66080ac5dab7 updated for version 7.0130
vimboss
parents: 323
diff changeset
128 is NOT useful. Do explain what they are for.
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
129 - Porting to another platform should be made easy, without having to change
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
130 too much platform-independent code.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
131 - Use the object-oriented spirit: Put data and code together. Minimize the
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
132 knowledge spread to other parts of the code.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
133
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
134
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
135 VIM IS... FLEXIBLE *design-flexible*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
136
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
137 Vim should make it easy for users to work in their preferred styles rather
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
138 than coercing its users into particular patterns of work. This can be for
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
139 items with a large impact (e.g., the 'compatible' option) or for details. The
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
140 defaults are carefully chosen such that most users will enjoy using Vim as it
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
141 is. Commands and options can be used to adjust Vim to the desire of the user
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
142 and its environment.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
143
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
144
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
145 VIM IS... NOT *design-not*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
146
11914
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 10548
diff changeset
147 - Vim is not a shell or an Operating System. It does provide a terminal
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 10548
diff changeset
148 window, in which you can run a shell or debugger. E.g. to be able to do
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 10548
diff changeset
149 this over an ssh connection. But if you don't need a text editor with that
4f7081eb1e26 Updated runtime files
Christian Brabandt <cb@256bit.org>
parents: 10548
diff changeset
150 it is out of scope (use something like screen or tmux instead).
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
151 A satirical way to say this: "Unlike Emacs, Vim does not attempt to include
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
152 everything but the kitchen sink, but some people say that you can clean one
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
153 with it. ;-)"
20115
bd021eb62e73 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 18879
diff changeset
154 To use Vim with gdb see |terminal-debugger|. Other (older) tools can be
bd021eb62e73 Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 18879
diff changeset
155 found at http://www.agide.org and http://clewn.sf.net.
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
156 - Vim is not a fancy GUI editor that tries to look nice at the cost of
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
157 being less consistent over all platforms. But functional GUI features are
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
158 welcomed.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
159
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
160 ==============================================================================
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
161 2. Coding style *coding-style*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
162
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
163 These are the rules to use when making changes to the Vim source code. Please
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
164 stick to these rules, to keep the sources readable and maintainable.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
165
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
166 This list is not complete. Look in the source code for more examples.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
167
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
168
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
169 MAKING CHANGES *style-changes*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
170
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
171 The basic steps to make changes to the code:
7707
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
172 1. Get the code from github. That makes it easier to keep your changed
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
173 version in sync with the main code base (it may be a while before your
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
174 changes will be included). You do need to spend some time learning git,
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
175 it's not the most user friendly tool.
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
176 2. Adjust the documentation. Doing this first gives you an impression of how
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
177 your changes affect the user.
7707
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
178 3. Make the source code changes.
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
179 4. Check ../doc/todo.txt if the change affects any listed item.
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
180 5. Make a patch with "git diff". You can also create a pull request on
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
181 github, but it's the diff that matters.
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
182 6. Make a note about what changed, preferably mentioning the problem and the
10548
74effdaa369e Updated runtime files.
Christian Brabandt <cb@256bit.org>
parents: 10198
diff changeset
183 solution. Send an email to the |vim-dev| maillist with an explanation and
7707
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
184 include the diff. Or create a pull request on github.
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
185
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
186
13818
28ac7914b2b6 Update runtime files and translations
Christian Brabandt <cb@256bit.org>
parents: 13735
diff changeset
187 C COMPILER *style-compiler* *ANSI-C* *C89* *C99*
7707
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
188
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
189 The minimal C compiler version supported is C89, also known as ANSI C.
13716
30f9ebe3e602 patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
190 Later standards, such as C99, are not widely supported, or at least not 100%
30377
c9d2c554f314 patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents: 29314
diff changeset
191 supported. Therefore we use only some of the C99 features and explicitly
c9d2c554f314 patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents: 29314
diff changeset
192 disallow some (this will gradually be adjusted over time).
13716
30f9ebe3e602 patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
193
30f9ebe3e602 patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
194 Please don't make changes everywhere to use the C99 features, it causes merge
30f9ebe3e602 patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
195 problems for existing patches. Only use them for new and changed code.
30f9ebe3e602 patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
196
30f9ebe3e602 patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
197 Comments ~
30f9ebe3e602 patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
198
18719
99586852c2db Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 17667
diff changeset
199 Traditionally Vim uses /* comments */. We intend to keep it that way
99586852c2db Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 17667
diff changeset
200 for file and function headers and larger blocks of code, E.g.:
99586852c2db Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 17667
diff changeset
201 /*
99586852c2db Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 17667
diff changeset
202 * The "foo" argument does something useful.
99586852c2db Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 17667
diff changeset
203 * Return OK or FAIL.
99586852c2db Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 17667
diff changeset
204 */
99586852c2db Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 17667
diff changeset
205 For new code or lines of code that change, it is preferred to use // comments.
99586852c2db Update runtime files
Bram Moolenaar <Bram@vim.org>
parents: 17667
diff changeset
206 Especially when it comes after code:
13716
30f9ebe3e602 patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
207 int some_var; // single line comment useful here
30f9ebe3e602 patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
208
30f9ebe3e602 patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
209 Enums ~
30f9ebe3e602 patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
210
30f9ebe3e602 patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
211 The last item in an enum may have a trailing comma. C89 didn't allow this.
30f9ebe3e602 patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
212
30f9ebe3e602 patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
213 Types ~
7707
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
214
13716
30f9ebe3e602 patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
215 "long long" is allowed and can be expected to be 64 bits. Use %lld in printf
30f9ebe3e602 patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
216 formats. Also "long long unsigned" with %llu.
30f9ebe3e602 patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
217
30377
c9d2c554f314 patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents: 29314
diff changeset
218 Declarations ~
c9d2c554f314 patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents: 29314
diff changeset
219
c9d2c554f314 patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents: 29314
diff changeset
220 Now that the minimal supported compiler is MSVC 2015 declarations do not need
c9d2c554f314 patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents: 29314
diff changeset
221 to be at the start of a block. However, it is often a good idea to do this
c9d2c554f314 patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents: 29314
diff changeset
222 anyway.
c9d2c554f314 patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents: 29314
diff changeset
223
c9d2c554f314 patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents: 29314
diff changeset
224 Declaration of the for loop variable inside the loop is recommended:
c9d2c554f314 patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents: 29314
diff changeset
225 for (int i = 0; i < len; ++i)
c9d2c554f314 patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents: 29314
diff changeset
226 Since this is clearly an advantage we'll use this more often.
c9d2c554f314 patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents: 29314
diff changeset
227
c9d2c554f314 patch 9.0.0524: build instructions for MS-Windows are outdated
Bram Moolenaar <Bram@vim.org>
parents: 29314
diff changeset
228
13716
30f9ebe3e602 patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
229 Not to be used ~
30f9ebe3e602 patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
230
30f9ebe3e602 patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
231 These C99 features are not to be used, because not enough compilers support
30f9ebe3e602 patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
232 them:
30f9ebe3e602 patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
233 - Variable length arrays (even in C11 this is an optional feature).
30f9ebe3e602 patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
234 - _Bool and _Complex types.
30f9ebe3e602 patch 8.0.1730: no configure check for the used C99 features
Christian Brabandt <cb@256bit.org>
parents: 11914
diff changeset
235 - "inline" (it's hardly ever needed, let the optimizer do its work)
13726
d35b1702a1da patch 8.0.1735: flexible array member feature not supported by HP-UX
Christian Brabandt <cb@256bit.org>
parents: 13716
diff changeset
236 - flexible array members: Not supported by HP-UX C compiler (John Marriott)
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
237
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
238
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
239 USE OF COMMON FUNCTIONS *style-functions*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
240
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
241 Some functions that are common to use, have a special Vim version. Always
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
242 consider using the Vim version, because they were introduced with a reason.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
243
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
244 NORMAL NAME VIM NAME DIFFERENCE OF VIM VERSION
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
245 free() vim_free() Checks for freeing NULL
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
246 malloc() alloc() Checks for out of memory situation
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
247 malloc() lalloc() Like alloc(), but has long argument
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
248 strcpy() STRCPY() Includes cast to (char *), for char_u * args
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
249 strchr() vim_strchr() Accepts special characters
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
250 strrchr() vim_strrchr() Accepts special characters
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
251 isspace() vim_isspace() Can handle characters > 128
1240
5bed56fce2b5 updated for version 7.1
vimboss
parents: 1197
diff changeset
252 iswhite() vim_iswhite() Only TRUE for tab and space
711
1babf94e0b24 updated for version 7.0214
vimboss
parents: 625
diff changeset
253 memcpy() mch_memmove() Handles overlapped copies
1babf94e0b24 updated for version 7.0214
vimboss
parents: 625
diff changeset
254 bcopy() mch_memmove() Handles overlapped copies
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
255 memset() vim_memset() Uniform for all systems
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
256
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
257
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
258 NAMES *style-names*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
259
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
260 Function names can not be more than 31 characters long (because of VMS).
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
261
7707
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
262 Don't use "delete" or "this" as a variable name, C++ doesn't like it.
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
263
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
264 Because of the requirement that Vim runs on as many systems as possible, we
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
265 need to avoid using names that are already defined by the system. This is a
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
266 list of names that are known to cause trouble. The name is given as a regexp
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
267 pattern.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
268
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
269 is.*() POSIX, ctype.h
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
270 to.*() POSIX, ctype.h
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
271
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
272 d_.* POSIX, dirent.h
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
273 l_.* POSIX, fcntl.h
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
274 gr_.* POSIX, grp.h
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
275 pw_.* POSIX, pwd.h
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
276 sa_.* POSIX, signal.h
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
277 mem.* POSIX, string.h
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
278 str.* POSIX, string.h
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
279 wcs.* POSIX, string.h
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
280 st_.* POSIX, stat.h
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
281 tms_.* POSIX, times.h
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
282 tm_.* POSIX, time.h
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
283 c_.* POSIX, termios.h
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
284 MAX.* POSIX, limits.h
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
285 __.* POSIX, system
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
286 _[A-Z].* POSIX, system
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
287 E[A-Z0-9]* POSIX, errno.h
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
288
1121
e63691e7c504 updated for version 7.1a
vimboss
parents: 874
diff changeset
289 .*_t POSIX, for typedefs. Use .*_T instead.
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
290
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
291 wait don't use as argument to a function, conflicts with types.h
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
292 index shadows global declaration
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
293 time shadows global declaration
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
294 new C++ reserved keyword
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
295
3281
af1e8a1714c2 Update runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2577
diff changeset
296 clear Mac curses.h
af1e8a1714c2 Update runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2577
diff changeset
297 echo Mac curses.h
af1e8a1714c2 Update runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2577
diff changeset
298 instr Mac curses.h
af1e8a1714c2 Update runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2577
diff changeset
299 meta Mac curses.h
af1e8a1714c2 Update runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2577
diff changeset
300 newwin Mac curses.h
af1e8a1714c2 Update runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2577
diff changeset
301 nl Mac curses.h
af1e8a1714c2 Update runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2577
diff changeset
302 overwrite Mac curses.h
af1e8a1714c2 Update runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2577
diff changeset
303 refresh Mac curses.h
af1e8a1714c2 Update runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2577
diff changeset
304 scroll Mac curses.h
af1e8a1714c2 Update runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2577
diff changeset
305 typeahead Mac curses.h
af1e8a1714c2 Update runtime files.
Bram Moolenaar <bram@vim.org>
parents: 2577
diff changeset
306
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
307 basename() GNU string function
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
308 dirname() GNU string function
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
309 get_env_value() Linux system function
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
310
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
311
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
312 VARIOUS *style-various*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
313
502
52e76e2b5b65 updated for version 7.0140
vimboss
parents: 481
diff changeset
314 Typedef'ed names should end in "_T": >
52e76e2b5b65 updated for version 7.0140
vimboss
parents: 481
diff changeset
315 typedef int some_T;
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
316 Define'ed names should be uppercase: >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
317 #define SOME_THING
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
318 Features always start with "FEAT_": >
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
319 #define FEAT_FOO
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
320
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
321 Don't use '\"', some compilers can't handle it. '"' works fine.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
322
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
323 Don't use:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
324 #if HAVE_SOME
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
325 Some compilers can't handle that and complain that "HAVE_SOME" is not defined.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
326 Use
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
327 #ifdef HAVE_SOME
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
328 or
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
329 #if defined(HAVE_SOME)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
330
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
331
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
332 STYLE *style-examples*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
333
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
334 General rule: One statement per line.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
335
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
336 Wrong: if (cond) a = 1;
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
337
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
338 OK: if (cond)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
339 a = 1;
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
340
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
341 Wrong: while (cond);
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
342
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
343 OK: while (cond)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
344 ;
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
345
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
346 Wrong: do a = 1; while (cond);
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
347
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
348 OK: do
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
349 a = 1;
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
350 while (cond);
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
351
7707
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
352 Wrong: if (cond) {
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
353 cmd;
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
354 cmd;
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
355 } else {
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
356 cmd;
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
357 cmd;
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
358 }
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
359
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
360 OK: if (cond)
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
361 {
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
362 cmd;
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
363 cmd;
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
364 }
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
365 else
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
366 {
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
367 cmd;
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
368 cmd;
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
369 }
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
370
15878
314694a2e74a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14421
diff changeset
371 When a block has one line the braces can be left out. When an if/else has
314694a2e74a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14421
diff changeset
372 braces on one block, it usually looks better when the other block also has
314694a2e74a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14421
diff changeset
373 braces:
314694a2e74a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14421
diff changeset
374 OK: if (cond)
314694a2e74a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14421
diff changeset
375 cmd;
314694a2e74a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14421
diff changeset
376 else
314694a2e74a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14421
diff changeset
377 cmd;
314694a2e74a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14421
diff changeset
378
314694a2e74a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14421
diff changeset
379 OK: if (cond)
314694a2e74a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14421
diff changeset
380 {
314694a2e74a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14421
diff changeset
381 cmd;
314694a2e74a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14421
diff changeset
382 }
314694a2e74a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14421
diff changeset
383 else
314694a2e74a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14421
diff changeset
384 {
314694a2e74a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14421
diff changeset
385 cmd;
314694a2e74a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14421
diff changeset
386 cmd;
314694a2e74a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14421
diff changeset
387 }
314694a2e74a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14421
diff changeset
388
7876
93f747af7b58 commit https://github.com/vim/vim/commit/5e9b2fa9bb0e6061cf18457c173cd141a5dc9c92
Christian Brabandt <cb@256bit.org>
parents: 7707
diff changeset
389 Use ANSI (new style) function declarations with the return type on a separate
93f747af7b58 commit https://github.com/vim/vim/commit/5e9b2fa9bb0e6061cf18457c173cd141a5dc9c92
Christian Brabandt <cb@256bit.org>
parents: 7707
diff changeset
390 indented line.
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
391
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
392 Wrong: int function_name(int arg1, int arg2)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
393
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
394 OK: /*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
395 * Explanation of what this function is used for.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
396 *
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
397 * Return value explanation.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
398 */
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
399 int
7707
41768bcebc9b commit https://github.com/vim/vim/commit/13d5aeef56e3140a8eb8f40c7062aa1c5700f76e
Christian Brabandt <cb@256bit.org>
parents: 5763
diff changeset
400 function_name(
15878
314694a2e74a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14421
diff changeset
401 int arg1, // short comment about arg1
314694a2e74a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14421
diff changeset
402 int arg2) // short comment about arg2
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
403 {
15878
314694a2e74a Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 14421
diff changeset
404 int local; // comment about local
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
405
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
406 local = arg1 * arg2;
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
407
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
408
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
409
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
410 SPACES AND PUNCTUATION *style-spaces*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
411
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
412 No space between a function name and the bracket:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
413
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
414 Wrong: func (arg);
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
415 OK: func(arg);
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
416
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
417 Do use a space after if, while, switch, etc.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
418
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
419 Wrong: if(arg) for(;;)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
420 OK: if (arg) for (;;)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
421
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
422 Use a space after a comma and semicolon:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
423
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
424 Wrong: func(arg1,arg2); for (i = 0;i < 2;++i)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
425 OK: func(arg1, arg2); for (i = 0; i < 2; ++i)
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
426
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
427 Use a space before and after '=', '+', '/', etc.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
428
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
429 Wrong: var=a*5;
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
430 OK: var = a * 5;
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
431
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
432 In general: Use empty lines to group lines of code together. Put a comment
2033
de5a43c5eedc Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents: 1702
diff changeset
433 just above the group of lines. This makes it easier to quickly see what is
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
434 being done.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
435
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
436 OK: /* Prepare for building the table. */
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
437 get_first_item();
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
438 table_idx = 0;
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
439
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
440 /* Build the table */
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
441 while (has_item())
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
442 table[table_idx++] = next_item();
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
443
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
444 /* Finish up. */
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
445 cleanup_items();
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
446 generate_hash(table);
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
447
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
448 ==============================================================================
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
449 3. Design decisions *design-decisions*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
450
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
451 Folding
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
452
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
453 Several forms of folding should be possible for the same buffer. For example,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
454 have one window that shows the text with function bodies folded, another
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
455 window that shows a function body.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
456
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
457 Folding is a way to display the text. It should not change the text itself.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
458 Therefore the folding has been implemented as a filter between the text stored
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
459 in a buffer (buffer lines) and the text displayed in a window (logical lines).
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
460
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
461
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
462 Naming the window
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
463
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
464 The word "window" is commonly used for several things: A window on the screen,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
465 the xterm window, a window inside Vim to view a buffer.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
466 To avoid confusion, other items that are sometimes called window have been
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
467 given another name. Here is an overview of the related items:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
468
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
469 screen The whole display. For the GUI it's something like 1024x768
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
470 pixels. The Vim shell can use the whole screen or part of it.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
471 shell The Vim application. This can cover the whole screen (e.g.,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
472 when running in a console) or part of it (xterm or GUI).
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
473 window View on a buffer. There can be several windows in Vim,
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
474 together with the command line, menubar, toolbar, etc. they
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
475 fit in the shell.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
476
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
477
236
4707450c2b33 updated for version 7.0066
vimboss
parents: 7
diff changeset
478 Spell checking *develop-spell*
4707450c2b33 updated for version 7.0066
vimboss
parents: 7
diff changeset
479
4707450c2b33 updated for version 7.0066
vimboss
parents: 7
diff changeset
480 When spell checking was going to be added to Vim a survey was done over the
4707450c2b33 updated for version 7.0066
vimboss
parents: 7
diff changeset
481 available spell checking libraries and programs. Unfortunately, the result
4707450c2b33 updated for version 7.0066
vimboss
parents: 7
diff changeset
482 was that none of them provided sufficient capabilities to be used as the spell
4707450c2b33 updated for version 7.0066
vimboss
parents: 7
diff changeset
483 checking engine in Vim, for various reasons:
4707450c2b33 updated for version 7.0066
vimboss
parents: 7
diff changeset
484
21991
bbca88cd13d5 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 21676
diff changeset
485 - Missing support for multibyte encodings. At least UTF-8 must be supported,
236
4707450c2b33 updated for version 7.0066
vimboss
parents: 7
diff changeset
486 so that more than one language can be used in the same file.
323
03b3684919e3 updated for version 7.0084
vimboss
parents: 300
diff changeset
487 Doing on-the-fly conversion is not always possible (would require iconv
03b3684919e3 updated for version 7.0084
vimboss
parents: 300
diff changeset
488 support).
236
4707450c2b33 updated for version 7.0066
vimboss
parents: 7
diff changeset
489 - For the programs and libraries: Using them as-is would require installing
323
03b3684919e3 updated for version 7.0084
vimboss
parents: 300
diff changeset
490 them separately from Vim. That's mostly not impossible, but a drawback.
236
4707450c2b33 updated for version 7.0066
vimboss
parents: 7
diff changeset
491 - Performance: A few tests showed that it's possible to check spelling on the
4707450c2b33 updated for version 7.0066
vimboss
parents: 7
diff changeset
492 fly (while redrawing), just like syntax highlighting. But the mechanisms
625
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
493 used by other code are much slower. Myspell uses a hashtable, for example.
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
494 The affix compression that most spell checkers use makes it slower too.
300
86cd0a77d2ae updated for version 7.0079
vimboss
parents: 236
diff changeset
495 - For using an external program like aspell a communication mechanism would
86cd0a77d2ae updated for version 7.0079
vimboss
parents: 236
diff changeset
496 have to be setup. That's complicated to do in a portable way (Unix-only
86cd0a77d2ae updated for version 7.0079
vimboss
parents: 236
diff changeset
497 would be relatively simple, but that's not good enough). And performance
86cd0a77d2ae updated for version 7.0079
vimboss
parents: 236
diff changeset
498 will become a problem (lots of process switching involved).
236
4707450c2b33 updated for version 7.0066
vimboss
parents: 7
diff changeset
499 - Missing support for words with non-word characters, such as "Etten-Leur" and
4707450c2b33 updated for version 7.0066
vimboss
parents: 7
diff changeset
500 "et al.", would require marking the pieces of them OK, lowering the
4707450c2b33 updated for version 7.0066
vimboss
parents: 7
diff changeset
501 reliability.
4707450c2b33 updated for version 7.0066
vimboss
parents: 7
diff changeset
502 - Missing support for regions or dialects. Makes it difficult to accept
4707450c2b33 updated for version 7.0066
vimboss
parents: 7
diff changeset
503 all English words and highlight non-Canadian words differently.
4707450c2b33 updated for version 7.0066
vimboss
parents: 7
diff changeset
504 - Missing support for rare words. Many words are correct but hardly ever used
4707450c2b33 updated for version 7.0066
vimboss
parents: 7
diff changeset
505 and could be a misspelled often-used word.
323
03b3684919e3 updated for version 7.0084
vimboss
parents: 300
diff changeset
506 - For making suggestions the speed is less important and requiring to install
03b3684919e3 updated for version 7.0084
vimboss
parents: 300
diff changeset
507 another program or library would be acceptable. But the word lists probably
03b3684919e3 updated for version 7.0084
vimboss
parents: 300
diff changeset
508 differ, the suggestions may be wrong words.
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
509
625
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
510
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
511 Spelling suggestions *develop-spell-suggestions*
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
512
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
513 For making suggestions there are two basic mechanisms:
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
514 1. Try changing the bad word a little bit and check for a match with a good
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
515 word. Or go through the list of good words, change them a little bit and
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
516 check for a match with the bad word. The changes are deleting a character,
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
517 inserting a character, swapping two characters, etc.
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
518 2. Perform soundfolding on both the bad word and the good words and then find
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
519 matches, possibly with a few changes like with the first mechanism.
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
520
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
521 The first is good for finding typing mistakes. After experimenting with
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
522 hashtables and looking at solutions from other spell checkers the conclusion
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
523 was that a trie (a kind of tree structure) is ideal for this. Both for
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
524 reducing memory use and being able to try sensible changes. For example, when
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
525 inserting a character only characters that lead to good words need to be
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
526 tried. Other mechanisms (with hashtables) need to try all possible letters at
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
527 every position in the word. Also, a hashtable has the requirement that word
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
528 boundaries are identified separately, while a trie does not require this.
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
529 That makes the mechanism a lot simpler.
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
530
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
531 Soundfolding is useful when someone knows how the words sounds but doesn't
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
532 know how it is spelled. For example, the word "dictionary" might be written
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
533 as "daktonerie". The number of changes that the first method would need to
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
534 try is very big, it's hard to find the good word that way. After soundfolding
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
535 the words become "tktnr" and "tkxnry", these differ by only two letters.
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
536
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
537 To find words by their soundfolded equivalent (soundalike word) we need a list
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
538 of all soundfolded words. A few experiments have been done to find out what
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
539 the best method is. Alternatives:
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
540 1. Do the sound folding on the fly when looking for suggestions. This means
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
541 walking through the trie of good words, soundfolding each word and
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
542 checking how different it is from the bad word. This is very efficient for
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
543 memory use, but takes a long time. On a fast PC it takes a couple of
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
544 seconds for English, which can be acceptable for interactive use. But for
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
545 some languages it takes more than ten seconds (e.g., German, Catalan),
17667
95c23e180022 Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 16606
diff changeset
546 which is unacceptably slow. For batch processing (automatic corrections)
1197
b7ad1c609161 updated for version 7.1b
vimboss
parents: 1121
diff changeset
547 it's too slow for all languages.
625
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
548 2. Use a trie for the soundfolded words, so that searching can be done just
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
549 like how it works without soundfolding. This requires remembering a list
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
550 of good words for each soundfolded word. This makes finding matches very
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
551 fast but requires quite a lot of memory, in the order of 1 to 10 Mbyte.
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
552 For some languages more than the original word list.
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
553 3. Like the second alternative, but reduce the amount of memory by using affix
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
554 compression and store only the soundfolded basic word. This is what Aspell
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
555 does. Disadvantage is that affixes need to be stripped from the bad word
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
556 before soundfolding it, which means that mistakes at the start and/or end
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
557 of the word will cause the mechanism to fail. Also, this becomes slow when
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
558 the bad word is quite different from the good word.
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
559
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
560 The choice made is to use the second mechanism and use a separate file. This
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
561 way a user with sufficient memory can get very good suggestions while a user
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
562 who is short of memory or just wants the spell checking and no suggestions
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
563 doesn't use so much memory.
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
564
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
565
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
566 Word frequency
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
567
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
568 For sorting suggestions it helps to know which words are common. In theory we
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
569 could store a word frequency with the word in the dictionary. However, this
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
570 requires storing a count per word. That degrades word tree compression a lot.
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
571 And maintaining the word frequency for all languages will be a heavy task.
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
572 Also, it would be nice to prefer words that are already in the text. This way
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
573 the words that appear in the specific text are preferred for suggestions.
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
574
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
575 What has been implemented is to count words that have been seen during
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
576 displaying. A hashtable is used to quickly find the word count. The count is
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
577 initialized from words listed in COMMON items in the affix file, so that it
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
578 also works when starting a new file.
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
579
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
580 This isn't ideal, because the longer Vim is running the higher the counts
1197
b7ad1c609161 updated for version 7.1b
vimboss
parents: 1121
diff changeset
581 become. But in practice it is a noticeable improvement over not using the word
625
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
582 count.
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
583
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
584 ==============================================================================
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
585 4. Assumptions *design-assumptions*
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
586
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
587 Size of variables:
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
588 char 8 bit signed
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
589 char_u 8 bit unsigned
625
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
590 int 32 or 64 bit signed (16 might be possible with limited features)
81fe2ccc1207 updated for version 7.0179
vimboss
parents: 502
diff changeset
591 unsigned 32 or 64 bit unsigned (16 as with ints)
7
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
592 long 32 or 64 bit signed, can hold a pointer
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
593
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
594 Note that some compilers cannot handle long lines or strings. The C89
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
595 standard specifies a limit of 509 characters.
3fc0f57ecb91 updated for version 7.0001
vimboss
parents:
diff changeset
596
14421
2f7e67dd088c Update runtime files.
Christian Brabandt <cb@256bit.org>
parents: 13963
diff changeset
597 vim:tw=78:ts=8:noet:ft=help:norl: