-
Notifications
You must be signed in to change notification settings - Fork 13
/
shell.txt
343 lines (283 loc) · 16.3 KB
/
shell.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
*shell.txt* Improved integration between Vim and its environment
===============================================================================
Contents ~
1. Introduction |shell-introduction|
2. Installation |shell-installation|
3. Usage (commands & functions) |shell-usage|
1. The |:Maximize| command
2. The |:Fullscreen| command
3. The |:Open| command
4. The |:MakeWithShell| command
5. The |xolox#shell#execute_with_dll()| function
6. The |xolox#shell#fullscreen()| function
7. The |xolox#shell#is_fullscreen()| function
8. The |g:shell_fullscreen_items| option
9. The |g:shell_fullscreen_always_on_top| option
10. The |g:shell_fullscreen_message| option
11. The |g:shell_mappings_enabled| option
12. The |g:shell_verify_urls| option
13. The |g:shell_use_dll| option
4. Background |shell-background|
5. Other full-screen implementations |shell-other-full-screen-implementations|
6. Contact |shell-contact|
7. License |shell-license|
8. References |shell-references|
===============================================================================
*shell-introduction*
Introduction ~
This plug-in aims to improve the integration between Vim and its environment
(your operating system) by providing the following functionality:
- The |:Fullscreen| command and '<F11>' mapping toggle Vim between normal and
full-screen mode (see the screenshots [1]). To invoke this functionality
without using the |:Fullscreen| command see the |xolox#shell#fullscreen()|
and |xolox#shell#is_fullscreen()| functions.
- The |:Maximize| command and '<Control-F11>' mapping toggle Vim between
normal and maximized state: They show/hide Vim's menu bar, tool bar and/or
tab line without hiding the operating system task bar.
- The |:Open| command and '<F6>' mapping know how to open file and directory
names, URLs and e-mail addresses in your favorite programs (file manager,
web browser, e-mail client, etc).
- The 'xolox#misc#os#exec()' function enables other Vim plug-ins (like my
easytags.vim [2] plug-in) to execute external commands in the background
(i.e. asynchronously) _without opening a command prompt window on Windows_.
Two Windows DLL files [3] are included to perform these functions on Windows,
while on UNIX external commands are used. MacVim supports full-screen out of
the box (and vim-shell knows how to enable it) but is otherwise treated as
UNIX.
===============================================================================
*shell-installation*
Installation ~
_Please note that the vim-shell plug-in requires my vim-misc plug-in which is
separately distributed._
Unzip the most recent ZIP archives of the vim-shell [4] and vim-misc [5] plug-
ins inside your Vim profile directory (usually this is '~/.vim' on UNIX and
'%USERPROFILE%\vimfiles' on Windows), restart Vim and execute the command
':helptags ~/.vim/doc' (use ':helptags ~\vimfiles\doc' instead on Windows).
If you prefer you can also use Pathogen [6], Vundle [7] or a similar tool to
install & update the vim-shell [8] and vim-misc [9] plug-ins using a local
clone of the git repository.
After you've installed the plug-in and restarted Vim, the following commands
will be available to you:
===============================================================================
*shell-usage*
Usage (commands & functions) ~
-------------------------------------------------------------------------------
The *:Maximize* command
This command toggles the visibility of Vim's main menu, tool bar and/or tab
line. It's mapped to '<Control-F11>' by default, see |g:shell_mappings_enabled|
if you don't like this. If you want to change which items are hidden see the
|g:shell_fullscreen_items| option.
-------------------------------------------------------------------------------
The *:Fullscreen* command
The |:Fullscreen| command toggles Vim between normal and full-screen mode [1].
It's mapped to '<F11>' by default, see |g:shell_mappings_enabled| if you don't
like this. This command first executes |:Maximize| and then (if possible)
switches Vim's |GUI| window to real full-screen mode (hiding any taskbars,
panels or docks [10]). When you leave full-screen Vim's main menu, toolbar and
tabline are restored and the |GUI| window is switched back to normal mode.
Note that on UNIX this command even works inside of graphical terminal
emulators like 'gnome-terminal' or 'xterm' (try it out!).
-------------------------------------------------------------------------------
The *:Open* command
The |:Open| command knows how to open files, directories, URLs and e-mail
addresses. It's mapped to '<F6>' by default, see |g:shell_mappings_enabled| if
you don't like this. You can provide a filename, URL or e-mail address as
argument to the command or if there's a filename, URL or e-mail address under
the text cursor that will be used. If both of those fail, the directory
containing the current file will be opened. You can use the command as follows:
>
:Open http://www.vim.org/
<
This will launch your preferred (or the best available) web browser. Likewise
the following command will open your file manager in the directory of Vim's
runtime files:
>
:Open $VIMRUNTIME
<
Note that on UNIX if the environment variable '$DISPLAY' is empty the plug-in
will fall back to a command-line web browser. Because such web browsers are
executed in front of Vim you have to quit the web browser to return to Vim.
-------------------------------------------------------------------------------
The *:MakeWithShell* command
This command is a very simple replacement for the |:make| command that does not
pop up a console window on Windows. It doesn't come with all of the bells and
whistles that Vim's built-in make command does but it should work. It properly
triggers the |QuickFixCmdPre| and |QuickFixCmdPost| events, although it does so
using |:silent| to avoid printing two "No matching autocommands" messages.
Because Vim's |v:shell_error| variable is read only (which means it cannot be
set by a Vim plug-in) the vim-shell plug-in defines its own variable with the
exit code of the 'make' process executed by |:MakeWithShell|. This variable is
called 'g:xolox#shell#make_exit_code'. The semantics are exactly the same as
for |v:shell_error|.
The |:MakeWithShell| command uses Vim's |quickfix| window. To make the shell
plug-in use the |location-list| instead you can use the command
':LMakeWithShell' instead.
-------------------------------------------------------------------------------
The *xolox#shell#execute_with_dll()* function
The function |xolox#shell#execute_with_dll()| is used by 'xolox#misc#os#exec()'
and shouldn't be called directly; instead please call 'xolox#misc#os#exec()'
(this is what my plug-ins do). For this reason the remainder of the following
text discusses the 'xolox#misc#os#exec()' function.
This function enables other Vim plug-ins to execute external commands in the
background (i.e. asynchronously) _without opening a command prompt window on
Windows_. For example try to execute the following command on Windows
(vimrun.exe (see |win32-vimrun|) is only included with Vim for Windows because
it isn't needed on other platforms):
>
:call xolox#misc#os#exec({'command': 'vimrun', 'async': 1})
<
Immediately after executing this command Vim will respond to input again
because 'xolox#misc#os#exec()' doesn't wait for the external command to finish
when the 'async' argument is true (1). In addition no command prompt window
will be shown which means vimrun.exe (see |win32-vimrun|) is running completely
invisible in the background.
The function returns a dictionary of return values. In asynchronous mode the
dictionary is empty. In synchronous mode it contains the following key/value
pairs:
>
:echo xolox#misc#os#exec({'command': 'echo "this is stdout" && echo "this is stderr" >&2 && exit 42', 'check': 0})
{'exit_code': 42, 'stdout': ['this is stdout'], 'stderr': ['this is stderr']}
<
If you want to verify that this function works as described, execute the
command mentioning 'vimrun' above, open the Windows task manager by pressing
'Control-Shift-Escape' and check that the process 'vimrun.exe' is listed in the
processes tab. If you don't see the problem this is solving, try executing
vimrun.exe (see |win32-vimrun|) using Vim's built-in |system()| function
instead:
>
:call system('vimrun')
<
Vim will be completely unresponsive until you "press any key to continue" in
the command prompt window that's running vimrun.exe (see |win32-vimrun|). Of
course the |system()| function should only be used with non-interactive
programs (the documentation says as much) but the point is to simulate an
external command that takes a while to finish and blocks Vim while doing so.
Note that on Windows this function uses Vim's |'shell'| and |'shellcmdflag'|
options to compose the command line passed to the DLL.
-------------------------------------------------------------------------------
The *xolox#shell#fullscreen()* function
Call this function to toggle Vim's full screen status. The |:Fullscreen|
command is just a shorter way to call this function.
-------------------------------------------------------------------------------
The *xolox#shell#is_fullscreen()* function
Call this function to determine whether Vim is in full screen mode. My
session.vim plug-in [11] uses this to persist full screen mode.
-------------------------------------------------------------------------------
The *g:shell_fullscreen_items* option
This variable is a string containing any combination of the following
characters:
- 'm': Hide the main menu (see |'go-m'|) when switching to full-screen;
- 'T': Hide the toolbar (see |'go-T'|) when switching to full-screen;
- 'e': Hide the tabline (see |'go-e'|) when switching to full-screen (this
also toggles the showtabline option (see |'showtabline'|)).
By default all the above items are hidden in full-screen mode. You can also set
the buffer local variable 'b:shell_fullscreen_items' to change these settings
for specific buffers.
-------------------------------------------------------------------------------
The *g:shell_fullscreen_always_on_top* option
On Windows the |:Fullscreen| command sets the Vim window to "always on top".
Some people don't like this which is why this option was added. Its default
value is true (1) so to disable the "always on top" feature you would add this
to your |vimrc| script:
>
:let g:shell_fullscreen_always_on_top = 0
<
-------------------------------------------------------------------------------
The *g:shell_fullscreen_message* option
When you enter full screen the plug-in shows a Vim message explaining how to
leave full screen. If you don't want to see this message you can set this
option to false (0).
-------------------------------------------------------------------------------
The *g:shell_mappings_enabled* option
If you don't like the default mappings for the |:Open| and |:Fullscreen|
commands then add the following to your |vimrc| script:
>
:let g:shell_mappings_enabled = 0
<
Since no mappings will be defined now you can add something like the following
to your |vimrc| script:
>
:inoremap <Leader>fs <C-o>:Fullscreen<CR>
:nnoremap <Leader>fs :Fullscreen<CR>
:inoremap <Leader>op <C-o>:Open<CR>
:nnoremap <Leader>op :Open<CR>
<
-------------------------------------------------------------------------------
The *g:shell_verify_urls* option
When you use the |:Open| command or the '<F6>' mapping to open the URL under
the text cursor, the shell plug-in uses a regular expression to guess where the
URL starts and ends. This works 99% percent of the time but it can break,
because in this process the shell plug-in will strip trailing punctuation
characters like dots (because they were likely not intended to be included in
the URL).
If you actually deal with URLs that include significant trailing punctuation
and your Vim is compiled with Python support you can enable the option
|g:shell_verify_urls| (by setting it to 1 in your |vimrc| script). When you do
this the plug-in will perform an HTTP HEAD request on the URL without stripping
trailing punctuation. If the request returns an HTTP status code that indicates
some form of success (the status code is at least 200 and less than 400) the
URL including trailing punctuation is opened. If the HEAD request fails the
plug-in will try again without trailing punctuation.
-------------------------------------------------------------------------------
The *g:shell_use_dll* option
If you set this to false (0) the DDL is never used. This is very useful during
testing :-).
===============================================================================
*shell-background*
Background ~
Vim has a limited ability to call external libraries using the Vim script
function |libcall()|. A few years ago when I was still using Windows a lot I
created a Windows DLL [3] that could be used with |libcall()| to toggle Vim's
GUI window between regular and full-screen mode. I also added a few other
useful functions, e.g. 'openurl()' to launch the default web browser and
'execute()' which works like Vim's |system()| function but doesn't wait for the
process to finish and doesn't show a command prompt.
Since then I switched to Linux and didn't look back, which meant the DLL sat in
my '~/.vim/etc/' waiting to be revived. Now that I've published my easytags.vim
[2] plug-in and put a lot of effort into making it Windows compatible, the
'execute()' function from the DLL would be very useful to run Exuberant Ctags
[12] in the background without stealing Vim's focus by opening a command prompt
window. This is why I've decided to release the DLL. Because I switched to
Linux I've also added an autoload script that wraps the DLL on Windows and
calls out to external programs such as 'wmctrl', 'gnome-open', 'kde-open', and
others on UNIX.
===============================================================================
*shell-other-full-screen-implementations*
Other full-screen implementations ~
After publishing this plug-in I found that the Vim plug-ins VimTweak [13] and
gvimfullscreen_win32 [14] also implement full-screen on Windows using a similar
approach as my plug-in. I prefer the effect of my plug-in because it seems to
hide window decorations more effectively. Also note that my plug-in was
developed independently of the other two.
===============================================================================
*shell-contact*
Contact ~
If you have questions, bug reports, suggestions, etc. the author can be
contacted at peter@peterodding.com. The latest version is available at
http://peterodding.com/code/vim/shell/ and http://github.com/xolox/vim-shell.
If you like the plug-in please vote for it on Vim Online [15].
===============================================================================
*shell-license*
License ~
This software is licensed under the MIT license [16]. Š 2014 Peter Odding
<peter@peterodding.com>.
===============================================================================
*shell-references*
References ~
[1] http://peterodding.com/code/vim/shell/screenshots/
[2] http://peterodding.com/code/vim/easytags/
[3] http://en.wikipedia.org/wiki/Dynamic-link_library
[4] http://peterodding.com/code/vim/downloads/shell.zip
[5] http://peterodding.com/code/vim/downloads/misc.zip
[6] http://www.vim.org/scripts/script.php?script_id=2332
[7] https://github.com/gmarik/vundle
[8] http://github.com/xolox/vim-shell
[9] http://github.com/xolox/vim-misc
[10] http://en.wikipedia.org/wiki/Taskbar
[11] http://peterodding.com/code/vim/session/
[12] http://en.wikipedia.org/wiki/Ctags
[13] http://www.vim.org/scripts/script.php?script_id=687
[14] http://www.vim.org/scripts/script.php?script_id=2596
[15] http://www.vim.org/scripts/script.php?script_id=3123
[16] http://en.wikipedia.org/wiki/MIT_License
vim: ft=help