Mercurial > vim
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 |
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: |