diff --git a/doc/snacks-picker.txt b/doc/snacks-picker.txt index e71fc7ab..6b7335a7 100644 --- a/doc/snacks-picker.txt +++ b/doc/snacks-picker.txt @@ -3,18 +3,20 @@ ============================================================================== Table of Contents *snacks-picker-table-of-contents* -1. Setup |snacks-picker-setup| -2. Config |snacks-picker-config| -3. Examples |snacks-picker-examples| +1. Features |snacks-picker-features| +2. Usage |snacks-picker-usage| +3. Setup |snacks-picker-setup| +4. Config |snacks-picker-config| +5. Examples |snacks-picker-examples| - general |snacks-picker-examples-general| - todo_comments |snacks-picker-examples-todo_comments| - trouble |snacks-picker-examples-trouble| -4. Types |snacks-picker-types| -5. Module |snacks-picker-module| +6. Types |snacks-picker-types| +7. Module |snacks-picker-module| - Snacks.picker() |snacks-picker-module-snacks.picker()| - Snacks.picker.pick() |snacks-picker-module-snacks.picker.pick()| - Snacks.picker.select() |snacks-picker-module-snacks.picker.select()| -6. Sources |snacks-picker-sources| +8. Sources |snacks-picker-sources| - autocmds |snacks-picker-sources-autocmds| - buffers |snacks-picker-sources-buffers| - cliphist |snacks-picker-sources-cliphist| @@ -58,7 +60,7 @@ Table of Contents *snacks-picker-table-of-contents* - resume |snacks-picker-sources-resume| - search_history |snacks-picker-sources-search_history| - zoxide |snacks-picker-sources-zoxide| -7. Layouts |snacks-picker-layouts| +9. Layouts |snacks-picker-layouts| - default |snacks-picker-layouts-default| - dropdown |snacks-picker-layouts-dropdown| - ivy |snacks-picker-layouts-ivy| @@ -66,7 +68,7 @@ Table of Contents *snacks-picker-table-of-contents* - telescope |snacks-picker-layouts-telescope| - vertical |snacks-picker-layouts-vertical| - vscode |snacks-picker-layouts-vscode| -8. snacks.picker.actions |snacks-picker-snacks.picker.actions| +10. snacks.picker.actions |snacks-picker-snacks.picker.actions| - Snacks.picker.actions.cmd()|snacks-picker-snacks.picker.actions-snacks.picker.actions.cmd()| - Snacks.picker.actions.copy()|snacks-picker-snacks.picker.actions-snacks.picker.actions.copy()| - Snacks.picker.actions.cycle_win()|snacks-picker-snacks.picker.actions-snacks.picker.actions.cycle_win()| @@ -105,7 +107,7 @@ Table of Contents *snacks-picker-table-of-contents* - Snacks.picker.actions.toggle_live()|snacks-picker-snacks.picker.actions-snacks.picker.actions.toggle_live()| - Snacks.picker.actions.toggle_maximize()|snacks-picker-snacks.picker.actions-snacks.picker.actions.toggle_maximize()| - Snacks.picker.actions.toggle_preview()|snacks-picker-snacks.picker.actions-snacks.picker.actions.toggle_preview()| -9. snacks.picker.core.picker |snacks-picker-snacks.picker.core.picker| +11. snacks.picker.core.picker |snacks-picker-snacks.picker.core.picker| - picker:action() |snacks-picker-snacks.picker.core.picker-picker:action()| - picker:close() |snacks-picker-snacks.picker.core.picker-picker:close()| - picker:count() |snacks-picker-snacks.picker.core.picker-picker:count()| @@ -121,9 +123,48 @@ Table of Contents *snacks-picker-table-of-contents* - picker:selected()|snacks-picker-snacks.picker.core.picker-picker:selected()| - picker:set_layout()|snacks-picker-snacks.picker.core.picker-picker:set_layout()| - picker:word() |snacks-picker-snacks.picker.core.picker-picker:word()| +12. Links |snacks-picker-links| +Snacks now comes with a modern fuzzy-finder to navigate the Neovim universe. + + + ============================================================================== -1. Setup *snacks-picker-setup* +1. Features *snacks-picker-features* + +- over 40 built-in sources +- Fast and powerful fuzzy matching engine that supports the fzf search syntax + - additionally supports field searches like `file:lua$ 'function` +- uses **treesitter** highlighting where it makes sense +- Sane default settings so you can start using it right away +- Finders and matchers run asynchronously for maximum performance +- Different layouts to suit your needs, or create your own. + Uses Snacks.layout + under the hood. +- Simple API to create your own pickers +- Better `vim.ui.select` + + +============================================================================== +2. Usage *snacks-picker-usage* + +The best way to get started is to copy some of the example configs + +below. + +>lua + -- Show all pickers + Snacks.picker() + + -- run files picker (all three are equivalent) + Snacks.picker.files(opts) + Snacks.picker.pick("files", opts) + Snacks.picker.pick({source = "files", ...}) +< + + +============================================================================== +3. Setup *snacks-picker-setup* >lua -- lazy.nvim @@ -142,7 +183,7 @@ Table of Contents *snacks-picker-table-of-contents* ============================================================================== -2. Config *snacks-picker-config* +4. Config *snacks-picker-config* >lua ---@class snacks.picker.Config @@ -181,6 +222,7 @@ Table of Contents *snacks-picker-table-of-contents* sources = {}, layout = { cycle = true, + --- Use the default layout or vertical if the window is too narrow preset = function() return vim.o.columns >= 120 and "default" or "vertical" end, @@ -354,7 +396,7 @@ Table of Contents *snacks-picker-table-of-contents* ============================================================================== -3. Examples *snacks-picker-examples* +5. Examples *snacks-picker-examples* GENERAL *snacks-picker-examples-general* @@ -457,7 +499,7 @@ TROUBLE *snacks-picker-examples-trouble* ============================================================================== -4. Types *snacks-picker-types* +6. Types *snacks-picker-types* >lua ---@alias snacks.picker.Extmark vim.api.keyset.set_extmark|{col:number, row?:number} @@ -468,12 +510,6 @@ TROUBLE *snacks-picker-examples-trouble* ---@alias snacks.picker.sort fun(a:snacks.picker.Item, b:snacks.picker.Item):boolean < ->lua - ---@class snacks.picker.finder.Item: snacks.picker.Item - ---@field idx? number - ---@field score? number -< - Generic filter used by finders to pre-filter items >lua @@ -484,6 +520,13 @@ Generic filter used by finders to pre-filter items ---@field filter? fun(item:snacks.picker.finder.Item):boolean custom filter function < +>lua + ---@class snacks.picker.matcher.Config + ---@field fuzzy? boolean use fuzzy matching (defaults to true) + ---@field smartcase? boolean use smartcase (defaults to true) + ---@field ignorecase? boolean use ignorecase (defaults to true) +< + >lua ---@class snacks.picker.Item ---@field [string] any @@ -496,6 +539,12 @@ Generic filter used by finders to pre-filter items ---@field highlights? snacks.picker.Highlight[][] < +>lua + ---@class snacks.picker.finder.Item: snacks.picker.Item + ---@field idx? number + ---@field score? number +< + >lua ---@class snacks.picker.sources.Config < @@ -525,9 +574,9 @@ Generic filter used by finders to pre-filter items >lua ---@class snacks.picker.win.Config - ---@field input? snacks.win.Config|{} - ---@field list? snacks.win.Config|{} - ---@field preview? snacks.win.Config|{} + ---@field input? snacks.win.Config|{} input window config + ---@field list? snacks.win.Config|{} result list window config + ---@field preview? snacks.win.Config|{} preview window config < >lua @@ -539,7 +588,7 @@ Generic filter used by finders to pre-filter items ============================================================================== -5. Module *snacks-picker-module* +7. Module *snacks-picker-module* >lua ---@class snacks.picker @@ -593,7 +642,7 @@ Implementation for `vim.ui.select` ============================================================================== -6. Sources *snacks-picker-sources* +8. Sources *snacks-picker-sources* AUTOCMDS *snacks-picker-sources-autocmds* @@ -1333,7 +1382,7 @@ Open a project from zoxide ============================================================================== -7. Layouts *snacks-picker-layouts* +9. Layouts *snacks-picker-layouts* DEFAULT *snacks-picker-layouts-default* @@ -1504,7 +1553,7 @@ VSCODE *snacks-picker-layouts-vscode* ============================================================================== -8. snacks.picker.actions *snacks-picker-snacks.picker.actions* +10. snacks.picker.actions *snacks-picker-snacks.picker.actions* >lua ---@class snacks.picker.actions @@ -1792,7 +1841,7 @@ SNACKS.PICKER.ACTIONS.TOGGLE_PREVIEW()*snacks-picker-snacks.picker.actions-snack ============================================================================== -9. snacks.picker.core.picker *snacks-picker-snacks.picker.core.picker* +11. snacks.picker.core.picker *snacks-picker-snacks.picker.core.picker* >lua ---@class snacks.Picker @@ -1963,6 +2012,14 @@ Get the word under the cursor or the current visual selection picker:word() < +============================================================================== +12. Links *snacks-picker-links* + +1. *image*: https://github.com/user-attachments/assets/b454fc3c-6613-4aa4-9296-f57a8b02bf6d +2. *image*: https://github.com/user-attachments/assets/3203aec4-7d75-4bca-b3d5-18d931277e4e +3. *image*: https://github.com/user-attachments/assets/291dcf63-0c1d-4e9a-97cb-dd5503660e6f +4. *image*: https://github.com/user-attachments/assets/976e0ed8-eb80-43e1-93ac-4683136c0a3c + Generated by panvimdoc vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/docs/picker.md b/docs/picker.md index 3b75c943..25579f21 100644 --- a/docs/picker.md +++ b/docs/picker.md @@ -1,5 +1,40 @@ # ๐Ÿฟ picker +Snacks now comes with a modern fuzzy-finder to navigate the Neovim universe. + +![image](https://github.com/user-attachments/assets/b454fc3c-6613-4aa4-9296-f57a8b02bf6d) +![image](https://github.com/user-attachments/assets/3203aec4-7d75-4bca-b3d5-18d931277e4e) +![image](https://github.com/user-attachments/assets/291dcf63-0c1d-4e9a-97cb-dd5503660e6f) +![image](https://github.com/user-attachments/assets/976e0ed8-eb80-43e1-93ac-4683136c0a3c) + +## โœจ Features + +- ๐Ÿ”Ž over 40 [built-in sources](https://github.com/folke/snacks.nvim/blob/main/docs/picker.md#-sources) +- ๐Ÿš€ Fast and powerful fuzzy matching engine that supports the [fzf](https://junegunn.github.io/fzf/search-syntax/) search syntax + - additionally supports field searches like `file:lua$ 'function` +- ๐ŸŒฒ uses **treesitter** highlighting where it makes sense +- ๐Ÿงน Sane default settings so you can start using it right away +- ๐Ÿ’ช Finders and matchers run asynchronously for maximum performance +- ๐ŸชŸ Different [layouts](https://github.com/folke/snacks.nvim/blob/main/docs/picker.md#%EF%B8%8F-layouts) to suit your needs, or create your own. + Uses [Snacks.layout](https://github.com/folke/snacks.nvim/blob/main/docs/layout.md) + under the hood. +- ๐Ÿ’ป Simple API to create your own pickers +- ๐Ÿ“‹ Better `vim.ui.select` + +## ๐Ÿ“š Usage + +The best way to get started is to copy some of the [example configs](https://github.com/folke/snacks.nvim/blob/main/docs/picker.md#-examples) below. + +```lua +-- Show all pickers +Snacks.picker() + +-- run files picker (all three are equivalent) +Snacks.picker.files(opts) +Snacks.picker.pick("files", opts) +Snacks.picker.pick({source = "files", ...}) +``` + ## ๐Ÿ“ฆ Setup @@ -58,6 +93,7 @@ sources = {}, layout = { cycle = true, + --- Use the default layout or vertical if the window is too narrow preset = function() return vim.o.columns >= 120 and "default" or "vertical" end, @@ -345,12 +381,6 @@ ---@alias snacks.picker.sort fun(a:snacks.picker.Item, b:snacks.picker.Item):boolean ``` -```lua ----@class snacks.picker.finder.Item: snacks.picker.Item ----@field idx? number ----@field score? number -``` - Generic filter used by finders to pre-filter items ```lua @@ -361,6 +391,13 @@ Generic filter used by finders to pre-filter items ---@field filter? fun(item:snacks.picker.finder.Item):boolean custom filter function ``` +```lua +---@class snacks.picker.matcher.Config +---@field fuzzy? boolean use fuzzy matching (defaults to true) +---@field smartcase? boolean use smartcase (defaults to true) +---@field ignorecase? boolean use ignorecase (defaults to true) +``` + ```lua ---@class snacks.picker.Item ---@field [string] any @@ -373,6 +410,12 @@ Generic filter used by finders to pre-filter items ---@field highlights? snacks.picker.Highlight[][] ``` +```lua +---@class snacks.picker.finder.Item: snacks.picker.Item +---@field idx? number +---@field score? number +``` + ```lua ---@class snacks.picker.sources.Config ``` @@ -402,9 +445,9 @@ Generic filter used by finders to pre-filter items ```lua ---@class snacks.picker.win.Config ----@field input? snacks.win.Config|{} ----@field list? snacks.win.Config|{} ----@field preview? snacks.win.Config|{} +---@field input? snacks.win.Config|{} input window config +---@field list? snacks.win.Config|{} result list window config +---@field preview? snacks.win.Config|{} preview window config ``` ## ๐Ÿ“ฆ Module diff --git a/lua/snacks/picker/config/defaults.lua b/lua/snacks/picker/config/defaults.lua index 2d25e586..b119d818 100644 --- a/lua/snacks/picker/config/defaults.lua +++ b/lua/snacks/picker/config/defaults.lua @@ -7,10 +7,6 @@ local M = {} ---@alias snacks.picker.preview fun(ctx: snacks.picker.preview.ctx):boolean? ---@alias snacks.picker.sort fun(a:snacks.picker.Item, b:snacks.picker.Item):boolean ----@class snacks.picker.finder.Item: snacks.picker.Item ----@field idx? number ----@field score? number - --- Generic filter used by finders to pre-filter items ---@class snacks.picker.filter.Config ---@field cwd? boolean|string only show files for the given cwd @@ -18,6 +14,11 @@ local M = {} ---@field paths? table only show items that include or exclude the given paths ---@field filter? fun(item:snacks.picker.finder.Item):boolean custom filter function +---@class snacks.picker.matcher.Config +---@field fuzzy? boolean use fuzzy matching (defaults to true) +---@field smartcase? boolean use smartcase (defaults to true) +---@field ignorecase? boolean use ignorecase (defaults to true) + ---@class snacks.picker.Item ---@field [string] any ---@field idx number @@ -28,6 +29,10 @@ local M = {} ---@field end_pos? {[1]:number, [2]:number} ---@field highlights? snacks.picker.Highlight[][] +---@class snacks.picker.finder.Item: snacks.picker.Item +---@field idx? number +---@field score? number + ---@class snacks.picker.sources.Config ---@class snacks.picker.preview.Config @@ -48,9 +53,9 @@ local M = {} ---@field preset? string|fun(source:string):string ---@class snacks.picker.win.Config ----@field input? snacks.win.Config|{} ----@field list? snacks.win.Config|{} ----@field preview? snacks.win.Config|{} +---@field input? snacks.win.Config|{} input window config +---@field list? snacks.win.Config|{} result list window config +---@field preview? snacks.win.Config|{} preview window config ---@class snacks.picker.Config ---@field source? string source name and config to use @@ -88,6 +93,7 @@ local defaults = { sources = {}, layout = { cycle = true, + --- Use the default layout or vertical if the window is too narrow preset = function() return vim.o.columns >= 120 and "default" or "vertical" end, diff --git a/lua/snacks/picker/core/matcher.lua b/lua/snacks/picker/core/matcher.lua index b82df9f3..97f89b38 100644 --- a/lua/snacks/picker/core/matcher.lua +++ b/lua/snacks/picker/core/matcher.lua @@ -17,11 +17,6 @@ M.INVERSE_SCORE = 1000 local YIELD_MATCH = 5 -- ms local clear = require("table.clear") ----@class snacks.picker.matcher.Config ----@field fuzzy? boolean ----@field smartcase? boolean ----@field ignorecase? boolean - ---@class snacks.picker.matcher.Mods ---@field pattern string ---@field entropy number higher entropy is less likely to match