Repository navigation
Expand file tree
/
Copy pathmap.lua
More file actions
1618 lines (1400 loc) · 63.1 KB
/
Copy pathmap.lua
File metadata and controls
1618 lines (1400 loc) · 63.1 KB
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
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
--- *mini.map* Window with buffer text overview
--- *MiniMap*
---
--- MIT License Copyright (c) 2022 Evgeni Chasnovski
---
--- ==============================================================================
---
--- Features:
--- - Show and manage special floating window displaying automatically updated
--- overview of current buffer text. Window takes up whole height of Neovim
--- instance and is fixed to a left/right side. Map content is computed by
--- taking all current lines, converting it to binary whitespace/non-whitespace
--- mask, rescaling to appropriate dimensions, and converting back to strings
--- consisting from special encoding symbols. All this is done **very fast** and
--- **asynchronously**. See |MiniMap.open()|, |MiniMap.refresh()|, |MiniMap.close()|,
--- |MiniMap.toggle()|, |MiniMap.toggle_side()|.
--- For a general overview and tips, see |mini.map-usage|.
---
--- - Show scrollbar next to map content. It represents current line and view
--- (top and bottom visible lines). Can be the only thing shown, making map
--- window a "pure scrollbar". See "Pure scrollbar config" section in
--- |MiniMap.config|.
---
--- - Highlight map lines representing certain data in current buffer. This is
--- done via extensible set of callables, called integrations (see
--- "Integrations" section in |MiniMap.config|). There are pre-built generators
--- for common integrations:
--- - Builtin search (as result of |/| and similar).
--- - Builtin diagnostic (taken from |vim.diagnostic.get()|).
--- - Git line status (with help of 'lewis6991/gitsigns.nvim', see
--- |gitsigns.get_hunks()|).
--- For more details see |MiniMap.gen_integration|.
---
--- - Focus on map window to quickly browse current (source) buffer. Moving inside
--- map window updates cursor position in source window enabling fast and
--- targeted buffer exploration. To focus back, hit `<CR>` to accept current
--- explored position or `<Esc>` to go back to original position. See
--- |MiniMap.toggle_focus()|.
---
--- - Customizable via |MiniMap.config| and/or `opts` argument of |MiniMap.open()|
--- or |MiniMap.refresh()|:
--- - Encoding symbols used to display binary information of different
--- resolution (default is 3x2). There are pre-built generators for
--- different basic character families and resolutions. See
--- |MiniMap.gen_encode_symbols|.
--- - Scrollbar symbols, separate for line and view. Can have any width
--- (even zero, which virtually disables scrollbar).
--- - Integrations producing map line highlights.
--- - Window options: side (left/right), width, 'winblend', and more.
---
--- What it doesn't do:
--- - Automatically refresh when typing in Insert mode. Although it can be done in
--- non-blocking way, it still might introduce considerable computation overhead
--- (especially in very large files).
--- - Has more flexible window configuration. In case a full height floating
--- window obstructs vision of underlying buffers, use |MiniMap.toggle()| or
--- |MiniMap.toggle_side()|. Works best with global statusline.
--- - Provide autoopen functionality. Due to vast differences in user preference
--- of when map window should be shown, set up of automatic opening is left to
--- user. A common approach would be to call `MiniMap.open()` on |VimEnter| event.
--- If you use |MiniStarter|, you can modify `<CR>` buffer mapping: >
---
--- vim.cmd([[autocmd User MiniStarterOpened
--- \ lua vim.keymap.set(
--- \ 'n',
--- \ '<CR>',
--- \ '<Cmd>lua MiniStarter.eval_current_item(); MiniMap.open()<CR>',
--- \ { buffer = true }
--- \ )]])
--- <
--- # Setup ~
---
--- This module needs a setup with `require('mini.map').setup({})` (replace
--- `{}` with your `config` table). It will create global Lua table `MiniMap`
--- which you can use for scripting or manually (with `:lua MiniMap.*`).
---
--- See |MiniMap.config| for available config settings.
---
--- You can override runtime config settings (like `config.modifiers`) locally
--- to buffer inside `vim.b.minimap_config` which should have same structure
--- as `MiniMap.config`. See |mini.nvim-buffer-local-config| for more details.
---
--- # Dependencies ~
---
--- Suggested dependencies (provide extra functionality for integrations):
--- - Plugin 'lewis6991/gitsigns.nvim' for Git status highlighting via
--- |MiniMap.gen_integration.gitsigns()|. If missing, no highlighting is added.
---
--- # Comparisons ~
---
--- - 'wfxr/minimap.vim':
--- - 'mini.map' doesn't have dependencies while being as fast as written
--- in Rust dependency of 'minimap.vim'.
--- - 'mini.map' uses floating window, while 'minimap.vim' uses regular one.
--- - 'mini.map' provides slightly different visual interface with
--- scrollbar and integration counts.
--- - 'mini.map' allows encode symbols customization, 'minimap.vim' does not.
--- - 'mini.map' allows extending highlight integrations, while only
--- builtin search and git status are supported in 'minimap.vim'.
--- - 'mini.map' updates in asynchronous (non-blocking) fashion, 'minimap.vim'
--- does not.
--- - 'mini.map' can be used as a pure scrollbar, 'minimap.vim' can not.
--- - 'dstein64/nvim-scrollview':
--- - 'mini.map' has two-part scrollbar showing current line and view (with
--- variable height), while 'nvim-scrollview' shows only current view
--- (with fixed height).
--- - 'nvim-scrollview' respects folds, i.e. shows view of visible lines,
--- while 'mini.map' by design always shows view based on actual lines.
--- - 'nvim-scrollview' creates scrollbar which can be dragged with mouse,
--- while 'mini.nvim' does not, by design (use |MiniMap.toggle_focus()|).
--- - 'mini.map' can show buffer outline, while 'nvim-scrollview' can not.
--- - 'mini.map' can show highlight integrations, while 'nvim-scrollview'
--- can not.
--- - 'petertriho/nvim-scrollbar':
--- - 'mini.map' has two-part scrollbar showing current line and view (with
--- variable height), while 'nvim-scrollbar' shows only current view.
--- - 'mini.map' can show buffer outline, while 'nvim-scrollbar' can not.
--- - 'mini.map' has fully extendable highlight integrations, while
--- 'nvim-scrollbar' only supports diagnostic and search (with dependency).
--- - 'lewis6991/satellite.nvim':
--- - Almost the same differences as with 'dstein64/nvim-scrollview', except
--- 'satellite.nvim' can display some set of integration highlights.
---
--- # Highlight groups ~
---
--- * `MiniMapNormal` - basic highlight of whole window.
--- * `MiniMapSymbolCount` - counts of per-line integration items.
--- * `MiniMapSymbolLine` - scrollbar part representing current line.
--- * `MiniMapSymbolView` - scrollbar part representing current view.
---
--- To change any highlight group, modify it directly with |:highlight|.
---
--- # Disabling ~
---
--- To disable, set `vim.g.minimap_disable` (globally) or `vim.b.minimap_disable`
--- (for a buffer) to `true`. Considering high number of different scenarios
--- and customization intentions, writing exact rules for disabling module's
--- functionality is left to user. See |mini.nvim-disabling-recipes| for common
--- recipes.
--- # Mappings ~
---
--- This module doesn't make mappings, only provides functions for users to map
--- manually. Here is how one |<Leader>| set of mappings can be constructed: >
---
--- vim.keymap.set('n', '<Leader>mc', MiniMap.close)
--- vim.keymap.set('n', '<Leader>mf', MiniMap.toggle_focus)
--- vim.keymap.set('n', '<Leader>mo', MiniMap.open)
--- vim.keymap.set('n', '<Leader>mr', MiniMap.refresh)
--- vim.keymap.set('n', '<Leader>ms', MiniMap.toggle_side)
--- vim.keymap.set('n', '<Leader>mt', MiniMap.toggle)
--- <
--- # How automatic refresh works ~
---
--- Automatic refresh is done by calling |MiniMap.refresh()| when appropriate
--- |events| occur. It is done with specially chosen `parts` argument value (to
--- avoid unnecessary computations). For example, when only cursor has moved
--- (|CursorMoved|), only scrollbar is updated; so no recomputation of integrations
--- or line encoding is done.
---
--- To avoid visual clutter, automatic refresh is done only in normal buffers
--- and help pages (i.e. with |buftype| being empty or "help")
---
--- When you think content is not up to date, try one of these:
--- - Call |MiniMap.refresh()| manually. Make mapping to make it easier.
--- - Save current buffer, for example with |:write|.
--- - Exit and enter Normal mode (if your Neovim version supports |ModeChanged|).
---@tag mini.map-usage
---@alias __map_opts table|nil Options used to define map configuration. Same structure
--- as |MiniMap.config|. Will have effect until at least one tabpage has opened
--- map window. Default values are taken in the following order:
--- - From `opts` field of |MiniMap.current|.
--- - From `vim.b.minimap_config`.
--- - From |MiniMap.config|.
---@diagnostic disable:undefined-field
-- Module definition ==========================================================
local MiniMap = {}
local H = {}
--- Module setup
---
---@param config table|nil Module config table. See |MiniMap.config|.
---
---@usage `require('mini.map').setup({})` (replace `{}` with your `config` table)
MiniMap.setup = function(config)
-- Export module
_G.MiniMap = MiniMap
-- Setup config
config = H.setup_config(config)
-- Apply config
H.apply_config(config)
-- Define behavior
H.create_autocommands()
-- Create default highlighting
H.create_default_hl()
end
--stylua: ignore
--- Module config
---
--- Default values:
---@eval return MiniDoc.afterlines_to_code(MiniDoc.current.eval_section)
---@text # Options ~
---
--- ## Symbols ~
---
--- Options in `config.symbols` define characters used to display various
--- information in map window.
---
--- ### Encode symbols ~
---
8BD0
--- The `config.symbols.encode` option defines which characters are used to
--- encode source buffer lines. For details of encode algorithm, see
--- |MiniMap.encode_strings()|.
---
--- This option should be a table with the following structure:
--- - <resolution> field - table containing <row> and <col> elements with row
--- and column resolution of each symbol. This defines encoding structure and
--- number of needed encode symbols.
--- - Numerical fields 1, 2, ..., 2^(row_resolution * col_resolution). Each symbol
--- represents a `(row_resolution, col_resolution)` boolean mask (`true` for
--- non-whitespace, `false` for whitespace), created as (reversed) binary digit:
--- `true` as 1; `false` as 0. Traversing left-right, top-bottom (top-left is
--- lowest bit, bottom-right - highest). So first symbol encodes a complete
--- whitespace, last - complete non-whitespace.
---
--- If `nil` (default), output of |MiniMap.gen_encode_symbols.block()| with `'3x2'`
--- identifier is used.
---
--- Example: { '1', '2', '3', '4', resolution = { row = 1, col = 2 } }. This
--- will encode two characters in each input row. So a string `' a aaa'` will
--- be encoded as `'1234'`.
---
--- There are pre-built generators of encode symbols:
--- - |MiniMap.gen_encode_symbols.block()|
--- - |MiniMap.gen_encode_symbols.dot()|
--- - |MiniMap.gen_encode_symbols.shade()|
---
--- ### Scrollbar symbols ~
---
--- Options `config.symbols.scroll_line` and `config.symbols.scroll_view` define
--- strings used to represent current line and current view inside map window.
--- Can have any length, map window content will adjust.
---
--- If supplied window width is small enough so that only (part of) of
--- scrollbar can be shown, it is called a "pure scrollbar". The behavior differs
--- slightly from normal map window. See "Pure scrollbar config" later section.
---
--- Some suggestions for scrollbar symbols:
--- - View-line pairs: '▒' and '█'.
--- - Line - '🮚', '▶'.
--- - View - '╎', '┋', '┋'.
---
--- ## Integrations ~
---
--- Option `config.integrations` is an array of integrations. Each one is used
--- to define map line highlights representing some important lines in source
--- buffer. If `nil` (default), no integrations are used.
---
--- Each integration should be a callable returning an array with data about
--- **source buffer** lines it wants to highlight. Each array element should be
--- a table with <line> (source buffer line number) and <hl_group> (string with
--- highlight group name) keys. Note: line number outside of source buffer
--- count will be converted to a nearest appropriate one.
---
--- Example output of single integration: >
---
--- {
--- { line = 1, hl_group = 'Search' },
--- { line = 2, hl_group = 'Operator' },
--- { line = 9, hl_group = 'Search'}
--- }
--- <
--- Conversion to map highlights is done on a "first seen" basis: actual
--- highlight group applied to a map line is taken from the first integration
--- output convertible to that map line. Other outputs with same map line
--- (after conversion) contribute to integration count shown between scrollbar
--- and encoded lines (if `config.window.show_integration_count` is `true`).
---
--- Previous example output with default `'3x2'` resolution will add |hl-Search|
--- highlight on map lines 1 and 3, and show integration count 2 on first line.
---
--- Every element of integrations array is called one by one from start to end
--- with their outputs appended to end of single array. This means that more
--- important integrations should be placed in the beginning of an array, as
--- this will make them have higher priority in case other integrations will
--- highlight same map line.
---
--- Example of using `config.integrations`: >
---
--- local map = require('mini.map')
--- map.setup({
--- integrations = {
--- map.gen_integration.builtin_search(),
--- map.gen_integration.gitsigns(),
--- map.gen_integration.diagnostic(),
--- },
--- })
--- <
--- ## Window config ~
---
--- Option `config.window` defines some properties of map window.
---
--- `window.focusable` - whether to allow focusing on map window with other
--- methods beside |MiniMap.toggle_focus()| (like |wincmd|, |CTRL-W|, or
--- mouse). Default: `false`.
---
--- `window.side` - which side to stick map window: `'left'` or `'right'` (default).
---
--- `window.show_integration_count` - whether to show integration count between
--- scrollbar and encoded lines. Integration count is a number of integration
--- outputs which were converted to same map line. When `true`, adds single
--- cell column with numbers from 2 to 9 and character '+' indicating count
--- greater than 9. Count 1 is not shown, because it is redundant to highlighted
--- map line. Default: `true`.
---
--- `window.width` - width of floating window, including scrollbar and
--- integration count column. Default: 10.
---
--- `window.winblend` - value of 'winblend' of floating window. Value 0 makes it
--- completely non-transparent, 100 - completely transparent (content is still
--- visible, but with slightly different highlights).
---
--- `window.zindex` - z-index of floating window. Default: 10.
---
--- # Pure scrollbar config ~
---
--- "Pure scrollbar" is a configuration when window width is not enough to show
--- encoded content. It has following differences from default "map" approach:
--- - It doesn't perform line encoding with |MiniMap.encode_strings()|
--- but instead uses encoding with fixed number of lines (equal to window
--- height).
--- - Integration highlights are not computed.
---
--- Config: >
---
--- require('mini.map').setup({
--- -- Customize `symbols` to your liking
---
--- window = {
--- -- Set this to the maximum width of your scroll symbols
--- width = 1,
---
--- -- Set this to your liking. Try values 0, 25, 50, 75, 100
--- winblend = 100,
---
--- -- Don't need extra column
--- show_integration_count = false,
--- }
--- })
MiniMap.config = {
-- Highlight integrations (none by default)
integrations = nil,
-- Symbols used to display data
symbols = {
-- Encode symbols. See `:h MiniMap.config` for specification and
-- `:h MiniMap.gen_encode_symbols` for pre-built ones.
-- Default: solid blocks with 3x2 resolution.
encode = nil,
-- Scrollbar parts for view and line. Use empty string to disable any.
scroll_line = '█',
scroll_view = '┃',
},
-- Window options
window = {
-- Whether window is focusable in normal way (with `wincmd` or mouse)
focusable = false,
-- Side to stick ('left' or 'right')
side = 'right',
-- Whether to show count of multiple integration highlights
show_integration_count = true,
-- Total width
width = 10,
-- Value of 'winblend' option
winblend = 25,
-- Z-index
zindex = 10,
},
}
--minidoc_afterlines_end
--- Table with information about current state of map
---
--- At least these keys are supported:
--- - <buf_data> - table with buffer identifiers. Field <map> contains
--- identifier of a buffer used to display map. Field <source> - buffer
--- identifier which content map is displaying (i.e. source buffer).
--- - <win_data> - table of window identifiers used to display map in certain
--- tabpage. Keys: tabpage identifier. Values: window identifier.
--- - <opts> - current options used to control map display. Same structure
--- as |MiniMap.config|. Takes precedence over global and buffer-local configs.
--- Is reset when last map window is closed with |MiniMap.close()|.
MiniMap.current = {
buf_data = {},
win_data = {},
opts = {},
}
-- Module functionality =======================================================
--- Encode strings
---
--- This takes arbitrary array of strings and computes its non-whitespace
--- outline. Output is an array of strings with configurable array length, string
--- width, and symbols representing encoding.
---
--- Each encode symbol is assumed to have resolution within which it can convey
--- binary information. For example, resolution `3x2` (row resolution 3,
--- column - 2) means that each symbol can encode 3 rows and 2 columns of
--- binary data. Here it is used to encode non-whitespace mask. See more in
--- "Encode symbols" section of |MiniMap.config|.
---
--- Encoding has the following steps:
--- - Convert strings to boolean mask: 2d boolean array with each row
--- representing a string. Element in every row subarray is `true` if
--- respective (possibly multibyte) character in a string is not a whitespace,
--- `false` otherwise. Note: tabs are expanded into 'tabstop' spaces.
--- - Rescale to appropriate dimensions:
--- - Each output dimension is just enough to encode all input strings, but
--- not more than supplied dimensions (`opts.n_rows * resolution.row` and
--- `opts.n_cols * resolution.col` respectively).
--- - If input dimensions are too big to fit inside output, perform grid
--- downscaling with loss of information. Input boolean mask is divided
--- into 2d-bins with as equal as possible dimensions. Each bin then
--- converted into single boolean value: `true` if bin contains at least
--- one `true` element, `false` otherwise. This leads to a whitespace
--- output meaning that **all** entries in a bin are whitespace, while
--- non-whitespace output means that **some** entry is non-whitespace.
--- - Convert boolean mask to symbol strings:
--- - Input rescaled boolean mask is divided into bins with dimensions of
--- symbol resolution (assuming `false` outer padding).
--- - Each bin with resolution dimensions is transformed into encode symbol.
--- Single convertible `(resolution.row, resolution.col)` boolean
--- mask is treated as (reversed) binary digit: `true` as 1; `false` as 0.
--- Traversing left-right, top-bottom (top-left is lowest bit,
--- bottom-right - highest).
---
--- Example ~
---
--- Assume the output should have 3 rows of symbols each with width 2. Encode
--- symbols are ' ', '▌', '▐', '█' with `1x2` resolution.
---
--- Assume input strings: >
--- aaaaa
--- b b
---
--- d d
--- e e
--- <
--- Steps:
--- - Convert to boolean mask (each row is a boolean array, "t"/"f" ~ `true`/`false`,
--- empty spots are equivalent to being `false`): >
--- ttttt
--- ftft
---
--- ftft
--- tft
--- <
--- - Rescale. Output dimensions are `n_rows * resolution.row = 3 * 1 = 3` rows and
--- `n_cols * resolution.col = 2 * 2 = 4`. It creates as equal as possible grid
--- with 3 rows and 4 columns and converts bins to single booleans. Result: >
--- tttt
--- tftf
--- ttff
--- - Convert to symbols. It makes `1x2` bins, treats their input as (reversed)
--- binary digits (`ff=00=0`, `tf=10=1`, `ft=01=2`, `tt=11=3`) and takes
--- corresponding symbols from supplied options (value plus 1). Result: >
--- ██
--- ▌▌
--- █
--- <
---@param strings table Array of arbitrary strings.
---@param opts table|nil Options. Possible fields:
--- - <n_rows> - number of rows in output encoding. If too big, will be
--- truncated to be maximum needed to encode all input strings (taking into
--- account symbols row resolution). Default: `math.huge`.
--- - <n_cols> - width of every encoding string. If too big, will be truncated
--- to be maximum needed to encode all input strings (taking into account
--- symbols column resolution). Default: `math.huge`.
--- - <symbols> - array of symbols with extra `resolution` field. See "Encode
--- symbols" section of |MiniMap.config| for more details. Default: output
--- of |MiniMap.gen_encode_symbols.block()| with `'3x2'` identifier.
---
---@return table Array of encoded strings.
MiniMap.encode_strings = function(strings, opts)
-- Validate input
if not H.is_array_of(strings, H.is_string) then
H.error('`strings` argument of `encode_strings()` should be array of strings.')
end
opts = vim.tbl_deep_extend(
'force',
{ n_rows = math.huge, n_cols = math.huge, symbols = H.get_config().symbols.encode or H.default_symbols },
opts or {}
)
-- Compute encoding
local mask = H.mask_from_strings(strings, opts)
mask = H.mask_rescale(mask, opts)
return H.mask_to_symbols(mask, opts)
end
--- Open map window
---
--- This creates and shows map window in current tabpage. It basically has
--- two steps:
--- - If not already done, create map buffer (used to set lines and other
--- visual indicators) and map window.
--- - Call |MiniMap.refresh()|.
---
---@param opts __map_opts
MiniMap.open = function(opts)
-- Early returns
if H.is_disabled() then return end
-- Normalize input
opts = H.normalize_opts(opts)
-- Allow execution in case of already opened window
if H.is_window_open() then
MiniMap.refresh(opts)
return
end
-- Open buffer and window
local buf_id = MiniMap.current.buf_data.map
if buf_id == nil or not vim.api.nvim_buf_is_valid(buf_id) then
buf_id = H.create_map_buffer()
MiniMap.current.buf_data.map = buf_id
end
local win_id = vim.api.nvim_open_win(buf_id, false, H.normalize_window_options(opts.window))
H.set_current_map_win(win_id)
-- Set buffer and window options. Other important options are handled by
-- `style = 'minimal'` in `nvim_open_win()`.
vim.api.nvim_win_call(win_id, function()
--stylua: ignore
local options = {
'buftype=nofile', 'foldcolumn=0', 'foldlevel=999', 'matchpairs=', 'nobuflisted',
'nomodeline', 'noreadonly', 'noswapfile', 'synmaxcol&', 'nowrap',
}
-- Vim's `setlocal` is currently more robust compared to `opt_local`
-- Use `noautocmd` to make it more invisible for others
vim.cmd(('silent! noautocmd setlocal %s'):format(table.concat(options, ' ')))
-- Override Normal highlighting locally for map window
vim.cmd('silent! setlocal winhighlight=NormalFloat:MiniMapNormal')
end)
-- Refresh content
MiniMap.refresh(opts)
end
--- Refresh map window
---
--- This function serves two purposes:
--- - Update current map configuration via `opts`.
--- - Update parts of displayed content via `parts`.
---
---@param opts __map_opts
---@param parts table|nil Which parts to update. Recognised keys with boolean
--- values (all `true` by default):
--- - <integrations> - whether to update integration highlights.
--- - <lines> - whether to update map lines.
--- - <scrollbar> - whether to update scrollbar.
MiniMap.refresh = function(opts, parts)
-- Early return
if H.is_disabled() or not H.is_window_open() then return end
-- Normalize input
opts = H.normalize_opts(opts)
parts = vim.tbl_deep_extend('force', { integrations = true, lines = true, scrollbar = true }, parts or {})
-- Update current data
H.cache.scrollbar_data.offset = math.max(H.str_width(opts.symbols.scroll_line), H.str_width(opts.symbols.scroll_view))
+ (opts.window.show_integration_count and 1 or 0)
MiniMap.current.opts = opts
-- Update window options
H.update_window_opts()
-- Possibly update parts in asynchronous fashion
if parts.lines then vim.schedule(H.update_map_lines) end
if parts.scrollbar then vim.schedule(H.update_map_scrollbar) end
if parts.integrations then vim.schedule(H.update_map_integrations) end
end
--- Close map window
---
--- Also resets `opts` field of |MiniMap.current| after closing last map window
--- (among possibly several tabpages).
MiniMap.close = function()
pcall(vim.api.nvim_win_close, H.get_current_map_win(), true)
H.set_current_map_win(nil)
-- Reset current options if closed last window so as to use config during
-- next opening
if vim.tbl_count(MiniMap.current.win_data) == 0 then MiniMap.current.opts = {} end
end
--- Toggle map window
---
--- Open if not shown in current tabpage, close otherwise.
---
---@param opts table|nil Input for |MiniMap.open()|.
MiniMap.toggle = function(opts)
if H.is_window_open() then
MiniMap.close()
else
MiniMap.open(opts)
end
end
--- Toggle focus to/from map window
---
--- When not inside map window, put cursor inside map window; otherwise put
--- cursor in previous window with source buffer.
---
--- When cursor is moving inside map window (but not just after focusing), view of
--- source window is updated to show first line convertible to current map line.
--- This allows quick targeted source buffer exploration.
---
--- There are at least these extra methods to focus back from map window:
--- - Press `<CR>` to accept current explored position in source buffer.
--- Equivalent to calling this function with `false` argument.
--- - Press `<Esc>` to go back to original position prior focusing on map window.
--- Equivalent to calling this function with `true` argument.
---
---@param use_previous_cursor boolean|nil Whether to focus on source window at
--- original cursor position (the one prior focusing on map window).
MiniMap.toggle_focus = function(use_previous_cursor)
if not H.is_window_open() then return end
local cur_win, map_win = vim.api.nvim_get_current_win(), H.get_current_map_win()
if cur_win == map_win then
-- Focus on previous window
vim.api.nvim_set_current_win(H.cache.previous_win.id)
-- Use either previous cursor or first non-whitespace character (if this
-- was the result of cursor movement inside map window)
if use_previous_cursor then
vim.api.nvim_win_set_cursor(0, H.cache.previous_win.cursor)
elseif H.cache.n_map_cursor_moves > 1 then
vim.cmd('normal! ^')
end
else
-- Focus on map window. Cursor is set on `BufEnter` to account for other
-- ways of focusing on buffer (for example, with `<C-w><C-w>`)
vim.api.nvim_set_current_win(map_win)
end
end
--- Toggle side of map window
---
--- A small convenience wrapper for calling |MiniMap.refresh()| to change the
--- side of map window.
MiniMap.toggle_side = function()
if not H.is_window_open() then return end
local cur_side = MiniMap.current.opts.window.side
MiniMap.refresh(
{ window = { side = cur_side == 'left' and 'right' or 'left' } },
{ integrations = false, lines = false, scrollbar = false }
)
end
--- Generate encode symbols
---
--- This is a table with function elements. Call to actually get encode symbols.
---
--- Each element takes a string resolution identifier of a form `'rxc'` (like `'3x2'`)
--- where `r` is a row resolution of each symbol (how many rows of binary data it
--- can encode) and `c` is a column resolution (how many columns it can encode).
MiniMap.gen_encode_symbols = {}
--- Generate block encode symbols
---
--- Outputs use solid block to encode binary data. Example: '🬗', '▟', '█'.
---
---@param id string Resolution identifier.
--- Available values: `'1x2'`, `'2x1'`, `'2x2'`, `'3x2'` (default in 'mini.map').
MiniMap.gen_encode_symbols.block = function(id) return H.block_symbols[id] end
--- Generate dot encode symbols
---
--- Outputs use dots to encode binary data. Example: '⡪', '⣼', '⣿'.
---
---@param id string Resolution identifier. Available values: `'4x2'`, `'3x2'`.
MiniMap.gen_encode_symbols.dot = function(id) return H.dot_symbols[id] end
--- Generate shade encode symbols
---
--- Outputs use whole cell shades to encode binary data. They use same set of
--- characters ('░', '▒', '▒', '▓), but with different resolution.
---
---@param id string Resolution identifier. Available values: `'1x2'`, `'2x1'`.
MiniMap.gen_encode_symbols.shade = function(id) return H.shade_symbols[id] end
--- Generate integrations
---
--- This is a table with function elements. Call to actually get encode symbols.
---
--- Each element takes a table defining highlight groups used for to highlight
--- map lines.
MiniMap.gen_integration = {}
--- Builtin search
---
--- Highlight lines with matches of current builtin search (like with |/|, |?|, etc.).
--- Integration count reflects number of actual matches.
---
--- It prompts integration highlighting update on every change of |hlsearch| option
--- (see |OptionSet|). Note, that it doesn't do that when search is
--- started with |n|, |N|, or similar (there is no good approach for this yet).
--- To enable highlight update on this keys, make custom mappings. Like this: >
---
--- for _, key in ipairs({ 'n', 'N', '*', '#' }) do
--- vim.keymap.set(
--- 'n',
--- key,
--- key ..
--- '<Cmd>lua MiniMap.refresh({}, {lines = false, scrollbar = false})<CR>'
--- )
--- end
--- <
---@param hl_groups table|nil Table defining highlight groups. Can have the
--- following fields:
--- - <search> - highlight group for search matches. Default: |hl-Search|.
MiniMap.gen_integration.builtin_search = function(hl_groups)
if hl_groups == nil then hl_groups = { search = 'Search' } end
-- Update when necessary. Not ideal, because it won't react on `n/N/*`, etc.
-- See https://github.com/neovim/neovim/issues/18879
local augroup = vim.api.nvim_create_augroup('MiniMapBuiltinSearch', {})
vim.api.nvim_create_autocmd(
'OptionSet',
{ group = augroup, pattern = 'hlsearch', callback = H.on_integration_update, desc = "On 'hlsearch' update" }
)
local search_hl = hl_groups.search
return function()
-- Do nothing of search is not active
if vim.v.hlsearch == 0 or not vim.o.hlsearch then return {} end
-- Do nothing if not inside source buffer (can happen in map buffer, for example)
if not H.is_source_buffer() then return {} end
-- Save window view to later restore, as the only way to get positions of
-- search matches seems to be consecutive application of `search()` and
-- retrieving cursor position.
local win_view = vim.fn.winsaveview()
vim.api.nvim_win_set_cursor(0, { 1, 0 })
local search_count = vim.fn.searchcount({ recompute = true, maxcount = 0 })
local search_pattern = vim.fn.getreg('/')
local line_hl = {}
for _ = 1, (search_count.total or 0) do
vim.fn.search(search_pattern)
table.insert(line_hl, { line = vim.fn.line('.'), hl_group = search_hl })
end
vim.fn.winrestview(win_view)
return line_hl
end
end
--- Builtin diagnostic
---
--- Highlight lines with matches of current diagnostic items. Items are computed
--- with |vim.diagnostic.get()| for current (source) buffer.
---
--- It prompts integration highlighting update on every |DiagnosticChanged| event.
--- Diagnostic items with higher severity (see |vim.diagnostic.severity|) have
--- higher highlight priority (errors will be shown over all others, etc.).
---
---@param hl_groups table|nil Table defining highlight groups. Supplied fields
--- also define which diagnostic severity to highlight.
--- Can have the following fields:
--- - <error> - highlight group for error items.
--- Default: |hl-DiagnosticFloatingError|.
--- - <warn> - highlight group for warning items. Default: `nil` (not shown).
--- - <info> - highlight group for info items. Default: `nil` (not shown).
--- - <hint> - highlight group for hint items. Default: `nil` (not shown).
---
---@usage Show all diagnostic levels: >
--- local map = require('mini.map')
--- local diagnostic_integration = map.gen_integration.diagnostic({
--- error = 'DiagnosticFloatingError',
--- warn = 'DiagnosticFloatingWarn',
--- info = 'DiagnosticFloatingInfo',
--- hint = 'DiagnosticFloatingHint',
--- })
--- map.setup({ integrations = { diagnostic_integration } })
MiniMap.gen_integration.diagnostic = function(hl_groups)
if hl_groups == nil then hl_groups = { error = 'DiagnosticFloatingError' } end
-- Precompute ordered array of supported levels. Using keys of
-- `severity_highlights` is not enough because higher severity should be
-- processed later in order to appear on top.
local severity_level_names = vim.tbl_filter(
function(x) return vim.tbl_contains(vim.tbl_keys(hl_groups), x) end,
{ 'error', 'warn', 'info', 'hint' }
)
local severity_data = vim.tbl_map(
function(x) return { severity = vim.diagnostic.severity[x:upper()], hl_group = hl_groups[x] } end,
severity_level_names
)
-- Refresh map when needed
local augroup = vim.api.nvim_create_augroup('MiniMapDiagnostics', {})
vim.api.nvim_create_autocmd(
'DiagnosticChanged',
{ group = augroup, callback = H.on_integration_update, desc = 'On DiagnosticChanged' }
)
return function()
local line_hl = {}
local diagnostic_arr = vim.diagnostic.get(MiniMap.current.buf_data.source)
for _, data in ipairs(severity_data) do
local severity_diagnostic_arr = vim.tbl_filter(function(x) return x.severity == data.severity end, diagnostic_arr)
for _, diag in ipairs(severity_diagnostic_arr) do
-- Add all diagnostic lines to highlight
for i = diag.lnum, diag.end_lnum do
table.insert(line_hl, { line = i + 1, hl_group = data.hl_group })
end
end
end
return line_hl
end
end
--- Git line status
---
--- Highlight lines which have non-trivial Git status. Requires dependency
--- 'lewis6991/gitsigns.nvim' installed and set up. Uses |gitsigns.get_hunks()|
--- and should highlight map lines similarly to how Gitsigns highlights source
--- buffer lines (except dealing with rescaled input on "first seen" bases; see
--- "Integrations" section in |MiniMap.config|).
---
--- It prompts integration highlighting update on every |gitsigns-event|.
---
---@param hl_groups table|nil Table defining highlight groups. If `nil` (not
--- supplied), this status is not highlighted. Can have the following fields:
--- - <add> - highlight group for added lines. Default: "GitSignsAdd".
--- - <change> - highlight group for changed lines. Default: "GitSignsChange".
--- - <delete> - highlight group for deleted lines. Default: "GitSignsDelete".
MiniMap.gen_integration.gitsigns = function(hl_groups)
if hl_groups == nil then hl_groups = { add = 'GitSignsAdd', change = 'GitSignsChange', delete = 'GitSignsDelete' } end
local augroup = vim.api.nvim_create_augroup('MiniMapGitsigns', {})
vim.api.nvim_create_autocmd(
'User',
{ group = augroup, pattern = 'GitSignsUpdate', callback = H.on_integration_update, desc = 'On GitSignsUpdate' }
)
return function()
local has_gitsigns, gitsigns = pcall(require, 'gitsigns')
if not has_gitsigns or gitsigns == nil then return {} end
local has_hunks, hunks = pcall(gitsigns.get_hunks, MiniMap.current.buf_data.source)
if not has_hunks or hunks == nil then return {} end
local line_hl = {}
for _, hunk in ipairs(hunks) do
local from_line = hunk.added.start
local n_added, n_removed = hunk.added.count, hunk.removed.count
local n_lines = math.max(n_added, 1)
-- Highlight similar to 'gitsigns' itself:
-- - Delete - single first line if nothing was added.
-- - Change - added lines that are within first removed lines.
-- - Added - added lines after first removed lines.
for i = 1, n_lines do
local hl_type = (n_added < i and 'delete') or (i <= n_removed and 'change' or 'add')
local hl_group = hl_groups[hl_type]
if hl_group ~= nil then table.insert(line_hl, { line = from_line + i - 1, hl_group = hl_group }) end
end
end
return line_hl
end
end
-- Helper data ================================================================
-- Module default config
H.default_config = vim.deepcopy(MiniMap.config)
-- Cache for various operations
H.cache = {
-- Data about previous window. Used for focus related computations.
previous_win = {},
-- Table with information used for latest buffer lines encoding. Used for
-- quick conversion between source and map coordinates.
encode_data = {},
-- Table with information about scrollbar. Used for quick scrollbar related
-- computations.
scrollbar_data = { view = {}, line = nil },
-- Number of cursor movements inside map buffer since focusing. Needed to not
-- update source buffer view just after focusing.
n_map_cursor_moves = 0,
}
H.ns_id = {
integrations = vim.api.nvim_create_namespace('MiniMapIntegrations'),
scroll_view = vim.api.nvim_create_namespace('MiniMapScrollView'),
scroll_line = vim.api.nvim_create_namespace('MiniMapScrollLine'),
}
--stylua: ignore start
H.block_symbols = {}
H.block_symbols['1x2'] = { ' ', '▌', '▐', '█', resolution = { row = 1, col = 2 } }
H.block_symbols['2x1'] = { ' ', '▀', '▄', '█', resolution = { row = 2, col = 1 } }
H.block_symbols['2x2'] = {
' ', '▘', '▝', '▀', '▖', '▌', '▞', '▛', '▗', '▚', '▐', '▜', '▄', '▙', '▟', '█',
resolution = { row = 2, col = 2 },
}
H.block_symbols['3x2'] = {
' ', '🬀', '🬁', '🬂', '🬃', '🬄', '🬅', '🬆', '🬇', '🬈', '🬉', '🬊', '🬋', '🬌', '🬍', '🬎',
'🬏', '🬐', '🬑', '🬒', '🬓', '▌', '🬔', '🬕', '🬖', '🬗', '🬘', '🬙', '🬚', '🬛', '🬜', '🬝',
'🬞', '🬟', '🬠', '🬡', '🬢', '🬣', '🬤', '🬥', '🬦', '🬧', '▐', '🬨', '🬩', '🬪', '🬫', '🬬',
'🬭', '🬮', '🬯', '🬰', '🬱', '🬲', '🬳', '🬴', '🬵', '🬶', '🬷', '🬸', '🬹', '🬺', '🬻', '█',
resolution = { row = 3, col = 2 },
}
H.dot_symbols = {}
H.dot_symbols['4x2'] = {
'⠀', '⠁', '⠈', '⠉', '⠂', '⠃', '⠊', '⠋', '⠐', '⠑', '⠘', '⠙', '⠒', '⠓', '⠚', '⠛',
'⠄', '⠅', '⠌', '⠍', '⠆', '⠇', '⠎', '⠏', '⠔', '⠕', '⠜', '⠝', '⠖', '⠗', '⠞', '⠟',
'⠠', '⠡', '⠨', '⠩', '⠢', '⠣', '⠪', '⠫', '⠰', '⠱', '⠸', '⠹', '⠲', '⠳', '⠺', '⠻',
'⠤', '⠥', '⠬', '⠭', '⠦', '⠧', '⠮', '⠯', '⠴', '⠵', '⠼', '⠽', '⠶', '⠷', '⠾', '⠿',
'⡀', '⡁', '⡈', '⡉', '⡂', '⡃', '⡊', '⡋', '⡐', '⡑', '⡘', '⡙', '⡒', '⡓', '⡚', '⡛',
'⡄', '⡅', '⡌', '⡍', '⡆', '⡇', '⡎', '⡏', '⡔', '⡕', '⡜', '⡝', '⡖', '⡗', '⡞', '⡟',
'⡠', '⡡', '⡨', '⡩', '⡢', '⡣', '⡪', '⡫', '⡰', '⡱', '⡸', '⡹', '⡲', '⡳', '⡺', '⡻',
'⡤', '⡥', '⡬', '⡭', '⡦', '⡧', '⡮', '⡯', '⡴', '⡵', '⡼', '⡽', '⡶', '⡷', '⡾', '⡿',
'⢀', '⢁', '⢈', '⢉', '⢂', '⢃', '⢊', '⢋', '⢐', '⢑', '⢘', '⢙', '⢒', '⢓', '⢚', '⢛',
'⢄', '⢅', '⢌', '⢍', '⢆', '⢇', '⢎', '⢏', '⢔', '⢕', '⢜', '⢝', '⢖', '⢗', '⢞', '⢟',
'⢠', '⢡', '⢨', '⢩', '⢢', '⢣', '⢪', '⢫', '⢰', '⢱', '⢸', '⢹', '⢲', '⢳', '⢺', '⢻',
'⢤', '⢥', '⢬', '⢭', '⢦', '⢧', '⢮', '⢯', '⢴', '⢵', '⢼', '⢽', '⢶', '⢷', '⢾', '⢿',
'⣀', '⣁', '⣈', '⣉', '⣂', '⣃', '⣊', '⣋', '⣐', '⣑', '⣘', '⣙', '⣒', '⣓', '⣚', '⣛',
'⣄', '⣅', '⣌', '⣍', '⣆', '⣇', '⣎', '⣏', '⣔', '⣕', '⣜', '⣝', '⣖', '⣗', '⣞', '⣟',
'⣠', '⣡', '⣨', '⣩', '⣢', '⣣', '⣪', '⣫', '⣰', '⣱', '⣸', '⣹', '⣲', '⣳', '⣺', '⣻',
'⣤', '⣥', '⣬', '⣭', '⣦', '⣧', '⣮', '⣯', '⣴', '⣵', '⣼', '⣽', '⣶', '⣷', '⣾', '⣿',
resolution = { row = 4, col = 2 },
}
H.dot_symbols['3x2'] = { resolution = { row = 3, col = 2 } }
for i = 1,64 do H.dot_symbols['3x2'][i] = H.dot_symbols['4x2'][i] end
H.shade_symbols = {}
H.shade_symbols['2x1'] = { '░', '▒', '▒', '▓', resolution = { row = 2, col = 1 } }
H.shade_symbols['1x2'] = { '░', '▒', '▒', '▓', resolution = { row = 1, col = 2 } }
H.default_symbols = H.block_symbols['3x2']
--stylua: ignore end
-- Helper functionality =======================================================
-- Settings -------------------------------------------------------------------
H.setup_config = function(config)
-- General idea: if some table elements are not present in user-supplied
-- `config`, take them from default config
vim.validate({ config = { config, 'table', true } })
config = vim.tbl_deep_extend('force', vim.deepcopy(H.default_config), config or {})
vim.validate({
integrations = { config.integrations, H.is_valid_config_integrations },
symbols = { config.symbols, H.is_valid_config_symbols },
window = { config.window, H.is_valid_config_window },
})
return config
end
H.apply_config = function(config) MiniMap.config = config end