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

feat(docs): simplified architecture flow chart (#1925)

Browse Source 
`:h telescope.nvim` now shows an overview of the telescope architecture
This commit is contained in:
fdschmidt93
2022-05-09 11:43:22 +02:00
committed by GitHub
parent 85239d9c3e
commit 795a63ed29
3 changed files with 101 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
developers.md
View File

@@ -20,9 +20,12 @@
So you want to develop your own picker and/or extension for telescope? Then you
are in the right place! This file will first present an introduction on how to
do this. After that, this document will present a technical explanation of
pickers, finders, actions and the previewer. You can find more information
in specific help pages and we will probably move some of the technical stuff to
our vim help docs in the future.
pickers, finders, actions and the previewer. Should you now yet have an idea of
the general telescope architecture and its components, it is first recommend to
familiarize yourself with the architectural flow-chart that is provided in
vim docs (`:h telescope.nvim`). You can find more information in specific help
pages and we will probably move some of the technical stuff to our vim help docs
in the future.
This guide is mainly for telescope so it will assume that you already have some knowledge of the Lua
programming language. If not then you can find information for Lua here:

47
doc/telescope.txt
View File

@@ -15,6 +15,51 @@ Getting started with telescope:
what options these implement
6. Profit
The below flow chart illustrates a simplified telescope architecture:
┌───────────────────────────────────────────────────────────┐
│ ┌────────┐ │
│ │ Multi │ ┌───────+ │
│ │ Select │ ┌───────┐ │ Entry │ │
│ └─────┬──* │ Entry │ ┌────────+ │ Maker │ │
│ │ ┌───│Manager│────│ Sorter │┐ └───┬───* │
│ ▼ ▼ └───────* └────────┘│ │ │
│ 1────────┐ 2───┴──┐ │ │
│ ┌─────│ Picker │ │Finder│◄────┘ │
│ ▼ └───┬────┘ └──────* │
│ ┌────────┐ │ 3────────+ ▲ │
│ │Selected│ └───────│ Prompt │─────────┘ │
│ │ Entry │ └───┬────┘ │
│ └────────* ┌───┴────┐ ┌────────┐ ┌────────┐ │
│ │ ▲ 4─────────┐│ Prompt │ │(Attach)│ │Actions │ │
│ ▼ └──► │ Results ││ Buffer │◄─┤Mappings│◄─┤User Fn │ │
│5─────────┐ └─────────┘└────────┘ └────────┘ └────────┘ │
││Previewer│ │
│└─────────┘ telescope.nvim architecture │
└───────────────────────────────────────────────────────────┘
+ The `Entry Maker` at least defines
- value: "raw" result of the finder
- ordinal: string to be sorted derived from value
- display: line representation of entry in results buffer
* The finder, entry manager, selected entry, and multi selections
comprises `entries` constructed by the `Entry Maker` from
raw results of the finder (`value`s)
Primary components:
1 Picker: central UI dedicated to varying use cases
(finding files, grepping, diagnostics, etc.)
see :h telescope.builtin
2 Finder: pipe or interactively generates results to pick over
3 Prompt: user input that triggers the finder which sorts results
in order into the entry manager
4 Results: listed entries scored by sorter from finder results
5 Previewer: preview of context of selected entry
see :h telescope.previewers
A practical introduction into telescope customization is our `developers.md`
(top-level of repo) and `:h telescope.actions` that showcase how to access
information about the state of the picker (current selection, etc.).
To find out more:
https://github.com/nvim-telescope/telescope.nvim
@@ -29,8 +74,8 @@ https://github.com/nvim-telescope/telescope.nvim
:h telescope.actions.set
:h telescope.actions.utils
:h telescope.actions.generate
:h telescope.previewers
:h telescope.actions.history
:h telescope.previewers
telescope.setup({opts}) *telescope.setup()*
Setup function to be run by user. Configures the defaults, pickers and

50
lua/telescope/init.lua
View File

@@ -21,6 +21,54 @@ local telescope = {}
--- 5. Read |telescope.builtin| to check which builtin pickers are offered and what options these implement
--- 6. Profit
---
--- The below flow chart illustrates a simplified telescope architecture:
--- <pre>
--- ┌───────────────────────────────────────────────────────────┐
--- │ ┌────────┐ │
--- │ │ Multi │ ┌───────+ │
--- │ │ Select │ ┌───────┐ │ Entry │ │
--- │ └─────┬──* │ Entry │ ┌────────+ │ Maker │ │
--- │ │ ┌───│Manager│────│ Sorter │┐ └───┬───* │
--- │ ▼ ▼ └───────* └────────┘│ │ │
--- │ 1────────┐ 2───┴──┐ │ │
--- │ ┌─────│ Picker │ │Finder│◄────┘ │
--- │ ▼ └───┬────┘ └──────* │
--- │ ┌────────┐ │ 3────────+ ▲ │
--- │ │Selected│ └───────│ Prompt │─────────┘ │
--- │ │ Entry │ └───┬────┘ │
--- │ └────────* ┌───┴────┐ ┌────────┐ ┌────────┐ │
--- │ │ ▲ 4─────────┐│ Prompt │ │(Attach)│ │Actions │ │
--- │ ▼ └──► │ Results ││ Buffer │◄─┤Mappings│◄─┤User Fn │ │
--- │5─────────┐ └─────────┘└────────┘ └────────┘ └────────┘ │
--- ││Previewer│ │
--- │└─────────┘ telescope.nvim architecture │
--- └───────────────────────────────────────────────────────────┘
---
--- + The `Entry Maker` at least defines
--- - value: "raw" result of the finder
--- - ordinal: string to be sorted derived from value
--- - display: line representation of entry in results buffer
---
--- * The finder, entry manager, selected entry, and multi selections
--- comprises `entries` constructed by the `Entry Maker` from
--- raw results of the finder (`value`s)
---
--- Primary components:
--- 1 Picker: central UI dedicated to varying use cases
--- (finding files, grepping, diagnostics, etc.)
--- see :h telescope.builtin
--- 2 Finder: pipe or interactively generates results to pick over
--- 3 Prompt: user input that triggers the finder which sorts results
--- in order into the entry manager
--- 4 Results: listed entries scored by sorter from finder results
--- 5 Previewer: preview of context of selected entry
--- see :h telescope.previewers
--- </pre>
---
--- A practical introduction into telescope customization is our
--- `developers.md` (top-level of repo) and `:h telescope.actions` that
--- showcase how to access information about the state of the picker (current
--- selection, etc.).
--- <pre>
--- To find out more:
--- https://github.com/nvim-telescope/telescope.nvim
@@ -36,8 +84,8 @@ local telescope = {}
--- :h telescope.actions.set
--- :h telescope.actions.utils
--- :h telescope.actions.generate
--- :h telescope.previewers
--- :h telescope.actions.history
--- :h telescope.previewers
--- </pre>
---@brief ]]