diff --git a/doc/telescope.txt b/doc/telescope.txt index 6c932be..a264ec5 100644 --- a/doc/telescope.txt +++ b/doc/telescope.txt @@ -41,13 +41,43 @@ telescope.setup({opts}) *telescope.setup()* Default: false - *telescope.defaults.entry_prefix* entry_prefix: ~ Prefix in front of each result entry. Current selection not included. Default: ' ' + *telescope.defaults.history* + history: ~ + This field handles the configuration for prompt history. + By default it is a table, with default values (more below). + To disable history, set it to either false or nil. + + Currently mappings still need to be added, Example: + mappings = { + i = { + [""] = require('telescope.actions').cycle_history_next, + [""] = require('telescope.actions').cycle_history_prev, + }, + }, + + Fields: + - path: The path to the telescope history as string. + default: stdpath("data")/telescope_history + - limit: The amount of entries that will be written in the + history. + Warning: If limit is set to nil it will grown unbound. + default: 100 + - handler: A lua function that implements the history. + This is meant as a developer setting for extensions to + override the history handling, e.g., + https://github.com/nvim-telescope/telescope-smart-history.nvim, + which allows context sensitive (cwd + picker) history. + + Default: + require('telescope.actions.history').get_simple_history + + *telescope.defaults.layout_config* layout_config: ~ Determines the default configuration values for layout strategies. @@ -220,374 +250,6 @@ telescope.extensions() *telescope.extensions()* -================================================================================ - *telescope.themes* - -Themes are ways to combine several elements of styling together. - -They are helpful for managing the several differnt UI aspects for telescope and -provide a simple interface for users to get a particular "style" of picker. - -themes.get_dropdown() *themes.get_dropdown()* - Dropdown style theme. - - Usage: - - `local builtin = require('telescope.builtin')` - `local themes = require('telescope.themes')` - `builtin.find_files(themes.get_dropdown())` - - - -themes.get_ivy() *themes.get_ivy()* - Ivy style theme. - - Usage: - - `local builtin = require('telescope.builtin')` - `local themes = require('telescope.themes')` - `builtin.find_files(themes.get_ivy())` - - - - -================================================================================ - *telescope.actions.set* - -Telescope action sets are used to provide an interface for managing actions -that all primarily do the same thing, but with slight tweaks. - -For example, when editing files you may want it in the current split, a -vertical split, etc. Instead of making users have to overwrite EACH of those -every time they want to change this behavior, they can instead replace the -`set` itself and then it will work great and they're done. - -action_set.shift_selection({prompt_bufnr}, {change})*action_set.shift_selection()* - Move the current selection of a picker {change} rows. Handles not - overflowing / underflowing the list. - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - {change} (number) The amount to shift the selection by - - -action_set.select({prompt_bufnr}, {type}) *action_set.select()* - Select the current entry. This is the action set to overwrite common - actions by the user. - - By default maps to editing a file. - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - {type} (string) The type of selection to make - - -action_set.edit({prompt_bufnr}, {command}) *action_set.edit()* - Edit a file based on the current selection. - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - {command} (string) The command to use to open the file. - - -action_set.scroll_previewer({prompt_bufnr}, {direction})*action_set.scroll_previewer()* - Scrolls the previewer up or down - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - {direction} (number) The direction of the scrolling - - - -================================================================================ - *telescope.actions* - -Actions functions that are useful for people creating their own mappings. - -actions.move_selection_next({prompt_bufnr}) *actions.move_selection_next()* - Move the selection to the next entry - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - - -actions.move_selection_previous({prompt_bufnr})*actions.move_selection_previous()* - Move the selection to the previous entry - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - - -actions.move_selection_worse({prompt_bufnr}) *actions.move_selection_worse()* - Move the selection to the entry that has a worse score - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - - -actions.move_selection_better({prompt_bufnr})*actions.move_selection_better()* - Move the selection to the entry that has a better score - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - - -actions.move_to_top({prompt_bufnr}) *actions.move_to_top()* - Move to the top of the picker - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - - -actions.move_to_middle({prompt_bufnr}) *actions.move_to_middle()* - Move to the middle of the picker - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - - -actions.move_to_bottom({prompt_bufnr}) *actions.move_to_bottom()* - Move to the bottom of the picker - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - - -actions.add_selection({prompt_bufnr}) *actions.add_selection()* - Add current entry to multi select - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - - -actions.remove_selection({prompt_bufnr}) *actions.remove_selection()* - Remove current entry from multi select - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - - -actions.toggle_selection({prompt_bufnr}) *actions.toggle_selection()* - Toggle current entry status for multi select - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - - -actions.select_all({prompt_bufnr}) *actions.select_all()* - Multi select all entries. - - Note: selected entries may include results not visible in the results - popup. - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - - -actions.drop_all({prompt_bufnr}) *actions.drop_all()* - Drop all entries from the current multi selection. - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - - -actions.toggle_all({prompt_bufnr}) *actions.toggle_all()* - Toggle multi selection for all entries. - - Note: toggled entries may include results not visible in the results - popup. - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - - -actions.git_create_branch({prompt_bufnr}) *actions.git_create_branch()* - Create and checkout a new git branch if it doesn't already exist - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - - -actions.git_apply_stash({prompt_bufnr}) *actions.git_apply_stash()* - Applies an existing git stash - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - - -actions.git_checkout({prompt_bufnr}) *actions.git_checkout()* - Checkout an existing git branch - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - - -actions.git_switch_branch({prompt_bufnr}) *actions.git_switch_branch()* - Switch to git branch. - If the branch already exists in local, switch to that. If the branch is - only in remote, create new branch tracking remote and switch to new one. - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - - -actions.git_track_branch({prompt_bufnr}) *actions.git_track_branch()* - Tell git to track the currently selected remote branch in Telescope - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - - -actions.git_delete_branch({prompt_bufnr}) *actions.git_delete_branch()* - Delete the currently selected branch - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - - -actions.git_rebase_branch({prompt_bufnr}) *actions.git_rebase_branch()* - Rebase to selected git branch - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - - -actions.git_staging_toggle({prompt_bufnr}) *actions.git_staging_toggle()* - Stage/unstage selected file - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - - -actions.send_selected_to_qflist() *actions.send_selected_to_qflist()* - Sends the selected entries to the quickfix list, replacing the previous - entries. - - - -actions.add_selected_to_qflist() *actions.add_selected_to_qflist()* - Adds the selected entries to the quickfix list, keeping the previous - entries. - - - -actions.send_to_qflist() *actions.send_to_qflist()* - Sends all entries to the quickfix list, replacing the previous entries. - - - -actions.add_to_qflist() *actions.add_to_qflist()* - Adds all entries to the quickfix list, keeping the previous entries. - - - -actions.send_selected_to_loclist() *actions.send_selected_to_loclist()* - Sends the selected entries to the location list, replacing the previous - entries. - - - -actions.add_selected_to_loclist() *actions.add_selected_to_loclist()* - Adds the selected entries to the location list, keeping the previous - entries. - - - -actions.send_to_loclist() *actions.send_to_loclist()* - Sends all entries to the location list, replacing the previous entries. - - - -actions.add_to_loclist() *actions.add_to_loclist()* - Adds all entries to the location list, keeping the previous entries. - - - -actions.smart_send_to_qflist() *actions.smart_send_to_qflist()* - Sends the selected entries to the quickfix list, replacing the previous - entries. If no entry was selected, sends all entries. - - - -actions.smart_add_to_qflist() *actions.smart_add_to_qflist()* - Adds the selected entries to the quickfix list, keeping the previous - entries. If no entry was selected, adds all entries. - - - -actions.smart_send_to_loclist() *actions.smart_send_to_loclist()* - Sends the selected entries to the location list, replacing the previous - entries. If no entry was selected, sends all entries. - - - -actions.smart_add_to_loclist() *actions.smart_add_to_loclist()* - Adds the selected entries to the location list, keeping the previous - entries. If no entry was selected, adds all entries. - - - -actions.open_qflist() *actions.open_qflist()* - Open the quickfix list - - - -actions.open_loclist() *actions.open_loclist()* - Open the location list - - - -actions.delete_buffer({prompt_bufnr}) *actions.delete_buffer()* - Delete the selected buffer or all the buffers selected using multi - selection. - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - - -actions.cycle_previewers_next({prompt_bufnr})*actions.cycle_previewers_next()* - Cycle to the next previewer if there is one available. - This action is not mapped on default. - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - - -actions.cycle_previewers_prev({prompt_bufnr})*actions.cycle_previewers_prev()* - Cycle to the previous previewer if there is one available. - This action is not mapped on default. - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - - - ================================================================================ *telescope.builtin* @@ -1209,6 +871,628 @@ builtin.lsp_workspace_diagnostics({opts})*builtin.lsp_workspace_diagnostics()* +================================================================================ + *telescope.themes* + +Themes are ways to combine several elements of styling together. + +They are helpful for managing the several differnt UI aspects for telescope and +provide a simple interface for users to get a particular "style" of picker. + +themes.get_dropdown() *themes.get_dropdown()* + Dropdown style theme. + + Usage: + + `local builtin = require('telescope.builtin')` + `local themes = require('telescope.themes')` + `builtin.find_files(themes.get_dropdown())` + + + +themes.get_ivy() *themes.get_ivy()* + Ivy style theme. + + Usage: + + `local builtin = require('telescope.builtin')` + `local themes = require('telescope.themes')` + `builtin.find_files(themes.get_ivy())` + + + + +================================================================================ + *telescope.layout* + +Layout strategies are different functions to position telescope. + +All layout strategies are functions with the following signature: + + function(picker, columns, lines, layout_config) + -- Do some calculations here... + return { + preview = preview_configuration + results = results_configuration, + prompt = prompt_configuration, + } + end + + Parameters: ~ + - picker : A Picker object. (docs coming soon) + - columns : (number) Columns in the vim window + - lines : (number) Lines in the vim window + - layout_config : (table) The configuration values specific to the picker. + + +This means you can create your own layout strategy if you want! Just be aware +for now that we may change some APIs or interfaces, so they may break if you +create your own. + +A good method for creating your own would be to copy one of the strategies that +most resembles what you want from +"./lua/telescope/pickers/layout_strategies.lua" in the telescope repo. + + +layout_strategies.horizontal() *layout_strategies.horizontal()* + Horizontal layout has two columns, one for the preview and one for the + prompt and results. + + ┌──────────────────────────────────────────────────┐ + │ │ + │ ┌───────────────────┐┌───────────────────┐ │ + │ │ ││ │ │ + │ │ ││ │ │ + │ │ ││ │ │ + │ │ Results ││ │ │ + │ │ ││ Preview │ │ + │ │ ││ │ │ + │ │ ││ │ │ + │ └───────────────────┘│ │ │ + │ ┌───────────────────┐│ │ │ + │ │ Prompt ││ │ │ + │ └───────────────────┘└───────────────────┘ │ + │ │ + └──────────────────────────────────────────────────┘ + + `picker.layout_config` shared options: + - height: + - How tall to make Telescope's entire layout + - See |resolver.resolve_height()| + - mirror: Flip the location of the results/prompt and preview windows + - scroll_speed: The number of lines to scroll through the previewer + - width: + - How wide to make Telescope's entire layout + - See |resolver.resolve_width()| + + `picker.layout_config` unique options: + - preview_cutoff: When columns are less than this value, the preview will be disabled + - preview_width: + - Change the width of Telescope's preview window + - See |resolver.resolve_width()| + - prompt_position: + - Where to place prompt window. + - Available Values: 'bottom', 'top' + + +layout_strategies.center() *layout_strategies.center()* + Centered layout with a combined block of the prompt and results aligned to + the middle of the screen. The preview window is then placed in the + remaining space above. Particularly useful for creating dropdown menus (see + |telescope.themes| and |themes.get_dropdown()|`). + + ┌──────────────────────────────────────────────────┐ + │ ┌────────────────────────────────────────┐ │ + │ | Preview | │ + │ | Preview | │ + │ └────────────────────────────────────────┘ │ + │ ┌────────────────────────────────────────┐ │ + │ | Prompt | │ + │ ├────────────────────────────────────────┤ │ + │ | Result | │ + │ | Result | │ + │ └────────────────────────────────────────┘ │ + │ │ + │ │ + │ │ + │ │ + └──────────────────────────────────────────────────┘ + + `picker.layout_config` shared options: + - height: + - How tall to make Telescope's entire layout + - See |resolver.resolve_height()| + - mirror: Flip the location of the results/prompt and preview windows + - scroll_speed: The number of lines to scroll through the previewer + - width: + - How wide to make Telescope's entire layout + - See |resolver.resolve_width()| + + `picker.layout_config` unique options: + - preview_cutoff: When lines are less than this value, the preview will be disabled + + +layout_strategies.vertical() *layout_strategies.vertical()* + Vertical layout stacks the items on top of each other. Particularly useful + with thinner windows. + + ┌──────────────────────────────────────────────────┐ + │ │ + │ ┌────────────────────────────────────────┐ │ + │ | Preview | │ + │ | Preview | │ + │ | Preview | │ + │ └────────────────────────────────────────┘ │ + │ ┌────────────────────────────────────────┐ │ + │ | Result | │ + │ | Result | │ + │ └────────────────────────────────────────┘ │ + │ ┌────────────────────────────────────────┐ │ + │ | Prompt | │ + │ └────────────────────────────────────────┘ │ + │ │ + └──────────────────────────────────────────────────┘ + + `picker.layout_config` shared options: + - height: + - How tall to make Telescope's entire layout + - See |resolver.resolve_height()| + - mirror: Flip the location of the results/prompt and preview windows + - scroll_speed: The number of lines to scroll through the previewer + - width: + - How wide to make Telescope's entire layout + - See |resolver.resolve_width()| + + `picker.layout_config` unique options: + - preview_cutoff: When lines are less than this value, the preview will be disabled + - preview_height: + - Change the height of Telescope's preview window + - See |resolver.resolve_height()| + - prompt_position: + - (unimplemented, but we plan on supporting) + + +layout_strategies.flex() *layout_strategies.flex()* + Flex layout swaps between `horizontal` and `vertical` strategies based on + the window width + - Supports |layout_strategies.vertical| or |layout_strategies.horizontal| + features + + + `picker.layout_config` shared options: + - height: + - How tall to make Telescope's entire layout + - See |resolver.resolve_height()| + - mirror: Flip the location of the results/prompt and preview windows + - scroll_speed: The number of lines to scroll through the previewer + - width: + - How wide to make Telescope's entire layout + - See |resolver.resolve_width()| + + `picker.layout_config` unique options: + - flip_columns: The number of columns required to move to horizontal mode + - flip_lines: The number of lines required to move to horizontal mode + - horizontal: Options to pass when switching to horizontal layout + - vertical: Options to pass when switching to vertical layout + + +layout_strategies.bottom_pane() *layout_strategies.bottom_pane()* + Bottom pane can be used to create layouts similar to "ivy". + + For an easy ivy configuration, see |themes.get_ivy()| + + + + +================================================================================ + *telescope.resolve* + +Provides "resolver functions" to allow more customisable inputs for options. + +resolver.resolve_height() *resolver.resolve_height()* + Converts input to a function that returns the height. The input must take + one of four forms: + 1. 0 <= number < 1 + This means total height as a percentage. + 2. 1 <= number + This means total height as a fixed number. + 3. function + Must have signature: function(self, max_columns, max_lines): number + 4. table of the form: {padding = `foo`} + where `foo` has one of the previous three forms. + The height is then set to be the remaining space after padding. For + example, if the window has height 50, and the input is {padding = 5}, + the height returned will be `40 = 50 - 2*5` + + The returned function will have signature: function(self, max_columns, + max_lines): number + + + +resolver.resolve_width() *resolver.resolve_width()* + Converts input to a function that returns the width. The input must take + one of four forms: + 1. 0 <= number < 1 + This means total width as a percentage. + 2. 1 <= number + This means total width as a fixed number. + 3. function + Must have signature: function(self, max_columns, max_lines): number + 4. table of the form: {padding = `foo`} + where `foo` has one of the previous three forms. + The width is then set to be the remaining space after padding. For + example, if the window has width 100, and the input is {padding = 5}, + the width returned will be `90 = 100 - 2*5` + + The returned function will have signature: function(self, max_columns, + max_lines): number + + + + +================================================================================ + *telescope.actions* + +Actions functions that are useful for people creating their own mappings. + +actions.move_selection_next({prompt_bufnr}) *actions.move_selection_next()* + Move the selection to the next entry + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + +actions.move_selection_previous({prompt_bufnr})*actions.move_selection_previous()* + Move the selection to the previous entry + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + +actions.move_selection_worse({prompt_bufnr}) *actions.move_selection_worse()* + Move the selection to the entry that has a worse score + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + +actions.move_selection_better({prompt_bufnr})*actions.move_selection_better()* + Move the selection to the entry that has a better score + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + +actions.move_to_top({prompt_bufnr}) *actions.move_to_top()* + Move to the top of the picker + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + +actions.move_to_middle({prompt_bufnr}) *actions.move_to_middle()* + Move to the middle of the picker + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + +actions.move_to_bottom({prompt_bufnr}) *actions.move_to_bottom()* + Move to the bottom of the picker + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + +actions.add_selection({prompt_bufnr}) *actions.add_selection()* + Add current entry to multi select + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + +actions.remove_selection({prompt_bufnr}) *actions.remove_selection()* + Remove current entry from multi select + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + +actions.toggle_selection({prompt_bufnr}) *actions.toggle_selection()* + Toggle current entry status for multi select + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + +actions.select_all({prompt_bufnr}) *actions.select_all()* + Multi select all entries. + - Note: selected entries may include results not visible in the results + popup. + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + +actions.drop_all({prompt_bufnr}) *actions.drop_all()* + Drop all entries from the current multi selection. + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + +actions.toggle_all({prompt_bufnr}) *actions.toggle_all()* + Toggle multi selection for all entries. + - Note: toggled entries may include results not visible in the results + popup. + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + +actions.git_create_branch({prompt_bufnr}) *actions.git_create_branch()* + Create and checkout a new git branch if it doesn't already exist + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + +actions.git_apply_stash({prompt_bufnr}) *actions.git_apply_stash()* + Applies an existing git stash + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + +actions.git_checkout({prompt_bufnr}) *actions.git_checkout()* + Checkout an existing git branch + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + +actions.git_switch_branch({prompt_bufnr}) *actions.git_switch_branch()* + Switch to git branch. + If the branch already exists in local, switch to that. If the branch is + only in remote, create new branch tracking remote and switch to new one. + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + +actions.git_track_branch({prompt_bufnr}) *actions.git_track_branch()* + Tell git to track the currently selected remote branch in Telescope + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + +actions.git_delete_branch({prompt_bufnr}) *actions.git_delete_branch()* + Delete the currently selected branch + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + +actions.git_rebase_branch({prompt_bufnr}) *actions.git_rebase_branch()* + Rebase to selected git branch + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + +actions.git_staging_toggle({prompt_bufnr}) *actions.git_staging_toggle()* + Stage/unstage selected file + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + +actions.send_selected_to_qflist() *actions.send_selected_to_qflist()* + Sends the selected entries to the quickfix list, replacing the previous + entries. + + + +actions.add_selected_to_qflist() *actions.add_selected_to_qflist()* + Adds the selected entries to the quickfix list, keeping the previous + entries. + + + +actions.send_to_qflist() *actions.send_to_qflist()* + Sends all entries to the quickfix list, replacing the previous entries. + + + +actions.add_to_qflist() *actions.add_to_qflist()* + Adds all entries to the quickfix list, keeping the previous entries. + + + +actions.send_selected_to_loclist() *actions.send_selected_to_loclist()* + Sends the selected entries to the location list, replacing the previous + entries. + + + +actions.add_selected_to_loclist() *actions.add_selected_to_loclist()* + Adds the selected entries to the location list, keeping the previous + entries. + + + +actions.send_to_loclist() *actions.send_to_loclist()* + Sends all entries to the location list, replacing the previous entries. + + + +actions.add_to_loclist() *actions.add_to_loclist()* + Adds all entries to the location list, keeping the previous entries. + + + +actions.smart_send_to_qflist() *actions.smart_send_to_qflist()* + Sends the selected entries to the quickfix list, replacing the previous + entries. If no entry was selected, sends all entries. + + + +actions.smart_add_to_qflist() *actions.smart_add_to_qflist()* + Adds the selected entries to the quickfix list, keeping the previous + entries. If no entry was selected, adds all entries. + + + +actions.smart_send_to_loclist() *actions.smart_send_to_loclist()* + Sends the selected entries to the location list, replacing the previous + entries. If no entry was selected, sends all entries. + + + +actions.smart_add_to_loclist() *actions.smart_add_to_loclist()* + Adds the selected entries to the location list, keeping the previous + entries. If no entry was selected, adds all entries. + + + +actions.open_qflist() *actions.open_qflist()* + Open the quickfix list + + + +actions.open_loclist() *actions.open_loclist()* + Open the location list + + + +actions.delete_buffer({prompt_bufnr}) *actions.delete_buffer()* + Delete the selected buffer or all the buffers selected using multi + selection. + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + +actions.cycle_previewers_next({prompt_bufnr})*actions.cycle_previewers_next()* + Cycle to the next previewer if there is one available. + This action is not mapped on default. + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + +actions.cycle_previewers_prev({prompt_bufnr})*actions.cycle_previewers_prev()* + Cycle to the previous previewer if there is one available. + This action is not mapped on default. + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + + +================================================================================ + *telescope.actions.state* + +Functions to be used to determine the current state of telescope. + +Generally used from within other |telescope.actions| + +action_state.get_selected_entry() *action_state.get_selected_entry()* + Get the current entry + + + +action_state.get_current_line() *action_state.get_current_line()* + Gets the current line + + + +action_state.get_current_picker({prompt_bufnr})*action_state.get_current_picker()* + Gets the current picker + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + + + +================================================================================ + *telescope.actions.set* + +Telescope action sets are used to provide an interface for managing actions +that all primarily do the same thing, but with slight tweaks. + +For example, when editing files you may want it in the current split, a +vertical split, etc. Instead of making users have to overwrite EACH of those +every time they want to change this behavior, they can instead replace the +`set` itself and then it will work great and they're done. + +action_set.shift_selection({prompt_bufnr}, {change})*action_set.shift_selection()* + Move the current selection of a picker {change} rows. Handles not + overflowing / underflowing the list. + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + {change} (number) The amount to shift the selection by + + +action_set.select({prompt_bufnr}, {type}) *action_set.select()* + Select the current entry. This is the action set to overwrite common + actions by the user. + + By default maps to editing a file. + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + {type} (string) The type of selection to make + + +action_set.edit({prompt_bufnr}, {command}) *action_set.edit()* + Edit a file based on the current selection. + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + {command} (string) The command to use to open the file. + + +action_set.scroll_previewer({prompt_bufnr}, {direction})*action_set.scroll_previewer()* + Scrolls the previewer up or down + + + Parameters: ~ + {prompt_bufnr} (number) The prompt bufnr + {direction} (number) The direction of the scrolling + + + ================================================================================ *telescope.actions.utils* @@ -1273,78 +1557,6 @@ utils.map_selections({prompt_bufnr}, {f}) *utils.map_selections()* -================================================================================ - *telescope.actions.state* - -Functions to be used to determine the current state of telescope. - -Generally used from within other |telescope.actions| - -action_state.get_selected_entry() *action_state.get_selected_entry()* - Get the current entry - - - -action_state.get_current_line() *action_state.get_current_line()* - Gets the current line - - - -action_state.get_current_picker({prompt_bufnr})*action_state.get_current_picker()* - Gets the current picker - - - Parameters: ~ - {prompt_bufnr} (number) The prompt bufnr - - - -================================================================================ - *telescope.resolve* - -Provides "resolver functions" to allow more customisable inputs for options. - -resolver.resolve_height() *resolver.resolve_height()* - Converts input to a function that returns the height. The input must take - one of four forms: - 1. 0 <= number < 1 - This means total height as a percentage. - 2. 1 <= number - This means total height as a fixed number. - 3. function - Must have signature: function(self, max_columns, max_lines): number - 4. table of the form: {padding = `foo`} - where `foo` has one of the previous three forms. - The height is then set to be the remaining space after padding. For - example, if the window has height 50, and the input is {padding = 5}, - the height returned will be `40 = 50 - 2*5` - - The returned function will have signature: function(self, max_columns, - max_lines): number - - - -resolver.resolve_width() *resolver.resolve_width()* - Converts input to a function that returns the width. The input must take - one of four forms: - 1. 0 <= number < 1 - This means total width as a percentage. - 2. 1 <= number - This means total width as a fixed number. - 3. function - Must have signature: function(self, max_columns, max_lines): number - 4. table of the form: {padding = `foo`} - where `foo` has one of the previous three forms. - The width is then set to be the remaining space after padding. For - example, if the window has width 100, and the input is {padding = 5}, - the width returned will be `90 = 100 - 2*5` - - The returned function will have signature: function(self, max_columns, - max_lines): number - - - - ================================================================================ *telescope.previewers* @@ -1671,183 +1883,108 @@ previewers.display_content() *previewers.display_content()* ================================================================================ - *telescope.layout* + *telescope.actions.history* -Layout strategies are different functions to position telescope. +A base implementation of a prompt history that provides a simple history and +can be replaced with a custom implementation. -All layout strategies are functions with the following signature: +For example: We provide a extension for a smart history that uses sql.nvim to +map histories to metadata, like the calling picker or cwd. - function(picker, columns, lines, layout_config) - -- Do some calculations here... - return { - preview = preview_configuration - results = results_configuration, - prompt = prompt_configuration, - } - end +So you have a history for: +- find_files project_1 +- grep_string project_1 +- live_grep project_1 +- find_files project_2 +- grep_string project_2 +- live_grep project_2 +- etc - Parameters: ~ - - picker : A Picker object. (docs coming soon) - - columns : (number) Columns in the vim window - - lines : (number) Lines in the vim window - - layout_config : (table) The configuration values specific to the picker. +See github.com/nvim-telescope/telescope-smart-history.nvim + +histories.History() *histories.History()* + Manages prompt history -This means you can create your own layout strategy if you want! Just be aware -for now that we may change some APIs or interfaces, so they may break if you -create your own. - -A good method for creating your own would be to copy one of the strategies that -most resembles what you want from -"./lua/telescope/pickers/layout_strategies.lua" in the telescope repo. + Fields: ~ + {enabled} (boolean) Will indicate if History is enabled or disabled + {path} (string) Will point to the location of the history file + {limit} (string) Will have the limit of the history. Can be nil, if + limit is disabled. + {content} (table) History table. Needs to be filled by your own + History implementation + {index} (number) Used to keep track of the next or previous index. + Default is #content + 1 -layout_strategies.horizontal() *layout_strategies.horizontal()* - Horizontal layout has two columns, one for the preview and one for the - prompt and results. - - ┌──────────────────────────────────────────────────┐ - │ │ - │ ┌───────────────────┐┌───────────────────┐ │ - │ │ ││ │ │ - │ │ ││ │ │ - │ │ ││ │ │ - │ │ Results ││ │ │ - │ │ ││ Preview │ │ - │ │ ││ │ │ - │ │ ││ │ │ - │ └───────────────────┘│ │ │ - │ ┌───────────────────┐│ │ │ - │ │ Prompt ││ │ │ - │ └───────────────────┘└───────────────────┘ │ - │ │ - └──────────────────────────────────────────────────┘ - - `picker.layout_config` shared options: - - height: - - How tall to make Telescope's entire layout - - See |resolver.resolve_height()| - - mirror: Flip the location of the results/prompt and preview windows - - scroll_speed: The number of lines to scroll through the previewer - - width: - - How wide to make Telescope's entire layout - - See |resolver.resolve_width()| - - `picker.layout_config` unique options: - - preview_cutoff: When columns are less than this value, the preview will be disabled - - preview_width: - - Change the width of Telescope's preview window - - See |resolver.resolve_width()| - - prompt_position: - - Where to place prompt window. - - Available Values: 'bottom', 'top' +histories.History:new({opts}) *histories.History:new()* + Create a new History -layout_strategies.center() *layout_strategies.center()* - Centered layout with a combined block of the prompt and results aligned to - the middle of the screen. The preview window is then placed in the - remaining space above. Particularly useful for creating dropdown menus (see - |telescope.themes| and |themes.get_dropdown()|`). + Parameters: ~ + {opts} (table) Defines the behavior of History - ┌──────────────────────────────────────────────────┐ - │ ┌────────────────────────────────────────┐ │ - │ | Preview | │ - │ | Preview | │ - │ └────────────────────────────────────────┘ │ - │ ┌────────────────────────────────────────┐ │ - │ | Prompt | │ - │ ├────────────────────────────────────────┤ │ - │ | Result | │ - │ | Result | │ - │ └────────────────────────────────────────┘ │ - │ │ - │ │ - │ │ - │ │ - └──────────────────────────────────────────────────┘ - - `picker.layout_config` shared options: - - height: - - How tall to make Telescope's entire layout - - See |resolver.resolve_height()| - - mirror: Flip the location of the results/prompt and preview windows - - scroll_speed: The number of lines to scroll through the previewer - - width: - - How wide to make Telescope's entire layout - - See |resolver.resolve_width()| - - `picker.layout_config` unique options: - - preview_cutoff: When lines are less than this value, the preview will be disabled + Fields: ~ + {init} (function) Will be called after handling configuration + (required) + {append} (function) How to append a new prompt item (required) + {reset} (function) What happens on reset. Will be called when + telescope closes (required) + {pre_get} (function) Will be called before a next or previous item + will be returned (optional) -layout_strategies.vertical() *layout_strategies.vertical()* - Vertical layout stacks the items on top of each other. Particularly useful - with thinner windows. - - ┌──────────────────────────────────────────────────┐ - │ │ - │ ┌────────────────────────────────────────┐ │ - │ | Preview | │ - │ | Preview | │ - │ | Preview | │ - │ └────────────────────────────────────────┘ │ - │ ┌────────────────────────────────────────┐ │ - │ | Result | │ - │ | Result | │ - │ └────────────────────────────────────────┘ │ - │ ┌────────────────────────────────────────┐ │ - │ | Prompt | │ - │ └────────────────────────────────────────┘ │ - │ │ - └──────────────────────────────────────────────────┘ - - `picker.layout_config` shared options: - - height: - - How tall to make Telescope's entire layout - - See |resolver.resolve_height()| - - mirror: Flip the location of the results/prompt and preview windows - - scroll_speed: The number of lines to scroll through the previewer - - width: - - How wide to make Telescope's entire layout - - See |resolver.resolve_width()| - - `picker.layout_config` unique options: - - preview_cutoff: When lines are less than this value, the preview will be disabled - - preview_height: - - Change the height of Telescope's preview window - - See |resolver.resolve_height()| - - prompt_position: - - (unimplemented, but we plan on supporting) +histories.new() *histories.new()* + Shorthand to create a new history -layout_strategies.flex() *layout_strategies.flex()* - Flex layout swaps between `horizontal` and `vertical` strategies based on - the window width - - Supports |layout_strategies.vertical| or |layout_strategies.horizontal| - features + +histories.History:reset() *histories.History:reset()* + Will reset the history index to the default initial state. Will happen + after the picker closed - `picker.layout_config` shared options: - - height: - - How tall to make Telescope's entire layout - - See |resolver.resolve_height()| - - mirror: Flip the location of the results/prompt and preview windows - - scroll_speed: The number of lines to scroll through the previewer - - width: - - How wide to make Telescope's entire layout - - See |resolver.resolve_width()| - `picker.layout_config` unique options: - - flip_columns: The number of columns required to move to horizontal mode - - flip_lines: The number of lines required to move to horizontal mode - - horizontal: Options to pass when switching to horizontal layout - - vertical: Options to pass when switching to vertical layout +histories.History:append({line}, {picker}, {no_reset})*histories.History:append()* + Append a new line to the history -layout_strategies.bottom_pane() *layout_strategies.bottom_pane()* - Bottom pane can be used to create layouts similar to "ivy". + Parameters: ~ + {line} (string) current line that will be appended + {picker} (table) the current picker object + {no_reset} (boolean) On default it will reset the state at the end. If + you don't want to do this set to true - For an easy ivy configuration, see |themes.get_ivy()| + +histories.History:get_next({line}, {picker}) *histories.History:get_next()* + Will return the next history item. Can be nil if there are no next items + + + Parameters: ~ + {line} (string) the current line + {picker} (table) the current picker object + + Return: ~ + string: the next history item + + +histories.History:get_prev({line}, {picker}) *histories.History:get_prev()* + Will return the previous history item. Can be nil if there are no previous + items + + + Parameters: ~ + {line} (string) the current line + {picker} (table) the current picker object + + Return: ~ + string: the previous history item + + +histories.get_simple_history() *histories.get_simple_history()* + A simple implementation of history. + + It will keep one unified history across all pickers. diff --git a/lua/telescope/actions/history.lua b/lua/telescope/actions/history.lua new file mode 100644 index 0000000..8ec58e2 --- /dev/null +++ b/lua/telescope/actions/history.lua @@ -0,0 +1,186 @@ +local conf = require('telescope.config').values +local Path = require('plenary.path') + +local uv = vim.loop + +---@brief [[ +--- A base implementation of a prompt history that provides a simple history +--- and can be replaced with a custom implementation. +--- +--- For example: We provide a extension for a smart history that uses sql.nvim +--- to map histories to metadata, like the calling picker or cwd. +--- +--- So you have a history for: +--- - find_files project_1 +--- - grep_string project_1 +--- - live_grep project_1 +--- - find_files project_2 +--- - grep_string project_2 +--- - live_grep project_2 +--- - etc +--- +--- See github.com/nvim-telescope/telescope-smart-history.nvim +---@brief ]] +---@tag telescope.actions.history + +-- TODO(conni2461): currently not present in plenary path only sync. +-- But sync is just unnecessary here +local write_async = function(path, txt, flag) + uv.fs_open(path, flag, 438, function(open_err, fd) + assert(not open_err, open_err) + uv.fs_write(fd, txt, -1, function(write_err) + assert(not write_err, write_err) + uv.fs_close(fd, function(close_err) + assert(not close_err, close_err) + end) + end) + end) +end + +local append_async = function(path, txt) write_async(path, txt, "a") end + +local histories = {} + +--- Manages prompt history +---@class History @Manages prompt history +---@field enabled boolean: Will indicate if History is enabled or disabled +---@field path string: Will point to the location of the history file +---@field limit string: Will have the limit of the history. Can be nil, if limit is disabled. +---@field content table: History table. Needs to be filled by your own History implementation +---@field index number: Used to keep track of the next or previous index. Default is #content + 1 +histories.History = {} +histories.History.__index = histories.History + +--- Create a new History +---@param opts table: Defines the behavior of History +---@field init function: Will be called after handling configuration (required) +---@field append function: How to append a new prompt item (required) +---@field reset function: What happens on reset. Will be called when telescope closes (required) +---@field pre_get function: Will be called before a next or previous item will be returned (optional) +function histories.History:new(opts) + local obj = {} + if not conf.history or type(conf.history) ~= "table" then + obj.enabled = false + return setmetatable(obj, self) + end + obj.enabled = true + if conf.history.limit then + obj.limit = conf.history.limit + end + obj.path = vim.fn.expand(conf.history.path) + obj.content = {} + obj.index = 1 + + opts.init(obj) + obj._reset = opts.reset + obj._append = opts.append + obj._pre_get = opts.pre_get + + return setmetatable(obj, self) +end + +--- Shorthand to create a new history +function histories.new(...) + return histories.History:new(...) +end + +--- Will reset the history index to the default initial state. Will happen after the picker closed +function histories.History:reset() + if not self.enabled then return end + self._reset(self) +end + +--- Append a new line to the history +---@param line string: current line that will be appended +---@param picker table: the current picker object +---@param no_reset boolean: On default it will reset the state at the end. If you don't want to do this set to true +function histories.History:append(line, picker, no_reset) + if not self.enabled then return end + self._append(self, line, picker, no_reset) +end + +--- Will return the next history item. Can be nil if there are no next items +---@param line string: the current line +---@param picker table: the current picker object +---@return string: the next history item +function histories.History:get_next(line, picker) + if not self.enabled then + print("You are cycling to next the history item but history is disabled.", + "Read ':help telescope.defaults.history'") + return false + end + if self._pre_get then self._pre_get(self, line, picker) end + + local next_idx = self.index + 1 + if next_idx <= #self.content then + self.index = next_idx + return self.content[next_idx] + end + self.index = #self.content + 1 + return nil +end + +--- Will return the previous history item. Can be nil if there are no previous items +---@param line string: the current line +---@param picker table: the current picker object +---@return string: the previous history item +function histories.History:get_prev(line, picker) + if not self.enabled then + print("You are cycling to previous the history item but history is disabled.", + "Read ':help telescope.defaults.history'") + return false + end + if self._pre_get then self._pre_get(self, line, picker) end + + local next_idx = self.index - 1 + if self.index == #self.content + 1 then + if line ~= '' then self:append(line, picker, true) end + end + if next_idx >= 1 then + self.index = next_idx + return self.content[next_idx] + end + return nil +end + +--- A simple implementation of history. +--- +--- It will keep one unified history across all pickers. +histories.get_simple_history = function() + return histories.new({ + init = function(obj) + local p = Path:new(obj.path) + if not p:exists() then p:touch({ parents = true }) end + + obj.content = Path:new(obj.path):readlines() + obj.index = #obj.content + table.remove(obj.content, obj.index) + end, + reset = function(self) + self.index = #self.content + 1 + end, + append = function(self, line, _, no_reset) + if line ~= '' then + if self.content[#self.content] ~= line then + table.insert(self.content, line) + + local len = #self.content + if self.limit and len > self.limit then + local diff = len - self.limit + for i = diff, 1, -1 do + table.remove(self.content, i) + end + write_async(self.path, table.concat(self.content, '\n') .. '\n', 'w') + else + append_async(self.path, line .. '\n') + end + end + end + if not no_reset then + self:reset() + end + end, + }) +end + +return histories diff --git a/lua/telescope/actions/init.lua b/lua/telescope/actions/init.lua index bf45bb3..8ca96c7 100644 --- a/lua/telescope/actions/init.lua +++ b/lua/telescope/actions/init.lua @@ -196,21 +196,53 @@ function actions.center(_) vim.cmd(':normal! zz') end -function actions.select_default(prompt_bufnr) - return action_set.select(prompt_bufnr, "default") -end +actions.select_default = { + pre = function(prompt_bufnr) + action_state.get_current_history():append( + action_state.get_current_line(), + action_state.get_current_picker(prompt_bufnr) + ) + end, + action = function(prompt_bufnr) + return action_set.select(prompt_bufnr, "default") + end +} -function actions.select_horizontal(prompt_bufnr) - return action_set.select(prompt_bufnr, "horizontal") -end +actions.select_horizontal = { + pre = function(prompt_bufnr) + action_state.get_current_history():append( + action_state.get_current_line(), + action_state.get_current_picker(prompt_bufnr) + ) + end, + action = function(prompt_bufnr) + return action_set.select(prompt_bufnr, "horizontal") + end +} -function actions.select_vertical(prompt_bufnr) - return action_set.select(prompt_bufnr, "vertical") -end +actions.select_vertical = { + pre = function(prompt_bufnr) + action_state.get_current_history():append( + action_state.get_current_line(), + action_state.get_current_picker(prompt_bufnr) + ) + end, + action = function(prompt_bufnr) + return action_set.select(prompt_bufnr, "vertical") + end +} -function actions.select_tab(prompt_bufnr) - return action_set.select(prompt_bufnr, "tab") -end +actions.select_tab = { + pre = function(prompt_bufnr) + action_state.get_current_history():append( + action_state.get_current_line(), + action_state.get_current_picker(prompt_bufnr) + ) + end, + action = function(prompt_bufnr) + return action_set.select(prompt_bufnr, "tab") + end +} -- TODO: consider adding float! -- https://github.com/nvim-telescope/telescope.nvim/issues/365 @@ -238,6 +270,7 @@ function actions.close_pum(_) end actions._close = function(prompt_bufnr, keepinsert) + action_state.get_current_history():reset() local picker = action_state.get_current_picker(prompt_bufnr) local prompt_win = state.get_status(prompt_bufnr).prompt_win local original_win_id = picker.original_win_id @@ -695,6 +728,33 @@ actions.complete_tag = function(prompt_bufnr) end +actions.cycle_history_next = function(prompt_bufnr) + local history = action_state.get_current_history() + local current_picker = actions.get_current_picker(prompt_bufnr) + local line = action_state.get_current_line() + + local entry = history:get_next(line, current_picker) + if entry == false then return end + + current_picker:reset_prompt() + if entry ~= nil then + current_picker:set_prompt(entry) + end +end + +actions.cycle_history_prev = function(prompt_bufnr) + local history = action_state.get_current_history() + local current_picker = actions.get_current_picker(prompt_bufnr) + local line = action_state.get_current_line() + + local entry = history:get_prev(line, current_picker) + if entry == false then return end + if entry ~= nil then + current_picker:reset_prompt() + current_picker:set_prompt(entry) + end +end + --- Open the quickfix list actions.open_qflist = function(_) vim.cmd [[copen]] diff --git a/lua/telescope/actions/mt.lua b/lua/telescope/actions/mt.lua index 5efeddf..7f233cf 100644 --- a/lua/telescope/actions/mt.lua +++ b/lua/telescope/actions/mt.lua @@ -19,6 +19,9 @@ action_mt.create = function(mod) __call = function(t, ...) local values = {} for _, action_name in ipairs(t) do + if t._static_pre[action_name] then + t._static_pre[action_name](...) + end if t._pre[action_name] then t._pre[action_name](...) end @@ -34,6 +37,9 @@ action_mt.create = function(mod) table.insert(values, res) end + if t._static_post[action_name] then + t._static_post[action_name](...) + end if t._post[action_name] then t._post[action_name](...) end @@ -55,8 +61,10 @@ action_mt.create = function(mod) return setmetatable(new_actions, getmetatable(lhs)) end, + _static_pre = {}, _pre = {}, _replacements = {}, + _static_post = {}, _post = {}, } @@ -119,8 +127,14 @@ action_mt.create = function(mod) return mt end -action_mt.transform = function(k, mt) - return setmetatable({k}, mt) +action_mt.transform = function(k, mt, mod, v) + local res = setmetatable({k}, mt) + if type(v) == "table" then + res._static_pre[k] = v.pre + res._static_post[k] = v.post + mod[k] = v.action + end + return res end action_mt.transform_mod = function(mod) @@ -130,8 +144,8 @@ action_mt.transform_mod = function(mod) -- This allows for custom errors, lookups, etc. local redirect = setmetatable({}, getmetatable(mod) or {}) - for k, _ in pairs(mod) do - redirect[k] = action_mt.transform(k, mt) + for k, v in pairs(mod) do + redirect[k] = action_mt.transform(k, mt, mod, v) end redirect._clear = mt.clear diff --git a/lua/telescope/actions/set.lua b/lua/telescope/actions/set.lua index 5b39c54..e790e34 100644 --- a/lua/telescope/actions/set.lua +++ b/lua/telescope/actions/set.lua @@ -48,6 +48,20 @@ action_set.select = function(prompt_bufnr, type) return action_set.edit(prompt_bufnr, action_state.select_key_to_edit_key(type)) end +-- goal: currently we have a workaround in actions/init.lua where we do this for all files +-- action_set.select = { +-- -- Will not be called if `select_default` is replaced rather than `action_set.select` because we never get here +-- pre = function(prompt_bufnr) +-- action_state.get_current_history():append( +-- action_state.get_current_line(), +-- action_state.get_current_picker(prompt_bufnr) +-- ) +-- end, +-- action = function(prompt_bufnr, type) +-- return action_set.edit(prompt_bufnr, action_state.select_key_to_edit_key(type)) +-- end +-- } + local edit_buffer do local map = { diff --git a/lua/telescope/actions/state.lua b/lua/telescope/actions/state.lua index 7ef9f6c..8470f2d 100644 --- a/lua/telescope/actions/state.lua +++ b/lua/telescope/actions/state.lua @@ -7,6 +7,7 @@ ---@brief ]] local global_state = require('telescope.state') +local conf = require('telescope.config').values local action_state = {} @@ -36,4 +37,19 @@ function action_state.select_key_to_edit_key(type) return select_to_edit_map[type] end +function action_state.get_current_history() + local history = global_state.get_global_key("history") + if not history then + if not conf.history or type(conf.history) ~= "table" then + history = require('telescope.actions.history').get_simple_history() + global_state.set_global_key("history", history) + else + history = conf.history.handler() + global_state.set_global_key("history", history) + end + end + + return history +end + return action_state diff --git a/lua/telescope/config.lua b/lua/telescope/config.lua index dd3d453..00d4101 100644 --- a/lua/telescope/config.lua +++ b/lua/telescope/config.lua @@ -2,6 +2,7 @@ local strings = require "plenary.strings" local deprecated = require "telescope.deprecated" local sorters = require "telescope.sorters" local if_nil = vim.F.if_nil +local os_sep = require("plenary.path").path.sep -- Keep the values around between reloads _TelescopeConfigurationValues = _TelescopeConfigurationValues or {} @@ -206,15 +207,48 @@ local telescope_defaults = { end, }, - dynamic_preview_title = { - false, - [[ + dynamic_preview_title = { false, [[ Will change the title of the preview window dynamically, where it is supported. Means the preview window will for example show the full filename. - Default: false - ]], + Default: false]], + }, + + history = { { + path = vim.fn.stdpath("data") .. os_sep .. "telescope_history", + limit = 100, + handler = function(...) return require('telescope.actions.history').get_simple_history(...) end, + }, [[ + This field handles the configuration for prompt history. + By default it is a table, with default values (more below). + To disable history, set it to either false or nil. + + Currently mappings still need to be added, Example: + mappings = { + i = { + [""] = require('telescope.actions').cycle_history_next, + [""] = require('telescope.actions').cycle_history_prev, + }, + }, + + Fields: + - path: The path to the telescope history as string. + default: stdpath("data")/telescope_history + - limit: The amount of entries that will be written in the + history. + Warning: If limit is set to nil it will grown unbound. + default: 100 + - handler: A lua function that implements the history. + This is meant as a developer setting for extensions to + override the history handling, e.g., + https://github.com/nvim-telescope/telescope-smart-history.nvim, + which allows context sensitive (cwd + picker) history. + + Default: + require('telescope.actions.history').get_simple_history + ]], + }, -- Builtin configuration @@ -346,6 +380,16 @@ function config.set_defaults(user_defaults, tele_defaults) vim.tbl_deep_extend("keep", if_nil(config.values[name], {}), if_nil(default_val, {})) ) end + if name == "history" then + if not user_defaults[name] or not config.values[name] then + return false + end + + return smarter_depth_2_extend( + if_nil(user_defaults[name], {}), + vim.tbl_deep_extend("keep", if_nil(config.values[name], {}), if_nil(default_val, {})) + ) + end return first_non_null(user_defaults[name], config.values[name], default_val) end diff --git a/lua/telescope/pickers.lua b/lua/telescope/pickers.lua index a60d2df..449d869 100644 --- a/lua/telescope/pickers.lua +++ b/lua/telescope/pickers.lua @@ -473,7 +473,7 @@ function Picker:find() pcall(a.nvim_buf_set_option, prompt_bufnr, 'filetype', 'TelescopePrompt') if self.default_text then - vim.api.nvim_buf_set_lines(prompt_bufnr, 0, 1, false, {self.default_text}) + self:set_prompt(self.default_text) end if self.initial_mode == "insert" then @@ -544,6 +544,11 @@ function Picker:delete_selection(delete_cb) end) end +function Picker:set_prompt(str) + -- TODO(conni2461): As soon as prompt_buffers are fix use this: + -- vim.api.nvim_buf_set_lines(self.prompt_bufnr, 0, 1, false, { str }) + vim.api.nvim_feedkeys(str, 'n', false) +end function Picker.close_windows(status) local prompt_win = status.prompt_win diff --git a/scripts/gendocs.lua b/scripts/gendocs.lua index 1533bd5..5f04727 100644 --- a/scripts/gendocs.lua +++ b/scripts/gendocs.lua @@ -11,20 +11,17 @@ docs.test = function() local input_files = { "./lua/telescope/init.lua", "./lua/telescope/builtin/init.lua", + "./lua/telescope/themes.lua", "./lua/telescope/pickers/layout_strategies.lua", + "./lua/telescope/config/resolve.lua", "./lua/telescope/actions/init.lua", "./lua/telescope/actions/state.lua", "./lua/telescope/actions/set.lua", "./lua/telescope/actions/utils.lua", "./lua/telescope/previewers/init.lua", - "./lua/telescope/config/resolve.lua", - "./lua/telescope/themes.lua", + "./lua/telescope/actions/history.lua", } - table.sort(input_files, function(a, b) - return #a < #b - end) - local output_file = "./doc/telescope.txt" local output_file_handle = io.open(output_file, "w")