From 440684edad0b56cb746c1f1aaef6a53aa703b2ce Mon Sep 17 00:00:00 2001 From: Ben Smith Date: Wed, 18 May 2022 18:27:06 +0000 Subject: break(git_files): change show_untracked default to false (#842) --- doc/telescope.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/telescope.txt b/doc/telescope.txt index 42f8da1..b79006b 100644 --- a/doc/telescope.txt +++ b/doc/telescope.txt @@ -977,7 +977,7 @@ builtin.git_files({opts}) *telescope.builtin.git_files()* (default: true) {show_untracked} (boolean) if true, adds `--others` flag to command and shows untracked files - (default: true) + (default: false) {recurse_submodules} (boolean) if true, adds the `--recurse-submodules` flag to command (default: false) -- cgit v1.2.3 From edc6f55ba2565930310542b3023f00e88dd3e6a8 Mon Sep 17 00:00:00 2001 From: Simon Hauser Date: Sun, 22 May 2022 11:32:55 +0200 Subject: docs: document limitations of file_ignore_patterns and transform_path (#1955) --- doc/telescope.txt | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) (limited to 'doc') diff --git a/doc/telescope.txt b/doc/telescope.txt index b79006b..0b769ee 100644 --- a/doc/telescope.txt +++ b/doc/telescope.txt @@ -655,6 +655,17 @@ telescope.setup({opts}) *telescope.setup()* Example: { "%.npz" } -- ignore all npz files See: https://www.lua.org/manual/5.1/manual.html#5.4.1 for more information about lua regex + Note: `file_ignore_patterns` will be used in all pickers that have a + file associated. This might lead to the problem that lsp_ pickers + aren't displaying results because they might be ignored by + `file_ignore_patterns`. For example, setting up node_modules as ignored + will never show node_modules in any results, even if you are + interested in lsp_ results. + + If you only want `file_ignore_patterns` for `find_files` and + `grep_string`/`live_grep` it is suggested that you setup `gitignore` + and have fd and or ripgrep installed because both tools will not show + `gitignore`d files on default. Default: nil @@ -1944,6 +1955,39 @@ resolver.resolve_anchor_pos() *telescope.resolve.resolve_anchor_pos()* +================================================================================ + *telescope.utils* + +Utilities for writing telescope pickers + +utils.transform_path({opts}, {path}) *telescope.utils.transform_path()* + Transform path is a util function that formats a path based on path_display + found in `opts` or the default value from config. It is meant to be used in + make_entry to have a uniform interface for builtins as well as extensions + utilizing the same user configuration Note: It is only supported inside + `make_entry`/`make_display` the use of this function outside of telescope + might yield to undefined behavior and will not be addressed by us + + + Parameters: ~ + {opts} (table) The opts the users passed into the picker. Might + contains a path_display key + {path} (string) The path that should be formated + + Return: ~ + string: The transformed path ready to be displayed + + +utils.notify({funname}, {opts}) *telescope.utils.notify()* + Telescope Wrapper around vim.notify + + + Parameters: ~ + {funname} (string) name of the function that will be + {opts} (table) opts.level string, opts.msg string, opts.once bool + + + ================================================================================ *telescope.actions* -- cgit v1.2.3 From a1aec79cb1abc5630f941bafbe83f6e00dcff316 Mon Sep 17 00:00:00 2001 From: fdschmidt93 <39233597+fdschmidt93@users.noreply.github.com> Date: Sun, 22 May 2022 12:08:07 +0200 Subject: feat: none strategy & control attachment (#1867) --- doc/telescope.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'doc') diff --git a/doc/telescope.txt b/doc/telescope.txt index 0b769ee..43a5ccc 100644 --- a/doc/telescope.txt +++ b/doc/telescope.txt @@ -142,6 +142,7 @@ telescope.setup({opts}) *telescope.setup()* - "follow" - "row" - "closest" + - "none" *telescope.defaults.scroll_strategy* scroll_strategy: ~ -- cgit v1.2.3 From 8488cd5ac7a5c5b99773b5b8de5723ce4cedc796 Mon Sep 17 00:00:00 2001 From: Jeremy Neal Date: Mon, 6 Jun 2022 08:06:34 -0400 Subject: feat: no-ignore-parent shorthand option for find_files. (#1963) --- doc/telescope.txt | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) (limited to 'doc') diff --git a/doc/telescope.txt b/doc/telescope.txt index 43a5ccc..9f3b339 100644 --- a/doc/telescope.txt +++ b/doc/telescope.txt @@ -878,19 +878,22 @@ builtin.find_files({opts}) *telescope.builtin.find_files()* {opts} (table) options to pass to the picker Options: ~ - {cwd} (string) root dir to search from (default: cwd, use - utils.buffer_dir() to search relative to - open buffer) - {find_command} (table) command line arguments for `find_files` to - use for the search, overrides default: - config - {follow} (boolean) if true, follows symlinks (i.e. uses `-L` - flag for the `find` command) - {hidden} (boolean) determines whether to show hidden files or - not (default: false) - {no_ignore} (boolean) show files ignored by .gitignore, .ignore, - etc. (default: false) - {search_dirs} (table) directory/directories to search in + {cwd} (string) root dir to search from (default: cwd, + use utils.buffer_dir() to search + relative to open buffer) + {find_command} (table) command line arguments for `find_files` + to use for the search, overrides + default: config + {follow} (boolean) if true, follows symlinks (i.e. uses + `-L` flag for the `find` command) + {hidden} (boolean) determines whether to show hidden files + or not (default: false) + {no_ignore} (boolean) show files ignored by .gitignore, + .ignore, etc. (default: false) + {no_ignore_parent} (boolean) show files ignored by .gitignore, + .ignore, etc. in parent dirs. (default: + false) + {search_dirs} (table) directory/directories to search in builtin.fd() *telescope.builtin.fd()* -- cgit v1.2.3 From 6703c957e7d9a5dc5f91ceb59326ab7e05274642 Mon Sep 17 00:00:00 2001 From: Bjarki Baldursson Harksen <62466569+mrbjarksen@users.noreply.github.com> Date: Sun, 12 Jun 2022 11:08:30 +0000 Subject: feat: add option `use_default_opts` to `builtin.builtin` (#1996) --- doc/telescope.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'doc') diff --git a/doc/telescope.txt b/doc/telescope.txt index 9f3b339..f0f78ef 100644 --- a/doc/telescope.txt +++ b/doc/telescope.txt @@ -1112,6 +1112,8 @@ builtin.builtin({opts}) *telescope.builtin.builtin()* Options: ~ {include_extensions} (boolean) if true will show the pickers of the installed extensions (default: false) + {use_default_opts} (boolean) if the selected picker should use its + default options (default: false) builtin.resume({opts}) *telescope.builtin.resume()* -- cgit v1.2.3 From 838c32d6a86c8a4b8f3333f66e797f7cad2e3c1b Mon Sep 17 00:00:00 2001 From: Yorick Peterse Date: Sun, 12 Jun 2022 20:29:10 +0800 Subject: refactor: make_entry more consistent (#1410) drops `ignore_filename`, use `path_display= { "hidden" }` Co-authored-by: Simon Hauser --- doc/telescope.txt | 68 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 38 insertions(+), 30 deletions(-) (limited to 'doc') diff --git a/doc/telescope.txt b/doc/telescope.txt index f0f78ef..8d90dc2 100644 --- a/doc/telescope.txt +++ b/doc/telescope.txt @@ -1195,9 +1195,11 @@ builtin.quickfix({opts}) *telescope.builtin.quickfix()* {opts} (table) options to pass to the picker Options: ~ - {ignore_filename} (boolean) dont show filenames (default: true) - {trim_text} (boolean) trim results text (default: false) - {nr} (number) specify the quickfix list number + {show_line} (boolean) show results text (default: true) + {trim_text} (boolean) trim results text (default: false) + {fname_width} (number) defines the width of the filename section + (default: 30) + {nr} (number) specify the quickfix list number builtin.quickfixhistory({opts}) *telescope.builtin.quickfixhistory()* @@ -1219,8 +1221,10 @@ builtin.loclist({opts}) *telescope.builtin.loclist()* {opts} (table) options to pass to the picker Options: ~ - {ignore_filename} (boolean) dont show filenames (default: true) - {trim_text} (boolean) trim results text (default: false) + {show_line} (boolean) show results text (default: true) + {trim_text} (boolean) trim results text (default: false) + {fname_width} (number) defines the width of the filename section + (default: 30) builtin.oldfiles({opts}) *telescope.builtin.oldfiles()* @@ -1419,8 +1423,10 @@ builtin.tagstack({opts}) *telescope.builtin.tagstack()* {opts} (table) options to pass to the picker Options: ~ - {ignore_filename} (boolean) dont show filenames (default: true) - {trim_text} (boolean) trim results text (default: false) + {show_line} (boolean) show results text (default: true) + {trim_text} (boolean) trim results text (default: false) + {fname_width} (number) defines the width of the filename section + (default: 30) builtin.jumplist({opts}) *telescope.builtin.jumplist()* @@ -1431,8 +1437,10 @@ builtin.jumplist({opts}) *telescope.builtin.jumplist()* {opts} (table) options to pass to the picker Options: ~ - {ignore_filename} (boolean) dont show filenames (default: true) - {trim_text} (boolean) trim results text (default: false) + {show_line} (boolean) show results text (default: true) + {trim_text} (boolean) trim results text (default: false) + {fname_width} (number) defines the width of the filename section + (default: 30) builtin.lsp_references({opts}) *telescope.builtin.lsp_references()* @@ -1449,6 +1457,8 @@ builtin.lsp_references({opts}) *telescope.builtin.lsp_references()* {include_current_line} (boolean) include current line (default: false) {trim_text} (boolean) trim results text (default: false) + {fname_width} (number) defines the width of the filename + section (default: 30) builtin.lsp_definitions({opts}) *telescope.builtin.lsp_definitions()* @@ -1460,11 +1470,12 @@ builtin.lsp_definitions({opts}) *telescope.builtin.lsp_definitions()* {opts} (table) options to pass to the picker Options: ~ - {jump_type} (string) how to goto definition if there is only - one, values: "tab", "split", "vsplit", - "never" - {ignore_filename} (boolean) dont show filenames (default: true) - {trim_text} (boolean) trim results text (default: false) + {jump_type} (string) how to goto definition if there is only one, + values: "tab", "split", "vsplit", "never" + {show_line} (boolean) show results text (default: true) + {trim_text} (boolean) trim results text (default: false) + {fname_width} (number) defines the width of the filename section + (default: 30) builtin.lsp_type_definitions({opts}) *telescope.builtin.lsp_type_definitions()* @@ -1476,11 +1487,12 @@ builtin.lsp_type_definitions({opts}) *telescope.builtin.lsp_type_definitions()* {opts} (table) options to pass to the picker Options: ~ - {jump_type} (string) how to goto definition if there is only - one, values: "tab", "split", "vsplit", - "never" - {ignore_filename} (boolean) dont show filenames (default: true) - {trim_text} (boolean) trim results text (default: false) + {jump_type} (string) how to goto definition if there is only one, + values: "tab", "split", "vsplit", "never" + {show_line} (boolean) show results text (default: true) + {trim_text} (boolean) trim results text (default: false) + {fname_width} (number) defines the width of the filename section + (default: 30) builtin.lsp_implementations({opts}) *telescope.builtin.lsp_implementations()* @@ -1492,11 +1504,13 @@ builtin.lsp_implementations({opts}) *telescope.builtin.lsp_implementations()* {opts} (table) options to pass to the picker Options: ~ - {jump_type} (string) how to goto implementation if there is - only one, values: "tab", "split", - "vsplit", "never" - {ignore_filename} (boolean) dont show filenames (default: true) - {trim_text} (boolean) trim results text (default: false) + {jump_type} (string) how to goto implementation if there is only + one, values: "tab", "split", "vsplit", + "never" + {show_line} (boolean) show results text (default: true) + {trim_text} (boolean) trim results text (default: false) + {fname_width} (number) defines the width of the filename section + (default: 30) builtin.lsp_document_symbols({opts}) *telescope.builtin.lsp_document_symbols()* @@ -1510,8 +1524,6 @@ builtin.lsp_document_symbols({opts}) *telescope.builtin.lsp_document_symbols()* {opts} (table) options to pass to the picker Options: ~ - {ignore_filename} (boolean) dont show filenames (default: - true) {show_line} (boolean) if true, shows the content of the line the tag is found on (default: false) @@ -1534,8 +1546,6 @@ builtin.lsp_workspace_symbols({opts}) *telescope.builtin.lsp_workspace_symbols() Options: ~ {query} (string) for what to query the workspace (default: "") - {ignore_filename} (boolean) dont show filenames (default: - false) {show_line} (boolean) if true, shows the content of the line the tag is found on (default: false) @@ -1556,8 +1566,6 @@ builtin.lsp_dynamic_workspace_symbols({opts}) *telescope.builtin.lsp_dynamic_wor {opts} (table) options to pass to the picker Options: ~ - {ignore_filename} (boolean) dont show filenames (default: - false) {show_line} (boolean) if true, shows the content of the line the symbol is found on (default: false) -- cgit v1.2.3 From f6efef4c4183407860618832cf9c51b20d15e96d Mon Sep 17 00:00:00 2001 From: Simon Hauser Date: Sun, 12 Jun 2022 15:37:24 +0200 Subject: feat: `find_command` can be a function (#2000) --- doc/telescope.txt | 34 ++++++++++++++++++---------------- 1 file changed, 18 insertions(+), 16 deletions(-) (limited to 'doc') diff --git a/doc/telescope.txt b/doc/telescope.txt index 8d90dc2..7fc66e2 100644 --- a/doc/telescope.txt +++ b/doc/telescope.txt @@ -878,22 +878,24 @@ builtin.find_files({opts}) *telescope.builtin.find_files()* {opts} (table) options to pass to the picker Options: ~ - {cwd} (string) root dir to search from (default: cwd, - use utils.buffer_dir() to search - relative to open buffer) - {find_command} (table) command line arguments for `find_files` - to use for the search, overrides - default: config - {follow} (boolean) if true, follows symlinks (i.e. uses - `-L` flag for the `find` command) - {hidden} (boolean) determines whether to show hidden files - or not (default: false) - {no_ignore} (boolean) show files ignored by .gitignore, - .ignore, etc. (default: false) - {no_ignore_parent} (boolean) show files ignored by .gitignore, - .ignore, etc. in parent dirs. (default: - false) - {search_dirs} (table) directory/directories to search in + {cwd} (string) root dir to search from (default: + cwd, use utils.buffer_dir() to + search relative to open buffer) + {find_command} (function|table) cmd to use for the search. Can be + a fn(opts) -> tbl (default: + autodetect) + {follow} (boolean) if true, follows symlinks (i.e. + uses `-L` flag for the `find` + command) + {hidden} (boolean) determines whether to show hidden + files or not (default: false) + {no_ignore} (boolean) show files ignored by .gitignore, + .ignore, etc. (default: false) + {no_ignore_parent} (boolean) show files ignored by .gitignore, + .ignore, etc. in parent dirs. + (default: false) + {search_dirs} (table) directory/directories to search + in builtin.fd() *telescope.builtin.fd()* -- cgit v1.2.3 From ffcc2221d63aa89665e468be1dd8cd8e40e5f581 Mon Sep 17 00:00:00 2001 From: Simon Hauser Date: Sun, 12 Jun 2022 16:02:21 +0200 Subject: docs: clarify docs around `search_dirs` and `map_entries` --- doc/telescope.txt | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) (limited to 'doc') diff --git a/doc/telescope.txt b/doc/telescope.txt index 7fc66e2..ce171f1 100644 --- a/doc/telescope.txt +++ b/doc/telescope.txt @@ -827,8 +827,8 @@ builtin.live_grep({opts}) *telescope.builtin.live_grep()* {grep_open_files} (boolean) if true, restrict search to open files only, mutually exclusive with `search_dirs` - {search_dirs} (table) directory/directories to search in, - mutually exclusive with + {search_dirs} (table) directory/directories/files to + search, mutually exclusive with `grep_open_files` {glob_pattern} (string) argument to be used with `--glob`, e.g. "*.toml", can use the opposite @@ -855,7 +855,8 @@ builtin.grep_string({opts}) *telescope.builtin.grep_string()* cwd, use utils.buffer_dir() to search relative to open buffer) {search} (string) the query to search - {search_dirs} (table) directory/directories to search in + {search_dirs} (table) directory/directories/files to + search {use_regex} (boolean) if true, special characters won't be escaped, allows for using regex (default: false) @@ -894,8 +895,8 @@ builtin.find_files({opts}) *telescope.builtin.find_files()* {no_ignore_parent} (boolean) show files ignored by .gitignore, .ignore, etc. in parent dirs. (default: false) - {search_dirs} (table) directory/directories to search - in + {search_dirs} (table) directory/directories/files to + search builtin.fd() *telescope.builtin.fd()* @@ -2830,7 +2831,8 @@ Generally used from within other |telescope.actions| utils.map_entries({prompt_bufnr}, {f}) *telescope.actions.utils.map_entries()* Apply `f` to the entries of the current picker. - Notes: - - Mapped entries may include results not visible in the results popup. + - Mapped entries include all currently filtered results, not just the + visible onces. - Indices are 1-indexed, whereas rows are 0-indexed. - Warning: `map_entries` has no return value. - The below example showcases how to collect results -- cgit v1.2.3 From 3a72cc89024120d09f32d70689cc9cbe367fc2b4 Mon Sep 17 00:00:00 2001 From: Manuel Date: Sun, 12 Jun 2022 16:06:20 +0200 Subject: feat(builtin.lsp): implement builtin handlers for lsp.(incoming|outgoing)_calls (#1484) Fixes #863 --- doc/telescope.txt | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'doc') diff --git a/doc/telescope.txt b/doc/telescope.txt index ce171f1..78cc7e4 100644 --- a/doc/telescope.txt +++ b/doc/telescope.txt @@ -1464,6 +1464,32 @@ builtin.lsp_references({opts}) *telescope.builtin.lsp_references()* section (default: 30) +builtin.lsp_incoming_calls({opts}) *telescope.builtin.lsp_incoming_calls()* + Lists LSP incoming calls for word under the cursor, jumps to reference on + `` + + + Parameters: ~ + {opts} (table) options to pass to the picker + + Options: ~ + {show_line} (boolean) show results text (default: true) + {trim_text} (boolean) trim results text (default: false) + + +builtin.lsp_outgoing_calls({opts}) *telescope.builtin.lsp_outgoing_calls()* + Lists LSP outgoing calls for word under the cursor, jumps to reference on + `` + + + Parameters: ~ + {opts} (table) options to pass to the picker + + Options: ~ + {show_line} (boolean) show results text (default: true) + {trim_text} (boolean) trim results text (default: false) + + builtin.lsp_definitions({opts}) *telescope.builtin.lsp_definitions()* Goto the definition of the word under the cursor, if there's only one, otherwise show all options in Telescope -- cgit v1.2.3 From bef86acb6c9ddf25602d28f4ad4980806f25420e Mon Sep 17 00:00:00 2001 From: Anton <14187674+antosha417@users.noreply.github.com> Date: Mon, 13 Jun 2022 19:51:48 +0300 Subject: feat(rg): pass multiple globs to rg by default (#2003) --- doc/telescope.txt | 42 ++++++++++++++++++++++-------------------- 1 file changed, 22 insertions(+), 20 deletions(-) (limited to 'doc') diff --git a/doc/telescope.txt b/doc/telescope.txt index 78cc7e4..15d957a 100644 --- a/doc/telescope.txt +++ b/doc/telescope.txt @@ -821,26 +821,28 @@ builtin.live_grep({opts}) *telescope.builtin.live_grep()* {opts} (table) options to pass to the picker Options: ~ - {cwd} (string) root dir to search from (default: - cwd, use utils.buffer_dir() to - search relative to open buffer) - {grep_open_files} (boolean) if true, restrict search to open - files only, mutually exclusive with - `search_dirs` - {search_dirs} (table) directory/directories/files to - search, mutually exclusive with - `grep_open_files` - {glob_pattern} (string) argument to be used with `--glob`, - e.g. "*.toml", can use the opposite - "!*.toml" - {type_filter} (string) argument to be used with `--type`, - e.g. "rust", see `rg --type-list` - {additional_args} (function) function(opts) which returns a table - of additional arguments to be passed - on - {max_results} (number) define a upper result value - {disable_coordinates} (boolean) don't show the line & row numbers - (default: false) + {cwd} (string) root dir to search from + (default: cwd, use + utils.buffer_dir() to search + relative to open buffer) + {grep_open_files} (boolean) if true, restrict search to open + files only, mutually exclusive + with `search_dirs` + {search_dirs} (table) directory/directories/files to + search, mutually exclusive with + `grep_open_files` + {glob_pattern} (string|table) argument to be used with + `--glob`, e.g. "*.toml", can use + the opposite "!*.toml" + {type_filter} (string) argument to be used with + `--type`, e.g. "rust", see `rg + --type-list` + {additional_args} (function) function(opts) which returns a + table of additional arguments to + be passed on + {max_results} (number) define a upper result value + {disable_coordinates} (boolean) don't show the line & row + numbers (default: false) builtin.grep_string({opts}) *telescope.builtin.grep_string()* -- cgit v1.2.3 From d1f3e12a353d4d04baa1f9096a0b720c713c37ee Mon Sep 17 00:00:00 2001 From: Simon Hauser Date: Sun, 26 Jun 2022 11:37:51 +0200 Subject: feat: add min max boundary to width, hight resolver (#2002) --- doc/telescope.txt | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) (limited to 'doc') diff --git a/doc/telescope.txt b/doc/telescope.txt index 15d957a..a12bb09 100644 --- a/doc/telescope.txt +++ b/doc/telescope.txt @@ -1947,14 +1947,17 @@ Provides "resolver functions" to allow more customisable inputs for options. resolver.resolve_height() *telescope.resolve.resolve_height()* Converts input to a function that returns the height. The input must take - one of four forms: + one of five 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`} + 4. table of the form: { val, max = ..., min = ... } + val has to be in the first form 0 <= val < 1 and only one is given, + `min` or `max` as fixed number + 5. 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}, @@ -1967,14 +1970,17 @@ resolver.resolve_height() *telescope.resolve.resolve_height()* resolver.resolve_width() *telescope.resolve.resolve_width()* Converts input to a function that returns the width. The input must take - one of four forms: + one of five 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`} + 4. table of the form: { val, max = ..., min = ... } + val has to be in the first form 0 <= val < 1 and only one is given, + `min` or `max` as fixed number + 5. 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}, -- cgit v1.2.3 From a50352eb2435a75f1d0c7af2e80133e3945fa20a Mon Sep 17 00:00:00 2001 From: Simon Hauser Date: Thu, 30 Jun 2022 14:36:41 +0200 Subject: docs: document limitation of action close #1994 --- doc/telescope.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'doc') diff --git a/doc/telescope.txt b/doc/telescope.txt index a12bb09..9903ac2 100644 --- a/doc/telescope.txt +++ b/doc/telescope.txt @@ -2380,6 +2380,8 @@ actions.edit_register({prompt_bufnr}) *telescope.actions.edit_register()* actions.paste_register({prompt_bufnr}) *telescope.actions.paste_register()* Paste the selected register into the buffer + Note: only meant to be used inside builtin.registers + Parameters: ~ {prompt_bufnr} (number) The prompt bufnr -- cgit v1.2.3 From a0a038170dbb5e4b69a50f648a8cf5cae6a910a3 Mon Sep 17 00:00:00 2001 From: julianf Date: Thu, 30 Jun 2022 16:03:55 +0200 Subject: docs: `make_entry` and `entry_display` --- doc/telescope.txt | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) (limited to 'doc') diff --git a/doc/telescope.txt b/doc/telescope.txt index 9903ac2..a736d18 100644 --- a/doc/telescope.txt +++ b/doc/telescope.txt @@ -2006,6 +2006,101 @@ resolver.resolve_anchor_pos() *telescope.resolve.resolve_anchor_pos()* +================================================================================ + *telescope.make_entry* + +Each picker has a finder made up of two parts, the results which are the data +to be displayed, and the entry_maker. These entry_makers are functions returned +from make_entry functions. These will be referrd to as entry_makers in the +following documentation. + +Every entry maker returns a function which accepts the data to be used for an +entry. This function will return an entry table (or nil, meaning skip this +entry) which contains of the - following important keys: +- value any: value key can be anything but still required +- valid bool: is an optional key because it defaults to true but if the key is + set to false it will not be displayed by the picker. (optional) +- ordinal string: is the text that is used for filtering (required) +- display string|function: is either a string of the text that is being + displayed or a function receiving the entry at a later stage, when the entry + is actually being displayed. A function can be useful here if complex + calculation have to be done. `make_entry` can also return a second value a + highlight array which will then apply to the line. Highlight entry in this + array has the following signature `{ { start_col, end_col }, hl_group }` + (required). +- filename string: will be interpreted by the default `` action as open + this file (optional) +- bufnr number: will be interpreted by the default `` action as open this + buffer (optional) +- lnum number: lnum value which will be interpreted by the default `` + action as a jump to this line (optional) +- col number: col value which will be interpreted by the default `` action + as a jump to this column (optional) + +More information on easier displaying, see |telescope.pickers.entry_display| + +TODO: Document something we call `entry_index` + + +================================================================================ + *telescope.pickers.entry_display* + +Entry Display is used to format each entry shown in the result panel. + +Entry Display create() will give us a function based on the configuration of +column widths we pass into it. We then can use this function n times to return +a string based on structured input. + +Note that if you call `create()` inside `make_display` it will be called for +every single entry. So it is suggested to do this outside of `make_display` for +the best performance. + +The create function will use the column widths passed to it in +configaration.items. Each item in that table is the number of characters in the +column. It's also possible for the final column to not have a fixed width, this +will be shown in the configuartion as 'remaining = true'. + +An example of this configuration is shown for the buffers picker +> +local displayer = entry_display.create { + separator = " ", + items = { + { width = opts.bufnr_width }, + { width = 4 }, + { width = icon_width }, + { remaining = true }, + }, +} +< + +This shows 4 columns, the first is defined in the opts as the width we'll use +when display_string the number of the buffer. The second has a fixed width of 4 +and the 3rd column's widht will be decided by the width of the icons we use. +The fourth column will use the remaining space. Finally we have also defined +the seperator between each column will be the space " ". + +An example of how the display reference will be used is shown, again for the +buffers picker: +> +return displayer { + { entry.bufnr, "TelescopeResultsNumber" }, + { entry.indicator, "TelescopeResultsComment" }, + { icon, hl_group }, + display_bufname .. ":" .. entry.lnum, +} +< + +There are two types of values each column can have. Either a simple String or a +table containing the String as well as the hl_group. + +The displayer can return values, string and an optional highlights. String is +all the text to be displayed for this entry as a single string. If parts of the +string are to be highlighted they will be described in the highlights table. + +For better understanding of how create() and displayer are used it's best to +look at the code in make_entry.lua. + + ================================================================================ *telescope.utils* -- cgit v1.2.3 From bf1a25dbfe9a4368b10354cb46e4b3a0ab0a41a4 Mon Sep 17 00:00:00 2001 From: Turiiya <34311583+tobealive@users.noreply.github.com> Date: Fri, 1 Jul 2022 22:10:31 +0200 Subject: feat: search_file option for builtin fd command (#2029) --- doc/telescope.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'doc') diff --git a/doc/telescope.txt b/doc/telescope.txt index a736d18..6381b12 100644 --- a/doc/telescope.txt +++ b/doc/telescope.txt @@ -899,6 +899,7 @@ builtin.find_files({opts}) *telescope.builtin.find_files()* (default: false) {search_dirs} (table) directory/directories/files to search + {search_file} (string) specify a filename to search for builtin.fd() *telescope.builtin.fd()* -- cgit v1.2.3 From 5dd4b5291085d0a843a43c94c5880b513fd0f484 Mon Sep 17 00:00:00 2001 From: marcel <62728887+marcelarie@users.noreply.github.com> Date: Fri, 1 Jul 2022 22:58:05 +0200 Subject: break: cleanup preview.treesitter language setting (#1612) this follows nvim-treesitter more closely but enable can also be a table of enabled languages The config now looks like this: ```lua defaults = { preview = { treesitter = { enable = false, -- or enable = { "c" }, -- disable can be set if enable isn't set disable = { "perl", "javascript" }, }, }, }, ``` --- doc/telescope.txt | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/telescope.txt b/doc/telescope.txt index 6381b12..4a6eb1a 100644 --- a/doc/telescope.txt +++ b/doc/telescope.txt @@ -497,8 +497,17 @@ telescope.setup({opts}) *telescope.setup()* highlighting, which falls back to regex-based highlighting. `true`: treesitter highlighting for all available filetypes `false`: regex-based highlighting for all filetypes - `table`: table of filetypes for which to attach treesitter - highlighting + `table`: following nvim-treesitters highlighting options: + It contains two keys: + - enable boolean|table: if boolean, enable all ts + highlighing with that flag, + disable still considered. + Containing a list of filetypes, + that are enabled, disabled + ignored because it doesnt make + any sense in this case. + - disable table: containing a list of filetypes + that are disabled Default: true - msg_bg_fillchar: Character to fill background of unpreviewable buffers with Default: "╱" -- cgit v1.2.3 From e778abfdb457cc47ca47ce9b76905e043e87e598 Mon Sep 17 00:00:00 2001 From: Simon Hauser Date: Fri, 1 Jul 2022 23:20:07 +0200 Subject: docs: changelog for dev branch, 1945 --- doc/telescope_changelog.txt | 59 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) (limited to 'doc') diff --git a/doc/telescope_changelog.txt b/doc/telescope_changelog.txt index a11ad84..a1a474d 100644 --- a/doc/telescope_changelog.txt +++ b/doc/telescope_changelog.txt @@ -195,5 +195,64 @@ https://github.com/stevearc/dressing.nvim which has support for multiple different backends including telescope. + *telescope.changelog-1945* + +Date: July 01, 2022 +PR: https://github.com/nvim-telescope/telescope.nvim/pull/1945 + +This is our dev branch which contains a lot of PRs, a lot of fixes, +refactoring and general quality of life improvements. It also contains new +features, the most noteworthy are the following (mostly developed by the +community): +- feat: none strategy & control attachment (#1867) +- feat: force buffer delete for terminal and improvements for + Picker:delete_selection (#1943) +- feat(tags): process tagfiles on the fly (#1989) +- feat(builtin.lsp): implement builtin handlers for + lsp.(incoming|outgoing)_calls (#1484) +- feat: clear previewer if no item is selected (#2004) +- feat: add min max boundary to width, height resolver (#2002) +- feat: Add entry_index for entry_makers (#1850) +- feat: refine with new_table (#1115) + +The last one is one of the most existing new features, because it allows you +to go from live_grep into a fuzzy environment with the following mapping +``. It's a general interface we now implemented for `live_grep` and +`lsp_dynamic_workspace_symbols` but it could also be easily implemented for +other builtins, by us or the user. It's now available for extension developers. +We will add documentation in the next couple of days and improve it by adding +more options to configure it after the initial 0.1 release. + +But with all longer development phases, there are also some breaking changes. +This is the main reason we moved development to a separate branch, for the +past two months. We can't promise that there won't be more breaking changes, +but it is the plan that this is the last set of breaking changes prior to the +0.1 release on July, 12. We are deeply sorry for the inconvenience. The +following breaking changes are included in this PR: +- break(git_files): change `show_untracked` default to false. Can be changed + back with `:Telescope git_files show_untracked=true` +- break: deprecate `utils.get_default` `utils.if_nil`, will be removed prior + to 0.1, so if you use it in your config, please move to `vim.F.if_nil` +- break: drops `ignore_filename` option, use `path_display= { "hidden" }` + instead +- break: prefix internal interfaces with __ so + `require("telescope.builtin.files").find_files` will show a notify error but + still works for now. The error will be removed prior to 0.1! You should use + `require("telescope.builtin").find_files` because we wrap all the functions + that are exposed in this module. +- break: defaults.preview.treesitter rework that allows you to either enable a + list of languages, or enable all and disable some. Please read + `:help telescope.defaults.preview` for more information. + Something like this is now possible: + > + treesitter = { + enable = false, + -- or + enable = { "c" }, + -- disable can be set if enable isn't set + disable = { "perl", "javascript" }, + }, +< + vim:tw=78:ts=8:ft=help:norl: -- cgit v1.2.3