Repository navigation
Expand file tree
/
Copy pathmini-notify.txt
More file actions
427 lines (331 loc) · 15.7 KB
/
Copy pathmini-notify.txt
File metadata and controls
427 lines (331 loc) · 15.7 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
*mini.notify* Show notifications
*MiniNotify*
MIT License Copyright (c) 2024 Evgeni Chasnovski
==============================================================================
Features:
- Show one or more highlighted notifications in a single floating window.
- Manage notifications (add, update, remove, clear).
- |vim.notify()| wrapper generator (see |MiniNotify.make_notify()|).
- Automated show of LSP progress report.
- Track history which can be accessed with |MiniNotify.get_all()|
and shown with |MiniNotify.show_history()|.
# Setup ~
This module needs a setup with `require('mini.notify').setup({})` (replace
`{}` with your `config` table). It will create global Lua table `MiniNotify`
which you can use for scripting or manually (with `:lua MiniNotify.*`).
See |MiniNotify.config| for `config` structure and default values.
You can override runtime config settings locally to buffer inside
`vim.b.mininotify_config` which should have same structure as
`MiniNotify.config`. See |mini.nvim-buffer-local-config| for more details.
# Comparisons ~
- 'j-hui/fidget.nvim':
- Basic goals of providing interface for notifications are similar.
- Has more configuration options and visual effects, while this module
does not (by design).
- 'rcarriga/nvim-notify':
- Similar to 'j-hui/fidget.nvim'.
# Highlight groups ~
* `MiniNotifyBorder` - window border.
* `MiniNotifyLspProgress` - notifications from built-in LSP progress report.
* `MiniNotifyNormal` - basic foreground/background highlighting.
* `MiniNotifyTitle` - window title.
To change any highlight group, modify it directly with |:highlight|.
# Disabling ~
To disable showing notifications, set `vim.g.mininotify_disable` (globally) or
`vim.b.mininotify_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.
------------------------------------------------------------------------------
*MiniNotify-specification*
# Notification specification ~
Notification is a table with the following keys:
- <msg> `(string)` - single string with notification message.
Use `\n` to delimit several lines.
- <level> `(string)` - notification level as key of |vim.log.levels|.
Like "ERROR", "WARN", "INFO", etc.
- <hl_group> `(string)` - highlight group with which notification is shown.
- <data> `(table)` - extra data to store in notification (like `source`, etc.).
- <ts_add> `(number)` - timestamp of when notification is added.
- <ts_update> `(number)` - timestamp of the latest notification update.
- <ts_remove> `(number|nil)` - timestamp of when notification is removed.
It is `nil` if notification was never removed and thus considered "active".
Notes:
- Timestamps are compatible with |strftime()| and have fractional part.
------------------------------------------------------------------------------
*MiniNotify.setup()*
`MiniNotify.setup`({config})
Module setup
This will also clean the history. Use `MiniNotify.setup(MiniNotify.config)` to
force clean history while preserving the config.
Parameters ~
{config} `(table|nil)` Module config table. See |MiniNotify.config|.
Usage ~
>lua
require('mini.notify').setup() -- use default config
-- OR
require('mini.notify').setup({}) -- replace {} with your config table
<
------------------------------------------------------------------------------
*MiniNotify.config*
`MiniNotify.config`
Module config
Default values:
>lua
MiniNotify.config = {
-- Content management
content = {
-- Function which formats the notification message
-- By default prepends message with notification time
format = nil,
-- Function which orders notification array from most to least important
-- By default orders first by level and then by update timestamp
sort = nil,
},
-- Notifications about LSP progress
lsp_progress = {
-- Whether to enable showing
enable = true,
-- Notification level
level = 'INFO',
-- Duration (in ms) of how long last message should be shown
duration_last = 1000,
},
-- Window options
window = {
-- Floating window config
config = {},
-- Maximum window width as share (between 0 and 1) of available columns
max_width_share = 0.382,
-- Value of 'winblend' option
winblend = 25,
},
}
<
# Content ~
`config.content` defines how notifications are shown.
`content.format` is a function which takes single notification object
(see |MiniNotify-specification|) and returns a string to be used directly
when showing notification.
Default: `nil` for |MiniNotify.default_format()|.
`content.sort` is a function which takes array of notification objects
(see |MiniNotify-specification|) and returns an array of such objects.
It can be used to define custom order and/or filter for notifications which
are shown simultaneously.
Note: Input contains notifications before applying `content.format`.
Default: `nil` for |MiniNotify.default_sort()|.
Example: >lua
require('mini.notify').setup({
content = {
-- Use notification message as is for LSP progress
format = function(notif)
if notif.data.source == 'lsp_progress' then return notif.msg end
return MiniNotify.default_format(notif)
end,
-- Show more recent notifications first
sort = function(notif_arr)
table.sort(
notif_arr,
function(a, b) return a.ts_update > b.ts_update end
)
return notif_arr
end,
},
})
<
# LSP progress ~
`config.lsp_progress` defines automated notifications for LSP progress.
It is implemented as a single updating notification per progress with all
information about it.
Setting up is done inside |MiniNotify.setup()| via |vim.schedule()|'ed setting
of |lsp-handler| for "$/progress" method.
`lsp_progress.enable` is a boolean indicating whether LSP progress should
be shown in notifications. Can be disabled in current session.
Default: `true`. Note: Should be `true` during |MiniNotify.setup()| call to be able
to enable it in current session.
`lsp_progress.level` is a level to be used in |MiniNotify.add()|.
Default: `'INFO'`.
`lsp_progress.duration_last` is a number of milliseconds for the last progress
report to be shown on screen before removing it.
Default: 1000.
Notes:
- This respects previously set handler by saving and calling it.
- Overriding "$/progress" method of `vim.lsp.handlers` disables notifications.
- All LSP progress notifications set the following fields in `data`:
- <source> is `"lsp_progress"`.
- <client_name> is set to client's name (provided by client or inferred).
- <context> is the latest LSP request context (`ctx` arg of |lsp-handler|).
- <response> is the latest LSP response (`result` arg of |lsp-handler|).
# Window ~
`config.window` defines behavior of notification window.
`window.config` is a table defining floating window characteristics
or a callable returning such table (will be called with identifier of
window's buffer already showing notifications). It should have the same
structure as in |nvim_open_win()|. It has the following default values
which show notifications in the upper right corner with upper limit on width:
- `width` is chosen to fit buffer content but at most `window.max_width_share`
share of 'columns'.
To have higher maximum width, use function in `config.window` which computes
dimensions inside of it (based on buffer content).
- `height` is chosen to fit buffer content with enabled 'wrap' (assuming
default value of `width`).
- `anchor`, `col`, and `row` are "NE", 'columns', and 0 or 1 (depending on tabline).
- `border` is "single".
- `zindex` is 999 to be as much on top as reasonably possible.
`window.max_width_share` defines maximum window width as a share of 'columns'.
Should be a number between 0 (not included) and 1.
Default: 0.382.
Example for showing notifications in bottom right corner: >lua
local win_config = function()
local has_statusline = vim.o.laststatus > 0
local pad = vim.o.cmdheight + (has_statusline and 1 or 0)
return { anchor = 'SE', col = vim.o.columns, row = vim.o.lines - pad }
end
require('mini.notify').setup({ window = { config = win_config } })
<
`window.winblend` defines 'winblend' value for notification window.
Default: 25.
------------------------------------------------------------------------------
*MiniNotify.make_notify()*
`MiniNotify.make_notify`({opts})
Make vim.notify wrapper
Calling this function creates an implementation of |vim.notify()| powered by
this module. General idea is to show notification as soon as safely possible
(see |vim.schedule_wrap()|) and remove it after a configurable amount of time.
All notifications set `source = "vim.notify"` in their `data` field.
Examples: >lua
-- Defaults
vim.notify = require('mini.notify').make_notify()
-- Change duration for errors to show them longer
local opts = { ERROR = { duration = 10000 } }
vim.notify = require('mini.notify').make_notify(opts)
<
Parameters ~
{opts} `(table|nil)` Options to configure behavior of notification `level`
(as in |MiniNotfiy.add()|). Fields are the same as names of `vim.log.levels`
with values being tables with possible fields:
- <duration> `(number)` - duration (in ms) of how much a notification
should be shown. If 0 or negative, notification is not shown at all.
- <hl_group> `(string)` - highlight group of notification.
Only data different to default can be supplied.
Default: >lua
{
ERROR = { duration = 5000, hl_group = 'DiagnosticError' },
WARN = { duration = 5000, hl_group = 'DiagnosticWarn' },
INFO = { duration = 5000, hl_group = 'DiagnosticInfo' },
DEBUG = { duration = 0, hl_group = 'DiagnosticHint' },
TRACE = { duration = 0, hl_group = 'DiagnosticOk' },
OFF = { duration = 0, hl_group = 'MiniNotifyNormal' },
}
<
------------------------------------------------------------------------------
*MiniNotify.add()*
`MiniNotify.add`({msg}, {level}, {hl_group}, {data})
Add notification
Add notification to history. It is considered "active" and is shown.
To hide, call |MiniNotfiy.remove()| with identifier this function returns.
Example: >lua
local id = MiniNotify.add('Hello', 'WARN', 'Comment')
vim.defer_fn(function() MiniNotify.remove(id) end, 1000)
<
Parameters ~
{msg} `(string)` Notification message.
{level} `(string|nil)` Notification level as key of |vim.log.levels|.
Default: `'INFO'`.
{hl_group} `(string|nil)` Notification highlight group.
Default: `'MiniNotifyNormal'`.
{data} `(table|nil)` Extra data to store in the notification.
Default: `{}`.
Return ~
`(number)` Notification identifier.
------------------------------------------------------------------------------
*MiniNotify.update()*
`MiniNotify.update`({id}, {new})
Update active notification
Modify contents of active notification.
Parameters ~
{id} `(number)` Identifier of currently active notification as returned
by |MiniNotify.add()|.
{new} `(table)` Table with contents to update. Keys should be as non-timestamp
fields of |MiniNotify-specification| and values - new content values.
If present, field `data` is updated as is. Use |MiniNotify.get()| together
with |vim.tbl_deep_extend()| to change only part of it.
------------------------------------------------------------------------------
*MiniNotify.remove()*
`MiniNotify.remove`({id})
Remove notification
If notification is active, make it not active (by setting `ts_remove` field).
If not active, do nothing.
Parameters ~
{id} `(number|nil)` Identifier of previously added notification.
If it is not, nothing is done (silently).
------------------------------------------------------------------------------
*MiniNotify.clear()*
`MiniNotify.clear`()
Remove all active notifications
Hide all active notifications and stop showing window (if shown).
------------------------------------------------------------------------------
*MiniNotify.refresh()*
`MiniNotify.refresh`()
Refresh notification window
Make notification window show relevant information:
- Create an array of active notifications (see |MiniNotify-specification|).
- Apply `config.content.sort` to an array. If output has zero notifications,
make notification window to not show.
- Apply `config.content.format` to each element of notification array and
update its message.
- Construct content from notifications and show them in a window.
Note: effects are delayed if inside fast event (|vim.in_fast_event()|).
------------------------------------------------------------------------------
*MiniNotify.get()*
`MiniNotify.get`({id})
Get previously added notification by id
Parameters ~
{id} `(number)` Identifier of notification.
Return ~
`(table)` Notification object (see |MiniNotify-specification|).
------------------------------------------------------------------------------
*MiniNotify.get_all()*
`MiniNotify.get_all`()
Get all previously added notifications
Get map of used notifications with keys being notification identifiers.
Can be used to get only active notification objects. Example: >lua
-- Get active notifications
vim.tbl_filter(
function(notif) return notif.ts_remove == nil end,
MiniNotify.get_all()
)
<
Return ~
`(table)` Map with notification object values (see |MiniNotify-specification|).
Note: messages are taken from last valid update.
------------------------------------------------------------------------------
*MiniNotify.show_history()*
`MiniNotify.show_history`()
Show history
Open or reuse a scratch buffer with all previously shown notifications.
Notes:
- Content is ordered from oldest to newest based on latest update time.
- Message is formatted with `config.content.format`.
------------------------------------------------------------------------------
*MiniNotify.default_format()*
`MiniNotify.default_format`({notif})
Default content format
Used by default as `config.content.format`. Prepends notification message
with the human readable update time and a separator.
Parameters ~
{notif} `(table)` Notification object (see |MiniNotify-specification|).
Return ~
`(string)` Formatted notification message.
------------------------------------------------------------------------------
*MiniNotify.default_sort()*
`MiniNotify.default_sort`({notif_arr})
Default content sort
Used by default as `config.content.sort`. First sorts by notification's `level`
("ERROR" > "WARN" > "INFO" > "DEBUG" > "TRACE" > "OFF"; the bigger the more
important); if draw - by latest update time (the later the more important).
Parameters ~
{notif_arr} `(table)` Array of notifications (see |MiniNotify-specification|).
Return ~
`(table)` Sorted array of notifications.
vim:tw=78:ts=8:noet:ft=help:norl: