Draw pretty boxes in Vim
This README was converted by hand from the vimdoc included with the plugin. Please see that file for the definitive documentation.
This plugin is written in vim9script
and requires Vim v9.1.0120 or higher.
-
Plug 'jessepav/vim-boxdraw'
-
Manual installation:
Copy files from the
plugin
,autoload
, anddoc
directories to your.vim
directory.
BoxDraw provides a command to draw boxes using ASCII or Unicode box-drawing characters. It can also draw horizontal, vertical, and diagonal lines, and select existing boxes.
(We use images in the examples below because many fonts won't display all the box types correctly.)
When you draw a "box" that is just a vertical or horizontal line, we attempt to join the ends intelligently by examining the surrounding characters:
Once the plugin is loaded, it provides one command:
:BoxDraw [box-type or command] [force] [empty]
You make a selection in block-wise visual mode (setting 'virtualedit'
to
block
is very useful in this regard), and then invoke :BoxDraw
with the
desired arguments. Or you can use the boxdraw-mappings
below.
Argument | Description |
---|---|
box-type / command | Either one of the named box types above (single , rounded , double , ascii , clear ), or IBID , to use the same box type as last time, or a special command (SELECTBOX , DIAGONAL_BACKWARD , DIAGONAL_FORWARD ), each of which will be described below. |
force | Use true or 1 to disable intelligent box joining, and just draw the type of box indicated, overwriting any existing box characters encountered. |
empty | Use true or 1 to replace the interior of the box with spaces, thus "emptying" it. |
If the command provided to BoxDraw
is SELECTBOX
, we examine the character
under the cursor, and attempt to visually select the box that the character
belongs to. This works for stand-alone boxes, or the enclosing box of a
table, but not for table cells. It also works better for box-types other than
ascii
, since they have different characters for each of the four corners.
If the command is DIAGONAL_FORWARD
or DIAGONAL_BACKWARD
, we draw a
diagonal line starting at the bottom-left (for FORWARD
) or top-left (for
BACKWARD
) corner of the visual selection, and proceed until the line reaches
a selection boundary, horizontal or vertical.
If the global variable g:boxdraw_skip_mappings
is unset or is 0
, then
these mappings will be provided when the plugin is loaded:
# Not-forced not-emptied boxes
vnoremap <Leader>bs <Esc><Cmd>BoxDraw single<CR>
vnoremap <Leader>bd <Esc><Cmd>BoxDraw double<CR>
vnoremap <Leader>br <Esc><Cmd>BoxDraw rounded<CR>
vnoremap <Leader>ba <Esc><Cmd>BoxDraw ascii<CR>
vnoremap <Leader>bc <Esc><Cmd>BoxDraw clear<CR>
vnoremap <Leader>bb <Esc><Cmd>BoxDraw<CR>
# Not-forced emptied boxes
vnoremap <Leader>bes <Esc><Cmd>BoxDraw single false true<CR>
vnoremap <Leader>bed <Esc><Cmd>BoxDraw double false true<CR>
vnoremap <Leader>ber <Esc><Cmd>BoxDraw rounded false true<CR>
vnoremap <Leader>bea <Esc><Cmd>BoxDraw ascii false true<CR>
vnoremap <Leader>bec <Esc><Cmd>BoxDraw clear false true<CR>
# Diagonals (always 'single' style)
vnoremap <Leader>b/ <Esc><Cmd>BoxDraw DIAGONAL_FORWARD<CR>
vnoremap <Leader>b\ <Esc><Cmd>BoxDraw DIAGONAL_BACKWARD<CR>
# Selection
vnoremap <Leader>bl <Esc><Cmd>BoxDraw SELECTBOX<CR>
# Forced not-emptied boxes
vnoremap <Leader>BS <Esc><Cmd>BoxDraw single true<CR>
vnoremap <Leader>BD <Esc><Cmd>BoxDraw double true<CR>
vnoremap <Leader>BR <Esc><Cmd>BoxDraw rounded true<CR>
vnoremap <Leader>BA <Esc><Cmd>BoxDraw ascii true<CR>
vnoremap <Leader>BC <Esc><Cmd>BoxDraw clear true<CR>
vnoremap <Leader>BB <Esc><Cmd>BoxDraw IBID true<CR>
# Forced emptied boxes
vnoremap <Leader>BES <Esc><Cmd>BoxDraw single true true<CR>
vnoremap <Leader>BED <Esc><Cmd>BoxDraw double true true<CR>
vnoremap <Leader>BER <Esc><Cmd>BoxDraw rounded true true<CR>
vnoremap <Leader>BEA <Esc><Cmd>BoxDraw ascii true true<CR>
vnoremap <Leader>BEC <Esc><Cmd>BoxDraw clear true true<CR>
# Normal mode selection
nnoremap <Leader><Leader>bl <Cmd>BoxDraw SELECTBOX<CR>
# One-key meta shortcuts
vnoremap <M-b> <Esc><Cmd>BoxDraw<CR>
vnoremap <M-B> <Esc><Cmd>BoxDraw IBID true<CR>
vnoremap <M-l> <Esc><Cmd>BoxDraw SELECTBOX<CR>
nnoremap <M-l> <Cmd>BoxDraw SELECTBOX<CR>
Jesse Pavel
[email protected]
https://github.com/jessepav/vim-boxdraw
MIT