diff --git a/doc/telescope.txt b/doc/telescope.txt index e69de29..9560042 100644 --- a/doc/telescope.txt +++ b/doc/telescope.txt @@ -0,0 +1,701 @@ +================================================================================ + *telescope.nvim* + +Telescope.nvim is a plugin for fuzzy finding and neovim. It helps you search, +filter, find and pick things in Lua. + +To find out more: +https://github.com/nvim-telescope/telescope.nvim + + :h telescope.setup + :h telescope.builtin + :h telescope.layout + :h telescope.actions + +telescope.setup({opts}) *telescope.setup()* + Setup function to be run by user. Configures the defaults, extensions and + other aspects of telescope. + + + Valid keys for {opts.defaults} + + *telescope.defaults.entry_prefix* + entry_prefix: ~ + Prefix in front of each result entry. Current selection not included. + + Default: ' ' + + *telescope.defaults.prompt_prefix* + prompt_prefix: ~ + Will be shown in front of the prompt. + + Default: '> ' + + *telescope.defaults.scroll_strategy* + scroll_strategy: ~ + Determines what happens you try to scroll past view of the picker. + + Available options are: + - "cycle" (default) + - "limit" + + *telescope.defaults.selection_caret* + selection_caret: ~ + Will be shown in front of the selection. + + Default: '> ' + + *telescope.defaults.selection_strategy* + selection_strategy: ~ + Determines how the cursor acts after each sort iteration. + + Available options are: + - "reset" (default) + - "follow" + - "row" + + *telescope.defaults.sorting_strategy* + sorting_strategy: ~ + Determines the direction "better" results are sorted towards. + + Available options are: + - "descending" (default) + - "ascending" + + Parameters: ~ + {opts} (table) Configuration opts. Keys: defaults, extensions + + +telescope.register_extension({mod}) *telescope.register_extension()* + Register an extension. To be used by plugin authors. + + + Parameters: ~ + {mod} (table) Module + + +telescope.load_extension({name}) *telescope.load_extension()* + Load an extension. + + + Parameters: ~ + {name} (string) Name of the extension + + +telescope.extensions() *telescope.extensions()* + Use telescope.extensions to reference any extensions within your + configuration. + While the docs currently generate this as a function, it's actually a + table. Sorry. + + + + +================================================================================ + *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. + +The first two arguments of all action sets are: function(prompt_bufnr, context, +...) + + +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. + +All actions follow the same signature: function(prompt_bufnr, context) + +prompt_bufnr: The bufnr for the prompt context: Table, Valid keys: index: The +multi-selection index, if applicable entry: The entry to perform the action on. + + +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_default() *actions.select_default()* + THIS DOESNT ACTUALLY EXIST YET + + + +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_checkout({prompt_bufnr}) *actions.git_checkout()* + Checkout an existing git branch + + + 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.send_selected_to_qflist() *actions.send_selected_to_qflist()* + TODO: These would be good candidates for thinking about how to add them one + at a time OR with the list of items. + + Very cool + + + +actions.open_qflist() *actions.open_qflist()* + Open the quickfix list + + + + +================================================================================ + *telescope.builtin* + +A collection of builtin pickers for telescope. + +Meant for both example and for easy startup. + +Any of these functions can just be called directly by doing: + +:lua require('telescope.builtin').$NAME() + +This will use the default configuration options. Other configuration options +are still in flux at the moment + +builtin.live_grep() *builtin.live_grep()* + Live grep means grep as you type. + + + + +================================================================================ + *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() *action_state.get_current_picker()* + Gets the current picker + + + + +================================================================================ + *telescope.previewers* + +Provides a Previewer table that has to be implemented by each previewer. To +achieve this, this module also provides two wrappers that abstract most of the +work and make it really easy create new previewers. + - `previewers.new_termopen_previewer` + - `previewers.new_buffer_previewer` + +Furthermore, there are a collection of previewers already defined which can be +used for every picker, as long as the entries of the picker provide the +necessary fields. The more important once are + - `previewers.cat` + - `previewers.vimgrep` + - `previewers.qflist` + - `previewers.vim_buffer_cat` + - `previewers.vim_buffer_vimgrep` + - `previewers.vim_buffer_qflist` + +Previewers can be disabled for any builtin or custom picker by doing :Telescope +find_files previewer=false + +previewers.Previewer() *previewers.Previewer()* + This is the base table all previewers have to implement. It's possible to + write a wrapper for this because most previewers need to have the same keys + set. Examples of wrappers are: + - `new_buffer_previewer` + - `new_termopen_previewer` + + To create a new table do following: + - `local new_previewer = Previewer:new(opts)` + + What `:new` expects is listed below + + The interface provides following set of functions. All of them, besides + `new`, will be handled by telescope pickers. + - `:new(opts)` + - `:preview(entry, status)` + - `:teardown()` + - `:send_input(input)` + - `:scroll_fn(direction)` + + `Previewer:new()` expects a table as input with following keys: + - `setup` function(self): Will be called the first time preview will be + called. + - `teardown` function(self): Will be called on cleanup. + - `preview_fn` function(self, entry, status): Will be called each time a + new entry was selected. + - `send_input` function(self, input): This is meant for + `termopen_previewer` and it can be used to send input to the terminal + application, like less. + - `scroll_fn` function(self, direction): Used to make scrolling work. + + + +previewers.new() *previewers.new()* + A shorthand for creating a new Previewer. The provided table will be + forwarded to `Previewer:new(...)` + + + +previewers.new_termopen_previewer() *previewers.new_termopen_previewer()* + Is a wrapper around Previewer and helps with creating a new + `termopen_previewer`. + + It requires you to specify one table entry `get_command(entry, status)`. + This `get_command` function has to return the terminal command that will be + executed for each entry. Example: + get_command = function(entry, status) + return { 'bat', entry.path } + end + + It's an easy way to get your first previewer going and it integrates well + with `bat` and `less`. Providing out of the box scrolling if the command + uses less. + + Furthermore, it will forward all `config.set_env` environment variables to + that terminal process. + + While this interface is a good start, it was replaced with the way more + flexible `buffer_previewer` and is now deprecated. + + + +previewers.cat() *previewers.cat()* + Provides a `termopen_previewer` which has the ability to display files. It + will always show the top of the file and has support for `bat`(prioritized) + and `cat`. Each entry has to provide either the field `path` or `filename` + in order to make this previewer work. + + The preferred way of using this previewer is like this + `require('telescope.config').values.cat_previewer` This will respect user + configuration and will use `buffer_previewers` in case it's configured that + way. + + + +previewers.vimgrep() *previewers.vimgrep()* + Provides a `termopen_previewer` which has the ability to display files at + the provided line. It has support for `bat`(prioritized) and `cat`. Each + entry has to provide either the field `path` or `filename` and a `lnum` + field in order to make this previewer work. + + The preferred way of using this previewer is like this + `require('telescope.config').values.grep_previewer` This will respect user + configuration and will use `buffer_previewers` in case it's configured that + way. + + + +previewers.qflist() *previewers.qflist()* + Provides a `termopen_previewer` which has the ability to display files at + the provided line or range. It has support for `bat`(prioritized) and + `cat`. Each entry has to provide either the field `path` or `filename`, + `lnum` and a `start` and `finish` range in order to make this previewer + work. + + The preferred way of using this previewer is like this + `require('telescope.config').values.qflist_previewer` This will respect + user configuration and will use buffer previewers in case it's configured + that way. + + + +previewers.new_buffer_previewer() *previewers.new_buffer_previewer()* + An interface to instantiate a new `buffer_previewer`. That means that the + content actually lives inside a vim buffer which enables us more control + over the actual content. For example, we can use `vim.fn.search` to jump to + a specific line or reuse buffers/already opened files more easily. This + interface is more complex than `termopen_previewer` but offers more + flexibility over your content. It was designed to display files but was + extended to also display the output of terminal commands. + + In the following options, state table and general tips are mentioned to + make your experience with this previewer more seamless. + + + options: + - `define_preview = function(self, entry, status)` (required) Is called + for each selected entry, after each selection_move (up or down) and is + meant to handle things like reading file, jump to line or attach a + highlighter. + - `setup = function(self)` (optional) Is called once at the beginning, + before the preview for the first entry is displayed. You can return a + table of vars that will be available in `self.state` in each + `define_preview` call. + - `teardown = function(self)` (optional) Will be called at the end, when + the picker is being closed and is meant to cleanup everything that was + allocated by the previewer. The `buffer_previewer` will automatically + cleanup all created buffers. So you only need to handle things that + were introduced by you. + - `keep_last_buf = true` (optional) Will not delete the last selected + buffer. This would allow you to reuse that buffer in the select action. + For example, that buffer can be opened in a new split, rather than + recreating that buffer in an action. To access the last buffer number: + `require('telescope.state').get_global_key("last_preview_bufnr")` + - `get_buffer_by_name = function(self, entry)` Allows you to set a unique + name for each buffer. This is used for caching purpose. + `self.state.bufname` will be nil if the entry was never loaded or the + unique name when it was loaded once. For example, useful if you have + one file but multiple entries. This happens for grep and lsp builtins. + So to make the cache work only load content if `self.state.bufname ~= + entry.your_unique_key` + + `self.state` table: + - `self.state.bufnr` Is the current buffer number, in which you have to + write the loaded content. Don't create a buffer yourself, otherwise + it's not managed by the buffer_previewer interface and you will + probably be better off writing your own interface. + - self.state.winid Current window id. Useful if you want to set the + cursor to a provided line number. + - self.state.bufname Will return the current buffer name, if + `get_buffer_by_name` is defined. nil will be returned if the entry was + never loaded or when `get_buffer_by_name` is not set. + + Tips: + - If you want to display content of a terminal job, use: + `require('telescope.previewers.utils').job_maker(cmd, bufnr, opts)` + - `cmd` table: for example { 'git', 'diff', entry.value } + - `bufnr` number: in which the content will be written + - `opts` table: with following keys + - `bufname` string: used for cache + - `value` string: used for cache + - `mode` string: either "insert" or "append". "insert" is default + - `env` table: define environment variables. Example: + - `{ ['PAGER'] = '', ['MANWIDTH'] = 50 }` + - `cwd` string: define current working directory for job + - `callback` function(bufnr, content): will be called when job is + done. Content will be nil if job is already loaded. So you can do + highlighting only the first time the previewer is created for + that entry. Use the returned `bufnr` and not `self.state.bufnr` + in callback, because state can already be changed at this point + in time. + - If you want to attach a highlighter use: + - `require('telescope.previewers.utils').highlighter(bufnr, ft)` + - This will prioritize tree sitter highlighting if available for + environment and language. + - `require('telescope.previewers.utils').regex_highlighter(bufnr, ft)` + - `require('telescope.previewers.utils').ts_highlighter(bufnr, ft)` + - If you want to use `vim.fn.search` or similar you need to run it in + that specific buffer context. Do + vim.api.nvim_buf_call(bufnr, function() + -- for example `search` and `matchadd` + end) + to achieve that. + - If you want to read a file into the buffer it's best to use + `buffer_previewer_maker`. But access this function with + `require('telescope.config').values.buffer_previewer_maker` because it + can be redefined by users. + + + +previewers.buffer_previewer_maker({filepath}, {bufnr}, {opts})*previewers.buffer_previewer_maker()* + A universal way of reading a file into a buffer previewer. It handles async + reading, cache, highlighting, displaying directories and provides a + callback which can be used, to jump to a line in the buffer. + + + Parameters: ~ + {filepath} (string) String to the filepath, will be expanded + {bufnr} (number) Where the content will be written + {opts} (table) keys: `use_ft_detect`, `bufname` and `callback` + + +previewers.vim_buffer_cat() *previewers.vim_buffer_cat()* + A previewer that is used to display a file. It uses the `buffer_previewer` + interface and won't jump to the line. To integrate this one into your own + picker make sure that the field `path` or `filename` is set for each entry. + The preferred way of using this previewer is like this + `require('telescope.config').values.file_previewer` This will respect user + configuration and will use `termopen_previewer` in case it's configured + that way. + + + +previewers.vim_buffer_vimgrep() *previewers.vim_buffer_vimgrep()* + A previewer that is used to display a file and jump to the provided line. + It uses the `buffer_previewer` interface. To integrate this one into your + own picker make sure that the field `path` or `filename` and `lnum` is set + in each entry. If the latter is not present, it will default to the first + line. The preferred way of using this previewer is like this + `require('telescope.config').values.grep_previewer` This will respect user + configuration and will use `termopen_previewer` in case it's configured + that way. + + + +previewers.vim_buffer_qflist() *previewers.vim_buffer_qflist()* + Is the same as `vim_buffer_vimgrep` and only exist for consistency with + `term_previewers`. + + The preferred way of using this previewer is like this + `require('telescope.config').values.qflist_previewer` This will respect + user configuration and will use `termopen_previewer` in case it's + configured that way. + + + +previewers.display_content() *previewers.display_content()* + A deprecated way of displaying content more easily. Was written at a time, + where the buffer_previewer interface wasn't present. Nowadays it's easier + to just use this. We will keep it around for backwards compatibility + because some extensions use it. It doesn't use cache or some other clever + tricks. + + + + +================================================================================ + *telescope.layout* + +Layout strategies are different functions to position telescope. + +All layout strategies are functions with the following signature: + + function(picker, columns, lines) + -- 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 + + +TODO: I would like to make these link to `telescope.layout_strategies.*`, but +it's not yet possible. + +Available layout strategies include: + - horizontal: + - See |layout_strategies.horizontal| + + - vertical: + - See |layout_strategies.vertical| + + - flex: + - See |layout_strategies.flex| + +Available tweaks to the settings in layout defaults include (can be applied to +horizontal and vertical layouts): + - mirror (default is `false`): + - Flip the view of the current layout: + - If using horizontal: if `true`, swaps the location of the + results/prompt window and preview window + - If using vertical: if `true`, swaps the location of the results and + prompt windows + + - width_padding: + - How many cells to pad the width of Telescope's layout window + + - height_padding: + - How many cells to pad the height of Telescope's layout window + + - preview_width: + - Change the width of Telescope's preview window + + - scroll_speed: + - Change the scrolling speed of the previewer + +layout_strategies.horizontal() *layout_strategies.horizontal()* + Horizontal previewer + + +-------------+--------------+ + | | | + | Results | | + | | Preview | + | | | + +-------------| | + | Prompt | | + +-------------+--------------+ + + + +layout_strategies.center() *layout_strategies.center()* + Centered layout wih smaller default sizes (I think) + + +--------------+ + | Preview | + +--------------+ + | Prompt | + +--------------+ + | Result | + | Result | + | Result | + +--------------+ + + + +layout_strategies.vertical() *layout_strategies.vertical()* + Vertical perviewer stacks the items on top of each other. + + +-----------------+ + | Previewer | + | Previewer | + | Previewer | + +-----------------+ + | Result | + | Result | + | Result | + +-----------------+ + | Prompt | + +-----------------+ + + + +layout_strategies.flex() *layout_strategies.flex()* + Swap between `horizontal` and `vertical` strategies based on the window + width + - Supports `vertical` or `horizontal` features + + Uses: + - flip_columns + - flip_lines + + + + + vim:tw=78:ts=8:ft=help:norl: