Mercurial > vim
annotate runtime/doc/usr_30.txt @ 32936:c517845bd10e v9.0.1776
patch 9.0.1776: No support for stable Python 3 ABI
Commit: https://github.com/vim/vim/commit/c13b3d1350b60b94fe87f0761ea31c0e7fb6ebf3
Author: Yee Cheng Chin <ychin.git@gmail.com>
Date: Sun Aug 20 21:18:38 2023 +0200
patch 9.0.1776: No support for stable Python 3 ABI
Problem: No support for stable Python 3 ABI
Solution: Support Python 3 stable ABI
Commits:
1) Support Python 3 stable ABI to allow mixed version interoperatbility
Vim currently supports embedding Python for use with plugins, and the
"dynamic" linking option allows the user to specify a locally installed
version of Python by setting `pythonthreedll`. However, one caveat is
that the Python 3 libs are not binary compatible across minor versions,
and mixing versions can potentially be dangerous (e.g. let's say Vim was
linked against the Python 3.10 SDK, but the user sets `pythonthreedll`
to a 3.11 lib). Usually, nothing bad happens, but in theory this could
lead to crashes, memory corruption, and other unpredictable behaviors.
It's also difficult for the user to tell something is wrong because Vim
has no way of reporting what Python 3 version Vim was linked with.
For Vim installed via a package manager, this usually isn't an issue
because all the dependencies would already be figured out. For prebuilt
Vim binaries like MacVim (my motivation for working on this), AppImage,
and Win32 installer this could potentially be an issue as usually a
single binary is distributed. This is more tricky when a new Python
version is released, as there's a chicken-and-egg issue with deciding
what Python version to build against and hard to keep in sync when a new
Python version just drops and we have a mix of users of different Python
versions, and a user just blindly upgrading to a new Python could lead to
bad interactions with Vim.
Python 3 does have a solution for this problem: stable ABI / limited API
(see https://docs.python.org/3/c-api/stable.html). The C SDK limits the
API to a set of functions that are promised to be stable across
versions. This pull request adds an ifdef config that allows us to turn
it on when building Vim. Vim binaries built with this option should be
safe to freely link with any Python 3 libraies without having the
constraint of having to use the same minor version.
Note: Python 2 has no such concept and this doesn't change how Python 2
integration works (not that there is going to be a new version of Python
2 that would cause compatibility issues in the future anyway).
---
Technical details:
======
The stable ABI can be accessed when we compile with the Python 3 limited
API (by defining `Py_LIMITED_API`). The Python 3 code (in `if_python3.c`
and `if_py_both.h`) would now handle this and switch to limited API
mode. Without it set, Vim will still use the full API as before so this
is an opt-in change.
The main difference is that `PyType_Object` is now an opaque struct that
we can't directly create "static types" out of, and we have to create
type objects as "heap types" instead. This is because the struct is not
stable and changes from version to version (e.g. 3.8 added a
`tp_vectorcall` field to it). I had to change all the types to be
allocated on the heap instead with just a pointer to them.
Other functions are also simply missing in limited API, or they are
introduced too late (e.g. `PyUnicode_AsUTF8AndSize` in 3.10) to it that
we need some other ways to do the same thing, so I had to abstract a few
things into macros, and sometimes re-implement functions like
`PyObject_NEW`.
One caveat is that in limited API, `OutputType` (used for replacing
`sys.stdout`) no longer inherits from `PyStdPrinter_Type` which I don't
think has any real issue other than minor differences in how they
convert to a string and missing a couple functions like `mode()` and
`fileno()`.
Also fixed an existing bug where `tp_basicsize` was set incorrectly for
`BufferObject`, `TabListObject, `WinListObject`.
Technically, there could be a small performance drop, there is a little
more indirection with accessing type objects, and some APIs like
`PyUnicode_AsUTF8AndSize` are missing, but in practice I didn't see any
difference, and any well-written Python plugin should try to avoid
excessing callbacks to the `vim` module in Python anyway.
I only tested limited API mode down to Python 3.7, which seemes to
compile and work fine. I haven't tried earlier Python versions.
2) Fix PyIter_Check on older Python vers / type##Ptr unused warning
For PyIter_Check, older versions exposed them as either macros (used in
full API), or a function (for use in limited API). A previous change
exposed PyIter_Check to the dynamic build because Python just moved it
to function-only in 3.10 anyway. Because of that, just make sure we
always grab the function in dynamic builds in earlier versions since
that's what Python eventually did anyway.
3) Move Py_LIMITED_API define to configure script
Can now use --with-python-stable-abi flag to customize what stable ABI
version to target. Can also use an env var to do so as well.
4) Show +python/dyn-stable in :version, and allow has() feature query
Not sure if the "/dyn-stable" suffix would break things, or whether we
should do it another way. Or just don't show it in version and rely on
has() feature checking.
5) Documentation first draft. Still need to implement v:python3_version
6) Fix PyIter_Check build breaks when compiling against Python 3.8
7) Add CI coverage stable ABI on Linux/Windows / make configurable on Windows
This adds configurable options for Windows make files (both MinGW and
MSVC). CI will also now exercise both traditional full API and stable
ABI for Linux and Windows in the matrix for coverage.
Also added a "dynamic" option to Linux matrix as a drive-by change to
make other scripting languages like Ruby / Perl testable under both
static and dynamic builds.
8) Fix inaccuracy in Windows docs
Python's own docs are confusing but you don't actually want to use
`python3.dll` for the dynamic linkage.
9) Add generated autoconf file
10) Add v:python3_version support
This variable indicates the version of Python3 that Vim was built
against (PY_VERSION_HEX), and will be useful to check whether the Python
library you are loading in dynamically actually fits it. When built with
stable ABI, it will be the limited ABI version instead
(`Py_LIMITED_API`), which indicates the minimum version of Python 3 the
user should have, rather than the exact match. When stable ABI is used,
we won't be exposing PY_VERSION_HEX in this var because it just doesn't
seem necessary to do so (the whole point of stable ABI is the promise
that it will work across versions), and I don't want to confuse the user
with too many variables.
Also, cleaned up some documentation, and added help tags.
11) Fix Python 3.7 compat issues
Fix a couple issues when using limited API < 3.8
- Crash on exit: In Python 3.7, if a heap-allocated type is destroyed
before all instances are, it would cause a crash later. This happens
when we destroyed `OptionsType` before calling `Py_Finalize` when
using the limited API. To make it worse, later versions changed the
semantics and now each instance has a strong reference to its own type
and the recommendation has changed to have each instance de-ref its
own type and have its type in GC traversal. To avoid dealing with
these cross-version variations, we just don't free the heap type. They
are static types in non-limited-API anyway and are designed to last
through the entirety of the app, and we also don't restart the Python
runtime and therefore do not need it to have absolutely 0 leaks.
See:
- https://docs.python.org/3/whatsnew/3.8.html#changes-in-the-c-api
- https://docs.python.org/3/whatsnew/3.9.html#changes-in-the-c-api
- PyIter_Check: This function is not provided in limited APIs older than
3.8. Previously I was trying to mock it out using manual
PyType_GetSlot() but it was brittle and also does not actually work
properly for static types (it will generate a Python error). Just
return false. It does mean using limited API < 3.8 is not recommended
as you lose the functionality to handle iterators, but from playing
with plugins I couldn't find it to be an issue.
- Fix loading of PyIter_Check so it will be done when limited API < 3.8.
Otherwise loading a 3.7 Python lib will fail even if limited API was
specified to use it.
12) Make sure to only load `PyUnicode_AsUTF8AndSize` in needed in limited API
We don't use this function unless limited API >= 3.10, but we were
loading it regardless. Usually it's ok in Unix-like systems where Python
just has a single lib that we load from, but in Windows where there is a
separate python3.dll this would not work as the symbol would not have
been exposed in this more limited DLL file. This makes it much clearer
under what condition is this function needed.
closes: #12032
Signed-off-by: Christian Brabandt <cb@256bit.org>
Co-authored-by: Yee Cheng Chin <ychin.git@gmail.com>
| author | Christian Brabandt <cb@256bit.org> |
|---|---|
| date | Sun, 20 Aug 2023 21:30:04 +0200 |
| parents | f8116058ca76 |
| children | 4635e43f2c6f |
| rev | line source |
|---|---|
| 29314 | 1 *usr_30.txt* For Vim version 9.0. Last change: 2007 Nov 10 |
| 7 | 2 |
| 3 VIM USER MANUAL - by Bram Moolenaar | |
| 4 | |
| 5 Editing programs | |
| 6 | |
| 7 | |
| 8 Vim has various commands that aid in writing computer programs. Compile a | |
| 9 program and directly jump to reported errors. Automatically set the indent | |
| 10 for many languages and format comments. | |
| 11 | |
| 12 |30.1| Compiling | |
| 13 |30.2| Indenting C files | |
| 14 |30.3| Automatic indenting | |
| 15 |30.4| Other indenting | |
| 16 |30.5| Tabs and spaces | |
| 17 |30.6| Formatting comments | |
| 18 | |
| 19 Next chapter: |usr_31.txt| Exploiting the GUI | |
| 20 Previous chapter: |usr_29.txt| Moving through programs | |
| 21 Table of contents: |usr_toc.txt| | |
| 22 | |
| 23 ============================================================================== | |
| 24 *30.1* Compiling | |
| 25 | |
| 26 Vim has a set of so called "quickfix" commands. They enable you to compile a | |
| 27 program from within Vim and then go through the errors generated and fix them | |
| 28 (hopefully). You can then recompile and fix any new errors that are found | |
| 29 until finally your program compiles without any error. | |
| 30 | |
| 31 The following command runs the program "make" (supplying it with any argument | |
| 32 you give) and captures the results: > | |
| 33 | |
| 34 :make {arguments} | |
| 35 | |
| 36 If errors were generated, they are captured and the editor positions you where | |
| 37 the first error occurred. | |
| 237 | 38 Take a look at an example ":make" session. (Typical :make sessions generate |
| 7 | 39 far more errors and fewer stupid ones.) After typing ":make" the screen looks |
| 40 like this: | |
| 41 | |
| 42 :!make | &tee /tmp/vim215953.err ~ | |
| 43 gcc -g -Wall -o prog main.c sub.c ~ | |
| 44 main.c: In function 'main': ~ | |
| 45 main.c:6: too many arguments to function 'do_sub' ~ | |
| 46 main.c: At top level: ~ | |
| 47 main.c:10: parse error before '}' ~ | |
| 48 make: *** [prog] Error 1 ~ | |
| 49 | |
| 50 2 returned ~ | |
| 51 "main.c" 11L, 111C ~ | |
| 52 (3 of 6): too many arguments to function 'do_sub' ~ | |
| 1125 | 53 Press ENTER or type command to continue ~ |
| 7 | 54 |
| 55 From this you can see that you have errors in the file "main.c". When you | |
| 56 press <Enter>, Vim displays the file "main.c", with the cursor positioned on | |
| 57 line 6, the first line with an error. You did not need to specify the file or | |
| 58 the line number, Vim knew where to go by looking in the error messages. | |
| 59 | |
| 60 +---------------------------------------------------+ | |
| 61 |int main() | | |
| 62 |{ | | |
| 63 | int i=3; | | |
| 64 cursor -> | do_sub("foo"); | | |
| 65 | ++i; | | |
| 66 | return (0); | | |
| 67 |} | | |
| 68 |} | | |
| 69 | ~ | | |
| 70 |(3 of 12): too many arguments to function 'do_sub' | | |
| 71 +---------------------------------------------------+ | |
| 72 | |
| 73 The following command goes to where the next error occurs: > | |
| 74 | |
| 75 :cnext | |
| 76 | |
| 77 Vim jumps to line 10, the last line in the file, where there is an extra '}'. | |
| 78 When there is not enough room, Vim will shorten the error message. To see | |
| 79 the whole message use: > | |
| 80 | |
| 81 :cc | |
| 82 | |
| 83 You can get an overview of all the error messages with the ":clist" command. | |
| 84 The output looks like this: > | |
| 85 | |
| 86 :clist | |
| 87 < 3 main.c: 6:too many arguments to function 'do_sub' ~ | |
| 88 5 main.c: 10:parse error before '}' ~ | |
| 89 | |
| 90 Only the lines where Vim recognized a file name and line number are listed | |
| 91 here. It assumes those are the interesting lines and the rest is just boring | |
| 92 messages. However, sometimes unrecognized lines do contain something you want | |
| 93 to see. Output from the linker, for example, about an undefined function. | |
| 94 To see all the messages add a "!" to the command: > | |
| 95 | |
| 96 :clist! | |
| 97 < 1 gcc -g -Wall -o prog main.c sub.c ~ | |
| 98 2 main.c: In function 'main': ~ | |
| 99 3 main.c:6: too many arguments to function 'do_sub' ~ | |
| 100 4 main.c: At top level: ~ | |
| 101 5 main.c:10: parse error before '}' ~ | |
| 102 6 make: *** [prog] Error 1 ~ | |
| 103 | |
| 104 Vim will highlight the current error. To go back to the previous error, use: | |
| 105 > | |
| 106 :cprevious | |
| 107 | |
| 108 Other commands to move around in the error list: | |
| 109 | |
| 110 :cfirst to first error | |
| 111 :clast to last error | |
| 112 :cc 3 to error nr 3 | |
| 113 | |
| 114 | |
| 115 USING ANOTHER COMPILER | |
| 116 | |
| 117 The name of the program to run when the ":make" command is executed is defined | |
| 118 by the 'makeprg' option. Usually this is set to "make", but Visual C++ users | |
| 119 should set this to "nmake" by executing the following command: > | |
| 120 | |
| 121 :set makeprg=nmake | |
| 122 | |
| 123 You can also include arguments in this option. Special characters need to | |
| 124 be escaped with a backslash. Example: > | |
| 125 | |
| 126 :set makeprg=nmake\ -f\ project.mak | |
| 127 | |
| 128 You can include special Vim keywords in the command specification. The % | |
| 129 character expands to the name of the current file. So if you execute the | |
| 130 command: > | |
| 5690 | 131 :set makeprg=make\ %:S |
| 7 | 132 |
| 133 When you are editing main.c, then ":make" executes the following command: > | |
| 134 | |
| 135 make main.c | |
| 136 | |
| 137 This is not too useful, so you will refine the command a little and use the :r | |
| 138 (root) modifier: > | |
| 139 | |
| 5690 | 140 :set makeprg=make\ %:r:S.o |
| 7 | 141 |
| 142 Now the command executed is as follows: > | |
| 143 | |
| 144 make main.o | |
| 145 | |
| 146 More about these modifiers here: |filename-modifiers|. | |
| 147 | |
| 148 | |
| 149 OLD ERROR LISTS | |
| 150 | |
| 1125 | 151 Suppose you ":make" a program. There is a warning message in one file and an |
| 7 | 152 error message in another. You fix the error and use ":make" again to check if |
| 153 it was really fixed. Now you want to look at the warning message. It doesn't | |
| 154 show up in the last error list, since the file with the warning wasn't | |
| 155 compiled again. You can go back to the previous error list with: > | |
| 156 | |
| 157 :colder | |
| 158 | |
| 159 Then use ":clist" and ":cc {nr}" to jump to the place with the warning. | |
| 160 To go forward to the next error list: > | |
| 161 | |
| 162 :cnewer | |
| 163 | |
| 164 Vim remembers ten error lists. | |
| 165 | |
| 166 | |
| 167 SWITCHING COMPILERS | |
| 168 | |
| 169 You have to tell Vim what format the error messages are that your compiler | |
| 170 produces. This is done with the 'errorformat' option. The syntax of this | |
| 171 option is quite complicated and it can be made to fit almost any compiler. | |
| 172 You can find the explanation here: |errorformat|. | |
| 173 | |
| 174 You might be using various different compilers. Setting the 'makeprg' option, | |
| 175 and especially the 'errorformat' each time is not easy. Vim offers a simple | |
| 176 method for this. For example, to switch to using the Microsoft Visual C++ | |
| 177 compiler: > | |
| 178 | |
| 179 :compiler msvc | |
| 180 | |
| 181 This will find the Vim script for the "msvc" compiler and set the appropriate | |
| 182 options. | |
| 183 You can write your own compiler files. See |write-compiler-plugin|. | |
| 184 | |
| 185 | |
| 186 OUTPUT REDIRECTION | |
| 187 | |
| 188 The ":make" command redirects the output of the executed program to an error | |
| 189 file. How this works depends on various things, such as the 'shell'. If your | |
| 190 ":make" command doesn't capture the output, check the 'makeef' and | |
| 191 'shellpipe' options. The 'shellquote' and 'shellxquote' options might also | |
| 192 matter. | |
| 193 | |
| 194 In case you can't get ":make" to redirect the file for you, an alternative is | |
| 195 to compile the program in another window and redirect the output into a file. | |
| 196 Then have Vim read this file with: > | |
| 197 | |
| 198 :cfile {filename} | |
| 199 | |
| 200 Jumping to errors will work like with the ":make" command. | |
| 201 | |
| 202 ============================================================================== | |
| 1624 | 203 *30.2* Indenting C style text |
| 7 | 204 |
| 205 A program is much easier to understand when the lines have been properly | |
| 1624 | 206 indented. Vim offers various ways to make this less work. For C or C style |
| 207 programs like Java or C++, set the 'cindent' option. Vim knows a lot about C | |
| 208 programs and will try very hard to automatically set the indent for you. Set | |
| 209 the 'shiftwidth' option to the amount of spaces you want for a deeper level. | |
| 210 Four spaces will work fine. One ":set" command will do it: > | |
| 7 | 211 |
| 212 :set cindent shiftwidth=4 | |
| 213 | |
| 214 With this option enabled, when you type something such as "if (x)", the next | |
| 215 line will automatically be indented an additional level. | |
| 216 | |
| 217 if (flag) | |
| 218 Automatic indent ---> do_the_work(); | |
| 219 Automatic unindent <-- if (other_flag) { | |
| 220 Automatic indent ---> do_file(); | |
| 221 keep indent do_some_more(); | |
| 222 Automatic unindent <-- } | |
| 223 | |
| 224 When you type something in curly braces ({}), the text will be indented at the | |
| 225 start and unindented at the end. The unindenting will happen after typing the | |
| 226 '}', since Vim can't guess what you are going to type. | |
| 227 | |
| 228 One side effect of automatic indentation is that it helps you catch errors in | |
| 229 your code early. When you type a } to finish a function, only to find that | |
| 230 the automatic indentation gives it more indent than what you expected, there | |
| 231 is probably a } missing. Use the "%" command to find out which { matches the | |
| 232 } you typed. | |
| 233 A missing ) and ; also cause extra indent. Thus if you get more white | |
| 234 space than you would expect, check the preceding lines. | |
| 235 | |
| 236 When you have code that is badly formatted, or you inserted and deleted lines, | |
| 237 you need to re-indent the lines. The "=" operator does this. The simplest | |
| 238 form is: > | |
| 239 | |
| 240 == | |
| 241 | |
| 242 This indents the current line. Like with all operators, there are three ways | |
| 243 to use it. In Visual mode "=" indents the selected lines. A useful text | |
| 244 object is "a{". This selects the current {} block. Thus, to re-indent the | |
| 1125 | 245 code block the cursor is in: > |
| 7 | 246 |
| 247 =a{ | |
| 248 | |
| 249 I you have really badly indented code, you can re-indent the whole file with: | |
| 250 > | |
| 251 gg=G | |
| 252 | |
| 253 However, don't do this in files that have been carefully indented manually. | |
| 254 The automatic indenting does a good job, but in some situations you might want | |
| 255 to overrule it. | |
| 256 | |
| 257 | |
| 258 SETTING INDENT STYLE | |
| 259 | |
| 260 Different people have different styles of indentation. By default Vim does a | |
| 261 pretty good job of indenting in a way that 90% of programmers do. There are | |
| 262 different styles, however; so if you want to, you can customize the | |
| 263 indentation style with the 'cinoptions' option. | |
| 264 By default 'cinoptions' is empty and Vim uses the default style. You can | |
| 265 add various items where you want something different. For example, to make | |
| 266 curly braces be placed like this: | |
| 267 | |
| 268 if (flag) ~ | |
| 269 { ~ | |
| 270 i = 8; ~ | |
| 271 j = 0; ~ | |
| 272 } ~ | |
| 273 | |
| 274 Use this command: > | |
| 275 | |
| 276 :set cinoptions+={2 | |
| 277 | |
| 278 There are many of these items. See |cinoptions-values|. | |
| 279 | |
| 280 ============================================================================== | |
| 281 *30.3* Automatic indenting | |
| 282 | |
| 283 You don't want to switch on the 'cindent' option manually every time you edit | |
| 284 a C file. This is how you make it work automatically: > | |
| 285 | |
| 286 :filetype indent on | |
| 287 | |
| 288 Actually, this does a lot more than switching on 'cindent' for C files. First | |
| 289 of all, it enables detecting the type of a file. That's the same as what is | |
| 290 used for syntax highlighting. | |
| 291 When the filetype is known, Vim will search for an indent file for this | |
| 292 type of file. The Vim distribution includes a number of these for various | |
| 293 programming languages. This indent file will then prepare for automatic | |
| 294 indenting specifically for this file. | |
| 295 | |
| 296 If you don't like the automatic indenting, you can switch it off again: > | |
| 297 | |
| 298 :filetype indent off | |
| 299 | |
| 300 If you don't like the indenting for one specific type of file, this is how you | |
| 301 avoid it. Create a file with just this one line: > | |
| 302 | |
| 303 :let b:did_indent = 1 | |
| 304 | |
| 305 Now you need to write this in a file with a specific name: | |
| 306 | |
| 307 {directory}/indent/{filetype}.vim | |
| 308 | |
| 309 The {filetype} is the name of the file type, such as "cpp" or "java". You can | |
| 310 see the exact name that Vim detected with this command: > | |
| 311 | |
| 312 :set filetype | |
| 313 | |
| 314 In this file the output is: | |
| 315 | |
| 316 filetype=help ~ | |
| 317 | |
| 1125 | 318 Thus you would use "help" for {filetype}. |
| 7 | 319 For the {directory} part you need to use your runtime directory. Look at |
| 320 the output of this command: > | |
| 321 | |
| 322 set runtimepath | |
| 323 | |
| 324 Now use the first item, the name before the first comma. Thus if the output | |
| 325 looks like this: | |
| 326 | |
| 327 runtimepath=~/.vim,/usr/local/share/vim/vim60/runtime,~/.vim/after ~ | |
| 328 | |
| 329 You use "~/.vim" for {directory}. Then the resulting file name is: | |
| 330 | |
| 331 ~/.vim/indent/help.vim ~ | |
| 332 | |
| 333 Instead of switching the indenting off, you could write your own indent file. | |
| 334 How to do that is explained here: |indent-expression|. | |
| 335 | |
| 336 ============================================================================== | |
| 337 *30.4* Other indenting | |
| 338 | |
| 21676 | 339 The simplest form of automatic indenting is with the 'autoindent' option. |
| 7 | 340 It uses the indent from the previous line. A bit smarter is the 'smartindent' |
| 341 option. This is useful for languages where no indent file is available. | |
| 1125 | 342 'smartindent' is not as smart as 'cindent', but smarter than 'autoindent'. |
| 7 | 343 With 'smartindent' set, an extra level of indentation is added for each { |
| 344 and removed for each }. An extra level of indentation will also be added for | |
| 345 any of the words in the 'cinwords' option. Lines that begin with # are | |
| 346 treated specially: all indentation is removed. This is done so that | |
| 347 preprocessor directives will all start in column 1. The indentation is | |
| 348 restored for the next line. | |
| 349 | |
| 350 | |
| 351 CORRECTING INDENTS | |
| 352 | |
| 353 When you are using 'autoindent' or 'smartindent' to get the indent of the | |
| 354 previous line, there will be many times when you need to add or remove one | |
| 355 'shiftwidth' worth of indent. A quick way to do this is using the CTRL-D and | |
| 356 CTRL-T commands in Insert mode. | |
| 357 For example, you are typing a shell script that is supposed to look like | |
| 358 this: | |
| 359 | |
| 360 if test -n a; then ~ | |
| 361 echo a ~ | |
| 362 echo "-------" ~ | |
| 363 fi ~ | |
| 364 | |
|
2207
b17bbfa96fa0
Add the settabvar() and gettabvar() functions.
Bram Moolenaar <bram@vim.org>
parents:
2154
diff
changeset
|
365 Start off by setting these options: > |
| 7 | 366 |
| 367 :set autoindent shiftwidth=3 | |
| 368 | |
| 369 You start by typing the first line, <Enter> and the start of the second line: | |
| 370 | |
| 371 if test -n a; then ~ | |
| 372 echo ~ | |
| 373 | |
| 374 Now you see that you need an extra indent. Type CTRL-T. The result: | |
| 375 | |
| 376 if test -n a; then ~ | |
| 377 echo ~ | |
| 378 | |
| 379 The CTRL-T command, in Insert mode, adds one 'shiftwidth' to the indent, no | |
| 380 matter where in the line you are. | |
| 381 You continue typing the second line, <Enter> and the third line. This time | |
| 382 the indent is OK. Then <Enter> and the last line. Now you have this: | |
| 383 | |
| 384 if test -n a; then ~ | |
| 385 echo a ~ | |
| 386 echo "-------" ~ | |
| 387 fi ~ | |
| 388 | |
| 389 To remove the superfluous indent in the last line press CTRL-D. This deletes | |
| 390 one 'shiftwidth' worth of indent, no matter where you are in the line. | |
| 391 When you are in Normal mode, you can use the ">>" and "<<" commands to | |
| 392 shift lines. ">" and "<" are operators, thus you have the usual three ways to | |
| 393 specify the lines you want to indent. A useful combination is: > | |
| 394 | |
| 395 >i{ | |
| 396 | |
| 397 This adds one indent to the current block of lines, inside {}. The { and } | |
| 398 lines themselves are left unmodified. ">a{" includes them. In this example | |
| 399 the cursor is on "printf": | |
| 400 | |
| 401 original text after ">i{" after ">a{" | |
| 402 | |
| 403 if (flag) if (flag) if (flag) ~ | |
| 404 { { { ~ | |
| 405 printf("yes"); printf("yes"); printf("yes"); ~ | |
| 406 flag = 0; flag = 0; flag = 0; ~ | |
| 407 } } } ~ | |
| 408 | |
| 409 ============================================================================== | |
| 410 *30.5* Tabs and spaces | |
| 411 | |
| 412 'tabstop' is set to eight by default. Although you can change it, you quickly | |
| 413 run into trouble later. Other programs won't know what tabstop value you | |
| 414 used. They probably use the default value of eight, and your text suddenly | |
| 415 looks very different. Also, most printers use a fixed tabstop value of eight. | |
| 416 Thus it's best to keep 'tabstop' alone. (If you edit a file which was written | |
| 417 with a different tabstop setting, see |25.3| for how to fix that.) | |
| 418 For indenting lines in a program, using a multiple of eight spaces makes | |
| 419 you quickly run into the right border of the window. Using a single space | |
| 420 doesn't provide enough visual difference. Many people prefer to use four | |
| 421 spaces, a good compromise. | |
| 422 Since a <Tab> is eight spaces and you want to use an indent of four spaces, | |
| 423 you can't use a <Tab> character to make your indent. There are two ways to | |
| 424 handle this: | |
| 425 | |
| 426 1. Use a mix of <Tab> and space characters. Since a <Tab> takes the place of | |
| 427 eight spaces, you have fewer characters in your file. Inserting a <Tab> | |
| 428 is quicker than eight spaces. Backspacing works faster as well. | |
| 429 | |
| 430 2. Use spaces only. This avoids the trouble with programs that use a | |
| 431 different tabstop value. | |
| 432 | |
| 433 Fortunately, Vim supports both methods quite well. | |
| 434 | |
| 435 | |
| 436 SPACES AND TABS | |
| 437 | |
| 438 If you are using a combination of tabs and spaces, you just edit normally. | |
| 439 The Vim defaults do a fine job of handling things. | |
| 440 You can make life a little easier by setting the 'softtabstop' option. | |
| 441 This option tells Vim to make the <Tab> key look and feel as if tabs were set | |
| 442 at the value of 'softtabstop', but actually use a combination of tabs and | |
| 443 spaces. | |
| 444 After you execute the following command, every time you press the <Tab> key | |
| 445 the cursor moves to the next 4-column boundary: > | |
| 446 | |
| 447 :set softtabstop=4 | |
| 448 | |
| 449 When you start in the first column and press <Tab>, you get 4 spaces inserted | |
| 450 in your text. The second time, Vim takes out the 4 spaces and puts in a <Tab> | |
| 451 (thus taking you to column 8). Thus Vim uses as many <Tab>s as possible, and | |
| 452 then fills up with spaces. | |
| 453 When backspacing it works the other way around. A <BS> will always delete | |
| 1624 | 454 the amount specified with 'softtabstop'. Then <Tab>s are used as many as |
| 7 | 455 possible and spaces to fill the gap. |
| 456 The following shows what happens pressing <Tab> a few times, and then using | |
| 457 <BS>. A "." stands for a space and "------->" for a <Tab>. | |
| 458 | |
| 459 type result ~ | |
| 460 <Tab> .... | |
| 461 <Tab><Tab> -------> | |
| 462 <Tab><Tab><Tab> ------->.... | |
| 463 <Tab><Tab><Tab><BS> -------> | |
| 464 <Tab><Tab><Tab><BS><BS> .... | |
| 465 | |
| 466 An alternative is to use the 'smarttab' option. When it's set, Vim uses | |
| 467 'shiftwidth' for a <Tab> typed in the indent of a line, and a real <Tab> when | |
| 468 typed after the first non-blank character. However, <BS> doesn't work like | |
| 469 with 'softtabstop'. | |
| 470 | |
| 471 | |
| 472 JUST SPACES | |
| 473 | |
| 474 If you want absolutely no tabs in your file, you can set the 'expandtab' | |
| 475 option: > | |
| 476 | |
| 477 :set expandtab | |
| 478 | |
| 479 When this option is set, the <Tab> key inserts a series of spaces. Thus you | |
| 480 get the same amount of white space as if a <Tab> character was inserted, but | |
| 481 there isn't a real <Tab> character in your file. | |
| 482 The backspace key will delete each space by itself. Thus after typing one | |
| 483 <Tab> you have to press the <BS> key up to eight times to undo it. If you are | |
| 484 in the indent, pressing CTRL-D will be a lot quicker. | |
| 485 | |
| 486 | |
| 487 CHANGING TABS IN SPACES (AND BACK) | |
| 488 | |
| 489 Setting 'expandtab' does not affect any existing tabs. In other words, any | |
| 490 tabs in the document remain tabs. If you want to convert tabs to spaces, use | |
| 491 the ":retab" command. Use these commands: > | |
| 492 | |
| 493 :set expandtab | |
| 494 :%retab | |
| 495 | |
| 496 Now Vim will have changed all indents to use spaces instead of tabs. However, | |
| 497 all tabs that come after a non-blank character are kept. If you want these to | |
| 498 be converted as well, add a !: > | |
| 499 | |
| 500 :%retab! | |
| 501 | |
| 502 This is a little bit dangerous, because it can also change tabs inside a | |
| 503 string. To check if these exist, you could use this: > | |
| 504 | |
| 505 /"[^"\t]*\t[^"]*" | |
| 506 | |
| 507 It's recommended not to use hard tabs inside a string. Replace them with | |
| 508 "\t" to avoid trouble. | |
| 509 | |
| 510 The other way around works just as well: > | |
| 511 | |
| 512 :set noexpandtab | |
| 513 :%retab! | |
| 514 | |
| 515 ============================================================================== | |
| 516 *30.6* Formatting comments | |
| 517 | |
| 518 One of the great things about Vim is that it understands comments. You can | |
| 519 ask Vim to format a comment and it will do the right thing. | |
| 520 Suppose, for example, that you have the following comment: | |
| 521 | |
| 522 /* ~ | |
| 523 * This is a test ~ | |
| 524 * of the text formatting. ~ | |
| 525 */ ~ | |
| 526 | |
| 527 You then ask Vim to format it by positioning the cursor at the start of the | |
| 528 comment and type: > | |
| 529 | |
| 530 gq]/ | |
| 531 | |
| 532 "gq" is the operator to format text. "]/" is the motion that takes you to the | |
| 533 end of a comment. The result is: | |
| 534 | |
| 535 /* ~ | |
| 536 * This is a test of the text formatting. ~ | |
| 537 */ ~ | |
| 538 | |
| 539 Notice that Vim properly handled the beginning of each line. | |
| 540 An alternative is to select the text that is to be formatted in Visual mode | |
| 541 and type "gq". | |
| 542 | |
| 543 To add a new line to the comment, position the cursor on the middle line and | |
| 544 press "o". The result looks like this: | |
| 545 | |
| 546 /* ~ | |
| 547 * This is a test of the text formatting. ~ | |
| 548 * ~ | |
| 549 */ ~ | |
| 550 | |
| 551 Vim has automatically inserted a star and a space for you. Now you can type | |
| 552 the comment text. When it gets longer than 'textwidth', Vim will break the | |
| 553 line. Again, the star is inserted automatically: | |
| 554 | |
| 555 /* ~ | |
| 556 * This is a test of the text formatting. ~ | |
| 557 * Typing a lot of text here will make Vim ~ | |
| 558 * break ~ | |
| 559 */ ~ | |
| 560 | |
| 561 For this to work some flags must be present in 'formatoptions': | |
| 562 | |
| 563 r insert the star when typing <Enter> in Insert mode | |
| 564 o insert the star when using "o" or "O" in Normal mode | |
| 565 c break comment text according to 'textwidth' | |
| 566 | |
| 567 See |fo-table| for more flags. | |
| 568 | |
| 569 | |
| 570 DEFINING A COMMENT | |
| 571 | |
| 572 The 'comments' option defines what a comment looks like. Vim distinguishes | |
| 573 between a single-line comment and a comment that has a different start, end | |
| 574 and middle part. | |
| 575 Many single-line comments start with a specific character. In C++ // is | |
| 576 used, in Makefiles #, in Vim scripts ". For example, to make Vim understand | |
| 577 C++ comments: > | |
| 578 | |
| 579 :set comments=:// | |
| 580 | |
| 581 The colon separates the flags of an item from the text by which the comment is | |
| 582 recognized. The general form of an item in 'comments' is: | |
| 583 | |
| 584 {flags}:{text} | |
| 585 | |
| 586 The {flags} part can be empty, as in this case. | |
| 587 Several of these items can be concatenated, separated by commas. This | |
| 588 allows recognizing different types of comments at the same time. For example, | |
| 589 let's edit an e-mail message. When replying, the text that others wrote is | |
| 590 preceded with ">" and "!" characters. This command would work: > | |
| 591 | |
| 592 :set comments=n:>,n:! | |
| 593 | |
| 594 There are two items, one for comments starting with ">" and one for comments | |
| 595 that start with "!". Both use the flag "n". This means that these comments | |
| 596 nest. Thus a line starting with ">" may have another comment after the ">". | |
| 597 This allows formatting a message like this: | |
| 598 | |
| 599 > ! Did you see that site? ~ | |
| 600 > ! It looks really great. ~ | |
| 601 > I don't like it. The ~ | |
| 602 > colors are terrible. ~ | |
| 603 What is the URL of that ~ | |
| 604 site? ~ | |
| 605 | |
| 606 Try setting 'textwidth' to a different value, e.g., 80, and format the text by | |
| 607 Visually selecting it and typing "gq". The result is: | |
| 608 | |
| 237 | 609 > ! Did you see that site? It looks really great. ~ |
| 7 | 610 > I don't like it. The colors are terrible. ~ |
| 611 What is the URL of that site? ~ | |
| 612 | |
| 613 You will notice that Vim did not move text from one type of comment to | |
| 614 another. The "I" in the second line would have fit at the end of the first | |
| 615 line, but since that line starts with "> !" and the second line with ">", Vim | |
| 616 knows that this is a different kind of comment. | |
| 617 | |
| 618 | |
| 619 A THREE PART COMMENT | |
| 620 | |
| 621 A C comment starts with "/*", has "*" in the middle and "*/" at the end. The | |
| 622 entry in 'comments' for this looks like this: > | |
| 623 | |
| 624 :set comments=s1:/*,mb:*,ex:*/ | |
| 625 | |
| 626 The start is defined with "s1:/*". The "s" indicates the start of a | |
| 627 three-piece comment. The colon separates the flags from the text by which the | |
| 628 comment is recognized: "/*". There is one flag: "1". This tells Vim that the | |
| 629 middle part has an offset of one space. | |
| 630 The middle part "mb:*" starts with "m", which indicates it is a middle | |
| 631 part. The "b" flag means that a blank must follow the text. Otherwise Vim | |
| 632 would consider text like "*pointer" also to be the middle of a comment. | |
| 633 The end part "ex:*/" has the "e" for identification. The "x" flag has a | |
| 634 special meaning. It means that after Vim automatically inserted a star, | |
| 635 typing / will remove the extra space. | |
| 636 | |
| 637 For more details see |format-comments|. | |
| 638 | |
| 639 ============================================================================== | |
| 640 | |
| 641 Next chapter: |usr_31.txt| Exploiting the GUI | |
| 642 | |
| 14519 | 643 Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: |