Skip to content

Commit 40181f8

Browse files
ryanmsnyderryanmsnyder
committed
docs: update README
1 parent ce7822f commit 40181f8

3 files changed

Lines changed: 164 additions & 81 deletions

File tree

‎README.md‎

Lines changed: 97 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -6,16 +6,14 @@ A Telescope extension to manage toggleterm's terminal buffers
66

77
- List and switch between all terminal buffers opened with `toggleterm.nvim`
88
- Easily customize the appearance of the Telescope window
9-
- Map pre-defined actions to keybindings
10-
- Open buffer picker with `:Telescope toggleterm_manager`
11-
or `lua require('telescope-toggleterm').open()`
9+
- Map pre-defined and custom actions to keybindings
1210

1311
## ⚡ Requirements
1412

1513
- [`telescope`](https://github.com/nvim-telescope/telescope.nvim) plugin.
1614
- [`nvim-toggleterm`](https://github.com/akinsho/nvim-toggleterm.lua) plugin.
1715

18-
## 🛠️ Quickstart
16+
## 🛠️ Quickstart
1917

2018
Install using [ `lazy.nvim` ](https://github.com/folke/lazy.nvim) in lua:
2119

@@ -34,6 +32,7 @@ Install using [ `lazy.nvim` ](https://github.com/folke/lazy.nvim) in lua:
3432
```
3533

3634
Open `toggleterm-manager` by either:
35+
3736
- running the command `:Telescope toggleterm_manager`
3837
- calling `lua require('toggleterm-manager').open()`
3938

@@ -60,8 +59,8 @@ By default, the below table is passed to the `setup` function:
6059
"term_icon",
6160
"term_name",
6261
},
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
62+
separator = " ", -- the character that will be used to separate each field provided in results.fields
63+
term_icon = "", -- the icon that will be used for the term_icon in results.fields
6564

6665
},
6766
search = {
@@ -76,18 +75,102 @@ By default, the below table is passed to the `setup` function:
7675

7776
| Property | Type | Default Value | Description |
7877
|--------------------|--------------------------------|---------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
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. |
78+
| **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. See Mappings for more info. |
8079
| **telescope_titles.preview** | `string` | "Preview" | Title of the preview buffer in telescope. Any string. |
8180
| **telescope_titles.prompt** | `string` | " Pick Term" | Title of the prompt buffer in telescope. Any string. |
8281
| **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`. |
82+
| **results.separator** | `string` | " " | The character used to separate each field in `results.field`. Any string, though a space character and a pipe character are the most commonly used. |
83+
| **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 for more info. |
84+
| **results.term_icon** | `string` | "" | The icon used for `term_icon` in `results.fields`. Any string. |
85+
| **search.field** | `string` | "term_name" | The field that telescope's fuzzy search will use. Doesn't need to be a value provided in `results.fields`. Valid strings are: `bufname`, `bufnr`, `state`, `term_name`. |
86+
| **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.fields`. Valid strings are: `bufnr`, `recency`, `state`, `term_name`. |
8887
| **sort.ascending** | `boolean` | true | Determines the order used for sorting the telescope results. `true` = ascending, `false` = descending. |
88+
### Mappings
89+
90+
The `mappings` table should look something like this:
91+
92+
```lua
93+
local toggleterm_manager = require("toggleterm-manager")
94+
local actions = toggleterm_manager.actions
95+
96+
toggleterm_manager.setup {
97+
mappings = {
98+
i = {
99+
["<CR>"] = { action = actions.open_term, exit_on_action = true },
100+
["<C-d>"] = { action = actions.delete_term, exit_on_action = false },
101+
},
102+
n = {
103+
["<CR>"] = { action = actions.open_term, exit_on_action = true },
104+
["x"] = { action = actions.delete_term, exit_on_action = false },
105+
},
106+
},
107+
}
108+
```
109+
110+
Note that each key in the table should correspond to the NeoVim mode that the mappings should apply to (`i` for insert, `n` for normal). Each mode key should contain another table of key/value pairs where the key is the keybinding and the value is another table of key/value pairs. The valid keys of that table are `action`, which takes a function that manipulates a terminal in some way and `exit_on_action`, which determines if the telescope window should be closed on the execution of the action.
111+
112+
#### Actions
113+
114+
There are six pre-built actions that can be mapped to key bindings within the telescope window.
115+
116+
- `create_term`: Create a new terminal and open it. If `exit_on_action = true`, focus it. If `toggleterm`'s direction is `float` and `exit_on_action = false`, create a hidden terminal.
117+
- `create_and_name_term`: Create and name a new terminal and open it. If `exit_on_action = true`, focus it. If `toggleterm`'s direction is `float` and `exit_on_action = false`, create a hidden terminal. The name will be reflected in the `term_name` field if it's provided in `results.field`.
118+
- `rename_term`: Rename a terminal. If `exit_on_action = true` and the terminal is open, focus it. The name will be reflected in the `term_name` field if it's provided in `results.field`.
119+
- `open_term`: Open a terminal. If `exit_on_action = true`, focus it. If `exit_on_action = false` and `toggleterm`'s direction is `float`, this action won't do anything.
120+
- `toggle_term`: Toggle a terminal open or closed. If toggling open and `exit_on_action = true`, focus it.
121+
- `delete_term`: Delete a terminal.
122+
123+
> [!Floating toggleterm windows]
124+
> When configuring `toggleterm` (not `toggleterm-manager`), there is a property called `direction`, which takes a value of `horizontal`, `vertical`, or `float`. Some of the actions behave differently if `direction` is `float`. This is because of how NeoVim handles floating windows. Telescope is already a floating window so if, for example, `direction` is set to `float`, and the `create_term` action is called with `exit_on_action = false`, there would normally be a flash caused by opening a `toggleterm` float and switching back to telescope really fast. To prevent this, the `toggleterm` window will be created as a `hidden` terminal. Note that the `open_mapping` in `toggleterm` config won't be able to toggle these terminals open/closed.
125+
126+
#### Custom Actions
127+
128+
User-created functions can also be provided. Any function passed in as an action will receive two arguments: `prompt_bufnr` and `exit_on_action`.
129+
130+
```lua
131+
local function my_custom_action(prompt_bufnr, exit_on_action)
132+
133+
end
134+
```
135+
136+
See `actions/init.lua` for examples of creating actions.
137+
138+
### Results
139+
140+
The `results` property allows for easy customization of how toggleterm's terminal buffers appear in the telescope results buffer. `results.fields` allows for specifying the order that the results fields should appear, from left to right. Any combination and any number of the valid fields may be provided.
141+
142+
#### Valid Strings for `results.fields`
89143

144+
| Field | Description |
145+
|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------|
146+
| `bufname` | File name of the terminal buffer. |
147+
| `bufnr` | Buffer number of the terminal. |
148+
| `space` | Create additional space in between fields. |
149+
| `state` | Current state of the terminal buffer. `h` = hidden, `a` = active |
150+
| `term_icon` | An icon of a terminal. This icon can be overridden with the `results.term_icon` property. |
151+
| `term_name` | `toggleterm`'s `display_name` of the terminal, if assigned. Else, the `id`/`toggle_number` of the terminal assigned by `toggleterm` upon creation. |
90152

91-
### `results_format`
153+
#### Results Highlight Groups
154+
155+
The background and foreground colors of the results fields can also be customized by pairing any one of the above fields with a valid highlight group.
156+
157+
#### Examples
158+
159+
```lua
160+
local toggleterm_manager = require("toggleterm-manager")
161+
local actions = toggleterm_manager.actions
92162

93-
This propery allows for easy customization of how the terminal buffers appear in the telescope window.
163+
toggleterm_manager.setup {
164+
results = {
165+
fields = { "term_icon", "term_name", "space", "state" }
166+
},
167+
}
168+
```
169+
170+
Example of providing highlight groups:
171+
172+
```lua
173+
results = {
174+
fields = { "state", "space", { "bufnr", "TelescopeResultsIdentifier" }, "space", "term_icon", { "bufname", "Function" }}
175+
}
176+
```

0 commit comments

Comments
 (0)