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* diff --git a/lua/telescope/make_entry.lua b/lua/telescope/make_entry.lua index e8f2509..64993df 100644 --- a/lua/telescope/make_entry.lua +++ b/lua/telescope/make_entry.lua @@ -1,3 +1,40 @@ +---@tag telescope.make_entry + +---@brief [[ +--- +--- 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` +---@brief ]] + local entry_display = require "telescope.pickers.entry_display" local utils = require "telescope.utils" local strings = require "plenary.strings" @@ -190,9 +227,6 @@ do return { filename, lnum, col, text } end - --- Special options: - --- - disable_coordinates: Don't show the line & row numbers - --- - only_sort_text: Only sort via the text. Ignore filename and other items function make_entry.gen_from_vimgrep(opts) local mt_vimgrep_entry @@ -919,8 +953,6 @@ function make_entry.gen_from_vimoptions(opts) end end ---- Special options: ---- - only_sort_tags: Only sort via tag name. Ignore filename and other items function make_entry.gen_from_ctags(opts) opts = opts or {} diff --git a/lua/telescope/pickers/entry_display.lua b/lua/telescope/pickers/entry_display.lua index b1a1473..6e520f4 100644 --- a/lua/telescope/pickers/entry_display.lua +++ b/lua/telescope/pickers/entry_display.lua @@ -1,3 +1,63 @@ +---@tag telescope.pickers.entry_display + +---@brief [[ +--- 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. +---@brief ]] + local strings = require "plenary.strings" local state = require "telescope.state" local resolve = require "telescope.config.resolve" diff --git a/scripts/gendocs.lua b/scripts/gendocs.lua index 524cb04..cc9f158 100644 --- a/scripts/gendocs.lua +++ b/scripts/gendocs.lua @@ -17,6 +17,8 @@ docs.test = function() "./lua/telescope/themes.lua", "./lua/telescope/pickers/layout_strategies.lua", "./lua/telescope/config/resolve.lua", + "./lua/telescope/make_entry.lua", + "./lua/telescope/pickers/entry_display.lua", "./lua/telescope/utils.lua", "./lua/telescope/actions/init.lua", "./lua/telescope/actions/state.lua",