Skip to content

Commit ce7822f

Browse files
ryanmsnyderryanmsnyder
committed
refactor: change config naming for more clarity (i.e. group all config options related to the appearance of the telescope results into a table called 'results'
1 parent 5a5e4bd commit ce7822f

4 files changed

Lines changed: 111 additions & 38 deletions

File tree

‎README.md‎

Lines changed: 62 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,93 @@
11
<p align="center">
2-
A simple Telescope extension to manage Terminal buffers
2+
A Telescope extension to manage toggleterm's terminal buffers
33
</p>
44

55
## ✨ Features
66

7-
- List and switch between all terminal buffers opened with `toggleterm.nvim`.
8-
- Kill terminal buffers easily with keybindings.
9-
- Open buffer picker with `:Telescope toggleterm`
7+
- List and switch between all terminal buffers opened with `toggleterm.nvim`
8+
- Easily customize the appearance of the Telescope window
9+
- Map pre-defined actions to keybindings
10+
- Open buffer picker with `:Telescope toggleterm_manager`
1011
or `lua require('telescope-toggleterm').open()`
1112

1213
## ⚡ Requirements
1314

1415
- [`telescope`](https://github.com/nvim-telescope/telescope.nvim) plugin.
1516
- [`nvim-toggleterm`](https://github.com/akinsho/nvim-toggleterm.lua) plugin.
1617

17-
## 🛠️ Installation
18-
Using [ `lazy.nvim` ](https://github.com/folke/lazy.nvim) in lua:
18+
## 🛠️ Quickstart
19+
20+
Install using [ `lazy.nvim` ](https://github.com/folke/lazy.nvim) in lua:
21+
1922
```lua
2023
{
21-
"ryanmsnyder/telescope-toggleterm.nvim",
24+
"ryanmsnyder/toggleterm-manager.nvim",
2225
event = "TermOpen",
2326
dependencies = {
2427
"akinsho/nvim-toggleterm.lua",
2528
"nvim-telescope/telescope.nvim",
2629
"nvim-lua/popup.nvim",
2730
"nvim-lua/plenary.nvim",
2831
},
29-
config = function()
30-
require("telescope").load_extension "toggleterm"
31-
end,
32+
config = require("toggleterm-manager").setup()
3233
}
3334
```
3435

36+
Open `toggleterm-manager` by either:
37+
- running the command `:Telescope toggleterm_manager`
38+
- calling `lua require('toggleterm-manager').open()`
39+
40+
Keep reading if you want to change the default configuration.
41+
3542
## ⚙️ Configuration
3643

44+
### Defaults
45+
46+
By default, the below table is passed to the `setup` function:
47+
3748
```lua
38-
require("telescope-toggleterm").setup {
39-
mappings = {
40-
-- <ctrl-c> : kill the terminal buffer (default) .
41-
["<C-c>"] = require("telescope-toggleterm").actions.exit_terminal,
42-
},
49+
{
50+
mappings = {}, -- key mappings bound inside the telescope window
51+
telescope_titles = {
52+
preview = "Preview", -- title of the preview buffer in telescope
53+
prompt = " Pick Term", -- title of the prompt buffer in telescope
54+
results = "Results", -- title of the results buffer in telescope
55+
},
56+
results = {
57+
fields = {
58+
"state",
59+
"space",
60+
"term_icon",
61+
"term_name",
62+
},
63+
separator = " ", -- the character that will be used to separate each field provided in results_format
64+
term_icon = "", -- the icon that will be used for the term_icon in results_format
65+
66+
},
67+
search = {
68+
field = "term_name" -- the field that telescope fuzzy search will use
69+
},
70+
sort = {
71+
field = "term_name", -- the field that will be used for sorting in the telesocpe results
72+
ascending = true, -- whether or not the field provided above will be sorted in ascending or descending order
73+
},
4374
}
4475
```
4576

77+
| Property | Type | Default Value | Description |
78+
|--------------------|--------------------------------|---------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
79+
| **mappings** | `table` | | A table of key mappings for different modes. Each mode (like 'i' for insert mode, 'n' for normal mode) is a key in the table and maps to another table, where the key is the key combination (e.g., "<CR>") and the value is a table with the fields 'action' and 'exit_on_action'. The 'action' field is a function that will be called when the key combination is pressed, and 'exit_on_action' is a boolean that determines whether telescope should be exited after the action is performed. |
80+
| **telescope_titles.preview** | `string` | "Preview" | Title of the preview buffer in telescope. Any string. |
81+
| **telescope_titles.prompt** | `string` | " Pick Term" | Title of the prompt buffer in telescope. Any string. |
82+
| **telescope_titles.results** | `string` | "Results" | Title of the results buffer in telescope. Any string. |
83+
| **results.separator** | `string` | " " | The character used to separate each field in `results_format`. Any string, though a space character and a pipe character are the most commonly used. |
84+
| **results.fields** | `{string\|{string, string}}[]` | { "state", "space", "term_icon", "term_name", } | The format and order of the results displayed in the telescope buffer. This accepts a table where each element is either: an acceptable string a table of tuple-like tables where the first value in the tuple is one of the acceptable strings and the second is a valid NeoVim highlight group that the column should adhere to. The acceptable strings are: `bufname`, `bufnr`, `space`, `state`, `term_name`, `term_icon`. See results_format for more info. |
85+
| **results.term_icon** | `string` | "" | The icon used for `term_icon` in `results_format`. Any string. |
86+
| **search.field** | `string` | "term_name" | The field that telescope's fuzzy search will use. Doesn't need to be a value provided in `results_format`. Valid strings are: `bufname`, `bufnr`, `state`, `term_name`. |
87+
| **sort.field** | `table` | "term_name" | The field that will be used for sorting the results in telescope. Doesn't need to be a value provided in `results_format`. Valid strings are: `bufnr`, `recency`, `state`, `term_name`. |
88+
| **sort.ascending** | `boolean` | true | Determines the order used for sorting the telescope results. `true` = ascending, `false` = descending. |
89+
90+
91+
### `results_format`
4692

93+
This propery allows for easy customization of how the terminal buffers appear in the telescope window.

‎lua/config.lua‎

Lines changed: 39 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,50 @@
11
local M = {}
22

33
local defaults = {
4-
display_mappings = false,
54
mappings = {}, -- key mappings bound inside the telescope window
6-
preview_title = "Preview",
7-
prompt_title = " Pick Term",
8-
results_format = {
9-
"state",
10-
"space",
11-
"term_icon",
12-
"term_name",
5+
telescope_titles = {
6+
preview = "Preview", -- title of the preview buffer in telescope
7+
prompt = " Pick Term", -- title of the prompt buffer in telescope
8+
results = "Results", -- title of the results buffer in telescope
9+
},
10+
results = {
11+
fields = {
12+
"state",
13+
"space",
14+
"term_icon",
15+
"term_name",
16+
},
17+
separator = " ", -- the character that will be used to separate each field provided in results.fields
18+
term_icon = "", -- the icon that will be used for the term_icon in results.fields
19+
},
20+
search = {
21+
field = "term_name", -- the field that telescope fuzzy search will use
1322
},
14-
results_title = "Results",
15-
search_field = "term_name",
16-
separator = " ",
17-
term_icon = "",
1823
sort = {
19-
field = "bufnr",
20-
ascending = true,
24+
field = "term_name", -- the field that will be used for sorting in the telesocpe results
25+
ascending = true, -- whether or not the field provided above will be sorted in ascending or descending order
2126
},
2227
}
28+
-- local defaults = {
29+
-- mappings = {}, -- key mappings bound inside the telescope window
30+
-- preview_title = "Preview", -- title of the preview buffer in telescope
31+
-- prompt_title = " Pick Term", -- title of the prompt buffer in telescope
32+
-- results_title = "Results", -- title of the results buffer in telescope
33+
-- separator = " ", -- the character that will be used to separate each field provided in results_format
34+
-- results_format = {
35+
-- "state",
36+
-- "space",
37+
-- "term_icon",
38+
-- "term_name",
39+
-- },
40+
-- term_icon = "", -- the icon that will be used for the term_icon in results_format
41+
-- search_field = "term_name", -- the field that telescope fuzzy search will use
42+
-- sort = {
43+
-- field = "term_name", -- the field that will be used for sorting in the telesocpe results
44+
-- ascending = true, -- whether or not the field provided above will be sorted in ascending or descending order
45+
-- },
46+
-- }
47+
2348
M.options = {}
2449
function M.setup(opts)
2550
opts = opts or {}

‎lua/lib/displayer/init.lua‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ local config = require("config").options
77
local M = {}
88

99
local function process_results_config(target_table, insert_val)
10-
for _, configItem in ipairs(config.results_format) do
10+
for _, configItem in ipairs(config.results.fields) do
1111
-- if value in results_config is a table (contains the column type and highlight group)
1212
local col
1313
if type(configItem) == "table" then
@@ -47,7 +47,7 @@ local function results_formatter(opts)
4747
local items = {}
4848

4949
local icon_width = 0
50-
local term_icon = config.term_icon
50+
local term_icon = config.results.term_icon
5151
icon_width = strings.strdisplaywidth(term_icon)
5252

5353
local items_col_widths = {
@@ -94,7 +94,7 @@ function M.displayer(opts)
9494
local items, create_display_table = results_formatter(opts)
9595

9696
local displayer = entry_display.create({
97-
separator = config.separator,
97+
separator = config.results.separator,
9898
items = items,
9999
})
100100

@@ -105,15 +105,15 @@ function M.displayer(opts)
105105
return function(entry)
106106
-- helper for mapping user config for search_field to the appropriate value
107107
local ordinal_values = {
108+
bufname = entry._bufname,
109+
bufnr = tostring(entry.bufnr),
108110
state = entry._state,
109111
term_name = entry._term_name,
110-
bufnr = tostring(entry.bufnr),
111-
bufname = entry._bufname,
112112
}
113113

114114
return make_entry.set_default_entry_mt({
115115
value = entry,
116-
ordinal = ordinal_values[config.search_field], -- for filtering in telescope search
116+
ordinal = ordinal_values[config.search.field], -- for filtering in telescope search
117117
display = make_display,
118118
bufnr = entry.bufnr,
119119
filename = entry._bufname,

‎lua/lib/telescope/init.lua‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -37,9 +37,10 @@ M.open = function(opts)
3737
require("toggleterm.ui").set_origin_window()
3838

3939
local picker = pickers.new(opts, {
40-
prompt_title = config.prompt_title,
41-
results_title = config.display_mappings and util.format_results_title(config.mappings) or config.results_title,
42-
preview_title = config.preview_title,
40+
prompt_title = config.telescope_titles.prompt,
41+
results_title = config.display_mappings and util.format_results_title(config.mappings)
42+
or config.telescope_titles.results,
43+
preview_title = config.telescope_titles.preview,
4344
previewer = conf.grep_previewer(opts),
4445
finder = util.create_finder(),
4546
sorter = conf.generic_sorter(opts),

0 commit comments

Comments
 (0)