annotate runtime/doc/repeat.txt @ 33060:897f3ed27be2 v9.0.1818

patch 9.0.1818: dynamically linking perl is broken Commit: https://github.com/vim/vim/commit/55460da26c2756ec057c03c7d8641eda861bfcd2 Author: Christian Brabandt <cb@256bit.org> Date: Tue Aug 29 21:31:28 2023 +0200 patch 9.0.1818: dynamically linking perl is broken Problem: dynamically linking perl is broken Solution: Fix all issues This is a combination of several commits: 1) Fix if_perl.xs not being able to build on all versions of Perl (5.30) This fixes the dynamic builds of Perl interface. The Perl interface file previously had to manually copy and paste misc inline functions verbatim from the Perl headers, because we defined `PERL_NO_INLINE_FUNCTIONS` which prevents us form getting some function definitions. The original reason we defined it was because those inline functions would reference Perl functions that would cause linkage errors. This is a little fragile as every time a new version of Perl comes out, we inevitably have to copy over new versions of inline functions to our file, and it's also easy to miss updates to existing functions. Instead, remove the `PERL_NO_INLINE_FUNCTIONS` define, remove the manual copy-pasted inline functions. Simply add stub implementations of the missing linked functions like `Perl_sv_free2` and forward them to the DLL version of the function at runtime. There are only a few functions that need this treatment, and it's a simple stub so there is very low upkeep compared to copying whole implementations to the file. Also, fix the configure script so that if we are using dynamic linkage, we don't pass `-lperl` to the build flags, to avoid accidental external linkage while using dynamic builds. This is similar to how Python integration works. 2) Fix GIMME_V deprecation warnings in Perl 5.38 Just use GIMME_V, and only use GIMME when using 5.30 to avoid needing to link Perl_block_gimme. We could provide a stub like the other linked functions like Perl_sv_free2, but simply using GIMME is the simplest and it has always worked before. 3) Fix Perl 5.38 issues Fix two issues: 3.1. Perl 5.38 links against more functions in their inline headers, so we need to stub them too. 3.2. Perl 5.38 made Perl_get_context an inline function, but *only* for non-Windows build. Fix that. Note that this was happening in Vim currently, as it would build, but fail to run Perl code at runtime. 4) Fix Perl 5.36/5.38 when thread local is used Perl 5.36 introduced using `_Thread_local` for the current context, which causes inline functions to fail. Create a stub `PL_current_context` thread local variable to satisfy the linker for inlined functions. Note that this is going to result in a different `PL_current_context` being used than the one used in the library, but so far from testing it seems to work. 5) Add docs for how to build Perl for dynamic linking to work closes: #12827 closes: #12914 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 Tue, 29 Aug 2023 22:15:03 +0200
parents 695b50472e85
children 484543479bd7
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
32670
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1 *repeat.txt* For Vim version 9.0. Last change: 2023 May 26
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
2
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
3
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
4 VIM REFERENCE MANUAL by Bram Moolenaar
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
5
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
6
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
7 Repeating commands, Vim scripts and debugging *repeating*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
8
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
9 Chapter 26 of the user manual introduces repeating |usr_26.txt|.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
10
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
11 1. Single repeats |single-repeat|
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
12 2. Multiple repeats |multi-repeat|
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
13 3. Complex repeats |complex-repeat|
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
14 4. Using Vim scripts |using-scripts|
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
15 5. Using Vim packages |packages|
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
16 6. Creating Vim packages |package-create|
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
17 7. Debugging scripts |debug-scripts|
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
18 8. Profiling |profiling|
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
19
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
20 ==============================================================================
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
21 1. Single repeats *single-repeat*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
22
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
23 *.*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
24 . Repeat last change, with count replaced with [count].
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
25 Also repeat a yank command, when the 'y' flag is
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
26 included in 'cpoptions'. Does not repeat a
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
27 command-line command.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
28
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
29 Simple changes can be repeated with the "." command. Without a count, the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
30 count of the last change is used. If you enter a count, it will replace the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
31 last one. |v:count| and |v:count1| will be set.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
32
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
33 If the last change included a specification of a numbered register, the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
34 register number will be incremented. See |redo-register| for an example how
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
35 to use this.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
36
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
37 Note that when repeating a command that used a Visual selection, the same SIZE
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
38 of area is used, see |visual-repeat|.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
39
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
40 *@:*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
41 @: Repeat last command-line [count] times.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
42 {not available when compiled without the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
43 |+cmdline_hist| feature}
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
44
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
45
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
46 ==============================================================================
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
47 2. Multiple repeats *multi-repeat*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
48
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
49 *:g* *:global* *E148*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
50 :[range]g[lobal]/{pattern}/[cmd]
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
51 Execute the Ex command [cmd] (default ":p") on the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
52 lines within [range] where {pattern} matches.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
53
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
54 :[range]g[lobal]!/{pattern}/[cmd]
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
55 Execute the Ex command [cmd] (default ":p") on the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
56 lines within [range] where {pattern} does NOT match.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
57
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
58 *:v* *:vglobal*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
59 :[range]v[global]/{pattern}/[cmd]
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
60 Same as :g!.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
61
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
62 Example: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
63 :g/^Obsolete/d _
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
64 Using the underscore after `:d` avoids clobbering registers or the clipboard.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
65 This also makes it faster.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
66
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
67 Instead of the '/' which surrounds the {pattern}, you can use any other
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
68 single byte character, but not an alphabetic character, '\', '"', '|' or '!'.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
69 This is useful if you want to include a '/' in the search pattern or
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
70 replacement string.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
71
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
72 For the definition of a pattern, see |pattern|.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
73
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
74 NOTE [cmd] may contain a range; see |collapse| and |edit-paragraph-join| for
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
75 examples.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
76
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
77 The global commands work by first scanning through the [range] lines and
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
78 marking each line where a match occurs (for a multi-line pattern, only the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
79 start of the match matters).
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
80 In a second scan the [cmd] is executed for each marked line, as if the cursor
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
81 was in that line. For ":v" and ":g!" the command is executed for each not
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
82 marked line. If a line is deleted its mark disappears.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
83 The default for [range] is the whole buffer (1,$). Use "CTRL-C" to interrupt
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
84 the command. If an error message is given for a line, the command for that
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
85 line is aborted and the global command continues with the next marked or
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
86 unmarked line.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
87 *E147*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
88 When the command is used recursively, it only works on one line. Giving a
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
89 range is then not allowed. This is useful to find all lines that match a
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
90 pattern and do not match another pattern: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
91 :g/found/v/notfound/{cmd}
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
92 This first finds all lines containing "found", but only executes {cmd} when
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
93 there is no match for "notfound".
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
94
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
95 Any Ex command can be used, see |ex-cmd-index|. To execute a Normal mode
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
96 command, you can use the `:normal` command: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
97 :g/pat/normal {commands}
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
98 Make sure that {commands} ends with a whole command, otherwise Vim will wait
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
99 for you to type the rest of the command for each match. The screen will not
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
100 have been updated, so you don't know what you are doing. See |:normal|.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
101
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
102 The undo/redo command will undo/redo the whole global command at once.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
103 The previous context mark will only be set once (with "''" you go back to
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
104 where the cursor was before the global command).
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
105
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
106 The global command sets both the last used search pattern and the last used
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
107 substitute pattern (this is vi compatible). This makes it easy to globally
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
108 replace a string:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
109 :g/pat/s//PAT/g
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
110 This replaces all occurrences of "pat" with "PAT". The same can be done with:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
111 :%s/pat/PAT/g
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
112 Which is two characters shorter!
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
113
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
114 When using "global" in Ex mode, a special case is using ":visual" as a
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
115 command. This will move to a matching line, go to Normal mode to let you
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
116 execute commands there until you use |Q| to return to Ex mode. This will be
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
117 repeated for each matching line. While doing this you cannot use ":global".
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
118 To abort this type CTRL-C twice.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
119
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
120 ==============================================================================
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
121 3. Complex repeats *complex-repeat*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
122
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
123 *q* *recording*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
124 q{0-9a-zA-Z"} Record typed characters into register {0-9a-zA-Z"}
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
125 (uppercase to append). The 'q' command is disabled
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
126 while executing a register, and it doesn't work inside
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
127 a mapping and |:normal|.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
128
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
129 Note: If the register being used for recording is also
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
130 used for |y| and |p| the result is most likely not
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
131 what is expected, because the put will paste the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
132 recorded macro and the yank will overwrite the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
133 recorded macro.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
134
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
135 Note: The recording happens while you type, replaying
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
136 the register happens as if the keys come from a
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
137 mapping. This matters, for example, for undo, which
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
138 only syncs when commands were typed.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
139
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
140 q Stops recording. (Implementation note: The 'q' that
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
141 stops recording is not stored in the register, unless
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
142 it was the result of a mapping)
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
143
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
144 *@*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
145 @{0-9a-z".=*+} Execute the contents of register {0-9a-z".=*+} [count]
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
146 times. Note that register '%' (name of the current
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
147 file) and '#' (name of the alternate file) cannot be
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
148 used.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
149 The register is executed like a mapping, that means
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
150 that the difference between 'wildchar' and 'wildcharm'
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
151 applies, and undo might not be synced in the same way.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
152 For "@=" you are prompted to enter an expression. The
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
153 result of the expression is then executed.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
154 See also |@:|.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
155
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
156 *@@* *E748*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
157 @@ Repeat the previous @{0-9a-z":*} [count] times.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
158
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
159 *:@*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
160 :[addr]@{0-9a-z".=*+} Execute the contents of register {0-9a-z".=*+} as an Ex
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
161 command. First set cursor at line [addr] (default is
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
162 current line). When the last line in the register does
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
163 not have a <CR> it will be added automatically when
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
164 the 'e' flag is present in 'cpoptions'.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
165 For ":@=" the last used expression is used. The
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
166 result of evaluating the expression is executed as an
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
167 Ex command.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
168 Mappings are not recognized in these commands.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
169 When the |line-continuation| character (\) is present
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
170 at the beginning of a line in a linewise register,
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
171 then it is combined with the previous line. This is
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
172 useful for yanking and executing parts of a Vim
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
173 script.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
174 Future: Will execute the register for each line in the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
175 address range.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
176
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
177 :[addr]*{0-9a-z".=+} *:star-compatible*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
178 When '*' is present in 'cpoptions' |cpo-star|, use
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
179 ":*" in the same way as ":@". This is NOT the default
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
180 when 'nocompatible' is used. When the '*' flag is not
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
181 present in 'cpoptions', ":*" is an alias for ":'<,'>",
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
182 select the Visual area |:star|.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
183
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
184 *:@:*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
185 :[addr]@: Repeat last command-line. First set cursor at line
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
186 [addr] (default is current line).
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
187
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
188 :[addr]@ *:@@*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
189 :[addr]@@ Repeat the previous :@{register}. First set cursor at
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
190 line [addr] (default is current line).
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
191
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
192 ==============================================================================
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
193 4. Using Vim scripts *using-scripts*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
194
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
195 For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
196
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
197 *:so* *:source* *load-vim-script*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
198 :so[urce] {file} Read Ex commands from {file}. These are commands that
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
199 start with a ":".
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
200 Triggers the |SourcePre| autocommand.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
201 *:source-range*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
202 :[range]so[urce] [++clear]
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
203 Read Ex commands from the [range] of lines in the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
204 current buffer. When [range] is omitted read all
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
205 lines.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
206
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
207 When sourcing commands from the current buffer, the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
208 same script-ID |<SID>| is used even if the buffer is
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
209 sourced multiple times. If a buffer is sourced more
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
210 than once, then the functions in the buffer are
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
211 defined again.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
212
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
213 To source a range of lines that doesn't start with the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
214 |:vim9script| command in Vim9 script context, the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
215 |:vim9cmd| modifier can be used. If you use a Visual
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
216 selection and type ":", the range in the form "'<,'>"
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
217 can come before it: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
218 :'<,'>vim9cmd source
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
219 < Otherwise the range goes after the modifier and must
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
220 have a colon prefixed, like all Vim9 ranges: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
221 :vim9cmd :5,9source
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
222
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
223 < When a range of lines in a buffer is sourced in the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
224 Vim9 script context, the previously defined
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
225 script-local variables and functions are not cleared.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
226 This works like the range started with the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
227 ":vim9script noclear" command. The "++clear" argument
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
228 can be used to clear the script-local variables and
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
229 functions before sourcing the script. This works like
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
230 the range started with the `:vim9script` command
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
231 without the "noclear" argument. See |vim9-reload| for
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
232 more information.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
233 Examples: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
234 :4,5source
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
235 :10,18source ++clear
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
236 <
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
237 *:source!*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
238 :so[urce]! {file} Read Vim commands from {file}. These are commands
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
239 that are executed from Normal mode, like you type
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
240 them.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
241 When used after |:global|, |:argdo|, |:windo|,
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
242 |:bufdo|, in a loop or when another command follows
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
243 the display won't be updated while executing the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
244 commands.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
245 Cannot be used in the |sandbox|.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
246
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
247 *:ru* *:runtime*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
248 :ru[ntime][!] [where] {file} ..
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
249 Read Ex commands from {file} in each directory given
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
250 by 'runtimepath' and/or 'packpath'. There is no error
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
251 for non-existing files.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
252
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
253 Example: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
254 :runtime syntax/c.vim
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
255
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
256 < There can be multiple {file} arguments, separated by
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
257 spaces. Each {file} is searched for in the first
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
258 directory from 'runtimepath', then in the second
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
259 directory, etc. Use a backslash to include a space
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
260 inside {file} (although it's better not to use spaces
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
261 in file names, it causes trouble).
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
262
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
263 When [!] is included, all found files are sourced.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
264 When it is not included only the first found file is
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
265 sourced.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
266
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
267 When [where] is omitted only 'runtimepath' is used.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
268 Other values:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
269 START search under "start" in 'packpath'
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
270 OPT search under "opt" in 'packpath'
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
271 PACK search under "start" and "opt" in
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
272 'packpath'
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
273 ALL first use 'runtimepath', then search
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
274 under "start" and "opt" in 'packpath'
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
275
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
276 When {file} contains wildcards it is expanded to all
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
277 matching files. Example: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
278 :runtime! plugin/**/*.vim
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
279 < This is what Vim uses to load the plugin files when
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
280 starting up. This similar command: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
281 :runtime plugin/**/*.vim
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
282 < would source the first file only.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
283
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
284 When 'verbose' is one or higher, there is a message
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
285 when no file could be found.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
286 When 'verbose' is two or higher, there is a message
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
287 about each searched file.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
288
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
289 *:pa* *:packadd* *E919*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
290 :pa[ckadd][!] {name} Search for an optional plugin directory in 'packpath'
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
291 and source any plugin files found. The directory must
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
292 match:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
293 pack/*/opt/{name} ~
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
294 The directory is added to 'runtimepath' if it wasn't
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
295 there yet.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
296 If the directory pack/*/opt/{name}/after exists it is
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
297 added at the end of 'runtimepath'.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
298
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
299 If loading packages from "pack/*/start" was skipped,
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
300 then this directory is searched first:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
301 pack/*/start/{name} ~
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
302
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
303 Note that {name} is the directory name, not the name
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
304 of the .vim file. All the files matching the pattern
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
305 pack/*/opt/{name}/plugin/**/*.vim ~
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
306 will be sourced. This allows for using subdirectories
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
307 below "plugin", just like with plugins in
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
308 'runtimepath'.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
309
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
310 If the filetype detection was not enabled yet (this
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
311 is usually done with a `syntax enable` or `filetype on`
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
312 command in your .vimrc file), this will also look
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
313 for "{name}/ftdetect/*.vim" files.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
314
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
315 When the optional ! is added no plugin files or
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
316 ftdetect scripts are loaded, only the matching
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
317 directories are added to 'runtimepath'. This is
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
318 useful in your .vimrc. The plugins will then be
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
319 loaded during initialization, see |load-plugins| (note
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
320 that the loading order will be reversed, because each
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
321 directory is inserted before others).
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
322 Note that for ftdetect scripts to be loaded
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
323 you will need to write `filetype plugin indent on`
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
324 AFTER all `packadd!` commands.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
325
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
326 Also see |pack-add|.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
327 {only available when compiled with |+eval|}
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
328
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
329 *:packl* *:packloadall*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
330 :packl[oadall][!] Load all packages in the "start" directory under each
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
331 entry in 'packpath'.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
332
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
333 First all the directories found are added to
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
334 'runtimepath', then the plugins found in the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
335 directories are sourced. This allows for a plugin to
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
336 depend on something of another plugin, e.g. an
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
337 "autoload" directory. See |packload-two-steps| for
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
338 how this can be useful.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
339
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
340 This is normally done automatically during startup,
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
341 after loading your .vimrc file. With this command it
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
342 can be done earlier.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
343
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
344 Packages will be loaded only once. Using
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
345 `:packloadall` a second time will have no effect.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
346 When the optional ! is added this command will load
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
347 packages even when done before.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
348
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
349 Note that when using `:packloadall` in the |vimrc|
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
350 file, the 'runtimepath' option is updated, and later
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
351 all plugins in 'runtimepath' will be loaded, which
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
352 means they are loaded again. Plugins are expected to
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
353 handle that.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
354
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
355 An error only causes sourcing the script where it
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
356 happens to be aborted, further plugins will be loaded.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
357 See |packages|.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
358 {only available when compiled with |+eval|}
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
359
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
360 :scripte[ncoding] [encoding] *:scripte* *:scriptencoding* *E167*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
361 Specify the character encoding used in the script.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
362 The following lines will be converted from [encoding]
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
363 to the value of the 'encoding' option, if they are
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
364 different. Examples: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
365 scriptencoding iso-8859-5
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
366 scriptencoding cp932
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
367 <
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
368 When [encoding] is empty, no conversion is done. This
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
369 can be used to restrict conversion to a sequence of
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
370 lines: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
371 scriptencoding euc-jp
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
372 ... lines to be converted ...
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
373 scriptencoding
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
374 ... not converted ...
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
375
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
376 < When conversion isn't supported by the system, there
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
377 is no error message and no conversion is done. When a
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
378 line can't be converted there is no error and the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
379 original line is kept.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
380
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
381 Don't use "ucs-2" or "ucs-4", scripts cannot be in
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
382 these encodings (they would contain NUL bytes).
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
383 When a sourced script starts with a BOM (Byte Order
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
384 Mark) in utf-8 format Vim will recognize it, no need
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
385 to use ":scriptencoding utf-8" then.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
386
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
387 If you set the 'encoding' option in your |.vimrc|,
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
388 `:scriptencoding` must be placed after that. E.g.: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
389 set encoding=utf-8
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
390 scriptencoding utf-8
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
391 <
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
392
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
393 :scriptv[ersion] {version} *:scriptv* *:scriptversion*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
394 *E999* *E984* *E1040*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
395 Specify the version of Vim for the lines that follow
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
396 in the same file. Only applies at the toplevel of
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
397 sourced scripts, not inside functions.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
398
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
399 If {version} is higher than what the current Vim
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
400 version supports E999 will be given. You either need
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
401 to rewrite the script to make it work with an older
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
402 Vim version, or update Vim to a newer version. See
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
403 |vimscript-version| for what changed between versions.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
404
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
405 :vim9s[cript] [noclear] *:vim9s* *:vim9script*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
406 Marks a script file as containing |Vim9-script|
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
407 commands. Also see |vim9-namespace|. *E1038*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
408 Must be the first command in the file. *E1039*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
409 For [noclear] see |vim9-reload|.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
410 Without the |+eval| feature this changes the syntax
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
411 for some commands.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
412 See |:vim9cmd| for executing one command with Vim9
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
413 syntax and semantics.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
414
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
415 *:scr* *:scriptnames*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
416 :scr[iptnames] List all sourced script names, in the order they were
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
417 first encountered. The number is used for the script
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
418 ID |<SID>|.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
419 For a script that was used with `import autoload` but
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
420 was not actually sourced yet an "A" is shown after the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
421 script ID.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
422 For a script that was referred to by one name but
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
423 after resolving symbolic links got sourced with
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
424 another name the other script is after "->". E.g.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
425 "20->22" means script 20 was sourced as script 22.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
426 Also see `getscriptinfo()`.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
427 {not available when compiled without the |+eval|
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
428 feature}
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
429
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
430 :scr[iptnames][!] {scriptId} *:script*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
431 Edit script {scriptId}. Although ":scriptnames name"
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
432 works, using ":script name" is recommended.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
433 When the current buffer can't be |abandon|ed and the !
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
434 is not present, the command fails.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
435
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
436 *:fini* *:finish* *E168*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
437 :fini[sh] Stop sourcing a script. Can only be used in a Vim
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
438 script file. This is a quick way to skip the rest of
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
439 the file. If it is used after a |:try| but before the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
440 matching |:finally| (if present), the commands
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
441 following the ":finally" up to the matching |:endtry|
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
442 are executed first. This process applies to all
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
443 nested ":try"s in the script. The outermost ":endtry"
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
444 then stops sourcing the script.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
445
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
446 All commands and command sequences can be repeated by putting them in a named
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
447 register and then executing it. There are two ways to get the commands in the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
448 register:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
449 - Use the record command "q". You type the commands once, and while they are
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
450 being executed they are stored in a register. Easy, because you can see
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
451 what you are doing. If you make a mistake, "p"ut the register into the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
452 file, edit the command sequence, and then delete it into the register
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
453 again. You can continue recording by appending to the register (use an
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
454 uppercase letter).
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
455 - Delete or yank the command sequence into the register.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
456
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
457 Often used command sequences can be put under a function key with the ':map'
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
458 command.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
459
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
460 An alternative is to put the commands in a file, and execute them with the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
461 ':source!' command. Useful for long command sequences. Can be combined with
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
462 the ':map' command to put complicated commands under a function key.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
463
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
464 The ':source' command reads Ex commands from a file or a buffer line by line.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
465 You will have to type any needed keyboard input. The ':source!' command reads
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
466 from a script file character by character, interpreting each character as if
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
467 you typed it.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
468
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
469 Example: When you give the ":!ls" command you get the |hit-enter| prompt. If
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
470 you ':source' a file with the line "!ls" in it, you will have to type the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
471 <Enter> yourself. But if you ':source!' a file with the line ":!ls" in it,
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
472 the next characters from that file are read until a <CR> is found. You will
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
473 not have to type <CR> yourself, unless ":!ls" was the last line in the file.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
474
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
475 It is possible to put ':source[!]' commands in the script file, so you can
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
476 make a top-down hierarchy of script files. The ':source' command can be
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
477 nested as deep as the number of files that can be opened at one time (about
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
478 15). The ':source!' command can be nested up to 15 levels deep.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
479
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
480 You can use the "<sfile>" string (literally, this is not a special key) inside
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
481 of the sourced file, in places where a file name is expected. It will be
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
482 replaced by the file name of the sourced file. For example, if you have a
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
483 "other.vimrc" file in the same directory as your ".vimrc" file, you can source
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
484 it from your ".vimrc" file with this command: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
485 :source <sfile>:h/other.vimrc
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
486
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
487 In script files terminal-dependent key codes are represented by
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
488 terminal-independent two character codes. This means that they can be used
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
489 in the same way on different kinds of terminals. The first character of a
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
490 key code is 0x80 or 128, shown on the screen as "~@". The second one can be
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
491 found in the list |key-notation|. Any of these codes can also be entered
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
492 with CTRL-V followed by the three digit decimal code. This does NOT work for
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
493 the <t_xx> termcap codes, these can only be used in mappings.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
494
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
495 *:source_crnl* *W15*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
496 Win32: Files that are read with ":source" normally have <CR><NL> <EOL>s.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
497 These always work. If you are using a file with <NL> <EOL>s (for example, a
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
498 file made on Unix), this will be recognized if 'fileformats' is not empty and
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
499 the first line does not end in a <CR>. This fails if the first line has
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
500 something like ":map <F1> :help^M", where "^M" is a <CR>. If the first line
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
501 ends in a <CR>, but following ones don't, you will get an error message,
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
502 because the <CR> from the first lines will be lost.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
503
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
504 Mac Classic: Files that are read with ":source" normally have <CR> <EOL>s.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
505 These always work. If you are using a file with <NL> <EOL>s (for example, a
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
506 file made on Unix), this will be recognized if 'fileformats' is not empty and
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
507 the first line does not end in a <CR>. Be careful not to use a file with <NL>
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
508 linebreaks which has a <CR> in first line.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
509
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
510 On other systems, Vim expects ":source"ed files to end in a <NL>. These
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
511 always work. If you are using a file with <CR><NL> <EOL>s (for example, a
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
512 file made on MS-Windows), all lines will have a trailing <CR>. This may cause
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
513 problems for some commands (e.g., mappings). There is no automatic <EOL>
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
514 detection, because it's common to start with a line that defines a mapping
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
515 that ends in a <CR>, which will confuse the automaton.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
516
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
517 *line-continuation*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
518 Long lines in a ":source"d Ex command script file can be split by inserting
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
519 a line continuation symbol "\" (backslash) at the start of the next line.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
520 There can be white space before the backslash, which is ignored.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
521
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
522 Example: the lines >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
523 :set comments=sr:/*,mb:*,el:*/,
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
524 \://,
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
525 \b:#,
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
526 \:%,
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
527 \n:>,
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
528 \fb:-
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
529 are interpreted as if they were given in one line:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
530 :set comments=sr:/*,mb:*,el:*/,://,b:#,:%,n:>,fb:-
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
531
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
532 All leading whitespace characters in the line before a backslash are ignored.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
533 Note however that trailing whitespace in the line before it cannot be
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
534 inserted freely; it depends on the position where a command is split up
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
535 whether additional whitespace is allowed or not.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
536
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
537 When a space is required it's best to put it right after the backslash. A
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
538 space at the end of a line is hard to see and may be accidentally deleted. >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
539 :syn match Comment
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
540 \ "very long regexp"
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
541 \ keepend
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
542
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
543 In |Vim9| script the backslash can often be omitted, but not always.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
544 See |vim9-line-continuation|.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
545
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
546 There is a problem with the ":append" and ":insert" commands: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
547 :1append
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
548 \asdf
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
549 .
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
550 The backslash is seen as a line-continuation symbol, thus this results in the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
551 command: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
552 :1appendasdf
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
553 .
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
554 To avoid this, add the 'C' flag to the 'cpoptions' option: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
555 :set cpo+=C
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
556 :1append
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
557 \asdf
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
558 .
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
559 :set cpo-=C
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
560
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
561 Note that when the commands are inside a function, you need to add the 'C'
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
562 flag when defining the function, it is not relevant when executing it. >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
563 :set cpo+=C
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
564 :function Foo()
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
565 :1append
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
566 \asdf
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
567 .
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
568 :endfunction
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
569 :set cpo-=C
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
570 <
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
571 *line-continuation-comment*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
572 To add a comment in between the lines start with '"\ '. Notice the space
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
573 after the backslash. Example: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
574 let array = [
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
575 "\ first entry comment
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
576 \ 'first',
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
577 "\ second entry comment
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
578 \ 'second',
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
579 \ ]
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
580
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
581 Rationale:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
582 Most programs work with a trailing backslash to indicate line
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
583 continuation. Using this in Vim would cause incompatibility with Vi.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
584 For example for this Vi mapping: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
585 :map xx asdf\
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
586 < Therefore the unusual leading backslash is used.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
587
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
588 Starting a comment in a continuation line results in all following
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
589 continuation lines to be part of the comment. Since it was like this
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
590 for a long time, when making it possible to add a comment halfway a
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
591 sequence of continuation lines, it was not possible to use \", since
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
592 that was a valid continuation line. Using '"\ ' comes closest, even
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
593 though it may look a bit weird. Requiring the space after the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
594 backslash is to make it very unlikely this is a normal comment line.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
595
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
596 ==============================================================================
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
597 5. Using Vim packages *packages*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
598
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
599 A Vim package is a directory that contains one or more plugins. The
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
600 advantages over normal plugins:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
601 - A package can be downloaded as an archive and unpacked in its own directory.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
602 Thus the files are not mixed with files of other plugins. That makes it
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
603 easy to update and remove.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
604 - A package can be a git, mercurial, etc. repository. That makes it really
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
605 easy to update.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
606 - A package can contain multiple plugins that depend on each other.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
607 - A package can contain plugins that are automatically loaded on startup and
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
608 ones that are only loaded when needed with `:packadd`.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
609
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
610
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
611 Using a package and loading automatically ~
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
612
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
613 Let's assume your Vim files are in the "~/.vim" directory and you want to add a
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
614 package from a zip archive "/tmp/foopack.zip":
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
615 % mkdir -p ~/.vim/pack/foo
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
616 % cd ~/.vim/pack/foo
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
617 % unzip /tmp/foopack.zip
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
618
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
619 The directory name "foo" is arbitrary, you can pick anything you like.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
620
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
621 You would now have these files under ~/.vim:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
622 pack/foo/README.txt
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
623 pack/foo/start/foobar/plugin/foo.vim
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
624 pack/foo/start/foobar/syntax/some.vim
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
625 pack/foo/opt/foodebug/plugin/debugger.vim
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
626
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
627 When Vim starts up, after processing your .vimrc, it scans all directories in
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
628 'packpath' for plugins under the "pack/*/start" directory. First all those
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
629 directories are added to 'runtimepath'. Then all the plugins are loaded.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
630 See |packload-two-steps| for how these two steps can be useful.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
631
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
632 To allow for calling into package functionality while parsing your .vimrc,
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
633 |:colorscheme| and |autoload| will both automatically search under 'packpath'
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
634 as well in addition to 'runtimepath'. See the documentation for each for
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
635 details.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
636
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
637 In the example Vim will find "pack/foo/start/foobar/plugin/foo.vim" and adds
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
638 "~/.vim/pack/foo/start/foobar" to 'runtimepath'.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
639
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
640 If the "foobar" plugin kicks in and sets the 'filetype' to "some", Vim will
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
641 find the syntax/some.vim file, because its directory is in 'runtimepath'.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
642
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
643 Vim will also load ftdetect files, if there are any.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
644
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
645 Note that the files under "pack/foo/opt" are not loaded automatically, only the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
646 ones under "pack/foo/start". See |pack-add| below for how the "opt" directory
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
647 is used.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
648
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
649 Loading packages automatically will not happen if loading plugins is disabled,
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
650 see |load-plugins|.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
651
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
652 To load packages earlier, so that 'runtimepath' gets updated: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
653 :packloadall
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
654 This also works when loading plugins is disabled. The automatic loading will
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
655 only happen once.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
656
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
657 If the package has an "after" directory, that directory is added to the end of
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
658 'runtimepath', so that anything there will be loaded later.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
659
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
660
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
661 Using a single plugin and loading it automatically ~
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
662
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
663 If you don't have a package but a single plugin, you need to create the extra
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
664 directory level:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
665 % mkdir -p ~/.vim/pack/foo/start/foobar
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
666 % cd ~/.vim/pack/foo/start/foobar
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
667 % unzip /tmp/someplugin.zip
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
668
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
669 You would now have these files:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
670 pack/foo/start/foobar/plugin/foo.vim
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
671 pack/foo/start/foobar/syntax/some.vim
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
672
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
673 From here it works like above.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
674
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
675
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
676 Optional plugins ~
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
677 *pack-add*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
678 To load an optional plugin from a pack use the `:packadd` command: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
679 :packadd foodebug
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
680 This searches for "pack/*/opt/foodebug" in 'packpath' and will find
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
681 ~/.vim/pack/foo/opt/foodebug/plugin/debugger.vim and source it.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
682
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
683 This could be done if some conditions are met. For example, depending on
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
684 whether Vim supports a feature or a dependency is missing.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
685
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
686 You can also load an optional plugin at startup, by putting this command in
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
687 your |.vimrc|: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
688 :packadd! foodebug
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
689 The extra "!" is so that the plugin isn't loaded if Vim was started with
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
690 |--noplugin|.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
691
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
692 It is perfectly normal for a package to only have files in the "opt"
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
693 directory. You then need to load each plugin when you want to use it.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
694
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
695
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
696 Where to put what ~
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
697
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
698 Since color schemes, loaded with `:colorscheme`, are found below
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
699 "pack/*/start" and "pack/*/opt", you could put them anywhere. We recommend
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
700 you put them below "pack/*/opt", for example
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
701 ".vim/pack/mycolors/opt/dark/colors/very_dark.vim".
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
702
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
703 Filetype plugins should go under "pack/*/start", so that they are always
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
704 found. Unless you have more than one plugin for a file type and want to
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
705 select which one to load with `:packadd`. E.g. depending on the compiler
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
706 version: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
707 if foo_compiler_version > 34
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
708 packadd foo_new
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
709 else
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
710 packadd foo_old
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
711 endif
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
712
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
713 The "after" directory is most likely not useful in a package. It's not
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
714 disallowed though.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
715
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
716 ==============================================================================
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
717 6. Creating Vim packages *package-create*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
718
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
719 This assumes you write one or more plugins that you distribute as a package.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
720
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
721 If you have two unrelated plugins you would use two packages, so that Vim
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
722 users can choose what they include or not. Or you can decide to use one
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
723 package with optional plugins, and tell the user to add the preferred ones with
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
724 `:packadd`.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
725
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
726 Decide how you want to distribute the package. You can create an archive or
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
727 you could use a repository. An archive can be used by more users, but is a
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
728 bit harder to update to a new version. A repository can usually be kept
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
729 up-to-date easily, but it requires a program like "git" to be available.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
730 You can do both, github can automatically create an archive for a release.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
731
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
732 Your directory layout would be like this:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
733 start/foobar/plugin/foo.vim " always loaded, defines commands
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
734 start/foobar/plugin/bar.vim " always loaded, defines commands
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
735 start/foobar/autoload/foo.vim " loaded when foo command used
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
736 start/foobar/doc/foo.txt " help for foo.vim
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
737 start/foobar/doc/tags " help tags
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
738 opt/fooextra/plugin/extra.vim " optional plugin, defines commands
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
739 opt/fooextra/autoload/extra.vim " loaded when extra command used
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
740 opt/fooextra/doc/extra.txt " help for extra.vim
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
741 opt/fooextra/doc/tags " help tags
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
742
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
743 This allows for the user to do: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
744 mkdir ~/.vim/pack
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
745 cd ~/.vim/pack
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
746 git clone https://github.com/you/foobar.git myfoobar
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
747
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
748 Here "myfoobar" is a name that the user can choose, the only condition is that
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
749 it differs from other packages.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
750
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
751 In your documentation you explain what the plugins do, and tell the user how
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
752 to load the optional plugin: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
753 :packadd! fooextra
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
754
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
755 You could add this packadd command in one of your plugins, to be executed when
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
756 the optional plugin is needed.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
757
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
758 Run the `:helptags` command to generate the doc/tags file. Including this
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
759 generated file in the package means that the user can drop the package in the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
760 pack directory and the help command works right away. Don't forget to re-run
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
761 the command after changing the plugin help: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
762 :helptags path/start/foobar/doc
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
763 :helptags path/opt/fooextra/doc
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
764
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
765
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
766 Dependencies between plugins ~
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
767 *packload-two-steps*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
768 Suppose you have two plugins that depend on the same functionality. You can
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
769 put the common functionality in an autoload directory, so that it will be
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
770 found automatically. Your package would have these files:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
771
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
772 pack/foo/start/one/plugin/one.vim >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
773 call foolib#getit()
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
774 < pack/foo/start/two/plugin/two.vim >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
775 call foolib#getit()
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
776 < pack/foo/start/lib/autoload/foolib.vim >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
777 func foolib#getit()
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
778
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
779 This works, because loading packages will first add all found directories to
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
780 'runtimepath' before sourcing the plugins.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
781
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
782 ==============================================================================
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
783 7. Debugging scripts *debug-scripts*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
784
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
785 Besides the obvious messages that you can add to your scripts to find out what
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
786 they are doing, Vim offers a debug mode. This allows you to step through a
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
787 sourced file or user function and set breakpoints.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
788
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
789 NOTE: The debugging mode is far from perfect. Debugging will have side
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
790 effects on how Vim works. You cannot use it to debug everything. For
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
791 example, the display is messed up by the debugging messages.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
792
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
793 An alternative to debug mode is setting the 'verbose' option. With a bigger
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
794 number it will give more verbose messages about what Vim is doing.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
795
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
796
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
797 STARTING DEBUG MODE *debug-mode*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
798
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
799 To enter debugging mode use one of these methods:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
800 1. Start Vim with the |-D| argument: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
801 vim -D file.txt
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
802 < Debugging will start as soon as the first vimrc file is sourced. This is
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
803 useful to find out what is happening when Vim is starting up. A side
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
804 effect is that Vim will switch the terminal mode before initialisations
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
805 have finished, with unpredictable results.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
806 For a GUI-only version (Windows, Macintosh) the debugging will start as
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
807 soon as the GUI window has been opened. To make this happen early, add a
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
808 ":gui" command in the vimrc file.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
809 *:debug*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
810 2. Run a command with ":debug" prepended. Debugging will only be done while
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
811 this command executes. Useful for debugging a specific script or user
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
812 function. And for scripts and functions used by autocommands. Example: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
813 :debug edit test.txt.gz
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
814
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
815 3. Set a breakpoint in a sourced file or user function. You could do this in
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
816 the command line: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
817 vim -c "breakadd file */explorer.vim" .
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
818 < This will run Vim and stop in the first line of the "explorer.vim" script.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
819 Breakpoints can also be set while in debugging mode.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
820
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
821 In debugging mode every executed command is displayed before it is executed.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
822 Comment lines, empty lines and lines that are not executed are skipped. When
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
823 a line contains two commands, separated by "|", each command will be displayed
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
824 separately.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
825
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
826
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
827 DEBUG MODE
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
828
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
829 Once in debugging mode, the usual Ex commands can be used. For example, to
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
830 inspect the value of a variable: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
831 echo idx
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
832 When inside a user function, this will print the value of the local variable
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
833 "idx". Prepend "g:" to get the value of a global variable: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
834 echo g:idx
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
835 All commands are executed in the context of the current function or script.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
836 You can also set options, for example setting or resetting 'verbose' will show
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
837 what happens, but you might want to set it just before executing the lines you
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
838 are interested in: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
839 :set verbose=20
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
840
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
841 Commands that require updating the screen should be avoided, because their
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
842 effect won't be noticed until after leaving debug mode. For example: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
843 :help
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
844 won't be very helpful.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
845
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
846 There is a separate command-line history for debug mode.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
847
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
848 NOTE: In Vim9 script, if a command is written at the script level and
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
849 continues on the next line, not using the old way with a backslash for line
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
850 continuation, only the first line is printed before the debugging prompt.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
851
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
852 The line number for a function line is relative to the start of the function.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
853 If you have trouble figuring out where you are, edit the file that defines
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
854 the function in another Vim, search for the start of the function and do
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
855 "99j". Replace "99" with the line number.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
856
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
857 Additionally, these commands can be used:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
858 *>cont*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
859 cont Continue execution until the next breakpoint is hit.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
860 *>quit*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
861 quit Abort execution. This is like using CTRL-C, some
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
862 things might still be executed, doesn't abort
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
863 everything. Still stops at the next breakpoint.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
864 *>next*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
865 next Execute the command and come back to debug mode when
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
866 it's finished. This steps over user function calls
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
867 and sourced files.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
868 *>step*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
869 step Execute the command and come back to debug mode for
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
870 the next command. This steps into called user
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
871 functions and sourced files.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
872 *>interrupt*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
873 interrupt This is like using CTRL-C, but unlike ">quit" comes
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
874 back to debug mode for the next command that is
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
875 executed. Useful for testing |:finally| and |:catch|
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
876 on interrupt exceptions.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
877 *>finish*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
878 finish Finish the current script or user function and come
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
879 back to debug mode for the command after the one that
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
880 sourced or called it.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
881 *>bt*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
882 *>backtrace*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
883 *>where*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
884 backtrace Show the call stacktrace for current debugging session.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
885 bt
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
886 where
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
887 *>frame*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
888 frame N Goes to N backtrace level. + and - signs make movement
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
889 relative. E.g., ":frame +3" goes three frames up.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
890 *>up*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
891 up Goes one level up from call stacktrace.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
892 *>down*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
893 down Goes one level down from call stacktrace.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
894
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
895 About the additional commands in debug mode:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
896 - There is no command-line completion for them, you get the completion for the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
897 normal Ex commands only.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
898 - You can shorten them, up to a single character, unless more than one command
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
899 starts with the same letter. "f" stands for "finish", use "fr" for "frame".
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
900 - Hitting <CR> will repeat the previous one. When doing another command, this
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
901 is reset (because it's not clear what you want to repeat).
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
902 - When you want to use the Ex command with the same name, prepend a colon:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
903 ":cont", ":next", ":finish" (or shorter).
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
904 *vim9-debug*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
905 When debugging a compiled :def function, "step" will stop before every
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
906 executed line, not every single instruction. Thus it works mostly like a not
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
907 compiled function. Access to local variables is limited you can use: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
908 echo varname
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
909 But not much else.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
910 When executing a command that is not a specific bytecode instruction but
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
911 executed like a normal Ex command, "step" will stop once in the compiled
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
912 context, where local variables can be inspected, and once just before
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
913 executing the command.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
914
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
915 In a :def function variables that haven't been declared yet cannot be
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
916 inspected. Variables that have been declared can be inspected, also when the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
917 block they were declared in has finished. In commands this would not be
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
918 possible, thus is slightly misleading (but can be useful).
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
919
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
920 The backtrace shows the hierarchy of function calls, e.g.:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
921 >bt ~
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
922 3 function One[3] ~
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
923 2 Two[3] ~
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
924 ->1 Three[3] ~
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
925 0 Four ~
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
926 line 1: let four = 4 ~
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
927
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
928 The "->" points to the current frame. Use "up", "down" and "frame N" to
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
929 select another frame.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
930
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
931 In the current frame you can evaluate the local function variables. There is
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
932 no way to see the command at the current line yet.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
933
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
934
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
935 DEFINING BREAKPOINTS
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
936 *:breaka* *:breakadd*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
937 :breaka[dd] func [lnum] {name}
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
938 Set a breakpoint in a function. Example: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
939 :breakadd func Explore
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
940 < Doesn't check for a valid function name, thus the breakpoint
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
941 can be set before the function is defined.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
942
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
943 :breaka[dd] file [lnum] {name}
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
944 Set a breakpoint in a sourced file. Example: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
945 :breakadd file 43 .vimrc
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
946
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
947 :breaka[dd] here
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
948 Set a breakpoint in the current line of the current file.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
949 Like doing: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
950 :breakadd file <cursor-line> <current-file>
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
951 < Note that this only works for commands that are executed when
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
952 sourcing the file, not for a function defined in that file.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
953
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
954 :breaka[dd] expr {expression}
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
955 Sets a breakpoint, that will break whenever the {expression}
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
956 evaluates to a different value. Example: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
957 :breakadd expr g:lnum
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
958 < Will break, whenever the global variable lnum changes.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
959
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
960 Errors in evaluation are suppressed, you can use the name of a
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
961 variable that does not exist yet. This also means you will
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
962 not notice anything if the expression has a mistake.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
963
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
964 Note if you watch a |script-variable| this will break
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
965 when switching scripts, since the script variable is only
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
966 valid in the script where it has been defined and if that
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
967 script is called from several other scripts, this will stop
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
968 whenever that particular variable will become visible or
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
969 inaccessible again.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
970
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
971 The [lnum] is the line number of the breakpoint. Vim will stop at or after
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
972 this line. When omitted line 1 is used.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
973
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
974 *:debug-name*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
975 {name} is a pattern that is matched with the file or function name. The
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
976 pattern is like what is used for autocommands. There must be a full match (as
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
977 if the pattern starts with "^" and ends in "$"). A "*" matches any sequence
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
978 of characters. 'ignorecase' is not used, but "\c" can be used in the pattern
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
979 to ignore case |/\c|. Don't include the () for the function name!
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
980
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
981 The match for sourced scripts is done against the full file name. If no path
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
982 is specified the current directory is used. Examples: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
983 breakadd file explorer.vim
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
984 matches "explorer.vim" in the current directory. >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
985 breakadd file *explorer.vim
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
986 matches ".../plugin/explorer.vim", ".../plugin/iexplorer.vim", etc. >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
987 breakadd file */explorer.vim
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
988 matches ".../plugin/explorer.vim" and "explorer.vim" in any other directory.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
989
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
990 The match for functions is done against the name as it's shown in the output
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
991 of ":function". However, for local functions the script-specific prefix such
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
992 as "<SNR>99_" is ignored to make it easier to match script-local functions
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
993 without knowing the ID of the script.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
994
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
995 Note that functions are first loaded and later executed. When they are loaded
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
996 the "file" breakpoints are checked, when they are executed the "func"
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
997 breakpoints.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
998
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
999
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1000 DELETING BREAKPOINTS
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1001 *:breakd* *:breakdel* *E161*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1002 :breakd[el] {nr}
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1003 Delete breakpoint {nr}. Use |:breaklist| to see the number of
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1004 each breakpoint.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1005
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1006 :breakd[el] *
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1007 Delete all breakpoints.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1008
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1009 :breakd[el] func [lnum] {name}
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1010 Delete a breakpoint in a function.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1011
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1012 :breakd[el] file [lnum] {name}
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1013 Delete a breakpoint in a sourced file.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1014
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1015 :breakd[el] here
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1016 Delete a breakpoint at the current line of the current file.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1017
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1018 When [lnum] is omitted, the first breakpoint in the function or file is
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1019 deleted.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1020 The {name} must be exactly the same as what was typed for the ":breakadd"
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1021 command. "explorer", "*explorer.vim" and "*explorer*" are different.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1022
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1023
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1024 LISTING BREAKPOINTS
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1025 *:breakl* *:breaklist*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1026 :breakl[ist]
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1027 List all breakpoints.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1028
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1029
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1030 OBSCURE
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1031
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1032 *:debugg* *:debuggreedy*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1033 :debugg[reedy]
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1034 Read debug mode commands from the normal input stream, instead
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1035 of getting them directly from the user. Only useful for test
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1036 scripts. Example: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1037 echo 'q^Mq' | vim -e -s -c debuggreedy -c 'breakadd file script.vim' -S script.vim
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1038
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1039 :0debugg[reedy]
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1040 Undo ":debuggreedy": get debug mode commands directly from the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1041 user, don't use typeahead for debug commands.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1042
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1043 ==============================================================================
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1044 8. Profiling *profile* *profiling*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1045
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1046 Profiling means that Vim measures the time that is spent on executing
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1047 functions and/or scripts. The |+profile| feature is required for this.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1048 It is included when Vim was compiled with "huge" features.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1049
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1050 You can also use the |reltime()| function to measure time. This only requires
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1051 the |+reltime| feature, which is present in more builds.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1052
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1053 For profiling syntax highlighting see |:syntime|.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1054
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1055 For example, to profile the one_script.vim script file: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1056 :profile start /tmp/one_script_profile
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1057 :profile file one_script.vim
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1058 :source one_script.vim
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1059 :exit
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1060
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1061
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1062 :prof[ile] start {fname} *:prof* *:profile* *E750*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1063 Start profiling, write the output in {fname} upon exit or when
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1064 a `:profile stop` or `:profile dump` command is invoked.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1065 "~/" and environment variables in {fname} will be expanded.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1066 If {fname} already exists it will be silently overwritten.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1067 The variable |v:profiling| is set to one.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1068
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1069 :prof[ile] stop
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1070 Write the collected profiling information to the logfile and
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1071 stop profiling. You can use the `:profile start` command to
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1072 clear the profiling statistics and start profiling again.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1073
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1074 :prof[ile] pause
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1075 Don't profile until the following `:profile continue`. Can be
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1076 used when doing something that should not be counted (e.g., an
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1077 external command). Does not nest.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1078
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1079 :prof[ile] continue
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1080 Continue profiling after `:profile pause`.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1081
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1082 :prof[ile] func {pattern}
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1083 Profile function that matches the pattern {pattern}.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1084 See |:debug-name| for how {pattern} is used.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1085
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1086 :prof[ile][!] file {pattern}
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1087 Profile script file that matches the pattern {pattern}.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1088 See |:debug-name| for how {pattern} is used.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1089 This only profiles the script itself, not the functions
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1090 defined in it.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1091 When the [!] is added then all functions defined in the script
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1092 will also be profiled.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1093 Note that profiling only starts when the script is loaded
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1094 after this command. A :profile command in the script itself
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1095 won't work.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1096
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1097 :prof[ile] dump
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1098 Write the current state of profiling to the logfile
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1099 immediately. After running this command, Vim continues to
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1100 collect the profiling statistics.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1101
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1102 :profd[el] ... *:profd* *:profdel*
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1103 Stop profiling for the arguments specified. See |:breakdel|
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1104 for the arguments. Examples: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1105 profdel func MyFunc
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1106 profdel file MyScript.vim
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1107 profdel here
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1108
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1109 You must always start with a ":profile start fname" command. The resulting
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1110 file is written when Vim exits. For example, to profile one specific
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1111 function: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1112 profile start /tmp/vimprofile
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1113 profile func MyFunc
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1114
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1115 Here is an example of the output, with line
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1116 numbers prepended for the explanation:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1117
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1118 1 FUNCTION Test2() ~
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1119 2 Called 1 time ~
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1120 3 Total time: 0.155251 ~
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1121 4 Self time: 0.002006 ~
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1122 5 ~
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1123 6 count total (s) self (s) ~
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1124 7 9 0.000096 for i in range(8) ~
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1125 8 8 0.153655 0.000410 call Test3() ~
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1126 9 8 0.000070 endfor ~
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1127 10 " Ask a question ~
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1128 11 1 0.001341 echo input("give me an answer: ") ~
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1129
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1130 The header (lines 1-4) gives the time for the whole function. The "Total"
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1131 time is the time passed while the function was executing. The "Self" time is
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1132 the "Total" time reduced by time spent in:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1133 - other user defined functions
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1134 - sourced scripts
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1135 - executed autocommands
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1136 - external (shell) commands
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1137
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1138 Lines 7-11 show the time spent in each executed line. Lines that are not
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1139 executed do not count. Thus a comment line is never counted.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1140
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1141 The Count column shows how many times a line was executed. Note that the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1142 "for" command in line 7 is executed one more time as the following lines.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1143 That is because the line is also executed to detect the end of the loop.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1144
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1145 The time Vim spends waiting for user input isn't counted at all. Thus how
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1146 long you take to respond to the input() prompt is irrelevant.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1147
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1148 Profiling should give a good indication of where time is spent, but keep in
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1149 mind there are various things that may clobber the results:
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1150
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1151 - The accuracy of the time measured depends on the gettimeofday(), or
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1152 clock_gettime if available, system function. The accuracy ranges from 1/100
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1153 second to nanoseconds. With clock_gettime the times are displayed in
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1154 nanoseconds, otherwise microseconds. You can use `has("prof_nsec")`.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1155
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1156 - Real elapsed time is measured, if other processes are busy they may cause
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1157 delays at unpredictable moments. You may want to run the profiling several
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1158 times and use the lowest results.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1159
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1160 - If you have several commands in one line you only get one time. Split the
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1161 line to see the time for the individual commands.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1162
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1163 - The time of the lines added up is mostly less than the time of the whole
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1164 function. There is some overhead in between.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1165
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1166 - Functions that are deleted before Vim exits will not produce profiling
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1167 information. You can check the |v:profiling| variable if needed: >
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1168 :if !v:profiling
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1169 : delfunc MyFunc
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1170 :endif
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1171 <
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1172 - Profiling may give weird results on multi-processor systems, when sleep
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1173 mode kicks in or the processor frequency is reduced to save power.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1174
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1175 - The "self" time is wrong when a function is used recursively.
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1176
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1177
695b50472e85 Fix line endings issue
Christian Brabandt <cb@256bit.org>
parents: 32669
diff changeset
1178 vim:tw=78:ts=8:noet:ft=help:norl: