🐻 minimal ui2 fuzzy finder for Neovim
codeberg.org/comfysage/artio.nvim
1*artio.txt* a minimal, nature-infused file picker for neovim using ui2
2
3==============================================================================
4
5FEATURES *artio-features*
6
7Requires Neovim `>= 0.12`
8
9- Lightweight picker window built on Neovim's ui2
10- Prompt + list UI components - minimal and focused
11- Fuzzy filtering using matchfuzzy (built-in)
12- Optional icon support for common filetypes through mini.icons
13 (https://github.com/echasnovski/mini.nvim)
14- No heavy dependencies - pure Lua
15
16UI2
17
18artio requires ui2 to be enabled.
19
20an example of how to set this up is:
21
22>lua
23 require("vim._core.ui2").enable({ enable = true, msg = {
24 target = "msg",
25 } })
26<
27
28INSTALLATION
29
30`vim.pack`
31
32>lua
33 vim.pack.add({{ src = "https://github.com/comfysage/artio.nvim" }})
34<
35
36`lazy.nvim`
37
38>lua
39 {
40 "comfysage/artio.nvim", lazy = false,
41 }
42<
43
44==============================================================================
45
46CONFIGURATION *artio-config*
47
48Options ~
49
50options that change default behavior of the picker.
51
52>lua
53 {
54 opts = {
55 preselect = true, -- whether to preselect the first match
56 bottom = true, -- whether to draw the prompt at the bottom
57 shrink = true, -- whether the window should shrink to fit the matches
58 promptprefix = "", -- prefix for the prompt
59 prompt_title = true, -- whether to draw the prompt title
60 pointer = "", -- pointer for the selected match
61 marker = "│", -- prefix for marked items
62 infolist = { "list" }, -- index: [1] list: (4/5)
63 use_icons = true, -- requires mini.icons
64 },
65 }
66<
67
68Window Options ~
69
70some less used options for the picker window and its render logic.
71
72>lua
73 {
74 win = {
75 height = 12,
76 hidestatusline = false, -- works best with laststatus=3
77 },
78 }
79<
80
81Mappings ~
82
83these override the default mappings for any picker.
84these map keys to actions. its allowed to use multiple keys for the same
85action.
86
87NOTE: if you override the mappings, make sure to provide keys for all actions
88
89>lua
90 {
91 mappings = {
92 ["<down>"] = "down",
93 ["<up>"] = "up",
94 ["<cr>"] = "accept",
95 ["<esc>"] = "cancel",
96 ["<tab>"] = "mark",
97 ["<c-l>"] = "togglepreview",
98 ["<c-q>"] = "setqflist",
99 ["<m-q>"] = "setqflistmark",
100 },
101 }
102<
103
104Setup ~
105
106after setting up artio with your options there are some additional things to
107setup.
108
109Keymaps for artio are set using the |<Plug>| interface. These bindings are set
110by the api and can be rebound by the user to specific keybindings.
111
112By default there are <Plug> bindings for all builtins. |artio-builtins|
113
114Example ~
115
116>lua
117 require('artio').setup({})
118
119 -- override built-in ui select with artio
120 vim.ui.select = require("artio").select
121
122 vim.keymap.set("n", "<leader><leader>", "<Plug>(artio-files)")
123 vim.keymap.set("n", "<leader>fg", "<Plug>(artio-grep)")
124
125 -- smart file picker
126 vim.keymap.set("n", "<leader>ff", "<Plug>(artio-smart)")
127
128 -- general built-in pickers
129 vim.keymap.set("n", "<leader>fh", "<Plug>(artio-helptags)")
130 vim.keymap.set("n", "<leader>fb", "<Plug>(artio-buffers)")
131 vim.keymap.set("n", "<leader>f/", "<Plug>(artio-buffergrep)")
132 vim.keymap.set("n", "<leader>fo", "<Plug>(artio-oldfiles)")
133<
134
135==============================================================================
136
137API *artio-api*
138
139artio.pick({opts}) *artio.pick()*
140
141 create a new picker |artio.Picker| and start it.
142
143 >lua
144 artio.pick({
145 items = { 'a', 'b', 'c' },
146 fn = artio.sorter,
147 })
148 <
149
150artio.generic({items}, {props}) *artio.generic()*
151
152 creates a generic picker from the given items and props.
153 uses the default |artio.sorter| function.
154
155 *artio.select()*
156artio.select({items}, {opts}, {on_choice}, {start_opts?})
157
158 the |vim.ui.select| interface implemented for artio.
159 adds an optional `{start_opts?}` argument that accepts artio specific
160 options.
161
162artio.resume() *artio.resume()*
163
164 resume the last closed picker. does not work across neovim
165 restarts/sessions.
166
167 Plug: `<Plug>(artio-resume)`.
168
169API-PICKER *artio-api-picker*
170
171*artio.Picker*
172 a picker is a special table that holds the state of the picker.
173 the current active picker is stored in
174 `require('artio.picker').active_picker`.
175
176 Fields: ~
177 - {items} (`artio.Picker.item[]|string[]`)
178 array of |artio.Picker.item| or strings. an array of
179 strings will be converted to items.
180 - {fn} (`artio.Picker.sorter`)
181 an instance of |artio.Picker.sorter|.
182 - {on_close} (`fun(text: string, idx: integer)`)
183 callback function for when the picker closes (after
184 accepting a match). gets the `item.text` field as the
185 first argument and the item id as the second.
186 - {get_items}? (`fun(input: string): artio.Picker.item[]`)
187 - {format_item}? (`fun(item: any): string`)
188 - {preview_item}? (`fun(item: any): {buf?:integer, pos?:[integer,integer], pos_end?:[integer,integer]}`)
189 - {get_icon}? (`fun(item: artio.Picker.item): string, string`)
190 - {hl_item}? (`fun(item: artio.Picker.item): artio.Picker.hl[]`)
191 - {on_quit}? (`fun()`)
192 callback function for when the picker closes before
193 choosing a match.
194 - {prompt}? (`string`)
195 text before prompt prefix. can be disabled with
196 `config.opts.prompt_title = false`.
197 - {defaulttext}? (`string`)
198 start input for picker.
199 - {prompttext}? (`string`)
200 defaults to prompt title combined with prompt prefix.
201 - {opts}? (`artio.config.opts`)
202 picker options combined with the user config.
203 - {win}? (`artio.config.win`)
204 picker window options combined with the user config.
205 - {actions}? (`table<string, artio.Picker.action>`)
206 picker specific actions.
207 - {mappings}? (`table<string, string>`)
208 mappings from the user config.
209
210API-SORTER *artio-api-sorter*
211
212*artio.Picker.sorter*
213 a function that takes an array of |artio.Picker.item| and an input string
214 and returns a table of matches |artio.Picker.matches|.
215
216*artio.Picker.matches*
217 a table where each key is the id of the item and each value is of
218 |artio.Picker.match|.
219
220*artio.Picker.match*
221
222 Fields: ~
223 - {1} (`integer`)
224 id of the item
225 - {2} (`any`)
226 array of ' matching ' hls. these correspond to chars of the
227 `item.text` field. this is based on the output of
228 |matchfuzzypos|.
229 - {3} (`integer`)
230 the score of the match.
231
232*artio.Picker.item*
233
234 Fields: ~
235 - {id} (`integer`)
236 - {v} (`any`)
237 - {text} (`string`)
238
239artio.sorter({items}, {input}) *artio.sorter()*
240
241 the default sorter provides support for pattern matching. a `/.../` match at
242 the start of the input will limit the fuzzy sorter to items matching the
243 pattern. if you want to use `/.../` in your fuzzy matches, make sure to
244 escape it by starting the input with an empty space (` /.../`). fuzzy
245 sorting will be done on the input with the pattern removed.
246
247API-BUILTINS
248
249artio builtins are for general editor use. they are accessible through
250`require('artio.builtins')`.
251
252builtins.builtins() *artio-builtins*
253
254 list of all builtins.
255
256 Plug: `<Plug>(artio-builtins)`.
257
258builtins.files() *artio-files*
259
260 list all files within the current directory.
261
262 Plug: `<Plug>(artio-files)`.
263
264builtins.grep() *artio-grep*
265
266 grep in the current directory.
267 runs `rg` if available; uses `grep` as a fallback.
268
269 Plug: `<Plug>(artio-grep)`.
270
271builtins.oldfiles() *artio-oldfiles*
272
273 list all files in |v:oldfiles|; recently accessed files in neovim. these are
274 stored in |shada| memory.
275
276 Plug: `<Plug>(artio-oldfiles)`.
277
278builtins.buffergrep() *artio-buffergrep*
279
280 grep in the current buffer. uses the default sorter to match lines.
281
282 Plug: `<Plug>(artio-buffergrep)`.
283
284builtins.helptags() *artio-helptags*
285
286 list all help tags. behaves like |:help|.
287
288 Plug: `<Plug>(artio-helptags)`.
289
290builtins.buffers() *artio-buffers*
291
292 list all open buffers. behaves like |:buffers|.
293
294 Plug: `<Plug>(artio-buffers)`.
295
296builtins.smart() *artio-smart*
297
298 uses the regular files picker as a base
299 - boosts items in the bufferlist
300 - proportionally boosts items that match closely to the current file in
301 proximity within the filesystem
302
303 Plug: `<Plug>(artio-smart)`.
304
305builtins.colorschemes() *artio-colorschemes*
306
307 list all colorschemes by finding all `colors/*.{vim,lua}` files in the
308 runtime.
309
310 Plug: `<Plug>(artio-colorschemes)`.
311
312builtins.highlights() *artio-highlights*
313
314 list all highlights. behaves like |:highlight|.
315
316 Plug: `<Plug>(artio-highlights)`.
317
318builtins.diagnostics({buffer}) *artio-diagnostics*
319
320 list all diagnostics. uses diagnostics from |vim.diagnostic.get()|.
321 uses all diagnostics in the workspace if no buffer is specified.
322
323 Plug: `<Plug>(artio-diagnostics)`.
324
325builtins.diagnostics_buffer({buffer}) *artio-diagnostics-buffer*
326
327 list all diagnostics for the given buffer. uses diagnostics from
328 |vim.diagnostic.get()|. uses the current buffer if no buffer is specified.
329
330 Plug: `<Plug>(artio-diagnostics-buffer)`.
331
332builtins.keymaps() *artio-keymaps*
333
334 list all keymaps. uses formatted data from |nvim_get_keymap()|.
335
336 Plug: `<Plug>(artio-keymaps)`.
337
338builtins.commands() *artio-commands*
339
340 list all user commands. uses formatted data from |nvim_get_commands()|.
341
342 Plug: `<Plug>(artio-commands)`.
343
344builtins.quickfix() *artio-quickfix*
345
346 show current quickfix list. allows previewing items and updating the list.
347
348 Plug: `<Plug>(artio-quickfix)`.
349
350 vim:tw=78:ts=8:noet:ft=help:norl: