repeat.txt ForVim version 9.1. Last change: 2024 Oct 16VIM REFERENCE MANUAL by Bram MoolenaarRepeating commands, Vim scripts and debuggingrepeatingChapter 26 of the user manual introducesrepeatingusr_26.txt.1. Single repeatssingle-repeat2. Multiple repeatsmulti-repeat3. Complex repeatscomplex-repeat4. Using Vim scriptsusing-scripts5. Using Vimpackagespackages6. Creating Vimpackagespackage-create7. Debugging scriptsdebug-scripts8. Profilingprofiling==============================================================================1. Single repeatssingle-repeat..Repeat last change, withcount replaced with[count].Also repeatayank command, when the 'y' flagisincluded in'cpoptions'. Does not repeatacommand-line command.Simple changes can be repeated with the "." command. Withouta count, thecount of the last changeis used. If you entera count,it will replace thelast one.v:count andv:count1 will be set.If the last change includeda specification ofa numbered register, theregister number will be incremented. Seeredo-register for an example howto use this.Note that whenrepeatinga command that usedaVisual selection, the same SIZEof areais used, seevisual-repeat.@:@:Repeat last command-line[count] times.{not available when compiled without the+cmdline_hist feature}==============================================================================2. Multiple repeatsmulti-repeat:g:globalE148:[range]g[lobal]/{pattern}/[cmd]Execute theEx command[cmd] (default ":p") on thelines within[range] where{pattern} matches.:[range]g[lobal]!/{pattern}/[cmd]Execute theEx command[cmd] (default ":p") on thelines within[range] where{pattern} does NOT match.:v:vglobal:[range]v[global]/{pattern}/[cmd]Sameas :g!.Example::g/^Obsolete/d _Using the underscore after:d avoids clobberingregisters or the clipboard.This also makesit faster.Instead of the '/' which surrounds the{pattern}, you can use any othersingle byte character, but not an alphabetic character, '\','"','|' or '!'.Thisis useful if you want to includea '/' in the searchpattern orreplacement string.For the definition ofa pattern, seepattern.NOTE[cmd] may containa range; seecollapse andedit-paragraph-join forexamples.The global commands work by first scanning through the[range] lines andmarking each line wherea match occurs (fora multi-line pattern, only thestart of the match matters).Ina second scan the[cmd]is executed for each marked line,as if the cursorwas in that line. For ":v" and ":g!" the commandis executed for each notmarked line. Ifa lineis deleted itsmark disappears.The default for[range]is the whole buffer (1,$). Use "CTRL-C" to interruptthe command. If an error messageis given fora line, the command for thatlineis aborted and the global command continues with the next marked orunmarked line.E147When the commandis used recursively,it only works on one line. Givingarangeis then not allowed. Thisis useful to find all lines that matchapattern anddo not match another pattern::g/found/v/notfound/{cmd}This first finds all lines containing "found", but only executes{cmd} whenthereis no match for "notfound".AnyEx command can be used, seeex-cmd-index. To executeaNormal modecommand, you can use the:normal command::g/pat/normal {commands}Make sure that{commands} ends witha whole command, otherwise Vim will waitfor you to type the rest of the command for each match. The screen will nothave been updated, so you don't know what you are doing. See:normal.The undo/redo command will undo/redo the whole global commandat once.The previous contextmark will only be set once (with "''" yougo back towhere the cursor was before the global command).The global command sets both the last used searchpattern and the last usedsubstitutepattern (thisisvi compatible). This makesiteasy to globallyreplacea string::g/pat/s//PAT/gThis replaces all occurrences of "pat" with "PAT". The same can be done with::%s/pat/PAT/gWhichis two characters shorter!When using "global" inEx mode,a specialcaseis using ":visual"asacommand. This will move toa matching line,go toNormal mode to let youexecute commands there until you useQ to return toEx mode. This will berepeated for each matching line. While doing this you cannot use ":global".To abort this typeCTRL-C twice.==============================================================================3. Complex repeatscomplex-repeatqrecordingq{0-9a-zA-Z"}Record typed characters intoregister{0-9a-zA-Z"}(uppercase to append). The 'q' commandis disabledwhile executinga register, andit doesn't work insideamapping and:normal.Note: If theregister being used forrecordingis alsoused fory andp the resultis most likely notwhatis expected, because theput will paste therecordedmacro and theyank will overwrite therecorded macro.Note: Therecording happens while you type, replayingtheregister happensas if the keys come fromamapping. This matters, for example, for undo, whichonly syncs when commands were typed.qStops recording. (Implementationnote: The 'q' thatstopsrecordingis not stored in the register, unlessit was the result ofa mapping)@@{0-9a-z".=*+}Execute the contents ofregister{0-9a-z".=*+}[count]times.Note thatregister '%' (name of the currentfile) and '#' (name of the alternate file) cannot beused.Theregisteris executed likea mapping, that meansthat the difference between'wildchar' and'wildcharm'applies, andundo might not be synced in the same way.For "@=" you are prompted to enter an expression. Theresult of theexpressionis then executed.See also@:.@@E748@@Repeat the previous @{0-9a-z":*}[count] times.:@:[addr]@{0-9a-z".=*+}Execute the contents ofregister{0-9a-z".=*+}as anExcommand. First set cursorat line[addr] (defaultiscurrent line). When the last line in theregister doesnot havea<CR>it will be added automatically whenthe 'e' flagis present in'cpoptions'.For ":@=" the last usedexpressionis used. Theresult of evaluating theexpressionis executedas anEx command.Mappings are not recognized in these commands.When theline-continuation character (\)is presentat the beginning ofa line inalinewise register,thenitis combined with the previous line. Thisisuseful for yanking and executing parts ofa Vimscript.Future: Will execute theregister for each line in theaddress range.:[addr]*{0-9a-z".=+}:star-compatibleWhen'*'is present in'cpoptions'cpo-star, use":*" in the same wayas ":@". Thisis NOT the defaultwhen'nocompatible'is used. When the'*' flagis notpresent in'cpoptions', ":*"is an alias for ":'<,'>",select theVisual area:star.:@::[addr]@:Repeat last command-line. First set cursorat line[addr] (defaultis current line).:[addr]@:@@:[addr]@@Repeat the previous :@{register}. First set cursoratline[addr] (defaultis current line).==============================================================================4. Using Vim scriptsusing-scriptsForwritinga Vim script, see chapter 41 of the user manualusr_41.txt.:so:sourceload-vim-script:so[urce]{file}ReadEx commands from{file}. These are commands thatstart witha ":".Triggers theSourcePre autocommand.:source-range:[range]so[urce] [++clear]ReadEx commands from the[range] of lines in thecurrent buffer. When[range]is omitted read alllines.When sourcing commands from the current buffer, thesame script-ID<SID>is used even if the bufferissourced multiple times. Ifa bufferis sourced morethan once, then thefunctions in the buffer aredefined again.To sourcea range of lines that doesn't start with the:vim9script command inVim9script context, the:vim9cmd modifier can be used. If you useaVisualselection and type ":", the range in the form "'<,'>"can come before it::'<,'>vim9cmd sourceOtherwise the range goes after the modifier andmusthavea colon prefixed, like allVim9 ranges::vim9cmd :5,9sourceWhena range of lines ina bufferis sourced in theVim9script context, the previously definedscript-localvariables andfunctions are not cleared.This works like the range started with the":vim9script noclear" command. The "++clear" argumentcan be used to clear thescript-localvariables andfunctions before sourcing the script. This works likethe range started with the:vim9script commandwithout the "noclear" argument. Seevim9-reload formore information.Examples::4,5source:10,18source ++clear:source!:so[urce]!{file}Read Vim commands from{file}. These are commandsthat are executed fromNormal mode, like you typethem.When used after:global,:argdo,:windo,:bufdo, ina loop or when another command followsthe display won't be updated while executing thecommands.Cannot be used in thesandbox.:ru:runtime:ru[ntime][!][where]{file} ..ReadEx commands from{file} in each directory givenby'runtimepath' and/or'packpath'. Thereis no errorfor non-existing files.Example::runtime syntax/c.vimThere can be multiple{file} arguments, separated byspaces. Each{file}is searched for in the firstdirectory from'runtimepath', then in the seconddirectory, etc. Useabackslash to includeaspaceinside{file} (although it's better not to use spacesin file names,it causes trouble).When [!]is included, all found files are sourced.Whenitis not included only the first found fileissourced.When[where]is omitted only'runtimepath'is used.Other values:STARTsearch under "start" in'packpath'OPTsearch under "opt" in'packpath'PACKsearch under "start" and "opt" in'packpath'ALLfirst use'runtimepath', then searchunder "start" and "opt" in'packpath'When{file} containswildcardsitis expanded to allmatching files. Example::runtime! plugin/**/*.vimThisis what Vim uses to load theplugin files whenstarting up. This similar command::runtime plugin/**/*.vimwould source the first file only.When'verbose'is one or higher, thereisa messagewhen no file could be found.When'verbose'is two or higher, thereisa messageabout each searched file.:pa:packaddE919:pa[ckadd][!]{name}Search for an optionalplugin directory in'packpath'and source anyplugin files found. The directorymustmatch:pack/*/opt/{name}The directoryis added to'runtimepath' ifit wasn'tthere yet.If the directory pack/*/opt/{name}/after existsitisaddedat theend of'runtimepath'.If loadingpackages from "pack/*/start" was skipped,then this directoryis searched first:pack/*/start/{name}Note that{name}is the directory name, not the nameof the .vim file. All the files matching thepatternpack/*/opt/{name}/plugin/**/*.vimwill be sourced. This allows for using subdirectoriesbelow "plugin", just like with plugins in'runtimepath'.If thefiletype detection was not enabled yet (thisis usually done witha `syntax enable` or `filetype on`command in your.vimrc file), this will also lookfor "{name}/ftdetect/*.vim" files.When the optional!is added noplugin files orftdetect scripts are loaded, only the matchingdirectories are added to'runtimepath'. Thisisuseful in your .vimrc. The plugins will then beloaded during initialization, seeload-plugins (notethat the loading order will be reversed, because eachdirectoryis inserted before others).Note that forftdetect scripts to be loadedyou will need to write `filetypeplugin indent on`AFTER allpackadd! commands.Also seepack-add.{only available when compiled with |+eval|}:packl:packloadall:packl[oadall][!]Load allpackages in the "start" directory under eachentry in'packpath'.First all the directories found are added to'runtimepath', then the plugins found in thedirectories are sourced. This allows foraplugin todepend on something of another plugin, e.g. an"autoload" directory. Seepackload-two-steps forhow this can be useful.Thisis normally done automatically during startup,after loading your.vimrc file. With this commanditcan be done earlier.Packages will be loaded only once. Using:packloadalla second time will have no effect.When the optional!is added this command will loadpackages even when done before.Note that when using:packloadall in thevimrcfile, the'runtimepath' optionis updated, and laterall plugins in'runtimepath' will be loaded, whichmeans they are loaded again. Plugins are expected tohandle that.An error only causes sourcing thescript whereithappens to be aborted, further plugins will be loaded.Seepackages.{only available when compiled with |+eval|}:scripte[ncoding][encoding]:scripte:scriptencodingE167Specify the character encoding used in the script.The following lines will be converted from[encoding]to the value of the'encoding' option, if they aredifferent. Examples:scriptencoding iso-8859-5scriptencoding cp932When[encoding]is empty, no conversionis done. Thiscan be used to restrict conversion toa sequence oflines:scriptencoding euc-jp... lines to be converted ...scriptencoding... not converted ...When conversion isn't supported by the system, thereis no error message and no conversionis done. Whenaline can't be converted thereis no error and theoriginal lineis kept.Don't use "ucs-2" or "ucs-4", scripts cannot be inthese encodings (they would contain NUL bytes).Whena sourcedscript starts witha BOM (Byte OrderMark) inutf-8 format Vim will recognize it, no needto use ":scriptencodingutf-8" then.If you set the'encoding' option in your.vimrc,:scriptencodingmust be placed after that. E.g.:set encoding=utf-8scriptencoding utf-8:scriptv[ersion]{version}:scriptv:scriptversionE999E984E1040Specify the version of Vim for the lines that followin the same file. Only appliesat the toplevel ofsourced scripts, not inside functions.If{version}is higher than what the current Vimversion supportsE999 will be given. You either needto rewrite thescript to makeit work with an olderVim version, or update Vim toa newer version. Seevimscript-version for what changed between versions.:vim9s[cript][noclear]:vim9s:vim9scriptMarksascript fileas containingVim9-scriptcommands. Also seevim9-namespace.E1038Must be the first command in the file.E1039For[noclear] seevim9-reload.Without the+eval feature this changes thesyntaxfor some commands.See:vim9cmd for executing one command withVim9syntax and semantics.:scr:scriptnames:scr[iptnames]List all sourcedscript names, in the order they werefirst encountered. The numberis used for thescriptID<SID>.Forascript that was used with `import autoload` butwas not actually sourced yet an "A"is shown after thescript ID.Forascript that was referred to by one name butafter resolving symbolic links got sourced withanother name the otherscriptis after "->". E.g."20->22" meansscript 20 was sourcedasscript 22.Also seegetscriptinfo().{not available when compiled without the+evalfeature}:scr[iptnames][!]{scriptId}:scriptEditscript{scriptId}. Although ":scriptnames name"works, using ":script name"is recommended.When the current buffer can't beabandoned and the!is not present, the command fails.:fini:finishE168:fini[sh]Stop sourcinga script. Can only be used ina Vimscript file. Thisisa quick way to skip the rest ofthe file. Ifitis used aftera:try but before thematching:finally (if present), the commandsfollowing the ":finally" up to the matching:endtryare executed first. This process applies to allnested ":try"s in the script. The outermost ":endtry"then stops sourcing the script.All commands and command sequences can be repeated by putting them ina namedregister and then executing it. There are two ways to get the commands in theregister:- Use the record command "q". You type the commands once, and while they are being executed they are stored ina register. Easy, because you can see what you are doing. If you makea mistake, "p"ut theregister into the file, edit the command sequence, and then deleteit into theregister again. You can continuerecording by appending to theregister (use anuppercase letter).- Delete oryank the command sequence into the register.Often used command sequences can beput undera function key with the ':map'command.An alternativeis toput the commands ina file, and execute them with the':source!' command. Useful for long command sequences. Can be combined withthe ':map' command toput complicated commands undera function key.The ':source' command readsEx commands froma file ora buffer line by line.You will have to type any needed keyboard input. The ':source!' command readsfromascript file character by character, interpreting each characteras ifyou typed it.Example: When you give the ":!ls" command you get thehit-enter prompt. Ifyou ':source'a file with the line "!ls" in it, you will have to type the<Enter> yourself. But if you ':source!'a file with the line ":!ls" in it,the next characters from that file are read untila<CR>is found. You willnot have to type<CR> yourself, unless ":!ls" was the last line in the file.Itis possible toput ':source[!]' commands in thescript file, so you canmakea top-down hierarchy ofscript files. The ':source' command can benestedas deepas the number of files that can be openedat one time (about15). The ':source!' command can be nested up to 15 levels deep.You can use the "<sfile>"string (literally, thisis nota special key) insideof the sourced file, in places wherea file nameis expected. It will bereplaced by the file name of the sourced file. For example, if you havea"other.vimrc" file in the same directoryas your ".vimrc" file, you can sourceit from your ".vimrc" file with this command::source <sfile>:h/other.vimrcInscript files terminal-dependent key codes are represented byterminal-independent two character codes. This means that they can be usedin the same way on different kinds of terminals. The first character ofakey codeis 0x80 or 128, shown on the screenas "~@". The second one can befound in thelistkey-notation. Any of these codes can also be enteredwithCTRL-V followed by the three digit decimal code. This does NOT work forthe<t_xx>termcap codes, these can only be used in mappings.:source_crnlW15Win32: Files that are read with ":source" normally have<CR><NL><EOL>s.These always work. If you are usinga file with<NL><EOL>s (for example,afile made on Unix), this will be recognized if'fileformats'is not empty andthe first line does notend ina<CR>. This fails if the first line hassomething like ":map<F1> :help^M", where "^M"isa<CR>. If the first lineends ina<CR>, but following ones don't, you will get an error message,because the<CR> from the first lines will be lost.Mac Classic: Files that are read with ":source" normally have<CR><EOL>s.These always work. If you are usinga file with<NL><EOL>s (for example,afile made on Unix), this will be recognized if'fileformats'is not empty andthe first line does notend ina<CR>. Be careful not to usea file with<NL>linebreaks which hasa<CR> in first line.On other systems, Vim expects ":source"ed files toend ina<NL>. Thesealways work. If you are usinga file with<CR><NL><EOL>s (for example,afile made on MS-Windows), all lines will havea trailing<CR>. This may causeproblems for some commands (e.g., mappings). Thereis no automatic<EOL>detection, because it's common to start witha line that definesamappingthat ends ina<CR>, which will confuse the automaton.line-continuationLong lines ina ":source"dEx commandscript file can be split byinsertinga line continuation symbol "\" (backslash)at the start of the next line.There can be whitespace before the backslash, whichis ignored.Example: the lines:set comments=sr:/*,mb:*,el:*/, \://, \b:#, \:%, \n:>, \fb:-are interpretedas if they were given in one line::set comments=sr:/*,mb:*,el:*/,://,b:#,:%,n:>,fb:-All leadingwhitespace characters in the line beforeabackslash are ignored.Note however that trailingwhitespace in the line beforeit cannot beinserted freely;it depends on the position wherea commandis split upwhether additionalwhitespaceis allowed or not.Whenaspaceis required it's best toputit right after the backslash.Aspaceat theend ofa lineis hard to see and may be accidentally deleted.:syn match Comment\ "very long regexp"\ keependInVim9script thebackslash can often be omitted, but not always.Seevim9-line-continuation.Thereisa problem with the ":append" and ":insert" commands: :1append \asdf .Thebackslashis seenasaline-continuation symbol, thus this results in thecommand: :1appendasdf .To avoid this, add the 'C' flag to the'cpoptions' option: :set cpo+=C :1append \asdf . :set cpo-=CNote that when the commands are insidea function, you need to add the 'C'flag when defining the function,itis not relevant when executing it. :set cpo+=C :function Foo() :1append \asdf . :endfunction :set cpo-=Cline-continuation-commentTo adda comment in between the lines start with'"\'. Notice thespaceafter the backslash. Example:let array = ["\ first entry comment\ 'first',"\ second entry comment\ 'second',\ ]Rationale:Most programs work witha trailingbackslash to indicate linecontinuation. Using this in Vim would cause incompatibility with Vi.For example for thisVi mapping::map xx asdf\Therefore the unusual leadingbackslashis used.Startinga comment ina continuation line results in all followingcontinuation lines to be part of the comment. Sinceit was like thisfora long time, when makingit possible to adda comment halfwayasequence of continuation lines,it was not possible to use \", sincethat wasa valid continuation line. Using'"\' comes closest, eventhoughit may looka bit weird. Requiring thespace after thebackslashis to makeit very unlikely thisisa normal comment line.==============================================================================5. Using VimpackagespackagesA Vim packageisa directory that contains one or more plugins. Theadvantages over normal plugins:-A package can be downloadedas an archive and unpacked in its own directory. Thus the files are not mixed with files of other plugins. That makesiteasy to update and remove.-A package can bea git, mercurial, etc. repository. That makesit reallyeasy to update.-A package can contain multiple plugins that depend on each other.-A package can contain plugins that are automatically loaded onstartup and ones that are only loaded when needed with:packadd.Using a package and loading automaticallyLet's assume your Vim files are in the "~/.vim" directory and you want to addapackage fromazip archive "/tmp/foopack.zip":% mkdir -p ~/.vim/pack/foo% cd ~/.vim/pack/foo% unzip /tmp/foopack.zipThe directory name "foo"is arbitrary, you can pick anything you like.You would now have these files under ~/.vim:pack/foo/README.txtpack/foo/start/foobar/plugin/foo.vimpack/foo/start/foobar/syntax/some.vimpack/foo/opt/foodebug/plugin/debugger.vimWhen Vim starts up, after processing your .vimrc,it scans all directories in'packpath' for plugins under the "pack/*/start" directory. First all thosedirectories are added to'runtimepath'. Then all the plugins are loaded.Seepackload-two-steps for how these two steps can be useful.To allow for calling into package functionality while parsing your .vimrc,:colorscheme andautoload will both automatically search under'packpath'as well in addition to'runtimepath'. See the documentation for each fordetails.In the example Vim will find "pack/foo/start/foobar/plugin/foo.vim" and adds"~/.vim/pack/foo/start/foobar" to'runtimepath'.If the "foobar"plugin kicks in and sets the'filetype' to "some", Vim willfind the syntax/some.vim file, because its directoryis in'runtimepath'.Vim will also loadftdetect files, if there are any.Note that the files under "pack/foo/opt" are not loaded automatically, only theones under "pack/foo/start". Seepack-add below for how the "opt" directoryis used.Loadingpackages automatically will not happen if loading pluginsis disabled,seeload-plugins.To loadpackages earlier, so that'runtimepath' gets updated::packloadallThis also works when loading pluginsis disabled. The automatic loading willonly happen once.If the package has an "after" directory, that directoryis added to theend of'runtimepath', so that anything there will be loaded later.Using a single plugin and loading it automaticallyIf you don't havea package buta single plugin, you need to create the extradirectory level:% mkdir -p ~/.vim/pack/foo/start/foobar% cd ~/.vim/pack/foo/start/foobar% unzip /tmp/someplugin.zipYou would now have these files:pack/foo/start/foobar/plugin/foo.vimpack/foo/start/foobar/syntax/some.vimFrom hereit works like above.Optional pluginspack-addTo load an optionalplugin froma pack use the:packadd command::packadd foodebugThis searches for "pack/*/opt/foodebug" in'packpath' and will find~/.vim/pack/foo/opt/foodebug/plugin/debugger.vim and source it.This could be done if some conditions are met. For example, depending onwhether Vim supportsa feature ora dependencyis missing.You can also load an optionalpluginat startup, by putting this command inyour.vimrc::packadd! foodebugThe extra "!"is so that theplugin isn't loaded if Vim was started with--noplugin.Itis perfectly normal fora package to only have files in the "opt"directory. You then need to load eachplugin when you want to use it.Where to put whatSince color schemes, loaded with:colorscheme, are found below"pack/*/start" and "pack/*/opt", you couldput them anywhere. We recommendyouput them below "pack/*/opt", for example".vim/pack/mycolors/opt/dark/colors/very_dark.vim".Filetype plugins shouldgo under "pack/*/start", so that they are alwaysfound. Unless you have more than oneplugin fora file type and want toselect which one to load with:packadd. E.g. depending on the compilerversion:if foo_compiler_version > 34 packadd foo_newelse packadd foo_oldendifThe "after" directoryis most likely not useful ina package. It's notdisallowed though.==============================================================================6. Creating Vimpackagespackage-createThis assumes you write one or more plugins that you distributeasa package.If you have two unrelated plugins you would use two packages, so that Vimusers can choose what they include or not. Or you can decide to use onepackage with optional plugins, and tell the user to add the preferred ones with:packadd.Decide how you want to distribute the package. You can create an archive oryou could usea repository. An archive can be used by more users, butisabit harder to update toa new version.A repository can usually be keptup-to-date easily, butit requiresa program like "git" to be available.You cando both, github can automatically create an archive fora release.Your directory layout would be like this: start/foobar/plugin/foo.vim" always loaded, defines commands start/foobar/plugin/bar.vim" always loaded, defines commands start/foobar/autoload/foo.vim" loaded when foo command used start/foobar/doc/foo.txt"help for foo.vim start/foobar/doc/tags"helptags start/foobar/lang/<lang_id>/LC_MESSAGES/foobar.mo"messages for theplugin in the"<lang_id> language. These files are" optional. opt/fooextra/plugin/extra.vim" optional plugin, defines commands opt/fooextra/autoload/extra.vim" loaded when extra command used opt/fooextra/doc/extra.txt"help for extra.vim opt/fooextra/doc/tags"helptagsThis allows for the user to do:mkdir ~/.vim/packcd ~/.vim/packgit clone https://github.com/you/foobar.git myfoobarHere "myfoobar"isa name that the user can choose, the only conditionis thatit differs from other packages.In your documentation you explain what the plugins do, and tell the user howto load the optional plugin::packadd! fooextraYou could add this packadd command in one of your plugins, to be executed whenthe optionalpluginis needed.package-docpackage-documentationRun the:helptags command to generate the doc/tags file. Including thisgenerated file in the package means that the user can drop the package in thepack directory and thehelp command works right away. Don't forget to re-runthe command afterchanging theplugin help::helptags path/start/foobar/doc:helptags path/opt/fooextra/docpackage-translationIn order foraplugin to display translated messages,a few steps arerequired.Theauthor of theplugin who likes to translatemessagesmust define the nameof the package and the location of the directory where the translations can befound using thebindtextdomain() function::call bindtextdomain("foobar",\ fnamemodify(expand("<script>"), ':p:h') .. '/../lang/')Where: "foobar"is the unique package identifier by which thegettext()function will later search for translation strings for thisplugin. "lang/"is the relative or absolute path to the directory structurewhere the translation fileis located.The directory structure where the message translation files should be placedis (from the top-level directory of the package):"lang/<lang_id>/LC_MESSAGES". For the format of<lang_id> seemulti-lang.This function needs to be called only once during theinitialization of theplugin.Once thisis done, thegettext() function can be used to retrieve translatedmessages::echo gettext("Hello", "foobar")Where: "Hello"the message "Hello" to be translated into the user's language:lang "foobar"the package identifier, which was previously defined using thebindtextdomain() function.After that you need to createatemplate file for translation- POT-file.Todo this, execute the following commands (using the Vim repository):cd ~/forkvim/src/pomake -f Makefile "PLUGPACKAGE={package}" \"PO_PLUG_INPUTLIST={path/to/scripts-that-need-translations.vim}" \["POT_PLUGPACKAGE_PATH={path/where/to/write/{package}.pot}" \]["VIMPROG={path/to/vim} \]{package}.potWhere:PLUGPACKAGEA variable containing the name of the package that wespecified in thebindtextdomain() andgettext() functions, for example, "foobar".PO_PLUG_INPUTLISTA variable containing scripts that have stringsto translate, i.e. where we specified thegettext()function. Scripts are specified with an absoluteor relative path. Example: start/foobar/plugin/bar.vimuse blanks to separate scripts.POT_PLUGPACKAGE_PATHA variable containing the directory where the preparedPOT file will be saved. Thisis nota required variable,if no directoryis specified, then the POT file willbe placed in the "src/po" directory.VIMPROGA variable containinga directory witha working Vim.If the Vim editoris already built and installed, andis contained in the $PATH environment variable,then you can specify just the name of the vimexecutable.{package}.potThisis the Target. Itis specifiedas the name ofthe package, for example, "foobar" with the additionof the .pot extension.Oncea POT fileis created, its contents are copied into separate PO files foreach language for which the translation will be prepared.When the translationis finished,itis necessary to convert the PO files intobinary MO-files format and place these MO-files into the "lang/" directory, thestructure of which we created earlier.Todo this, run the following commands:cd ~/forkvim/src/pomake -f Makefile "PLUGPACKAGE={package}" \"PO_PLUGPACKAGE={path/to/{lang}.po}" \["MO_PLUGPACKAGE_PATH={path/to/lang/<lang_id>/LC_MESSAGES}" \]{package}.moWhere:PLUGPACKAGEA variable containing the name of the package that wespecified in thebindtextdomain() andgettext()functions, for example, "foobar".PO_PLUGPACKAGEA variable containinga PO file. The fileis specifiedwith an absolute or relative path. For example,"~/myproject/translate/en.po"MO_PLUGPACKAGE_PATHA variable containing the structure of the "lang/"directory, where the file with translations will beplaced, for example, "foobar.mo". Thisis nota required variable, if the directoryis not specified,the MO file will be saved in the "src/po" directory.{package}.moThisis the Target. Itis specifiedas the name ofthe package, for example, "foobar" with the additionof the .mo extension.package-translate_exampleLet's showit all on some concrete example and translate the"ftplugin/aap.vim" file intoRussian and German.First, let's prepare the "aap.vim" file, specifyingbindtextdomain() andgettext() function calls in it. " Only do this when not done yet for this buffer if exists("b:did_ftplugin") finish endif " Don't load another plugin for this buffer let b:did_ftplugin = 1 call bindtextdomain("aap", fnamemodify(expand("<script>"), ':p:h') .. '/../lang/') " Reset 'formatoptions', 'comments', 'commentstring' and 'expandtab' to undo " this plugin. let b:undo_ftplugin = "setl fo< com< cms< et<" " Set 'formatoptions' to break comment lines but not other lines, " and insert the comment leader when hitting <CR> or using "o". setlocal fo-=t fo+=croql " Set 'comments' to format dashed lists in comments. setlocal comments=s:#\ -,m:#\ \ ,e:#,n:#,fb:- setlocal commentstring=#\ %s " Expand tabs to spaces to avoid trouble. setlocal expandtab if (has("gui_win32") || has("gui_gtk")) && !exists("b:browsefilter") let b:browsefilter = gettext("Aap Recipe Files (*.aap)\t*.aap\n", "aap") if has("win32") let b:browsefilter ..= gettext("All Files (*.*)\t*\n", "aap") else let b:browsefilter ..= gettext("All Files (*)\t*\n", "aap") endif let b:undo_ftplugin ..= " | unlet! b:browsefilter" endifNow let's createa POT file forit (example uses Windows paths):cd /d f:\forkvim\src\po (the following command must be entered in one line, here it is separated for example)nmake.exe -f Make_mvc.mak "PLUGPACKAGE=aap" "PO_PLUG_INPUTLIST=d:\Programs\vim\vim91\ftplugin\aap.vim" "POT_PLUGPACKAGE_PATH=e:\project\translate\plugins" "VIMPROG=d:\Programs\vim\vim91\vim.exe" aap.potAfter the POT file of our packageis created,go to the directory where wesavedit and perform the translation.cd /d e:\project\translate\pluginscopy aap.pot ru.pocopy aap.pot de.poWe have prepareda PO file witha translation into Russian: # Test plugins translate # msgid "" msgstr "" "Project-Id-Version: aap\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2024-06-23 14:58+0300\n" "PO-Revision-Date: 2024-06-23 14:58+0300\n" "Last-Translator: Restorer\n" "Language-Team: RuVim\n" "Language: ru\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #: ../../runtime/ftplugin/aap.vim:32 msgid "Aap Recipe Files (*.aap)\t*.aap\n" msgstr "Файлы инструкций Aap (*.aap)\t*.aap\n" #: ../../runtime/ftplugin/aap.vim:34 msgid "All Files (*.*)\t*\n" msgstr "Все файлы (*.*)\t*\n" #: ../../runtime/ftplugin/aap.vim:36 msgid "All Files (*)\t*\n" msgstr "Все файлы (*)\t*\n"And the PO file in German: # Test plugins translate # msgid "" msgstr "" "Project-Id-Version: aap\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2024-06-23 14:58+0300\n" "PO-Revision-Date: 2024-06-24 13:11+0300\n" "Last-Translator: Restorer\n" "Language-Team: German\n" "Language: de\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #: ../../runtime/ftplugin/aap.vim:32 msgid "Aap Recipe Files (*.aap)\t*.aap\n" msgstr "Aap-Rezeptdateien (*.aap)\t*.aap\n" #: ../../runtime/ftplugin/aap.vim:34 msgid "All Files (*.*)\t*\n" msgstr "Alle Dateien (*.*)\t*.*\n" #: ../../runtime/ftplugin/aap.vim:36 msgid "All Files (*)\t*\n" msgstr "Alle Dateien (*)\t*\n"Now convert these files into MO files so thatgettext() can display messagetranslations.Note that since thisis nota specializedplugin package, wewillput the MO files in the "lang/" directory of the Vim editor.Type the following commands:cd /d f:\forkvim\src\po (the following commandmust be entered in one line, hereitis separated for example) For Russian:nmake.exe -f Make_mvc.mak "PLUGPACKAGE=aap""PO_PLUGPACKAGE=e:\project\translate\plugins\ru.po""MO_PLUGPACKAGE_PATH=d:\Programs\vim\vim91\lang\ru\LC_MESSAGES"aap.mo For German:nmake.exe -f Make_mvc.mak "PLUGPACKAGE=aap""PO_PLUGPACKAGE=e:\project\translate\plugins\de.po""MO_PLUGPACKAGE_PATH=d:\Programs\vim\vim91\lang\de\LC_MESSAGES"aap.moThat's it, the translations are ready and you can see the plugin'smessagesin your native language.Let's also try to translateaplugin package. For example, whena packagecontains several scripts containing strings that need to be translated.For example, let's translate the "netrw" package into Japanese.For this example, we will translate onlya few lines from this package.Let's prepare the scripts where we need to translate the message strings.The file "autoload\netrw.vim": " Load Once: if &cp || exists("g:loaded_netrw") finish endif call bindtextdomain("netrw", fnamemodify(expand("<script>"), ':p:h') .. '/../lang/') " Check that vim has patches that netrw requires. " Patches needed for v7.4: 1557, and 213. " (netrw will benefit from vim's having patch#656, too) let s:needspatches=[1557,213] if exists("s:needspatches") for ptch in s:needspatches if v:version < 704 || (v:version == 704 && !has("patch".ptch)) if !exists("s:needpatch{ptch}") unsilent echomsg gettext("***sorry*** this version of netrw requires vim v7.4 with patch#", "netrw") .. ptch endif let s:needpatch{ptch}= 1 finish endif endfor endifThe file "autoload\netrwSettings.vim": " Load Once: if exists("g:loaded_netrwSettings") || &cp finish endif call bindtextdomain("netrw", fnamemodify(expand("<script>"), ':p:h') .. '/../lang/') let g:loaded_netrwSettings = "v18" if v:version < 700 echohl WarningMsg echo gettext("***warning*** this version of netrwSettings needs vim 7.0", "netrw") echohl Normal finish endifNow we will preparea POT file for further translation of messages.Execute the following commands:cd ~/forkvim/src/pomake -f Makefile "VIMPROG=/usr/local/bin/vim" "PLUGPACKAGE=netrw" \"POT_PLUGPACKAGE_PATH=~/project/translate/plugins" \"PO_PLUG_INPUTLIST=../../runtime/autoload/netrw.vim../../runtime/autoload/netrwSettings.vim" \netrw.potGo to the directory with the POT file and make the translation:cd ~/project/translate/pluginscp ./netrw.pot ja.poWhen we have the translation ready in the "ja.po" file: # Test plugins translate # msgid "" msgstr "" "Project-Id-Version: netrw\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2024-06-23 17:14+0300\n" "PO-Revision-Date: 2024-06-23 17:14+0300\n" "Last-Translator: Restorer\n" "Language-Team: Japanese\n" "Language: ja\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #: ../../runtime/autoload/netrw.vim:51 msgid "***sorry*** this version of netrw requires vim v7.4 with patch#" msgstr "" "***申し訳ありません***このバージョンのnetrwには、パッチ付きのvim v7.4が必要です#" #: ../../runtime/autoload/netrwSettings.vim:28 msgid "***warning*** this version of netrwSettings needs vim 7.0" msgstr "***警告***このバージョンのnetrwSettingsにはvim7.0が必要です"Convert ja.po toa MO file:cd ~/forkvim/src/pomake -f Makefile "PLUGPACKAGE=netrw" \"PO_PLUGPACKAGE=~/project/translate/plugins/ja.po" \"MO_PLUGPACKAGE_PATH=/usr/local/share/vim/vim91/lang/ja/LC_MESSAGES" \netrw.moExecuting those steps will allow you to get translation of any third-partyplug-in packages.Dependencies between pluginspackload-two-stepsSuppose you have two plugins that depend on the same functionality. You canput the common functionality in anautoload directory, so thatit will befound automatically. Your package would have these files:pack/foo/start/one/plugin/one.vimcall foolib#getit()pack/foo/start/two/plugin/two.vimcall foolib#getit()pack/foo/start/lib/autoload/foolib.vimfunc foolib#getit()This works, because loadingpackages will first add all found directories to'runtimepath' before sourcing the plugins.==============================================================================7. Debugging scriptsdebug-scriptsBesides the obviousmessages that you can add to your scripts to find out whatthey are doing, Vim offersa debug mode. This allows you to step throughasourced file or user function and set breakpoints.NOTE: The debugging modeis far from perfect. Debugging will have sideeffects on how Vim works. You cannot useit to debug everything. Forexample, the displayis messed up by the debugging messages.An alternative to debug modeis setting the'verbose' option. Witha biggernumberit will give moreverbosemessages about what Vimis doing.STARTING DEBUG MODEdebug-modeTo enter debugging mode use one of these methods:1. Start Vim with the-D argument:vim -D file.txt Debugging will startas soonas the firstvimrc fileis sourced. Thisis useful to find out whatis happening when Vimisstarting up.A side effectis that Vim will switch theterminal mode before initialisations have finished, with unpredictable results. Fora GUI-only version (Windows, Macintosh) the debugging will startas soonas theGUIwindow has been opened. To make this happen early, adda ":gui" command in thevimrc file.:debug2. Runa command with ":debug" prepended. Debugging will only be done while this command executes. Useful for debugginga specificscript or user function. And for scripts andfunctions used by autocommands. Example::debug edit test.txt.gz3. Seta breakpoint ina sourced file or user function. You coulddo this in the command line:vim -c "breakadd file */explorer.vim" . This will run Vim and stop in the first line of the "explorer.vim" script. Breakpoints can also be set while in debugging mode.In debugging mode every executed commandis displayed beforeitis executed.Comment lines, empty lines and lines that are not executed are skipped. Whena line contains two commands, separated by "|", each command will be displayedseparately.DEBUG MODEOnce in debugging mode, the usualEx commands can be used. For example, toinspect the value ofa variable:echo idxWhen insidea user function, this will print the value of the local variable"idx". Prepend "g:" to get the value ofa global variable:echo g:idxAll commands are executed in the context of the current function or script.You can also set options, for example setting or resetting'verbose' will showwhat happens, but you might want to setit just before executing the lines youare interested in::set verbose=20Commands that require updating the screen should be avoided, because theireffect won't be noticed until after leaving debug mode. For example::helpwon't be very helpful.Thereisa separate command-linehistory for debug mode.NOTE: InVim9 script, ifa commandis writtenat thescript level andcontinues on the next line, not using the old way withabackslash for linecontinuation, only the first lineis printed before the debugging prompt.The line number fora function lineis relative to the start of the function.If you have trouble figuring out where you are, edit the file that definesthe function in another Vim, search for the start of the function anddo"99j".Replace "99" with the line number.Additionally, these commands can be used:>contcontContinue execution until the next breakpointis hit.>quitquitAbort execution. Thisis like usingCTRL-C, somethings might still be executed, doesn't aborteverything. Still stopsat the next breakpoint.>nextnextExecute the command and come back to debug mode whenit's finished. This steps over user function callsand sourced files.>stepstepExecute the command and come back to debug mode forthe next command. This steps into called userfunctions and sourced files.>interruptinterruptThisis like usingCTRL-C, but unlike ">quit" comesback to debug mode for the next command thatisexecuted. Useful fortesting:finally and:catchon interrupt exceptions.>finishfinishFinish the currentscript or user function and comeback to debug mode for the command after the one thatsourced or called it.>bt>backtrace>wherebacktraceShow the call stacktrace for current debugging session.btwhere>frameframeNGoes toN backtrace level.+ and-signs makemovementrelative. E.g., ":frame +3" goes three frames up.>upupGoes one level up from call stacktrace.>downdownGoes one level down from call stacktrace.About the additional commands in debug mode:- Thereis no command-line completion for them, you get the completion for the normalEx commands only.- You can shorten them, up toa single character, unless more than one command starts with the same letter. "f" stands for "finish", use "fr" for "frame".- Hitting<CR> will repeat the previous one. When doing another command, thisis reset (because it's not clear what you want to repeat).- When you want to use theEx command with the same name, prependa colon: ":cont", ":next", ":finish" (or shorter).vim9-debugWhen debugginga compiled:def function, "step" will stop before everyexecuted line, not every single instruction. Thusit works mostly likea notcompiled function. Access to localvariablesis limited you can use:echo varnameBut not much else.When executinga command thatis nota specific bytecode instruction butexecuted likea normalEx command, "step" will stop once in the compiledcontext, where localvariables can be inspected, and once just beforeexecuting the command.Ina:def functionvariables that haven't been declared yet cannot beinspected. Variables that have been declared can be inspected, also when theblock they were declared in has finished. In commands this would not bepossible, thusis slightly misleading (but can be useful).The backtrace shows the hierarchy of function calls, e.g.:>bt 3 function One[3] 2 Two[3]->1 Three[3] 0 Fourline 1: let four = 4The "->" points to the current frame. Use "up", "down" and "frameN" toselect another frame.In the current frame you can evaluate the local function variables. Thereisno way to see the commandat the current line yet.DEFINING BREAKPOINTS:breaka:breakadd:breaka[dd] func[lnum]{name}Seta breakpoint ina function. Example::breakadd func ExploreDoesn't check fora valid function name, thus the breakpointcan be set before the functionis defined.:breaka[dd] file[lnum]{name}Seta breakpoint ina sourced file. Example::breakadd file 43 .vimrc:breaka[dd] hereSeta breakpoint in the current line of the current file.Like doing::breakadd file <cursor-line> <current-file>Note that this only works for commands that are executed whensourcing the file, not fora function defined in that file.:breaka[dd]expr{expression}Setsa breakpoint, that will break whenever the{expression}evaluates toa different value. Example::breakadd expr g:lnumWill break, whenever the global variable lnum changes.Errors in evaluation are suppressed, you can use the name ofavariable that does not exist yet. This also means you willnot notice anything if theexpression hasa mistake.Note if you watchascript-variable this will breakwhen switching scripts, since thescript variableis onlyvalid in thescript whereit has been defined and if thatscriptis called from several other scripts, this will stopwhenever that particular variable will become visible orinaccessible again.The[lnum]is the line number of the breakpoint. Vim will stopat or afterthis line. When omitted line 1is used.:debug-name{name}isapattern thatis matched with the file or function name. Thepatternis like whatis used for autocommands. Theremust bea full match (asif thepattern starts with "^" and ends in "$").A "*" matches any sequenceof characters.'ignorecase'is not used, but "\c" can be used in thepatternto ignorecase/\c. Don't include the () for the function name!The match for sourced scriptsis done against the full file name. If no pathis specified the current directoryis used. Examples:breakadd file explorer.vimmatches "explorer.vim" in the current directory.breakadd file *explorer.vimmatches ".../plugin/explorer.vim", ".../plugin/iexplorer.vim", etc.breakadd file */explorer.vimmatches ".../plugin/explorer.vim" and "explorer.vim" in any other directory.The match forfunctionsis done against the nameas it's shown in the outputof ":function". However, for localfunctions the script-specific prefix suchas "<SNR>99_"is ignored to makeit easier to matchscript-localfunctionswithout knowing the ID of the script.Note thatfunctions are first loaded and later executed. When they are loadedthe "file" breakpoints are checked, when they are executed the "func"breakpoints.DELETING BREAKPOINTS:breakd:breakdelE161:breakd[el]{nr}Delete breakpoint{nr}. Use:breaklist to see the number ofeach breakpoint.:breakd[el] *Delete all breakpoints.:breakd[el] func[lnum]{name}Deletea breakpoint ina function.:breakd[el] file[lnum]{name}Deletea breakpoint ina sourced file.:breakd[el] hereDeletea breakpointat the current line of the current file.When[lnum]is omitted, the first breakpoint in the function or fileisdeleted.The{name}must be exactly the sameas what was typed for the ":breakadd"command. "explorer", "*explorer.vim" and "*explorer*" are different.LISTING BREAKPOINTS:breakl:breaklist:breakl[ist]List all breakpoints.OBSCURE:debugg:debuggreedy:debugg[reedy]Read debug mode commands from the normal input stream, insteadof getting them directly from the user. Only useful for testscripts. Example: echo 'q^Mq' | vim -e -s -c debuggreedy -c 'breakadd file script.vim' -S script.vim:0debugg[reedy]Undo ":debuggreedy": get debug mode commands directly from theuser, don't use typeahead for debug commands.==============================================================================8. ProfilingprofileprofilingProfiling means that Vim measures the time thatis spent on executingfunctions and/or scripts. The+profile featureis required for this.Itis included when Vim was compiled with "huge" features.You can also use thereltime() function to measure time. This only requiresthe+reltime feature, whichis present in more builds.Forprofilingsyntax highlighting see:syntime.For example, toprofile the one_script.vimscript file::profile start /tmp/one_script_profile:profile file one_script.vim:source one_script.vim:exit:prof[ile] start{fname}:prof:profileE750Start profiling, write the output in{fname} upon exit or whena `:profile stop` or `:profile dump` commandis invoked."~/" and environmentvariables in{fname} will be expanded.If{fname} already existsit will be silently overwritten.The variablev:profilingis set to one.:prof[ile] stopWrite the collectedprofiling information to the logfile andstop profiling. You can use the `:profile start` command toclear theprofiling statistics and startprofiling again.:prof[ile] pauseStopprofiling until the next `:profile continue` command.Can be used when doing something that should not be counted(e.g., an external command). Does not nest.:prof[ile] continueContinueprofiling after `:profile pause`.:prof[ile] func{pattern}Profile function that matches thepattern{pattern}.See:debug-name for how{pattern}is used.:prof[ile][!] file{pattern}Profilescript file that matches thepattern{pattern}.See:debug-name for how{pattern}is used.This only profiles thescript itself, not thefunctionsdefined in it.When the [!]is added then allfunctions defined in thescriptwill also be profiled.Note thatprofiling only starts when thescriptis loadedafter this command.A:profile command in thescript itselfwon't work.:prof[ile] dumpWrite the current state ofprofiling to the logfileimmediately. After running this command, Vim continues tocollect theprofiling statistics.:profd[el]...:profd:profdelStopprofiling for the arguments specified. See:breakdelfor the arguments. Examples:profdel func MyFuncprofdel file MyScript.vimprofdel hereYoumust always start witha ":profile start fname" command. The resultingfileis written when Vim exits. For example, toprofile one specificfunction:profile start /tmp/vimprofileprofile func MyFuncHereis an example of the output, with linenumbers prepended for the explanation: 1 FUNCTION Test2() 2 Called 1 time 3 Total time: 0.155251 4 Self time: 0.002006 5 6 count total (s) self (s) 79 0.000096 for i in range(8) 88 0.153655 0.000410 call Test3() 98 0.000070 endfor 10 " Ask a question 111 0.001341 echo input("give me an answer: ")The header (lines 1-4) gives the time for the whole function. The "Total"timeis the time passed while the function was executing. The "Self" timeisthe "Total" time reduced by time spent in:- other user definedfunctions- sourced scripts- executedautocommands- external (shell) commandsLines 7-11 show the time spent in each executed line. Lines that are notexecuteddo not count. Thusa comment lineis never counted.The Count column shows how many timesa line was executed.Note that the"for" command in line 7is executed one more timeas the following lines.Thatis because the lineis also executed to detect theend of the loop.The time Vim spends waiting for user input isn't countedat all. Thus howlong you take to respond to theinput() promptis irrelevant.Profiling should givea good indication of where timeis spent, but keep inmind there arevarious things that may clobber the results:- The accuracy of the time measured depends on the gettimeofday(), or clock_gettime() if available, system function. The accuracy ranges from 1/100 second to nanoseconds. With clock_gettime() the times are displayed in nanoseconds, otherwise microseconds. You can usehas("prof_nsec").- Real elapsed timeis measured, if other processes are busy they may cause delaysat unpredictable moments. You may want to run theprofiling several times and use the lowest results.- If you have several commands in one line you only get one time. Split the line to see the time for the individual commands.- The time of the lines added upis mostlyless than the time of the whole function. Thereis some overhead in between.- Functions that are deleted before Vim exits will not produceprofiling information. You can check thev:profiling variable if needed::if !v:profiling: delfunc MyFunc:endif- Profiling may give weird results on multi-processor systems, when sleep mode kicks in or the processor frequencyis reduced to save power.- The "self" timeis wrong whena functionis used recursively. vim:tw=78:ts=8:noet:ft=help:norl: