Mercurial > vim
view runtime/doc/usr_27.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 |
line wrap: on
line source
*usr_27.txt* For Vim version 9.0. Last change: 2019 Jul 14 VIM USER MANUAL - by Bram Moolenaar Search commands and patterns In chapter 3 a few simple search patterns were mentioned |03.9|. Vim can do much more complex searches. This chapter explains the most often used ones. A detailed specification can be found here: |pattern| |27.1| Ignoring case |27.2| Wrapping around the file end |27.3| Offsets |27.4| Matching multiple times |27.5| Alternatives |27.6| Character ranges |27.7| Character classes |27.8| Matching a line break |27.9| Examples Next chapter: |usr_28.txt| Folding Previous chapter: |usr_26.txt| Repeating Table of contents: |usr_toc.txt| ============================================================================== *27.1* Ignoring case By default, Vim's searches are case sensitive. Therefore, "include", "INCLUDE", and "Include" are three different words and a search will match only one of them. Now switch on the 'ignorecase' option: > :set ignorecase Search for "include" again, and now it will match "Include", "INCLUDE" and "InClUDe". (Set the 'hlsearch' option to quickly see where a pattern matches.) You can switch this off again with: > :set noignorecase But let's keep it set, and search for "INCLUDE". It will match exactly the same text as "include" did. Now set the 'smartcase' option: > :set ignorecase smartcase If you have a pattern with at least one uppercase character, the search becomes case sensitive. The idea is that you didn't have to type that uppercase character, so you must have done it because you wanted case to match. That's smart! With these two options set you find the following matches: pattern matches ~ word word, Word, WORD, WoRd, etc. Word Word WORD WORD WoRd WoRd CASE IN ONE PATTERN If you want to ignore case for one specific pattern, you can do this by prepending the "\c" string. Using "\C" will make the pattern to match case. This overrules the 'ignorecase' and 'smartcase' options, when "\c" or "\C" is used their value doesn't matter. pattern matches ~ \Cword word \CWord Word \cword word, Word, WORD, WoRd, etc. \cWord word, Word, WORD, WoRd, etc. A big advantage of using "\c" and "\C" is that it sticks with the pattern. Thus if you repeat a pattern from the search history, the same will happen, no matter if 'ignorecase' or 'smartcase' was changed. Note: The use of "\" items in search patterns depends on the 'magic' option. In this chapter we will assume 'magic' is on, because that is the standard and recommended setting. If you would change 'magic', many search patterns would suddenly become invalid. Note: If your search takes much longer than you expected, you can interrupt it with CTRL-C on Unix and CTRL-Break on MS-Windows. ============================================================================== *27.2* Wrapping around the file end By default, a forward search starts searching for the given string at the current cursor location. It then proceeds to the end of the file. If it has not found the string by that time, it starts from the beginning and searches from the start of the file to the cursor location. Keep in mind that when repeating the "n" command to search for the next match, you eventually get back to the first match. If you don't notice this you keep searching forever! To give you a hint, Vim displays this message: search hit BOTTOM, continuing at TOP ~ If you use the "?" command, to search in the other direction, you get this message: search hit TOP, continuing at BOTTOM ~ Still, you don't know when you are back at the first match. One way to see this is by switching on the 'ruler' option: > :set ruler Vim will display the cursor position in the lower righthand corner of the window (in the status line if there is one). It looks like this: 101,29 84% ~ The first number is the line number of the cursor. Remember the line number where you started, so that you can check if you passed this position again. NOT WRAPPING To turn off search wrapping, use the following command: > :set nowrapscan Now when the search hits the end of the file, an error message displays: E385: search hit BOTTOM without match for: forever ~ Thus you can find all matches by going to the start of the file with "gg" and keep searching until you see this message. If you search in the other direction, using "?", you get: E384: search hit TOP without match for: forever ~ ============================================================================== *27.3* Offsets By default, the search command leaves the cursor positioned on the beginning of the pattern. You can tell Vim to leave it some other place by specifying an offset. For the forward search command "/", the offset is specified by appending a slash (/) and the offset: > /default/2 This command searches for the pattern "default" and then moves to the beginning of the second line past the pattern. Using this command on the paragraph above, Vim finds the word "default" in the first line. Then the cursor is moved two lines down and lands on "an offset". If the offset is a simple number, the cursor will be placed at the beginning of the line that many lines from the match. The offset number can be positive or negative. If it is positive, the cursor moves down that many lines; if negative, it moves up. CHARACTER OFFSETS The "e" offset indicates an offset from the end of the match. It moves the cursor onto the last character of the match. The command: > /const/e puts the cursor on the "t" of "const". From that position, adding a number moves forward that many characters. This command moves to the character just after the match: > /const/e+1 A positive number moves the cursor to the right, a negative number moves it to the left. For example: > /const/e-1 moves the cursor to the "s" of "const". If the offset begins with "b", the cursor moves to the beginning of the pattern. That's not very useful, since leaving out the "b" does the same thing. It does get useful when a number is added or subtracted. The cursor then goes forward or backward that many characters. For example: > /const/b+2 Moves the cursor to the beginning of the match and then two characters to the right. Thus it lands on the "n". REPEATING To repeat searching for the previously used search pattern, but with a different offset, leave out the pattern: > /that //e Is equal to: > /that/e To repeat with the same offset: > / "n" does the same thing. To repeat while removing a previously used offset: > // SEARCHING BACKWARDS The "?" command uses offsets in the same way, but you must use "?" to separate the offset from the pattern, instead of "/": > ?const?e-2 The "b" and "e" keep their meaning, they don't change direction with the use of "?". START POSITION When starting a search, it normally starts at the cursor position. When you specify a line offset, this can cause trouble. For example: > /const/-2 This finds the next word "const" and then moves two lines up. If you use "n" to search again, Vim could start at the current position and find the same "const" match. Then using the offset again, you would be back where you started. You would be stuck! It could be worse: Suppose there is another match with "const" in the next line. Then repeating the forward search would find this match and move two lines up. Thus you would actually move the cursor back! When you specify a character offset, Vim will compensate for this. Thus the search starts a few characters forward or backward, so that the same match isn't found again. ============================================================================== *27.4* Matching multiple times The "*" item specifies that the item before it can match any number of times. Thus: > /a* matches "a", "aa", "aaa", etc. But also "" (the empty string), because zero times is included. The "*" only applies to the item directly before it. Thus "ab*" matches "a", "ab", "abb", "abbb", etc. To match a whole string multiple times, it must be grouped into one item. This is done by putting "\(" before it and "\)" after it. Thus this command: > /\(ab\)* Matches: "ab", "abab", "ababab", etc. And also "". To avoid matching the empty string, use "\+". This makes the previous item match one or more times. > /ab\+ Matches "ab", "abb", "abbb", etc. It does not match "a" when no "b" follows. To match an optional item, use "\=". Example: > /folders\= Matches "folder" and "folders". SPECIFIC COUNTS To match a specific number of items use the form "\{n,m}". "n" and "m" are numbers. The item before it will be matched "n" to "m" times |inclusive|. Example: > /ab\{3,5} matches "abbb", "abbbb" and "abbbbb". When "n" is omitted, it defaults to zero. When "m" is omitted it defaults to infinity. When ",m" is omitted, it matches exactly "n" times. Examples: pattern match count ~ \{,4} 0, 1, 2, 3 or 4 \{3,} 3, 4, 5, etc. \{0,1} 0 or 1, same as \= \{0,} 0 or more, same as * \{1,} 1 or more, same as \+ \{3} 3 MATCHING AS LITTLE AS POSSIBLE The items so far match as many characters as they can find. To match as few as possible, use "\{-n,m}". It works the same as "\{n,m}", except that the minimal amount possible is used. For example, use: > /ab\{-1,3} Will match "ab" in "abbb". Actually, it will never match more than one b, because there is no reason to match more. It requires something else to force it to match more than the lower limit. The same rules apply to removing "n" and "m". It's even possible to remove both of the numbers, resulting in "\{-}". This matches the item before it zero or more times, as few as possible. The item by itself always matches zero times. It is useful when combined with something else. Example: > /a.\{-}b This matches "axb" in "axbxb". If this pattern would be used: > /a.*b It would try to match as many characters as possible with ".*", thus it matches "axbxb" as a whole. ============================================================================== *27.5* Alternatives The "or" operator in a pattern is "\|". Example: > /foo\|bar This matches "foo" or "bar". More alternatives can be concatenated: > /one\|two\|three Matches "one", "two" and "three". To match multiple times, the whole thing must be placed in "\(" and "\)": > /\(foo\|bar\)\+ This matches "foo", "foobar", "foofoo", "barfoobar", etc. Another example: > /end\(if\|while\|for\) This matches "endif", "endwhile" and "endfor". A related item is "\&". This requires that both alternatives match in the same place. The resulting match uses the last alternative. Example: > /forever\&... This matches "for" in "forever". It will not match "fortuin", for example. ============================================================================== *27.6* Character ranges To match "a", "b" or "c" you could use "/a\|b\|c". When you want to match all letters from "a" to "z" this gets very long. There is a shorter method: > /[a-z] The [] construct matches a single character. Inside you specify which characters to match. You can include a list of characters, like this: > /[0123456789abcdef] This will match any of the characters included. For consecutive characters you can specify the range. "0-3" stands for "0123". "w-z" stands for "wxyz". Thus the same command as above can be shortened to: > /[0-9a-f] To match the "-" character itself make it the first or last one in the range. These special characters are accepted to make it easier to use them inside a [] range (they can actually be used anywhere in the search pattern): \e <Esc> \t <Tab> \r <CR> \b <BS> There are a few more special cases for [] ranges, see |/[]| for the whole story. COMPLEMENTED RANGE To avoid matching a specific character, use "^" at the start of the range. The [] item then matches everything but the characters included. Example: > /"[^"]*" < " a double quote [^"] any character that is not a double quote * as many as possible " a double quote again This matches "foo" and "3!x", including the double quotes. PREDEFINED RANGES A number of ranges are used very often. Vim provides a shortcut for these. For example: > /\a Finds alphabetic characters. This is equal to using "/[a-zA-Z]". Here are a few more of these: item matches equivalent ~ \d digit [0-9] \D non-digit [^0-9] \x hex digit [0-9a-fA-F] \X non-hex digit [^0-9a-fA-F] \s white space [ ] (<Tab> and <Space>) \S non-white characters [^ ] (not <Tab> and <Space>) \l lowercase alpha [a-z] \L non-lowercase alpha [^a-z] \u uppercase alpha [A-Z] \U non-uppercase alpha [^A-Z] Note: Using these predefined ranges works a lot faster than the character range it stands for. These items can not be used inside []. Thus "[\d\l]" does NOT work to match a digit or lowercase alpha. Use "\(\d\|\l\)" instead. See |/\s| for the whole list of these ranges. ============================================================================== *27.7* Character classes The character range matches a fixed set of characters. A character class is similar, but with an essential difference: The set of characters can be redefined without changing the search pattern. For example, search for this pattern: > /\f\+ The "\f" item stands for file name characters. Thus this matches a sequence of characters that can be a file name. Which characters can be part of a file name depends on the system you are using. On MS-Windows, the backslash is included, on Unix it is not. This is specified with the 'isfname' option. The default value for Unix is: > :set isfname isfname=@,48-57,/,.,-,_,+,,,#,$,%,~,= For other systems the default value is different. Thus you can make a search pattern with "\f" to match a file name, and it will automatically adjust to the system you are using it on. Note: Actually, Unix allows using just about any character in a file name, including white space. Including these characters in 'isfname' would be theoretically correct. But it would make it impossible to find the end of a file name in text. Thus the default value of 'isfname' is a compromise. The character classes are: item matches option ~ \i identifier characters 'isident' \I like \i, excluding digits \k keyword characters 'iskeyword' \K like \k, excluding digits \p printable characters 'isprint' \P like \p, excluding digits \f file name characters 'isfname' \F like \f, excluding digits ============================================================================== *27.8* Matching a line break Vim can find a pattern that includes a line break. You need to specify where the line break happens, because all items mentioned so far don't match a line break. To check for a line break in a specific place, use the "\n" item: > /one\ntwo This will match at a line that ends in "one" and the next line starts with "two". To match "one two" as well, you need to match a space or a line break. The item to use for it is "\_s": > /one\_stwo To allow any amount of white space: > /one\_s\+two This also matches when "one " is at the end of a line and " two" at the start of the next one. "\s" matches white space, "\_s" matches white space or a line break. Similarly, "\a" matches an alphabetic character, and "\_a" matches an alphabetic character or a line break. The other character classes and ranges can be modified in the same way by inserting a "_". Many other items can be made to match a line break by prepending "\_". For example: "\_." matches any character or a line break. Note: "\_.*" matches everything until the end of the file. Be careful with this, it can make a search command very slow. Another example is "\_[]", a character range that includes a line break: > /"\_[^"]*" This finds a text in double quotes that may be split up in several lines. ============================================================================== *27.9* Examples Here are a few search patterns you might find useful. This shows how the items mentioned above can be combined. FINDING A CALIFORNIA LICENSE PLATE A sample license plate number is "1MGU103". It has one digit, three uppercase letters and three digits. Directly putting this into a search pattern: > /\d\u\u\u\d\d\d Another way is to specify that there are three digits and letters with a count: > /\d\u\{3}\d\{3} Using [] ranges instead: > /[0-9][A-Z]\{3}[0-9]\{3} Which one of these you should use? Whichever one you can remember. The simple way you can remember is much faster than the fancy way that you can't. If you can remember them all, then avoid the last one, because it's both more typing and slower to execute. FINDING AN IDENTIFIER In C programs (and many other computer languages) an identifier starts with a letter and further consists of letters and digits. Underscores can be used too. This can be found with: > /\<\h\w*\> "\<" and "\>" are used to find only whole words. "\h" stands for "[A-Za-z_]" and "\w" for "[0-9A-Za-z_]". Note: "\<" and "\>" depend on the 'iskeyword' option. If it includes "-", for example, then "ident-" is not matched. In this situation use: > /\w\@<!\h\w*\w\@! < This checks if "\w" does not match before or after the identifier. See |/\@<!| and |/\@!|. ============================================================================== Next chapter: |usr_28.txt| Folding Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: