-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathvim-scratch-buffer.txt
332 lines (255 loc) · 10.3 KB
/
vim-scratch-buffer.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
*scratch-buffer.vim* The fastest way to open scratch buffers
Author: aiya000
License: MIT license
==============================================================================
CONTENTS *scratch-buffer-contents*
INTRODUCTION |scratch-buffer-introduction|
USAGE |scratch-buffer-usage|
INTERFACE |scratch-buffer-interface|
VARIABLES |scratch-buffer-variables|
COMMANDS |scratch-buffer-commands|
FUNCTIONS |scratch-buffer-functions|
CHANGELOG |scratch-buffer-changelog|
==============================================================================
INTRODUCTION *scratch-buffer-introduction*
** No more hassle with file paths! **
The fastest way to open an instant scratch buffer.
Supercharge with vim-quickrun!
Combine it with vim-quickrun (https://github.com/thinca/vim-quickrun) to
execute code instantly!
>
" Open a TypeScript buffer
:ScratchBufferOpen ts
" Write TypeScript code
" ...
" ...and run it immediately!
:QuickRun
<
Please see the |scratch-buffer-usage| section for usage of
|:ScratchBufferOpen|.
Newer Version:
https://github.com/aiya000/vim-scratch-buffer
==============================================================================
USAGE *scratch-buffer-usage*
Open a scratch buffer with or without a file extension:
>
" Open a new scratch buffer without file extension and filetype
:ScratchBufferOpen
:ScratchBufferOpen --no-file-ext
" Open a markdown buffer
:ScratchBufferOpen md
" Open a buffer without file extension and filetype with :sp and 3 lines
:ScratchBufferOpen --no-file-ext sp 3
" Open a markdown buffer with :sp and 3 lines
:ScratchBufferOpen md sp 3
<
Of course, you can open other file types too:
>
" Open a TypeScript buffer
:ScratchBufferOpen ts
<
==============================================================================
INTERFACE *scratch-buffer-interface*
------------------------------------------------------------------------------
VARIABLES *scratch-buffer-variables*
*g:scratch_buffer_file_pattern*
Type: `{ when_tmp_buffer?: string, when_file_buffer?: string }`
A dictionary specifying file patterns for different buffer types.
Has two keys:
.when_tmp_buffer ( Default: `'/tmp/vim-scratch-tmp-%d'` )
Pattern used for temporary buffers
created by |:ScratchBufferOpen|.
.when_file_buffer ( Default: `'/tmp/vim-scratch-file-%d'` )
Pattern used for persistent buffers
created by |:ScratchBufferOpenFile|.
Each pattern should contain '%d' which will be replaced with a number.
The number is determined by counting existing buffers of both types.
If a file extension is provided, it will be appended to the pattern.
Example:
>
" Use different directories for temporary and persistent buffers
let g:scratch_buffer_file_pattern = #{
\ when_tmp_buffer: '/tmp/scratch-tmp-%d',
\ when_file_buffer: '/tmp/vim-scratch-file-%d',
\ }
" This is useful if you want to keep a file buffer directory
" (`~/tmp` in the above case) with `.prettier`, etc.
" You can set only one of these options and leave the other as the default value.
let g:scratch_buffer_file_pattern = #{
\ when_file_buffer: expand('~/tmp/scratch-%d'),
\ }
<
This options is recommended that these two keys have different values,
but they can also be the same.
In that case, the below following behavior occurs.
>
let g:scratch_buffer_file_pattern = #{
\ when_tmp_buffer: '/tmp/scratch-%d',
\ when_file_buffer: '/tmp/scratch-%d',
\ }
" Open '/tmp/scratch-{first-number}.md' as a no file (tmp) buffer
:ScratchBufferOpen md
" !! Open '/tmp/scratch-{first-number}.md' again, but as a file (no tmp) buffer
:ScratchBufferOpen md
<
The latter buffer type will overwrite the former as well if the order
is reversed.
*g:scratch_buffer_default_file_ext*
Type: `string`
Default: `'md'`
The default file extension to use when opening a new scratch buffer.
This is used when no file extension is provided as an argument.
*g:scratch_buffer_default_open_method*
Type: `string`
Default: `'sp'`
The default method to use when opening a new scratch buffer.
Can be either 'sp' for horizontal split or 'vsp' for vertical split.
*g:scratch_buffer_default_buffer_size*
Type: `PositiveInt`
Default: `15`
The default size (height for 'sp' or width for 'vsp') of newly opened
scratch buffers. Set to a positive number to resize the buffer
upon opening.
Also if this is specified as `v:null`, resizing is not performed.
*g:scratch_buffer_auto_save_file_buffer*
Type: `boolean`
Default: `v:true`
When enabled, file buffers (not temporary buffers) will be
automatically saved when their content changes.
*g:scratch_buffer_auto_hide_buffer*
Type: `{ when_tmp_buffer?: boolean, when_file_buffer?: boolean }`
A dictionary that controls the auto-hiding behavior of scratch buffers.
Has the following keys:
.when_tmp_buffer ( Default: `v:false` )
When enabled,
temporary buffers will be automatically hidden
when leaving their window.
.when_file_buffer ( Default: `v:false` )
When enabled,
file buffers will be automatically hidden
when leaving their window.
Example:
>
" Disable auto-hiding for temporary buffers
let g:scratch_buffer_auto_hide_buffer = #{
\ when_tmp_buffer: v:false,
\ when_file_buffer: v:false,
\ }
<
*g:scratch_buffer_use_default_keymappings*
Type: `boolean`
Default: `v:false`
When enabled, the following default key mappings will be set:
>
nnoremap <silent> <leader>b <Cmd>ScratchBufferOpen<CR>
nnoremap <silent> <leader>B <Cmd>ScratchBufferOpenFile<CR>
<
*g:scratch_buffer_tmp_file_pattern*
Type: `string`
Default:
Deprecated.
Please use |g:scratch_buffer_file_pattern| instead.
------------------------------------------------------------------------------
COMMANDS *scratch-buffer-commands*
*:ScratchBufferOpen*
:ScratchBufferOpen [file-extension | --no-file-ext] [open-method] [buffer-size]
Open a temporary scratch buffer with a random file name.
This opens buffers by the rule
described in |g:scratch_buffer_file_pattern|.
If this command is called again, it will open the most recently used
scratch buffer.
[file-extension] is an optional argument:
- When omitted: Uses value from g:scratch_buffer_default_file_ext
- When --no-file-ext is specified:
Creates a buffer without file extension and filetype
- Otherwise:
Uses the specified extension (e.g., 'md', 'ts') as filetype
The buffer is opened as a temporary buffer with
the following properties:
>
setlocal buftype=nofile
setlocal bufhidden=hide
<
These settings make the buffer temporary and prevent writing to disk.
The buffer content remains in memory until Vim is closed or
|:ScratchBufferClean| is called.
[open-method] is an optional argument, should be `'sp'` or `'vsp'`.
Open the buffer on top if `'sp'`,
or open the buffer on the left if `'vsp'`.
Please also see |:split| and |:vsplit|.
Default value: see |g:scratch_buffer_default_open_method|
[buffer-size] is an optional argument, should be a positive number.
|:ScratchBufferOpen| resizes the opened buffer upon opening,
or uses the value from |g:scratch_buffer_default_buffer_size|
if omitted.
*:ScratchBufferOpenNext*
:ScratchBufferOpenNext [file-extension | --no-file-ext] [open-method] [buffer-size]
Similar to |:ScratchBufferOpen| but always creates a fresh temporary buffer
even if there are existing scratch buffers. This is useful when you want
to create multiple scratch buffers of the same type.
Takes the same arguments as |:ScratchBufferOpen|.
*:ScratchBufferOpenFile*
:ScratchBufferOpenFile [file-extension | --no-file-ext] [open-method] [buffer-size]
Similar to |:ScratchBufferOpen| but creates a persistent buffer instead of
a temporary one. Key differences:
1. The buffer is writable and changes can be saved to disk
2. If g:scratch_buffer_auto_save_file_buffer is enabled,
changes are automatically saved
3. The buffer behaves like a normal file buffer (buftype is empty)
This command is useful when you want to keep the content permanently
or need to share the file with other programs.
Takes the same arguments as |:ScratchBufferOpen|.
If you have a temporary buffer open and want to make it persistent,
you can use |:ScratchBufferOpenFile| with the same arguments - it will
use the same file path but make it writable.
*:ScratchBufferOpenFileNext*
:ScratchBufferOpenFileNext [file-extension | --no-file-ext] [open-method] [buffer-size]
Similar to |:ScratchBufferOpenFile| and |:ScratchBufferOpenNext|.
*:ScratchBufferClean*
:ScratchBufferClean
Delete all scratch files and buffers that
were opened by |:ScratchBufferOpen|.
==============================================================================
FUNCTIONS *scratch-buffer-functions*
*scratch_buffer#open()*
scratch_buffer#open(opening-next-fresh-buffer[, file-extension | --no-file-ext][, open-method][, buffer-size])
Function version of `:ScratchBufferOpen` and `:ScratchBufferOpenNext`.
Parameters:
opening-next-fresh-buffer:
Whether to create a new buffer (v:true) or
open the most recently used buffer (v:false)
file-extension:
Optional file extension or --no-file-ext
open-method:
Optional 'sp' or 'vsp'
buffer-size:
Optional positive number for buffer size
Creates a temporary buffer that cannot be written to disk.
See |:ScratchBufferOpen| for more details.
*scratch_buffer#open_file()*
scratch_buffer#open_file(opening-next-fresh-buffer[, file-extension | --no-file-ext][, open-method][, buffer-size])
Function version of |:ScratchBufferOpenFile|.
Parameters:
opening-next-fresh-buffer:
Whether to create a new buffer (v:true)
or open the most recently used buffer (v:false)
file-extension:
Optional file extension or --no-file-ext
open-method:
Optional 'sp' or 'vsp'
buffer-size:
Optional positive number for buffer size
Creates a persistent buffer that can be written to disk.
See |:ScratchBufferOpenFile| for more details.
*scratch_buffer#clean()*
scratch_buffer#clean()
Same as |:ScratchBufferClean|.
==============================================================================
CHANGELOG *scratch-buffer-changelog*
Also See https://github.com/aiya000/vim-scratch-buffer/commits/main
Breaking Changes:
- 2025-04-29:
Deprecate |g:scratch_buffer_tmp_file_pattern| .
Please use |g:scratch_buffer_file_pattern| instead.
==============================================================================
vim:tw=78:ts=8:ft=help:norl:noet:fen:fdm=marker