Skip to content

Commit

Permalink
docs: switch out docgen tools (#399)
Browse files Browse the repository at this point in the history
* docs: switch out docgen tools

- deprecate `tree-sitter-lua` docgen for `docgen.nvim`
- update docs and add type annotations
- update ci config slightly

* [docgen] Update doc/telescope-file-browser.txt
skip-checks: true

---------

Co-authored-by: Github Actions <actions@github>
jamestrew and Github Actions authored Jul 21, 2024
1 parent a7ab9a9 commit 8574946
Showing 11 changed files with 548 additions and 532 deletions.
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
doc/tags
deps/
.deps/
11 changes: 3 additions & 8 deletions Makefile
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
.PHONY: docgen test clean

DEPS_DIR := deps
TS_DIR := $(DEPS_DIR)/tree-sitter-lua
DEPS_DIR := .deps
PLENARY_DIR := $(DEPS_DIR)/plenary.nvim
TELESCOPE_DIR := $(DEPS_DIR)/telescope.nvim

@@ -20,15 +19,11 @@ $(DEPS_DIR):
plenary: | $(DEPS_DIR)
$(call git_clone_or_pull,$(PLENARY_DIR),https://github.com/nvim-lua/plenary.nvim)

docgen-deps: plenary | $(DEPS_DIR)
$(call git_clone_or_pull,$(TS_DIR),https://github.com/tjdevries/tree-sitter-lua)
cd "$(TS_DIR)" && make dist

test-deps: plenary | $(DEPS_DIR)
$(call git_clone_or_pull,$(TELESCOPE_DIR),https://github.com/nvim-telescope/telescope.nvim)

docgen: docgen-deps
nvim --headless --noplugin -u scripts/minimal_init.vim -c "luafile ./scripts/gendocs.lua" -c 'qa'
docgen: $(DEPS_DIR)
nvim -l scripts/gendocs.lua

test: test-deps
nvim --headless --noplugin -u scripts/minimal_init.vim -c "PlenaryBustedDirectory lua/tests/ { minimal_init = './scripts/minimal_init.vim' }"
671 changes: 319 additions & 352 deletions doc/telescope-file-browser.txt

Large diffs are not rendered by default.

35 changes: 23 additions & 12 deletions lua/telescope/_extensions/file_browser.lua
Original file line number Diff line number Diff line change
@@ -1,14 +1,12 @@
---@tag telescope-file-browser
---@config { ["module"] = "telescope-file-browser" }
---@brief [[
---@brief
--- `telescope-file-browser.nvim` is an extension for telescope.nvim. It helps you efficiently
--- create, delete, rename, or move files powered by navigation from telescope.nvim.
---
--- The `telescope-file-browser` is setup via the `telescope` extension interface.<br>
--- You can manage the settings for the `telescope-file-browser` analogous to how you
--- manage the settings of any other built-in picker of `telescope.nvim`.
--- You do not need to set any of these options.
--- <code>
--- ```lua
--- require('telescope').setup {
--- extensions = {
--- file_browser = {
@@ -17,17 +15,19 @@
--- }
--- }
--- }
--- </code>
--- ```
--- See |telescope-file-browser.SetupOpts| below for all available options.
---
--- To get telescope-file-browser loaded and working with telescope,
--- you need to call load_extension, somewhere after setup function:
--- <code>
--- ```lua
--- telescope.load_extension "file_browser"
--- </code>
--- ```
---
--- The extension exports `file_browser`, `actions`, `finder`, `_picker` modules via telescope extensions:
--- <code>
--- ```lua
--- require "telescope".extensions.file_browser
--- </code>
--- ```
--- In particular:
--- - `file_browser`: constitutes the main picker of the extension
--- - `actions`: extension actions make accessible for remapping and custom usage
@@ -42,9 +42,6 @@
--- :h |telescope-file-browser.actions|
--- :h |telescope-file-browser.finders|
--- </pre>
---@brief ]]

---@tag telescope-file-browser.nvim

local has_telescope, telescope = pcall(require, "telescope")
if not has_telescope then
@@ -56,6 +53,20 @@ local fb_finders = require "telescope._extensions.file_browser.finders"
local fb_picker = require "telescope._extensions.file_browser.picker"
local fb_config = require "telescope._extensions.file_browser.config"

---@class telescope-file-browser.SetupOpts : telescope-file-browser.PickerOpts
--- use telescope file browser when opening directory paths (default: `false`)
---@field hijack_netrw boolean?
---@field theme string?: theme to use for the file browser (default: `nil`)
--- define custom mappings for the file browser
---
--- See:
--- - |telescope-file-browser.picker| for preconfigured file browser specific mappings
--- - |telescope-file-browser.actions| for all available file browser specific actions
--- - |telescope.mappings| and |telescope.actions| for general telescope mappings/actions and implementation details
--- By default,
---@field mappings table<string, table<string, function>>?

---@param opts telescope-file-browser.SetupOpts?: telescope-file-brower setup options
local file_browser = function(opts)
opts = opts or {}
local defaults = (function()
72 changes: 40 additions & 32 deletions lua/telescope/_extensions/file_browser/actions.lua
Original file line number Diff line number Diff line change
@@ -1,12 +1,9 @@
---@tag telescope-file-browser.actions
---@config { ["module"] = "telescope-file-browser.actions" }

---@brief [[
---@brief
--- The file browser actions are functions enable file system operations from within the file browser picker.
--- In particular, the actions include creation, deletion, renaming, and moving of files and folders.
---
--- You can remap actions as follows:
--- <code>
--- ```lua
--- local fb_actions = require "telescope".extensions.file_browser.actions
--- require('telescope').setup {
--- extensions = {
@@ -23,8 +20,7 @@
--- }
--- }
--- }
--- </code>
---@brief ]]
--- ```

local a = vim.api

@@ -43,6 +39,7 @@ local popup = require "plenary.popup"
local scan = require "plenary.scandir"
local async = require "plenary.async"

---@package
local fb_actions = setmetatable({}, {
__index = function(_, k)
error("Key does not exist for 'fb_actions': " .. tostring(k))
@@ -134,11 +131,11 @@ end

--- Creates a new file or dir in the current directory of the |telescope-file-browser.picker.file_browser|.
--- - Finder:
--- - file_browser: create a file in the currently opened directory
--- - folder_browser: create a file in the currently selected directory
--- - file_browser: create a file in the currently opened directory
--- - folder_browser: create a file in the currently selected directory
--- - Notes:
--- - You can create folders by ending the name in the path separator of your OS, e.g. "/" on Unix systems
--- - You can implicitly create new folders by passing $/CWD/new_folder/filename.lua
--- - You can create folders by ending the name in the path separator of your OS, e.g. "/" on Unix systems
--- - You can implicitly create new folders by passing $/CWD/new_folder/filename.lua
---@param prompt_bufnr number: The prompt bufnr
fb_actions.create = function(prompt_bufnr)
local current_picker = action_state.get_current_picker(prompt_bufnr)
@@ -160,8 +157,8 @@ end

--- Creates a new file or dir via prompt in the current directory of the |telescope-file-browser.picker.file_browser|.
--- - Notes:
--- - You can create folders by ending the name in the path separator of your OS, e.g. "/" on Unix systems
--- - You can implicitly create new folders by passing $/CWD/new_folder/filename.lua
--- - You can create folders by ending the name in the path separator of your OS, e.g. "/" on Unix systems
--- - You can implicitly create new folders by passing $/CWD/new_folder/filename.lua
---@param prompt_bufnr number: The prompt bufnr
fb_actions.create_from_prompt = function(prompt_bufnr)
local current_picker = action_state.get_current_picker(prompt_bufnr)
@@ -250,9 +247,10 @@ local batch_rename = function(prompt_bufnr, selections)
))
end

--- Rename files or folders for |telescope-file-browser.picker.file_browser|.<br>
--- Rename files or folders for |telescope-file-browser.picker.file_browser|.
---
--- Notes:
--- - Triggering renaming with multi selections opens `Batch Rename` window<br>
--- - Triggering renaming with multi selections opens `Batch Rename` window
--- in which the user can rename/move files multi-selected files at once
--- - In `Batch Rename`, the number of paths must persist: keeping a file name means keeping the line unchanged
---@param prompt_bufnr number: The prompt bufnr
@@ -324,12 +322,13 @@ fb_actions.rename = function(prompt_bufnr)
end
end

--- Move multi-selected files or folders to current directory in |telescope-file-browser.picker.file_browser|.<br>
--- Move multi-selected files or folders to current directory in |telescope-file-browser.picker.file_browser|.
---
--- - Notes:
--- - Performs a blocking synchronized file-system operation.
--- - Moving multi-selections is sensitive to order of selection,
--- which potentially unpacks files from parent(s) dirs
--- if files are selected first.
--- - Performs a blocking synchronized file-system operation.
--- - Moving multi-selections is sensitive to order of selection,
--- which potentially unpacks files from parent(s) dirs
--- if files are selected first.
---@param prompt_bufnr number: The prompt bufnr
fb_actions.move = function(prompt_bufnr)
local current_picker = action_state.get_current_picker(prompt_bufnr)
@@ -380,10 +379,11 @@ fb_actions.move = function(prompt_bufnr)
current_picker:refresh(current_picker.finder, { reset_prompt = true })
end

--- Copy file or folders recursively to current directory in |telescope-file-browser.picker.file_browser|.<br>
--- Copy file or folders recursively to current directory in |telescope-file-browser.picker.file_browser|.
---
--- - Finder:
--- - file_browser: copies (multi-selected) file(s) in/to opened dir (w/o multi-selection, creates in-place copy)
--- - folder_browser: copies (multi-selected) file(s) in/to selected dir (w/o multi-selection, creates in-place copy)
--- - file_browser: copies (multi-selected) file(s) in/to opened dir (w/o multi-selection, creates in-place copy)
--- - folder_browser: copies (multi-selected) file(s) in/to selected dir (w/o multi-selection, creates in-place copy)
---@param prompt_bufnr number: The prompt bufnr
fb_actions.copy = function(prompt_bufnr)
local current_picker = action_state.get_current_picker(prompt_bufnr)
@@ -477,7 +477,8 @@ fb_actions.copy = function(prompt_bufnr)
fb_utils.selection_callback(current_picker, last_copied)
end

--- Remove file or folders recursively for |telescope-file-browser.picker.file_browser|.<br>
--- Remove file or folders recursively for |telescope-file-browser.picker.file_browser|.
---
--- Note: Performs a blocking synchronized file-system operation.
---@param prompt_bufnr number: The prompt bufnr
fb_actions.remove = function(prompt_bufnr)
@@ -571,13 +572,15 @@ fb_actions.toggle_respect_gitignore = function(prompt_bufnr)
current_picker:refresh(finder, { reset_prompt = true, multi = current_picker._multi })
end

--- Opens the file or folder with the default application.<br>
--- Opens the file or folder with the default application.
---
--- - Notes:
--- - map fb_actions.open + fb_actions.close if you want to close the picker post-action
--- - map fb_actions.open + fb_actions.close if you want to close the picker post-action
--- - OS: make sure your OS links against the desired applications:
--- - Linux: induces application via `xdg-open`
--- - macOS: relies on `open` to start the program
--- - Windows: defaults to default applications through `start`
--- - Linux: induces application via `xdg-open`
--- - macOS: relies on `open` to start the program
--- - Windows: defaults to default applications through `start`
---@pram prompt_bufnr number: The prompt bufnr
fb_actions.open = function(prompt_bufnr)
local quiet = action_state.get_current_picker(prompt_bufnr).finder.quiet
local selections = fb_utils.get_selected_files(prompt_bufnr, true)
@@ -713,8 +716,8 @@ end

--- Multi select all entries akin to |telescope.actions.select_all| but ignores parent & current directory
--- - Note:
--- - selected entries may include results not visible in the results popup.
--- - if the parent or current directly was previously selected, they will be ignored in the selected state (manually unselect with `<TAB>`)
--- - selected entries may include results not visible in the results popup.
--- - if the parent or current directly was previously selected, they will be ignored in the selected state (manually unselect with `<TAB>`)
---@param prompt_bufnr number: The prompt bufnr
fb_actions.select_all = function(prompt_bufnr)
local current_picker = action_state.get_current_picker(prompt_bufnr)
@@ -784,6 +787,7 @@ end

--- Toggle sorting by last change to the entry.<br>
--- Note: initially sorts desendingly from most to least recently changed entry.
---@param prompt_bufnr number: The prompt bufnr
fb_actions.sort_by_date = function(prompt_bufnr)
local finder = action_state.get_current_picker(prompt_bufnr).finder
finder.__sort_date = not finder.__sort_date
@@ -806,6 +810,8 @@ fb_actions.sort_by_date = function(prompt_bufnr)
end

--- If the prompt is empty, goes up to parent dir. Otherwise, acts as normal.
---@param prompt_bufnr number: The prompt bufnr
---@param bypass boolean: Allow passing beyond the globally set current working directory
fb_actions.backspace = function(prompt_bufnr, bypass)
local current_picker = action_state.get_current_picker(prompt_bufnr)

@@ -816,6 +822,8 @@ fb_actions.backspace = function(prompt_bufnr, bypass)
end
end

--- When a path separator is entered, navigate to the directory in the prompt.
---@param prompt_bufnr number: The prompt bufnr
fb_actions.path_separator = function(prompt_bufnr)
local current_picker = action_state.get_current_picker(prompt_bufnr)
local dir = Path:new(current_picker.finder.path .. os_sep .. current_picker:_get_prompt() .. os_sep)
@@ -858,7 +866,7 @@ local function open_dir_path(finder, path, upward)
return path
end

---comment open directory and refresh picker
--- Open directory and refresh picker
---@param prompt_bufnr integer
---@param _ any select type
---@param dir string? priority dir path
50 changes: 15 additions & 35 deletions lua/telescope/_extensions/file_browser/finders.lua
Original file line number Diff line number Diff line change
@@ -1,9 +1,5 @@
---@tag telescope-file-browser.finders
---@config { ["module"] = "telescope-file-browser.finders" }

---@brief [[
---@brief
--- The file browser finders power the picker with both a file and folder browser.
---@brief ]]

local fb_utils = require "telescope._extensions.file_browser.utils"
local fb_make_entry = require "telescope._extensions.file_browser.make_entry"
@@ -87,11 +83,8 @@ end

--- Returns a finder that is populated with files and folders in `path`.
--- - Notes:
--- - Uses `fd` if available for more async-ish browsing and speed-ups
---@param opts table: options to pass to the finder
---@field path string: root dir to browse from
---@field depth number: file tree depth to display, `false` for unlimited (default: 1)
---@field hidden table|boolean: determines whether to show hidden files or not (default: `{ file_browser = false, folder_browser = false }`)
--- - Uses `fd` if available for more async-ish browsing and speed-ups
---@param opts telescope-file-browser.FinderOpts?: options to pass to the finder
fb_finders.browse_files = function(opts)
opts = opts or {}
-- returns copy with properly set cwd for entry maker
@@ -144,12 +137,10 @@ end

--- Returns a finder that is populated with (sub-)folders of `cwd`.
--- - Notes:
--- - Uses `fd` if available for more async-ish browsing and speed-ups
---@param opts table: options to pass to the finder
---@field cwd string: root dir to browse from
---@field depth number: file tree depth to display (default: 1)
---@field hidden table|boolean: determines whether to show hidden files or not (default: `{ file_browser = false, folder_browser = false }`)
--- - Uses `fd` if available for more async-ish browsing and speed-ups
---@param opts telescope-file-browser.FinderOpts?: options to pass to the finder
fb_finders.browse_folders = function(opts)
opts = opts or {}
-- returns copy with properly set cwd for entry maker
local cwd = opts.cwd_to_path and opts.path or opts.cwd
local entry_maker = opts.entry_maker { cwd = cwd }
@@ -173,29 +164,18 @@ fb_finders.browse_folders = function(opts)
end
end

---@class telescope-file-browser.FinderOpts : telescope-file-browser.PickerOpts
---@field entry_maker fun(opts: table): function entry maker for the finder (advanced)
---@field _entry_cache table<string, table>

--- Returns a finder that combines |fb_finders.browse_files| and |fb_finders.browse_folders| into a unified finder.
---@param opts table: options to pass to the picker
---@field path string: root dir to file_browse from (default: vim.loop.cwd())
---@field cwd string: root dir (default: vim.loop.cwd())
---@field cwd_to_path boolean: folder browser follows `path` of file browser
---@field files boolean: start in file (true) or folder (false) browser (default: true)
---@field grouped boolean: group initial sorting by directories and then files (default: false)
---@field depth number: file tree depth to display (default: 1)
---@field hidden table|boolean: determines whether to show hidden files or not (default: `{ file_browser = false, folder_browser = false }`)
---@field respect_gitignore boolean: induces slow-down w/ plenary finder (default: false, true if `fd` available)
---@field no_ignore boolean: disable use of ignore files like .gitignore/.ignore/.fdignore (default: false, requires `fd`)
---@field follow_symlinks boolean: traverse symbolic links, i.e. files and folders (default: false, only works with `fd`)
---@field hide_parent_dir boolean: hide `../` in the file browser (default: false)
---@field dir_icon string: change the icon for a directory (default: )
---@field dir_icon_hl string: change the highlight group of dir icon (default: "Default")
---@field use_fd boolean: use `fd` if available over `plenary.scandir` (default: true)
---@field git_status boolean: show the git status of files (default: true)
---@field create_from_prompt boolean: Create file/folder from prompt if no entry selected (default: true)
---@param opts telescope-file-browser.FinderOpts?: options to pass to the picker
---@return table # telescope finder
fb_finders.finder = function(opts)
opts = opts or {}
-- cache entries such that multi selections are maintained across {file, folder}_browsers
-- otherwise varying metatables misalign selections
opts.entry_cache = {}
opts._entry_cache = {}

local hidden_default = { file_browser = false, folder_browser = false }
local hidden = vim.F.if_nil(opts.hidden, hidden_default)
@@ -234,8 +214,8 @@ fb_finders.finder = function(opts)
close = function(self)
self._finder = nil
end,
prompt_title = opts.custom_prompt_title,
results_title = opts.custom_results_title,
prompt_title = opts._custom_prompt_title,
results_title = opts._custom_results_title,
prompt_path = opts.prompt_path,
use_fd = vim.F.if_nil(opts.use_fd, true),
}, {
4 changes: 2 additions & 2 deletions lua/telescope/_extensions/file_browser/make_entry.lua
Original file line number Diff line number Diff line change
@@ -249,7 +249,7 @@ local make_entry = function(opts)

-- telescope-file-browser has to cache the entries to resolve multi-selections
-- across multiple folders
local cached_entry = opts.entry_cache[absolute_path]
local cached_entry = opts._entry_cache[absolute_path]
if cached_entry ~= nil then
-- update the entry in-place to keep multi selections in tact
cached_entry.ordinal = e.ordinal
@@ -258,7 +258,7 @@ local make_entry = function(opts)
return cached_entry
end

opts.entry_cache[absolute_path] = e
opts._entry_cache[absolute_path] = e
return e -- entry
end
end
191 changes: 126 additions & 65 deletions lua/telescope/_extensions/file_browser/picker.lua
Original file line number Diff line number Diff line change
@@ -1,17 +1,41 @@
---@tag telescope-file-browser.picker
---@config { ["module"] = "telescope-file-browser.picker" }

---@brief [[
---@brief
--- You can use the file browser as follows
--- <code>
--- :lua vim.api.nvim_set_keymap(
--- "n",
--- "<space>fb",
--- "<cmd>lua require 'telescope'.extensions.file_browser.file_browser()<CR>",
--- {noremap = true}
---
--- ```lua
--- vim.keymap.set(
--- "n",
--- "<space>fb",
--- "<cmd>Telescope file_browser<CR>",
--- { noremap = true }
--- )
--- </code>
---@brief ]]
---
--- -- or alternatively using lua functions
--- local picker = require "telescope._extensions.file_browser"
--- vim.api.keymap.set("n", "<space>fb", function()
--- picker.file_browser()
--- end, { noremap = true })
--- ```
--- The `file_browser` picker comes pre-configured with several keymaps:
--- - `<cr>` : Opens the currently selected file/directory, or creates whatever is in the prompt
--- - `<s-cr>` : Create path in prompt
--- - `/`, `\` : (OS Path separator) When typing filepath, the path separator will open a directory like `<cr>`.
--- - `<A-c>/c`: Create file/folder at current `path` (trailing path separator creates folder)
--- - `<A-r>/r`: Rename multi-selected files/folders
--- - `<A-m>/m`: Move multi-selected files/folders to current `path`
--- - `<A-y>/y`: Copy (multi-)selected files/folders to current `path`
--- - `<A-d>/d`: Delete (multi-)selected files/folders
--- - `<C-o>/o`: Open file/folder with default system application
--- - `<C-g>/g`: Go to parent directory
--- - `<C-e>/e`: Go to home directory
--- - `<C-w>/w`: Go to current working directory (cwd)
--- - `<C-t>/t`: Change nvim's cwd to selected folder/file(parent)
--- - `<C-f>/f`: Toggle between file and folder browser
--- - `<C-h>/h`: Toggle hidden files/folders
--- - `<C-s>/s`: Toggle all entries ignoring `./` and `../`
--- - `<bs>/` : Goes to parent dir if prompt is empty, otherwise acts normally
---
---
--- <br>The file browser picker can be configured with the following options:

local pickers = require "telescope.pickers"
local conf = require("telescope.config").values
@@ -27,65 +51,100 @@ local fb_picker = {}

-- try to get the index of entry of current buffer

--- List, create, delete, rename, or move files and folders of your cwd.<br>
--- Notes
--- - Default keymaps in insert/normal mode:
--- - `<cr>` : Opens the currently selected file/directory, or creates whatever is in the prompt
--- - `<s-cr>` : Create path in prompt
--- - `/`, `\` : (OS Path separator) When typing filepath, the path separator will open a directory like `<cr>`.
--- - `<A-c>/c`: Create file/folder at current `path` (trailing path separator creates folder)
--- - `<A-r>/r`: Rename multi-selected files/folders
--- - `<A-m>/m`: Move multi-selected files/folders to current `path`
--- - `<A-y>/y`: Copy (multi-)selected files/folders to current `path`
--- - `<A-d>/d`: Delete (multi-)selected files/folders
--- - `<C-o>/o`: Open file/folder with default system application
--- - `<C-g>/g`: Go to parent directory
--- - `<C-e>/e`: Go to home directory
--- - `<C-w>/w`: Go to current working directory (cwd)
--- - `<C-t>/t`: Change nvim's cwd to selected folder/file(parent)
--- - `<C-f>/f`: Toggle between file and folder browser
--- - `<C-h>/h`: Toggle hidden files/folders
--- - `<C-s>/s`: Toggle all entries ignoring `./` and `../`
--- - `<bs>/` : Goes to parent dir if prompt is empty, otherwise acts normally
--- - display_stat:
--- - A table that can currently hold `date` and/or `size` as keys -- order matters!
--- - To opt-out, you can pass { display_stat = false }; sorting by stat works regardlessly
--- - The value of a key can be one of `true` or a table of `{ width = integer, display = function, hl = string }`
--- - The flags can be incrementally changed via eg { date = true, size = { width = 20, hl = "ErrorMsg" } }
--- - See make_entry.lua for an example on how to further customize
--- Options for the base telescope picker.
---
---@param opts table: options to pass to the picker
---@field path string: dir to browse files from, `vim.fn.expanded` automatically (default: vim.loop.cwd())
---@field cwd string: dir to browse folders from, `vim.fn.expanded` automatically (default: vim.loop.cwd())
---@field cwd_to_path boolean: whether folder browser is launched from `path` rather than `cwd` (default: false)
---@field grouped boolean: group initial sorting by directories and then files (default: false)
---@field files boolean: start in file (true) or folder (false) browser (default: true)
---@field add_dirs boolean: whether the file browser shows folders (default: true)
---@field depth number: file tree depth to display, `false` for unlimited depth (default: 1)
---@field auto_depth boolean|number: unlimit or set `depth` to `auto_depth` & unset grouped on prompt for file_browser (default: false)
---@field select_buffer boolean: select current buffer if possible; may imply `hidden=true` (default: false)
--- This should eventually be moved up to telescope core
---@nodoc
---@class telescope.picker.opts
---@field prompt_title string? title of the prompt window
---@field results_title string? title of the results windows
---@field preview_title string? title of the preview window
---@field prompt_prefix string? prefix of the prompt
---@field wrap_results boolean?
---@field selection_caret string?
---@field entry_prefix string?
---@field multi_icon string?
---@field initial_mode ('insert'|'normal')?
---@field debounce number?
---@field default_text string?
---@field get_status_text (fun(picker: table): string)?
---@field on_input_filter_cb (fun(prompt: string): any)?
---@field finder table?
---@field sorter Sorter?
---@field previewer (table)?
---@field current_previewer_index number?
---@field default_selection_index number?
---@field get_selection_window (fun(picker: table, entry: table): number)?
---@field cwd string?
---@field _completion_callbacks ((fun(picker: table): nil)[])?
---@field manager table?
---@field _multi table?
---@field track boolean?
---@field attach_mappings (fun(prompt_bufnr: integer, map: fun()): boolean)?
---@field file_ignore_patterns (string[])?
---@field scroll_strategy ('cycle'|'limit')?
---@field sorting_strategy ('descending'|'ascending')?
---@field tiebreak (fun(current_entry: any, existing_entry: any, prompt: string): boolean)?
---@field selection_strategy ('reset'|'follow'|'row'|'closest'|'none')?
---@field push_cursor_on_edit boolean?
---@field push_tagstack_on_edit boolean?
---@field layout_strategy ('horizontal'|'vertical'|'center'|'cursor'|'flex'|'bottom_pane')?
---@field layout_config table?
---@field cycle_layout_list (string[])?
---@field winblend number?
---@field window table?
---@field border boolean?
---@field borderchars (string[])?

--- Options for the file browser picker.
---
--- Inherits options for the base telescope picker.<br>
--- See |telescope.defaults|
---
--- Notes:
--- - display_stat:
--- - A table that can currently hold `date` and/or `size` as keys -- order matters!
--- - To opt-out, you can pass { display_stat = false }; sorting by stat works regardlessly
--- - The value of a key can be one of `true` or a table of `{ width = integer, display = function, hl = string }`
--- - The flags can be incrementally changed via eg `{ date = true, size = { width = 21, hl = "ErrorMsg" } }`
--- - See make_entry.lua for an example on how to further customize
---@class telescope-file-browser.PickerOpts : telescope.picker.opts
---@field path string: dir to browse files from, `vim.fn.expanded` automatically (default: `vim.loop.cwd()`)
---@field cwd string: dir to browse folders from, `vim.fn.expanded` automatically (default: `vim.loop.cwd()`)
---@field cwd_to_path boolean: whether folder browser is launched from `path` rather than `cwd` (default: `false`)
---@field grouped boolean: group initial sorting by directories and then files (default: `false`)
---@field files boolean: start in file (true) or folder (false) browser (default: `true`)
---@field add_dirs boolean: whether the file browser shows folders (default: `true`)
---@field depth number: file tree depth to display, `false` for unlimited depth (default: `1`)
---@field auto_depth boolean|number: unlimit or set `depth` to `auto_depth` & unset grouped on prompt for file_browser (default: `false`)
---@field select_buffer boolean: select current buffer if possible; may imply `hidden=true` (default: `false`)
---@field hidden table|boolean: determines whether to show hidden files or not (default: `{ file_browser = false, folder_browser = false }`)
---@field respect_gitignore boolean: induces slow-down w/ plenary finder (default: false, true if `fd` available)
---@field no_ignore boolean: disable use of ignore files like .gitignore/.ignore/.fdignore (default: false, requires `fd`)
---@field follow_symlinks boolean: traverse symbolic links, i.e. files and folders (default: false, only works with `fd`)
---@field respect_gitignore boolean: induces slow-down w/ plenary finder (default: `false`, `true` if `fd` available)
---@field no_ignore boolean: disable use of ignore files like .gitignore/.ignore/.fdignore (default: `false, requires `fd``)
---@field follow_symlinks boolean: traverse symbolic links, i.e. files and folders (default: `false`, only works with `fd`)
---@field browse_files function: custom override for the file browser (default: |fb_finders.browse_files|)
---@field browse_folders function: custom override for the folder browser (default: |fb_finders.browse_folders|)
---@field hide_parent_dir boolean: hide `../` in the file browser (default: false)
---@field collapse_dirs boolean: skip dirs w/ only single (possibly hidden) sub-dir in file_browser (default: false)
---@field quiet boolean: surpress any notification from file_brower actions (default: false)
---@field use_ui_input boolean: Use vim.ui.input() instead of vim.fn.input() or vim.fn.confirm() (default: true)
---@field dir_icon string: change the icon for a directory (default: )
---@field dir_icon_hl string: change the highlight group of dir icon (default: "Default")
---@field hide_parent_dir boolean: hide `../` in the file browser (default: `false`)
---@field collapse_dirs boolean: skip dirs w/ only single (possibly hidden) sub-dir in file_browser (default: `false`)
---@field quiet boolean: surpress any notification from file_brower actions (default: `false`)
---@field use_ui_input boolean: Use vim.ui.input() instead of vim.fn.input() or vim.fn.confirm() (default: `true`)
---@field dir_icon string: change the icon for a directory (default: `""`)
---@field dir_icon_hl string: change the highlight group of dir icon (default: `"Default"`)
---@field display_stat boolean|table: ordered stat; see above notes, (default: `{ date = true, size = true, mode = true }`)
---@field hijack_netrw boolean: use telescope file browser when opening directory paths; must be set on `setup` (default: false)
---@field use_fd boolean: use `fd` if available over `plenary.scandir` (default: true)
---@field git_status boolean: show the git status of files (default: true if `git` executable can be found)
---@field prompt_path boolean: Show the current relative path from cwd as the prompt prefix. (default: false)
---@field create_from_prompt boolean: Create file/folder from prompt if no entry selected (default: true)
---@field use_fd boolean: use `fd` if available over `plenary.scandir` (default: `true`)
---@field git_status boolean: show the git status of files (default: `true` if `git` executable can be found)
---@field prompt_path boolean: Show the current relative path from cwd as the prompt prefix. (default: `false`)
---@field create_from_prompt boolean: Create file/folder from prompt if no entry selected (default: `true`)
---@field theme string?: theme to use for the file browser (default: `nil`)
---@field _custom_prompt_title boolean
---@field _custom_results_title boolean

--- Create a new file browser picker.
---@param opts telescope-file-browser.PickerOpts?: options to pass to the picker
fb_picker.file_browser = function(opts)
opts = opts or {}

local cwd = vim.loop.cwd()
local cwd = vim.loop.cwd() ---@cast cwd string
opts.depth = vim.F.if_nil(opts.depth, 1)
opts.cwd_to_path = vim.F.if_nil(opts.cwd_to_path, false)
opts.cwd = opts.cwd and fb_utils.to_absolute_path(opts.cwd) or cwd
@@ -95,8 +154,8 @@ fb_picker.file_browser = function(opts)
opts.hide_parent_dir = vim.F.if_nil(opts.hide_parent_dir, false)
opts.select_buffer = vim.F.if_nil(opts.select_buffer, false)
opts.display_stat = vim.F.if_nil(opts.display_stat, { mode = true, date = true, size = true })
opts.custom_prompt_title = opts.prompt_title ~= nil
opts.custom_results_title = opts.results_title ~= nil
opts._custom_prompt_title = opts.prompt_title ~= nil
opts._custom_results_title = opts.results_title ~= nil
opts.use_fd = vim.F.if_nil(opts.use_fd, true)
opts.git_status = vim.F.if_nil(opts.git_status, vim.fn.executable "git" == 1)
opts.prompt_path = vim.F.if_nil(opts.prompt_path, false)
@@ -105,6 +164,8 @@ fb_picker.file_browser = function(opts)
local select_buffer = opts.select_buffer and opts.files
-- handle case that current buffer is a hidden file
opts.hidden = (select_buffer and vim.fn.expand("%:p:t"):sub(1, 1) == ".") and true or opts.hidden

---@cast opts telescope-file-browser.FinderOpts
opts.finder = fb_finder.finder(opts)
-- find index of current buffer in the results
if select_buffer then
2 changes: 1 addition & 1 deletion lua/telescope/_extensions/file_browser/utils.lua
Original file line number Diff line number Diff line change
@@ -189,7 +189,7 @@ end
---@return string
fb_utils.sanitize_path_str = function(path)
path = path:gsub(os_sep .. os_sep, os_sep)
if iswin then
if fb_utils.iswin then
if path:match "^%w:\\$" then
return path
else
37 changes: 16 additions & 21 deletions scripts/gendocs.lua
Original file line number Diff line number Diff line change
@@ -1,27 +1,22 @@
local docgen = require "docgen"
vim.env.DOCGEN_PATH = vim.env.DOCGEN_PATH or ".deps/docgen.nvim"

local docs = {}
load(vim.fn.system "curl -s https://raw.githubusercontent.com/jamestrew/docgen.nvim/master/scripts/bootstrap.lua")()

docs.test = function()
local input_files = {
require("docgen").run {
name = "telescope-file-browser",
files = {
"./lua/telescope/_extensions/file_browser.lua",
"./lua/telescope/_extensions/file_browser/picker.lua",
"./lua/telescope/_extensions/file_browser/actions.lua",
"./lua/telescope/_extensions/file_browser/finders.lua",
}

local output_file = "./doc/telescope-file-browser.txt"
local output_file_handle = io.open(output_file, "w")

for _, input_file in ipairs(input_files) do
docgen.write(input_file, output_file_handle)
end

output_file_handle:write " vim:tw=78:ts=8:ft=help:norl:\n"
output_file_handle:close()
vim.cmd [[checktime]]
end

docs.test()

return docs
},
section_fmt = function(filename)
local section_names = {
["./lua/telescope/_extensions/file_browser.lua"] = "TELESCOPE-FILE-BROWSER",
["./lua/telescope/_extensions/file_browser/picker.lua"] = "PICKER",
["./lua/telescope/_extensions/file_browser/actions.lua"] = "ACTIONS",
["./lua/telescope/_extensions/file_browser/finders.lua"] = "FINDERS",
}
return section_names[filename]
end,
}
5 changes: 2 additions & 3 deletions scripts/minimal_init.vim
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
set rtp+=.
set rtp+=deps/plenary.nvim/
set rtp+=deps/telescope.nvim/
set rtp+=deps/tree-sitter-lua/
set rtp+=.deps/plenary.nvim/
set rtp+=.deps/telescope.nvim/

runtime! plugin/plenary.vim

0 comments on commit 8574946

Please sign in to comment.