Mercurial > vim
annotate runtime/doc/usr_04.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_04.txt* For Vim version 9.0. Last change: 2021 Feb 22 |
| 7 | 2 |
| 3 VIM USER MANUAL - by Bram Moolenaar | |
| 4 | |
| 5 Making small changes | |
| 6 | |
| 7 | |
| 8 This chapter shows you several ways of making corrections and moving text | |
| 9 around. It teaches you the three basic ways to change text: operator-motion, | |
| 10 Visual mode and text objects. | |
| 11 | |
| 12 |04.1| Operators and motions | |
| 13 |04.2| Changing text | |
| 14 |04.3| Repeating a change | |
| 15 |04.4| Visual mode | |
| 16 |04.5| Moving text | |
| 17 |04.6| Copying text | |
| 18 |04.7| Using the clipboard | |
| 19 |04.8| Text objects | |
| 20 |04.9| Replace mode | |
| 21 |04.10| Conclusion | |
| 22 | |
| 23 Next chapter: |usr_05.txt| Set your settings | |
| 24 Previous chapter: |usr_03.txt| Moving around | |
| 25 Table of contents: |usr_toc.txt| | |
| 26 | |
| 27 ============================================================================== | |
| 28 *04.1* Operators and motions | |
| 29 | |
| 30 In chapter 2 you learned the "x" command to delete a single character. And | |
| 31 using a count: "4x" deletes four characters. | |
| 32 The "dw" command deletes a word. You may recognize the "w" command as the | |
| 33 move word command. In fact, the "d" command may be followed by any motion | |
| 34 command, and it deletes from the current location to the place where the | |
| 35 cursor winds up. | |
| 18719 | 36 The "4w" command, for example, moves the cursor over four words. The "d4w" |
| 7 | 37 command deletes four words. |
| 38 | |
| 39 To err is human. To really foul up you need a computer. ~ | |
| 40 ------------------> | |
| 41 d4w | |
| 42 | |
| 43 To err is human. you need a computer. ~ | |
| 44 | |
| 45 Vim only deletes up to the position where the motion takes the cursor. That's | |
| 46 because Vim knows that you probably don't want to delete the first character | |
| 47 of a word. If you use the "e" command to move to the end of a word, Vim | |
| 48 guesses that you do want to include that last character: | |
| 49 | |
| 50 To err is human. you need a computer. ~ | |
| 51 --------> | |
| 52 d2e | |
| 53 | |
| 54 To err is human. a computer. ~ | |
| 55 | |
| 56 Whether the character under the cursor is included depends on the command you | |
| 57 used to move to that character. The reference manual calls this "exclusive" | |
| 58 when the character isn't included and "inclusive" when it is. | |
| 59 | |
| 60 The "$" command moves to the end of a line. The "d$" command deletes from the | |
| 61 cursor to the end of the line. This is an inclusive motion, thus the last | |
| 62 character of the line is included in the delete operation: | |
| 63 | |
| 64 To err is human. a computer. ~ | |
| 65 ------------> | |
| 66 d$ | |
| 67 | |
| 68 To err is human ~ | |
| 69 | |
| 70 There is a pattern here: operator-motion. You first type an operator command. | |
| 71 For example, "d" is the delete operator. Then you type a motion command like | |
| 72 "4l" or "w". This way you can operate on any text you can move over. | |
| 73 | |
| 74 ============================================================================== | |
| 75 *04.2* Changing text | |
| 76 | |
| 77 Another operator is "c", change. It acts just like the "d" operator, except | |
| 78 it leaves you in Insert mode. For example, "cw" changes a word. Or more | |
| 79 specifically, it deletes a word and then puts you in Insert mode. | |
| 80 | |
| 81 To err is human ~ | |
| 82 -------> | |
| 83 c2wbe<Esc> | |
| 84 | |
| 85 To be human ~ | |
| 86 | |
| 87 This "c2wbe<Esc>" contains these bits: | |
| 88 | |
| 89 c the change operator | |
| 90 2w move two words (they are deleted and Insert mode started) | |
| 91 be insert this text | |
| 92 <Esc> back to Normal mode | |
| 93 | |
| 18719 | 94 You will have noticed something strange: The space before "human" isn't |
| 95 deleted. There is a saying that for every problem there is an answer that is | |
| 96 simple, clear, and wrong. That is the case with the example used here for the | |
| 97 "cw" command. The c operator works just like the d operator, with one | |
| 98 exception: "cw". It actually works like "ce", change to end of word. Thus | |
| 99 the space after the word isn't included. This is an exception that dates back | |
| 100 to the old Vi. Since many people are used to it now, the inconsistency has | |
| 101 remained in Vim. | |
| 7 | 102 |
| 103 | |
| 104 MORE CHANGES | |
| 105 | |
| 106 Like "dd" deletes a whole line, "cc" changes a whole line. It keeps the | |
| 107 existing indent (leading white space) though. | |
| 108 | |
| 109 Just like "d$" deletes until the end of the line, "c$" changes until the end | |
| 110 of the line. It's like doing "d$" to delete the text and then "a" to start | |
| 111 Insert mode and append new text. | |
| 112 | |
| 113 | |
| 114 SHORTCUTS | |
| 115 | |
| 116 Some operator-motion commands are used so often that they have been given a | |
| 18719 | 117 single-letter command: |
| 7 | 118 |
| 119 x stands for dl (delete character under the cursor) | |
| 120 X stands for dh (delete character left of the cursor) | |
| 121 D stands for d$ (delete to end of the line) | |
| 122 C stands for c$ (change to end of the line) | |
| 123 s stands for cl (change one character) | |
| 124 S stands for cc (change a whole line) | |
| 125 | |
| 126 | |
| 127 WHERE TO PUT THE COUNT | |
| 128 | |
| 129 The commands "3dw" and "d3w" delete three words. If you want to get really | |
| 130 picky about things, the first command, "3dw", deletes one word three times; | |
| 131 the command "d3w" deletes three words once. This is a difference without a | |
| 132 distinction. You can actually put in two counts, however. For example, | |
| 133 "3d2w" deletes two words, repeated three times, for a total of six words. | |
| 134 | |
| 135 | |
| 136 REPLACING WITH ONE CHARACTER | |
| 137 | |
| 138 The "r" command is not an operator. It waits for you to type a character, and | |
| 139 will replace the character under the cursor with it. You could do the same | |
| 140 with "cl" or with the "s" command, but with "r" you don't have to press <Esc> | |
| 18719 | 141 to get back out of insert mode. |
| 7 | 142 |
| 143 there is somerhing grong here ~ | |
| 144 rT rt rw | |
| 145 | |
| 146 There is something wrong here ~ | |
| 147 | |
| 148 Using a count with "r" causes that many characters to be replaced with the | |
| 149 same character. Example: | |
| 150 | |
| 151 There is something wrong here ~ | |
| 152 5rx | |
| 153 | |
| 154 There is something xxxxx here ~ | |
| 155 | |
| 156 To replace a character with a line break use "r<Enter>". This deletes one | |
| 157 character and inserts a line break. Using a count here only applies to the | |
| 158 number of characters deleted: "4r<Enter>" replaces four characters with one | |
| 159 line break. | |
| 160 | |
| 161 ============================================================================== | |
| 162 *04.3* Repeating a change | |
| 163 | |
| 21676 | 164 The "." command is one of the simplest yet powerful commands in Vim. It |
| 7 | 165 repeats the last change. For instance, suppose you are editing an HTML file |
| 166 and want to delete all the <B> tags. You position the cursor on the first < | |
| 167 and delete the <B> with the command "df>". You then go to the < of the next | |
| 18719 | 168 </B> and delete it using the "." command. The "." command executes the last |
| 7 | 169 change command (in this case, "df>"). To delete another tag, position the |
| 170 cursor on the < and use the "." command. | |
| 171 | |
| 172 To <B>generate</B> a table of <B>contents ~ | |
| 173 f< find first < ---> | |
| 174 df> delete to > --> | |
| 175 f< find next < ---------> | |
| 176 . repeat df> ---> | |
| 177 f< find next < -------------> | |
| 178 . repeat df> --> | |
| 179 | |
| 18719 | 180 The "." command works for all changes you make, except for "u" (undo), CTRL-R |
| 181 (redo) and commands that start with a colon (:). | |
| 7 | 182 |
| 183 Another example: You want to change the word "four" to "five". It appears | |
| 184 several times in your text. You can do this quickly with this sequence of | |
| 185 commands: | |
| 186 | |
| 187 /four<Enter> find the first string "four" | |
| 188 cwfive<Esc> change the word to "five" | |
| 189 n find the next "four" | |
| 6180 | 190 . repeat the change to "five" |
| 7 | 191 n find the next "four" |
| 192 . repeat the change | |
| 193 etc. | |
| 194 | |
| 195 ============================================================================== | |
| 196 *04.4* Visual mode | |
| 197 | |
| 198 To delete simple items the operator-motion changes work quite well. But often | |
| 199 it's not so easy to decide which command will move over the text you want to | |
| 200 change. Then you can use Visual mode. | |
| 201 | |
| 202 You start Visual mode by pressing "v". You move the cursor over the text you | |
| 203 want to work on. While you do this, the text is highlighted. Finally type | |
| 204 the operator command. | |
| 18719 | 205 For example, to delete from the middle of one word to the middle of another |
| 206 word: | |
| 7 | 207 |
| 208 This is an examination sample of visual mode ~ | |
| 209 ----------> | |
| 210 velllld | |
| 211 | |
| 212 This is an example of visual mode ~ | |
| 213 | |
| 214 When doing this you don't really have to count how many times you have to | |
| 215 press "l" to end up in the right position. You can immediately see what text | |
| 216 will be deleted when you press "d". | |
| 217 | |
| 218 If at any time you decide you don't want to do anything with the highlighted | |
| 219 text, just press <Esc> and Visual mode will stop without doing anything. | |
| 220 | |
| 221 | |
| 222 SELECTING LINES | |
| 223 | |
| 224 If you want to work on whole lines, use "V" to start Visual mode. You will | |
| 225 see right away that the whole line is highlighted, without moving around. | |
| 226 When you move left or right nothing changes. When you move up or down the | |
| 227 selection is extended whole lines at a time. | |
| 228 For example, select three lines with "Vjj": | |
| 229 | |
| 230 +------------------------+ | |
| 231 | text more text | | |
| 232 >> | more text more text | | | |
| 233 selected lines >> | text text text | | Vjj | |
| 234 >> | text more | V | |
| 235 | more text more | | |
| 236 +------------------------+ | |
| 237 | |
| 238 | |
| 239 SELECTING BLOCKS | |
| 240 | |
| 241 If you want to work on a rectangular block of characters, use CTRL-V to start | |
| 242 Visual mode. This is very useful when working on tables. | |
| 243 | |
| 244 name Q1 Q2 Q3 | |
| 245 pierre 123 455 234 | |
| 246 john 0 90 39 | |
| 247 steve 392 63 334 | |
| 248 | |
| 249 To delete the middle "Q2" column, move the cursor to the "Q" of "Q2". Press | |
| 250 CTRL-V to start blockwise Visual mode. Now move the cursor three lines down | |
| 251 with "3j" and to the next word with "w". You can see the first character of | |
| 252 the last column is included. To exclude it, use "h". Now press "d" and the | |
| 253 middle column is gone. | |
| 254 | |
| 255 | |
| 256 GOING TO THE OTHER SIDE | |
| 257 | |
| 258 If you have selected some text in Visual mode, and discover that you need to | |
| 259 change the other end of the selection, use the "o" command (Hint: o for other | |
| 260 end). The cursor will go to the other end, and you can move the cursor to | |
| 261 change where the selection starts. Pressing "o" again brings you back to the | |
| 262 other end. | |
| 263 | |
| 264 When using blockwise selection, you have four corners. "o" only takes you to | |
| 265 one of the other corners, diagonally. Use "O" to move to the other corner in | |
| 266 the same line. | |
| 267 | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
268 Note that "o" and "O" in Visual mode work very differently from Normal mode, |
| 7 | 269 where they open a new line below or above the cursor. |
| 270 | |
| 271 ============================================================================== | |
| 272 *04.5* Moving text | |
| 273 | |
| 18719 | 274 When you delete something with "d", "x", or another command, the text is |
| 275 saved. You can paste it back by using the "p" command. (The Vim name for | |
| 7 | 276 this is put). |
| 277 Take a look at how this works. First you will delete an entire line, by | |
| 278 putting the cursor on the line you want to delete and typing "dd". Now you | |
| 279 move the cursor to where you want to put the line and use the "p" (put) | |
| 280 command. The line is inserted on the line below the cursor. | |
| 281 | |
| 282 a line a line a line | |
| 283 line 2 dd line 3 p line 3 | |
| 284 line 3 line 2 | |
| 285 | |
| 286 Because you deleted an entire line, the "p" command placed the text line below | |
| 287 the cursor. If you delete part of a line (a word, for instance), the "p" | |
| 288 command puts it just after the cursor. | |
| 289 | |
| 290 Some more boring try text to out commands. ~ | |
| 291 ----> | |
| 292 dw | |
| 293 | |
| 294 Some more boring text to out commands. ~ | |
| 295 -------> | |
| 296 welp | |
| 297 | |
| 298 Some more boring text to try out commands. ~ | |
| 299 | |
| 300 | |
| 301 MORE ON PUTTING | |
| 302 | |
| 303 The "P" command puts text like "p", but before the cursor. When you deleted a | |
| 304 whole line with "dd", "P" will put it back above the cursor. When you deleted | |
| 305 a word with "dw", "P" will put it back just before the cursor. | |
| 306 | |
| 307 You can repeat putting as many times as you like. The same text will be used. | |
| 308 | |
| 309 You can use a count with "p" and "P". The text will be repeated as many times | |
| 310 as specified with the count. Thus "dd" and then "3p" puts three copies of the | |
| 311 same deleted line. | |
| 312 | |
| 313 | |
| 314 SWAPPING TWO CHARACTERS | |
| 315 | |
| 316 Frequently when you are typing, your fingers get ahead of your brain (or the | |
| 317 other way around?). The result is a typo such as "teh" for "the". Vim | |
| 318 makes it easy to correct such problems. Just put the cursor on the e of "teh" | |
| 319 and execute the command "xp". This works as follows: "x" deletes the | |
| 320 character e and places it in a register. "p" puts the text after the cursor, | |
| 321 which is after the h. | |
| 322 | |
| 323 teh th the ~ | |
| 324 x p | |
| 325 | |
| 326 ============================================================================== | |
| 327 *04.6* Copying text | |
| 328 | |
| 329 To copy text from one place to another, you could delete it, use "u" to undo | |
| 330 the deletion and then "p" to put it somewhere else. There is an easier way: | |
| 331 yanking. The "y" operator copies text into a register. Then a "p" command | |
| 332 can be used to put it. | |
| 333 Yanking is just a Vim name for copying. The "c" letter was already used | |
| 334 for the change operator, and "y" was still available. Calling this | |
| 335 operator "yank" made it easier to remember to use the "y" key. | |
| 336 | |
| 337 Since "y" is an operator, you use "yw" to yank a word. A count is possible as | |
| 338 usual. To yank two words use "y2w". Example: | |
| 339 | |
| 340 let sqr = LongVariable * ~ | |
| 341 --------------> | |
| 342 y2w | |
| 343 | |
| 344 let sqr = LongVariable * ~ | |
| 345 p | |
| 346 | |
| 347 let sqr = LongVariable * LongVariable ~ | |
| 348 | |
| 349 Notice that "yw" includes the white space after a word. If you don't want | |
| 350 this, use "ye". | |
| 351 | |
| 352 The "yy" command yanks a whole line, just like "dd" deletes a whole line. | |
| 353 Unexpectedly, while "D" deletes from the cursor to the end of the line, "Y" | |
| 354 works like "yy", it yanks the whole line. Watch out for this inconsistency! | |
| 355 Use "y$" to yank to the end of the line. | |
| 356 | |
| 357 a text line yy a text line a text line | |
| 358 line 2 line 2 p line 2 | |
| 359 last line last line a text line | |
| 360 last line | |
| 361 | |
| 362 ============================================================================== | |
| 363 *04.7* Using the clipboard | |
| 364 | |
| 365 If you are using the GUI version of Vim (gvim), you can find the "Copy" item | |
| 366 in the "Edit" menu. First select some text with Visual mode, then use the | |
| 18719 | 367 Edit/Copy menu item. The selected text is now copied to the clipboard. You |
| 368 can paste the text in other programs. In Vim itself too. | |
| 7 | 369 |
| 370 If you have copied text to the clipboard in another application, you can paste | |
| 18719 | 371 it in Vim with the Edit/Paste menu item. This works in Normal mode and Insert |
| 7 | 372 mode. In Visual mode the selected text is replaced with the pasted text. |
| 373 | |
| 374 The "Cut" menu item deletes the text before it's put on the clipboard. The | |
| 375 "Copy", "Cut" and "Paste" items are also available in the popup menu (only | |
| 376 when there is a popup menu, of course). If your Vim has a toolbar, you can | |
| 377 also find these items there. | |
| 378 | |
| 379 If you are not using the GUI, or if you don't like using a menu, you have to | |
| 380 use another way. You use the normal "y" (yank) and "p" (put) commands, but | |
| 381 prepend "* (double-quote star) before it. To copy a line to the clipboard: > | |
| 382 | |
| 383 "*yy | |
| 384 | |
| 385 To put text from the clipboard back into the text: > | |
| 386 | |
| 387 "*p | |
| 388 | |
| 389 This only works on versions of Vim that include clipboard support. More about | |
| 18719 | 390 the clipboard can be found in section |09.3| and here: |clipboard|. |
| 7 | 391 |
| 392 ============================================================================== | |
| 393 *04.8* Text objects | |
| 394 | |
| 1125 | 395 If the cursor is in the middle of a word and you want to delete that word, you |
| 7 | 396 need to move back to its start before you can do "dw". There is a simpler way |
| 397 to do this: "daw". | |
| 398 | |
| 399 this is some example text. ~ | |
| 400 daw | |
| 401 | |
| 402 this is some text. ~ | |
| 403 | |
| 404 The "d" of "daw" is the delete operator. "aw" is a text object. Hint: "aw" | |
| 405 stands for "A Word". Thus "daw" is "Delete A Word". To be precise, the white | |
| 18719 | 406 space after the word is also deleted (or the white space before the word if at |
| 407 the end of the line). | |
| 7 | 408 |
| 409 Using text objects is the third way to make changes in Vim. We already had | |
| 410 operator-motion and Visual mode. Now we add operator-text object. | |
| 411 It is very similar to operator-motion, but instead of operating on the text | |
| 412 between the cursor position before and after a movement command, the text | |
| 413 object is used as a whole. It doesn't matter where in the object the cursor | |
| 414 was. | |
| 415 | |
| 416 To change a whole sentence use "cis". Take this text: | |
| 417 | |
| 418 Hello there. This ~ | |
| 419 is an example. Just ~ | |
| 420 some text. ~ | |
| 421 | |
| 422 Move to the start of the second line, on "is an". Now use "cis": | |
| 423 | |
| 424 Hello there. Just ~ | |
| 425 some text. ~ | |
| 426 | |
| 427 The cursor is in between the blanks in the first line. Now you type the new | |
| 428 sentence "Another line.": | |
| 429 | |
| 430 Hello there. Another line. Just ~ | |
| 431 some text. ~ | |
| 432 | |
| 433 "cis" consists of the "c" (change) operator and the "is" text object. This | |
| 18719 | 434 stands for "Inner Sentence". There is also the "as" ("A Sentence") object. |
| 435 The difference is that "as" includes the white space after the sentence and | |
| 436 "is" doesn't. If you would delete a sentence, you want to delete the white | |
| 437 space at the same time, thus use "das". If you want to type new text the | |
| 438 white space can remain, thus you use "cis". | |
| 7 | 439 |
| 440 You can also use text objects in Visual mode. It will include the text object | |
| 441 in the Visual selection. Visual mode continues, thus you can do this several | |
| 442 times. For example, start Visual mode with "v" and select a sentence with | |
| 443 "as". Now you can repeat "as" to include more sentences. Finally you use an | |
| 444 operator to do something with the selected sentences. | |
| 445 | |
| 446 You can find a long list of text objects here: |text-objects|. | |
| 447 | |
| 448 ============================================================================== | |
| 449 *04.9* Replace mode | |
| 450 | |
| 451 The "R" command causes Vim to enter replace mode. In this mode, each | |
| 452 character you type replaces the one under the cursor. This continues until | |
| 453 you type <Esc>. | |
| 454 In this example you start Replace mode on the first "t" of "text": | |
| 455 | |
| 456 This is text. ~ | |
| 457 Rinteresting.<Esc> | |
| 458 | |
| 459 This is interesting. ~ | |
| 460 | |
| 461 You may have noticed that this command replaced 5 characters in the line with | |
| 237 | 462 twelve others. The "R" command automatically extends the line if it runs out |
| 7 | 463 of characters to replace. It will not continue on the next line. |
| 464 | |
| 465 You can switch between Insert mode and Replace mode with the <Insert> key. | |
| 466 | |
| 24024 | 467 When you use <BS> (backspace) to make a correction, you will notice that the |
| 468 old text is put back. Thus it works like an undo command for the previously | |
| 469 typed character. | |
| 7 | 470 |
| 471 ============================================================================== | |
| 472 *04.10* Conclusion | |
| 473 | |
| 474 The operators, movement commands and text objects give you the possibility to | |
| 18719 | 475 make lots of combinations. Now that you know how they work, you can use N |
| 7 | 476 operators with M movement commands to make N * M commands! |
| 477 | |
| 18719 | 478 You can find a list of operators here: |operator|. |
| 7 | 479 |
| 480 For example, there are many other ways to delete pieces of text. Here are a | |
| 18719 | 481 few common ones: |
| 7 | 482 |
| 483 x delete character under the cursor (short for "dl") | |
| 484 X delete character before the cursor (short for "dh") | |
| 485 D delete from cursor to end of line (short for "d$") | |
| 486 dw delete from cursor to next start of word | |
| 487 db delete from cursor to previous start of word | |
| 488 diw delete word under the cursor (excluding white space) | |
| 489 daw delete word under the cursor (including white space) | |
| 490 dG delete until the end of the file | |
| 491 dgg delete until the start of the file | |
| 492 | |
| 493 If you use "c" instead of "d" they become change commands. And with "y" you | |
| 494 yank the text. And so forth. | |
| 495 | |
| 496 | |
| 18719 | 497 There are a few common commands to make changes that didn't fit somewhere |
| 7 | 498 else: |
| 499 | |
| 18719 | 500 ~ Change case of the character under the cursor, and move the |
| 7 | 501 cursor to the next character. This is not an operator (unless |
| 502 'tildeop' is set), thus you can't use it with a motion | |
| 18719 | 503 command. It does work in Visual mode, where it changes case |
| 504 for all the selected text. | |
| 7 | 505 |
| 506 I Start Insert mode after moving the cursor to the first | |
| 507 non-blank in the line. | |
| 508 | |
| 509 A Start Insert mode after moving the cursor to the end of the | |
| 510 line. | |
| 511 | |
| 512 ============================================================================== | |
| 513 | |
| 514 Next chapter: |usr_05.txt| Set your settings | |
| 515 | |
| 14519 | 516 Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: |