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