leigh/telescope.nvim
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: proof-read edits (#2311)

Browse Source
This commit is contained in:
James Trew
2023-01-22 03:57:53 -05:00
committed by GitHub
parent ed366bba14
commit 053f2303c4
13 changed files with 151 additions and 136 deletions
Download Patch File Download Diff File Expand all files Collapse all files

155
doc/telescope.txt
View File

@@ -6,9 +6,9 @@ filter, find and pick things in Lua.
Getting started with telescope:
1. Run `:checkhealth telescope` to make sure everything is installed.
2. Evaluate it working with `:Telescope find_files` or `:lua
2. Evaluate it is working with `:Telescope find_files` or `:lua
require("telescope.builtin").find_files()`
3. Put a `require("telescope").setup() call somewhere in your neovim config.
3. Put a `require("telescope").setup()` call somewhere in your neovim config.
4. Read |telescope.setup| to check what config keys are available and what
you can put inside the setup call
5. Read |telescope.builtin| to check which builtin pickers are offered and
@@ -24,14 +24,14 @@ The below flow chart illustrates a simplified telescope architecture:
│ │ ┌───│Manager│────│ Sorter │┐ └───┬───* │
│ ▼ ▼ └───────* └────────┘│ │ │
│ 1────────┐ 2───┴──┐ │ │
│ ┌─────│ Picker │ │Finder│◄────┘ │
│ ┌─────│ Picker │ │Finder│◀────┘ │
│ ▼ └───┬────┘ └──────* │
│ ┌────────┐ │ 3────────+ ▲ │
│ │Selected│ └───────│ Prompt │─────────┘ │
│ │ Entry │ └───┬────┘ │
│ └────────* ┌───┴────┐ ┌────────┐ ┌────────┐ │
│ │ ▲ 4─────────┐│ Prompt │ │(Attach)│ │Actions │ │
│ ▼ └──► │ Results ││ Buffer │◄─┤Mappings│◄─┤User Fn │ │
│ ▼ └──▶ │ Results ││ Buffer │◀─┤Mappings│◀─┤User Fn │ │
│5─────────┐ └─────────┘└────────┘ └────────┘ └────────┘ │
││Previewer│ │
│└─────────┘ telescope.nvim architecture │
@@ -196,9 +196,9 @@ telescope.setup({opts}) *telescope.setup()*
and `actions.layout.cycle_layout_prev`.
Should be a list of "layout setups".
Each "layout setup" can take one of two forms:
1. string <br>
1. string
This is interpreted as the name of a `layout_strategy`
2. table <br>
2. table
A table with possible keys `layout_strategy`, `layout_config` and `previewer`
Default: { "horizontal", "vertical" }
@@ -227,7 +227,6 @@ telescope.setup({opts}) *telescope.setup()*
selection_caret: ~
The character(s) that will be shown in front of the current selection.
Default: '> '
*telescope.defaults.entry_prefix*
@@ -260,7 +259,7 @@ telescope.setup({opts}) *telescope.setup()*
*telescope.defaults.path_display*
path_display: ~
Determines how file paths are displayed
Determines how file paths are displayed.
path_display can be set to an array with a combination of:
- "hidden" hide file names
@@ -273,7 +272,7 @@ telescope.setup({opts}) *telescope.setup()*
- "shorten" only display the first character of each directory in
the path
- "truncate" truncates the start of the path when the whole path will
not fit. To increase the the gap between the path and the edge.
not fit. To increase the gap between the path and the edge,
set truncate to number `truncate = 3`
You can also specify the number of characters of each directory name
@@ -352,7 +351,7 @@ telescope.setup({opts}) *telescope.setup()*
prompt_title: ~
Defines the default title of the prompt window. A false value
can be used to hide the title altogether. Most of the times builtins
define a prompt_title which will be prefered over this default.
define a prompt_title which will be preferred over this default.
Default: "Prompt"
@@ -371,6 +370,8 @@ telescope.setup({opts}) *telescope.setup()*
Will allow you to completely remove all of telescope's default maps
and use your own.
Default: nil
*telescope.defaults.history*
history: ~
@@ -388,11 +389,11 @@ telescope.setup({opts}) *telescope.setup()*
Fields:
- path: The path to the telescope history as string.
default: stdpath("data")/telescope_history
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 grow unbound.
default: 100
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.,
@@ -566,7 +567,7 @@ telescope.setup({opts}) *telescope.setup()*
file_sorter: ~
A function pointer that specifies the file_sorter. This sorter will
be used for find_files, git_files and similar.
Hint: If you load a native sorter, you dont need to change this value,
Hint: If you load a native sorter, you don't need to change this value,
the native sorter will override it anyway.
Default: require("telescope.sorters").get_fzy_sorter
@@ -575,7 +576,7 @@ telescope.setup({opts}) *telescope.setup()*
generic_sorter: ~
A function pointer to the generic sorter. The sorter that should be
used for everything that is not a file.
Hint: If you load a native sorter, you dont need to change this value,
Hint: If you load a native sorter, you don't need to change this value,
the native sorter will override it anyway.
Default: require("telescope.sorters").get_fzy_sorter
@@ -584,7 +585,7 @@ telescope.setup({opts}) *telescope.setup()*
prefilter_sorter: ~
This points to a wrapper sorter around the generic_sorter that is able
to do prefiltering.
Its usually used for lsp_*_symbols and lsp_*_diagnostics
It's usually used for lsp_*_symbols and lsp_*_diagnostics
Default: require("telescope.sorters").prefilter
@@ -896,7 +897,7 @@ builtin.current_buffer_fuzzy_find({opts}) *telescope.builtin.current_buffer_fuzz
{opts} (table) options to pass to the picker
Options: ~
{skip_empty_lines} (boolean) if true we dont display empty lines
{skip_empty_lines} (boolean) if true we don't display empty lines
(default: false)
@@ -965,7 +966,7 @@ builtin.git_files({opts}) *telescope.builtin.git_files()*
{recurse_submodules} (boolean) if true, adds the
`--recurse-submodules` flag to command
(default: false)
{git_command} (table) command that will be exectued.
{git_command} (table) command that will be executed.
{"git","ls-files","--exclude-standard","--cached"}
@@ -985,13 +986,13 @@ builtin.git_commits({opts}) *telescope.builtin.git_commits()*
{cwd} (string) specify the path of the repo
{use_git_root} (boolean) if we should use git root as cwd or the cwd
(important for submodule) (default: true)
{git_command} (table) command that will be exectued.
{git_command} (table) command that will be executed.
{"git","log","--pretty=oneline","--abbrev-commit","--","."}
builtin.git_bcommits({opts}) *telescope.builtin.git_bcommits()*
Lists commits for current buffer with diff preview
- Default keymaps or your overriden `select_` keys:
- Default keymaps or your overridden `select_` keys:
- `<cr>`: checks out the currently selected commit
- `<c-v>`: opens a diff in a vertical split
- `<c-x>`: opens a diff in a horizontal split
@@ -1007,7 +1008,7 @@ builtin.git_bcommits({opts}) *telescope.builtin.git_bcommits()*
(important for submodule) (default: true)
{current_file} (string) specify the current file that should be used
for bcommits (default: current buffer)
{git_command} (table) command that will be exectued.
{git_command} (table) command that will be executed.
{"git","log","--pretty=oneline","--abbrev-commit"}
@@ -1129,9 +1130,9 @@ builtin.planets({opts}) *telescope.builtin.planets()*
{opts} (table) options to pass to the picker
Options: ~
{show_pluto} (boolean) we love pluto (default: false, because its a
{show_pluto} (boolean) we love Pluto (default: false, because its a
hidden feature)
{show_moon} (boolean) we love the moon (default: false, because its
{show_moon} (boolean) we love the Moon (default: false, because its
a hidden feature)
@@ -1654,9 +1655,10 @@ themes.get_dropdown() *telescope.themes.get_dropdown()*
Usage:
>
`local builtin = require('telescope.builtin')`
`local themes = require('telescope.themes')`
`builtin.find_files(themes.get_dropdown())`
local opts = {...} -- picker options
local builtin = require('telescope.builtin')
local themes = require('telescope.themes')
builtin.find_files(themes.get_dropdown(opts))
<
@@ -1666,10 +1668,10 @@ themes.get_cursor() *telescope.themes.get_cursor()*
Usage:
>
`local builtin = require('telescope.builtin')`
`local themes = require('telescope.themes')`
`builtin.lsp_references(themes.get_cursor())`
local opts = {...} -- picker options
local builtin = require('telescope.builtin')
local themes = require('telescope.themes')
builtin.find_files(themes.get_cursor(opts))
<
@@ -1679,9 +1681,10 @@ themes.get_ivy() *telescope.themes.get_ivy()*
Usage:
>
`local builtin = require('telescope.builtin')`
`local themes = require('telescope.themes')`
`builtin.find_files(themes.get_ivy())`
local opts = {...} -- picker options
local builtin = require('telescope.builtin')
local themes = require('telescope.themes')
builtin.find_files(themes.get_ivy(opts))
<
@@ -1691,12 +1694,11 @@ themes.get_ivy() *telescope.themes.get_ivy()*
MAPPINGS *telescope.mappings*
|telescope.mappings| is used to configure the keybindings within a telescope
picker. These keybinds are only local to the picker window and will be cleared
picker. These key binds are only local to the picker window and will be cleared
once you exit the picker.
We provide multiple different ways of configuring, as described below, to
provide an easy to use experience for changing the default behavior of
telescope or extending for your own purposes.
We provide multiple configuration options to make it easy for you to adjust
telescope's default key bindings and create your own custom key binds.
To see many of the builtin actions that you can use as values for this table,
see |telescope.actions|
@@ -1729,7 +1731,6 @@ For example:
...,
}
<
Into your config.
To override behavior of a key, simply set the value to be a function (either by
requiring an action or by writing your own function)
@@ -1742,7 +1743,8 @@ requiring an action or by writing your own function)
<
If the function you want is part of `telescope.actions`, then you can simply
give a string. For example, the previous option is equivalent to:
supply the function name as a string. For example, the previous option is
equivalent to:
>
{
...,
@@ -1854,7 +1856,6 @@ All layout strategies are functions with the following signature:
- 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.
@@ -1979,6 +1980,20 @@ layout_strategies.cursor() *telescope.layout.cursor()*
│ │
└──────────────────────────────────────────────────┘
`picker.layout_config` shared options:
- height:
- How tall to make Telescope's entire layout
- See |resolver.resolve_height()|
- 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()|
layout_strategies.vertical() *telescope.layout.vertical()*
@@ -2141,24 +2156,23 @@ Every entry maker returns a function that accepts the data to be used for an
entry. This function will return an entry table (or nil, meaning skip this
entry) which contains 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)
- valid bool (optional): 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
- ordinal string: is the text that is used for filtering
- 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 a complex
calculation has to be done. `make_entry` can also return a second value a
calculation has 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 `<cr>` action as open
this file (optional)
- bufnr number: will be interpreted by the default `<cr>` action as open this
buffer (optional)
- lnum number: lnum value which will be interpreted by the default `<cr>`
action as a jump to this line (optional)
- col number: col value which will be interpreted by the default `<cr>` action
as a jump to this column (optional)
array has the following signature `{ { start_col, end_col }, hl_group }`
- filename string (optional): will be interpreted by the default `<cr>` action
as open this file
- bufnr number (optional): will be interpreted by the default `<cr>` action as
open this buffer
- lnum number (optional): lnum value which will be interpreted by the default
`<cr>` action as a jump to this line
- col number (optional): col value which will be interpreted by the default
`<cr>` action as a jump to this column
For more information on easier displaying, see
|telescope.pickers.entry_display|
@@ -2180,7 +2194,7 @@ 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
configuration.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 configuration as 'remaining = true'.
@@ -2243,7 +2257,7 @@ utils.transform_path({opts}, {path}) *telescope.utils.transform_path()*
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
{path} (string) The path that should be formatted
Return: ~
string: The transformed path ready to be displayed
@@ -2262,9 +2276,9 @@ utils.notify({funname}, {opts}) *telescope.utils.notify()*
================================================================================
ACTIONS *telescope.actions*
Actions functions that are useful for people creating their own mappings.
These functions are useful for people creating their own mappings.
Actions can be either normal functions that expect the prompt_bufnr as first
Actions can be either normal functions that expect the `prompt_bufnr` as first
argument (1) or they can be a custom telescope type called "action" (2).
(1) The `prompt_bufnr` of a normal function denotes the identifier of your
@@ -2305,8 +2319,8 @@ do the following:
action(bufnr)
<
Another interesing thing to do is that these actions now have functions you can
call. These functions include `:replace(f)`, `:replace_if(f, c)`,
Another interesting thing to do is that these actions now have functions you
can call. These functions include `:replace(f)`, `:replace_if(f, c)`,
`replace_map(tbl)` and `enhance(tbl)`. More information on these functions can
be found in the `developers.md` and `lua/tests/automated/action_spec.lua` file.
@@ -2392,8 +2406,8 @@ actions.toggle_selection({prompt_bufnr}) *telescope.actions.toggle_selection()*
actions.select_all({prompt_bufnr}) *telescope.actions.select_all()*
Multi select all entries.
- Note: selected entries may include results not visible in the results
popup.
- Note: selected entries may include results not visible in the results pop
up.
Parameters: ~
@@ -2410,8 +2424,8 @@ actions.drop_all({prompt_bufnr}) *telescope.actions.drop_all()*
actions.toggle_all({prompt_bufnr}) *telescope.actions.toggle_all()*
Toggle multi selection for all entries.
- Note: toggled entries may include results not visible in the results
popup.
- Note: toggled entries may include results not visible in the results pop
up.
Parameters: ~
@@ -2580,7 +2594,7 @@ actions._close({prompt_bufnr}) *telescope.actions._close()*
actions.edit_command_line({prompt_bufnr}) *telescope.actions.edit_command_line()*
Set a value in the command line and dont run it, making it editable.
Set a value in the command line and don't run it, making it editable.
Parameters: ~
@@ -2596,7 +2610,7 @@ actions.set_command_line({prompt_bufnr}) *telescope.actions.set_command_line()*
actions.edit_search_line({prompt_bufnr}) *telescope.actions.edit_search_line()*
Set a value in the search line and dont search for it, making it editable.
Set a value in the search line and don't search for it, making it editable.
Parameters: ~
@@ -3120,7 +3134,7 @@ utils.map_entries({prompt_bufnr}, {f}) *telescope.actions.utils.map_entries()*
Apply `f` to the entries of the current picker.
- Notes:
- Mapped entries include all currently filtered results, not just the
visible onces.
visible ones.
- Indices are 1-indexed, whereas rows are 0-indexed.
- Warning: `map_entries` has no return value.
- The below example showcases how to collect results
@@ -3133,7 +3147,7 @@ utils.map_entries({prompt_bufnr}, {f}) *telescope.actions.utils.map_entries()*
local prompt_bufnr = vim.api.nvim_get_current_buf()
local current_picker = action_state.get_current_picker(prompt_bufnr)
local results = {}
action_utils.map_entries(prompt_bufnr, function(entry, index, row)
action_utils.map_entries(prompt_bufnr, function(entry, index, row)
results[row] = entry.value
end)
return results
@@ -3152,7 +3166,8 @@ utils.map_selections({prompt_bufnr}, {f}) *telescope.actions.utils.map_selection
Apply `f` to the multi selections of the current picker and return a table
of mapped selections.
- Notes:
- Mapped selections may include results not visible in the results popup.
- Mapped selections may include results not visible in the results pop
up.
- Selected entries are returned in order of their selection.
- Warning: `map_selections` has no return value.
- The below example showcases how to collect results
@@ -3165,7 +3180,7 @@ utils.map_selections({prompt_bufnr}, {f}) *telescope.actions.utils.map_selection
local prompt_bufnr = vim.api.nvim_get_current_buf()
local current_picker = action_state.get_current_picker(prompt_bufnr)
local results = {}
action_utils.map_selections(prompt_bufnr, function(entry, index)
action_utils.map_selections(prompt_bufnr, function(entry, index)
results[index] = entry.value
end)
return results
@@ -3483,8 +3498,8 @@ previewers.new_buffer_previewer() *telescope.previewers.new_buffer_previewer()*
vim.api.nvim_buf_call(bufnr, function()
-- for example `search` and `matchadd`
end)
to achieve that.
<
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