Mercurial > vim
annotate runtime/doc/usr_43.txt @ 33399:95db67c7b754 v9.0.1958
patch 9.0.1958: cannot complete option values
Commit: https://github.com/vim/vim/commit/900894b09a95398dfc75599e9f0aa2ea25723384
Author: Yee Cheng Chin <ychin.git@gmail.com>
Date: Fri Sep 29 20:42:32 2023 +0200
patch 9.0.1958: cannot complete option values
Problem: cannot complete option values
Solution: Add completion functions for several options
Add cmdline tab-completion for setting string options
Add tab-completion for setting string options on the cmdline using
`:set=` (along with `:set+=` and `:set-=`).
The existing tab completion for setting options currently only works
when nothing is typed yet, and it only fills in with the existing value,
e.g. when the user does `:set diffopt=<Tab>` it will be completed to
`set diffopt=internal,filler,closeoff` and nothing else. This isn't too
useful as a user usually wants auto-complete to suggest all the possible
values, such as 'iblank', or 'algorithm:patience'.
For set= and set+=, this adds a new optional callback function for each
option that can be invoked when doing completion. This allows for each
option to have control over how completion works. For example, in
'diffopt', it will suggest the default enumeration, but if `algorithm:`
is selected, it will further suggest different algorithm types like
'meyers' and 'patience'. When using set=, the existing option value will
be filled in as the first choice to preserve the existing behavior. When
using set+= this won't happen as it doesn't make sense.
For flag list options (e.g. 'mouse' and 'guioptions'), completion will
take into account existing typed values (and in the case of set+=, the
existing option value) to make sure it doesn't suggest duplicates.
For set-=, there is a new `ExpandSettingSubtract` function which will
handle flag list and comma-separated options smartly, by only suggesting
values that currently exist in the option.
Note that Vim has some existing code that adds special handling for
'filetype', 'syntax', and misc dir options like 'backupdir'. This change
preserves them as they already work, instead of converting to the new
callback API for each option.
closes: #13182
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 | Fri, 29 Sep 2023 20:45:04 +0200 |
| parents | f8116058ca76 |
| children | 4635e43f2c6f |
| rev | line source |
|---|---|
| 29314 | 1 *usr_43.txt* For Vim version 9.0. Last change: 2015 Oct 23 |
| 7 | 2 |
| 3 VIM USER MANUAL - by Bram Moolenaar | |
| 4 | |
| 5 Using filetypes | |
| 6 | |
| 7 | |
| 8 When you are editing a file of a certain type, for example a C program or a | |
| 9 shell script, you often use the same option settings and mappings. You | |
| 10 quickly get tired of manually setting these each time. This chapter explains | |
| 11 how to do it automatically. | |
| 12 | |
| 13 |43.1| Plugins for a filetype | |
| 14 |43.2| Adding a filetype | |
| 15 | |
| 16 Next chapter: |usr_44.txt| Your own syntax highlighted | |
| 17 Previous chapter: |usr_42.txt| Add new menus | |
| 18 Table of contents: |usr_toc.txt| | |
| 19 | |
| 20 ============================================================================== | |
| 21 *43.1* Plugins for a filetype *filetype-plugin* | |
| 22 | |
| 23 How to start using filetype plugins has already been discussed here: | |
| 24 |add-filetype-plugin|. But you probably are not satisfied with the default | |
| 25 settings, because they have been kept minimal. Suppose that for C files you | |
| 26 want to set the 'softtabstop' option to 4 and define a mapping to insert a | |
| 27 three-line comment. You do this with only two steps: | |
| 28 | |
| 29 *your-runtime-dir* | |
| 30 1. Create your own runtime directory. On Unix this usually is "~/.vim". In | |
| 31 this directory create the "ftplugin" directory: > | |
| 32 | |
| 33 mkdir ~/.vim | |
| 34 mkdir ~/.vim/ftplugin | |
| 35 < | |
| 36 When you are not on Unix, check the value of the 'runtimepath' option to | |
| 37 see where Vim will look for the "ftplugin" directory: > | |
| 38 | |
| 39 set runtimepath | |
| 40 | |
| 41 < You would normally use the first directory name (before the first comma). | |
| 42 You might want to prepend a directory name to the 'runtimepath' option in | |
| 43 your |vimrc| file if you don't like the default value. | |
| 44 | |
| 45 2. Create the file "~/.vim/ftplugin/c.vim", with the contents: > | |
| 46 | |
| 47 setlocal softtabstop=4 | |
| 48 noremap <buffer> <LocalLeader>c o/**************<CR><CR>/<Esc> | |
|
7183
ffad29dc7eee
commit https://github.com/vim/vim/commit/a0f849ee40cbea3c889345256786b640b0becca2
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
49 let b:undo_ftplugin = "setl softtabstop< | unmap <buffer> <LocalLeader>c" |
| 7 | 50 |
| 51 Try editing a C file. You should notice that the 'softtabstop' option is set | |
| 52 to 4. But when you edit another file it's reset to the default zero. That is | |
| 53 because the ":setlocal" command was used. This sets the 'softtabstop' option | |
| 54 only locally to the buffer. As soon as you edit another buffer, it will be | |
| 55 set to the value set for that buffer. For a new buffer it will get the | |
| 56 default value or the value from the last ":set" command. | |
| 57 | |
| 58 Likewise, the mapping for "\c" will disappear when editing another buffer. | |
| 59 The ":map <buffer>" command creates a mapping that is local to the current | |
| 60 buffer. This works with any mapping command: ":map!", ":vmap", etc. The | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
61 |<LocalLeader>| in the mapping is replaced with the value of the |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
62 "maplocalleader" variable. |
| 7 | 63 |
|
7183
ffad29dc7eee
commit https://github.com/vim/vim/commit/a0f849ee40cbea3c889345256786b640b0becca2
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
64 The line to set b:undo_ftplugin is for when the filetype is set to another |
|
ffad29dc7eee
commit https://github.com/vim/vim/commit/a0f849ee40cbea3c889345256786b640b0becca2
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
65 value. In that case you will want to undo your preferences. The |
|
ffad29dc7eee
commit https://github.com/vim/vim/commit/a0f849ee40cbea3c889345256786b640b0becca2
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
66 b:undo_ftplugin variable is executed as a command. Watch out for characters |
|
ffad29dc7eee
commit https://github.com/vim/vim/commit/a0f849ee40cbea3c889345256786b640b0becca2
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
67 with a special meaning inside a string, such as a backslash. |
|
ffad29dc7eee
commit https://github.com/vim/vim/commit/a0f849ee40cbea3c889345256786b640b0becca2
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
68 |
| 7 | 69 You can find examples for filetype plugins in this directory: > |
| 70 | |
| 71 $VIMRUNTIME/ftplugin/ | |
| 72 | |
| 73 More details about writing a filetype plugin can be found here: | |
| 74 |write-plugin|. | |
| 75 | |
| 76 ============================================================================== | |
| 77 *43.2* Adding a filetype | |
| 78 | |
| 79 If you are using a type of file that is not recognized by Vim, this is how to | |
| 80 get it recognized. You need a runtime directory of your own. See | |
| 81 |your-runtime-dir| above. | |
| 82 | |
| 83 Create a file "filetype.vim" which contains an autocommand for your filetype. | |
| 84 (Autocommands were explained in section |40.3|.) Example: > | |
| 85 | |
| 86 augroup filetypedetect | |
| 87 au BufNewFile,BufRead *.xyz setf xyz | |
| 88 augroup END | |
| 89 | |
| 90 This will recognize all files that end in ".xyz" as the "xyz" filetype. The | |
| 91 ":augroup" commands put this autocommand in the "filetypedetect" group. This | |
| 92 allows removing all autocommands for filetype detection when doing ":filetype | |
| 93 off". The "setf" command will set the 'filetype' option to its argument, | |
| 94 unless it was set already. This will make sure that 'filetype' isn't set | |
| 95 twice. | |
| 96 | |
| 97 You can use many different patterns to match the name of your file. Directory | |
| 98 names can also be included. See |autocmd-patterns|. For example, the files | |
| 99 under "/usr/share/scripts/" are all "ruby" files, but don't have the expected | |
| 100 file name extension. Adding this to the example above: > | |
| 101 | |
| 102 augroup filetypedetect | |
| 103 au BufNewFile,BufRead *.xyz setf xyz | |
| 104 au BufNewFile,BufRead /usr/share/scripts/* setf ruby | |
| 105 augroup END | |
| 106 | |
| 107 However, if you now edit a file /usr/share/scripts/README.txt, this is not a | |
| 108 ruby file. The danger of a pattern ending in "*" is that it quickly matches | |
| 109 too many files. To avoid trouble with this, put the filetype.vim file in | |
| 110 another directory, one that is at the end of 'runtimepath'. For Unix for | |
| 111 example, you could use "~/.vim/after/filetype.vim". | |
| 112 You now put the detection of text files in ~/.vim/filetype.vim: > | |
| 113 | |
| 114 augroup filetypedetect | |
| 115 au BufNewFile,BufRead *.txt setf text | |
| 116 augroup END | |
| 117 | |
| 118 That file is found in 'runtimepath' first. Then use this in | |
| 119 ~/.vim/after/filetype.vim, which is found last: > | |
| 120 | |
| 121 augroup filetypedetect | |
| 122 au BufNewFile,BufRead /usr/share/scripts/* setf ruby | |
| 123 augroup END | |
| 124 | |
| 125 What will happen now is that Vim searches for "filetype.vim" files in each | |
| 126 directory in 'runtimepath'. First ~/.vim/filetype.vim is found. The | |
| 127 autocommand to catch *.txt files is defined there. Then Vim finds the | |
| 128 filetype.vim file in $VIMRUNTIME, which is halfway 'runtimepath'. Finally | |
| 129 ~/.vim/after/filetype.vim is found and the autocommand for detecting ruby | |
| 130 files in /usr/share/scripts is added. | |
| 131 When you now edit /usr/share/scripts/README.txt, the autocommands are | |
| 132 checked in the order in which they were defined. The *.txt pattern matches, | |
| 133 thus "setf text" is executed to set the filetype to "text". The pattern for | |
| 134 ruby matches too, and the "setf ruby" is executed. But since 'filetype' was | |
| 135 already set to "text", nothing happens here. | |
| 136 When you edit the file /usr/share/scripts/foobar the same autocommands are | |
| 137 checked. Only the one for ruby matches and "setf ruby" sets 'filetype' to | |
| 138 ruby. | |
| 139 | |
| 140 | |
| 141 RECOGNIZING BY CONTENTS | |
| 142 | |
| 143 If your file cannot be recognized by its file name, you might be able to | |
| 144 recognize it by its contents. For example, many script files start with a | |
| 145 line like: | |
| 146 | |
| 147 #!/bin/xyz ~ | |
| 148 | |
| 149 To recognize this script create a file "scripts.vim" in your runtime directory | |
| 150 (same place where filetype.vim goes). It might look like this: > | |
| 151 | |
| 152 if did_filetype() | |
| 153 finish | |
| 154 endif | |
| 155 if getline(1) =~ '^#!.*[/\\]xyz\>' | |
| 156 setf xyz | |
| 157 endif | |
| 158 | |
| 159 The first check with did_filetype() is to avoid that you will check the | |
| 160 contents of files for which the filetype was already detected by the file | |
| 161 name. That avoids wasting time on checking the file when the "setf" command | |
| 162 won't do anything. | |
| 163 The scripts.vim file is sourced by an autocommand in the default | |
| 164 filetype.vim file. Therefore, the order of checks is: | |
| 165 | |
| 166 1. filetype.vim files before $VIMRUNTIME in 'runtimepath' | |
| 167 2. first part of $VIMRUNTIME/filetype.vim | |
| 168 3. all scripts.vim files in 'runtimepath' | |
| 169 4. remainder of $VIMRUNTIME/filetype.vim | |
| 170 5. filetype.vim files after $VIMRUNTIME in 'runtimepath' | |
| 171 | |
| 172 If this is not sufficient for you, add an autocommand that matches all files | |
| 173 and sources a script or executes a function to check the contents of the file. | |
| 174 | |
| 175 ============================================================================== | |
| 176 | |
| 177 Next chapter: |usr_44.txt| Your own syntax highlighted | |
| 178 | |
| 14519 | 179 Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: |