You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Apr 24, 2022. It is now read-only.
The entrance of modes is user-defined, and their exit defaults to `<Esc>`. The function and name of modes is also user-defined, and is outlined in the documentation.
9
+
Forked from [`vim-win`](https://github.com/dstein64/vim-win):
`libmodal` is a Neo/vim library/plugin aimed at simplifying the creation of new "modes" (e.g. Insert, Normal). The entrance of modes is user-defined, and their exit defaults to `<Esc>`. The function and name of modes is also user-defined, and is outlined in `libmodal-usage`.
9
14
10
15
# Installation
11
16
12
-
Use `packadd`or one of the many package managers:
17
+
Use the built-in package manager or one of the various package managers.
For an example of a plugin that uses `vim-libmodal`, see [vim-tabmode](https://github.com/Iron-E/vim-tabmode).
28
+
## Commands
29
+
30
+
### `libmodal#Enter`
31
+
32
+
`libmodal#Enter` takes three parameters. These parameters are not formally named by the editor (as `libmodal#Enter` is declared `libmodal#Enter(...)` ). However, the names of these parameters will be used throughout the document to describe the index of the parameter (see `E740`).
|`modeName`| 0 | The name for the mode when prompting the user. |
37
+
|`modeCallback`| 1 | The function used to control the mode. |
38
+
|`modeCombos`| 1 | A dictionary of `libmodal-key-combinations`. |
39
+
|`supressExit`| 2 | A flag to enable `libmodal-exit-supression`. |
24
40
25
-
## `libmodal#Enter`
41
+
- Note that _either_`modeCallback`_or_`modeCombos` may be specified, __not both__.
26
42
27
-
`libmodal#Enter` takes two arguments: `modeName` and `modeCallback`.
43
+
### `libmodal#Prompt`
44
+
45
+
`libmodal#Prompt` takes two parameters. These parameters are not formally named by the editor (as `libmodal#Prompt` is declared `libmodal#Prompt(...)` ). However, the names of these parameters will be used throughout the document to describe the index of the parameter (see `E740`).
|`modeName`| 0 | The name for the mode when prompting the user. |
32
50
|`modeCallback`| 1 | The function used to control the mode. |
33
-
|`modeCombos`| 1 | A dictionary of key combos. |
34
-
|`supressExit`| 2 |Whether or not to leave the mode on (`<Esc>`).|
51
+
|`modeCommands`| 1 | A dictionary of commands→strings to execute.|
52
+
|`commandList`| 2 |A list of the commands in a `modeCallback`. |
35
53
36
-
Note that either `modeCallback` OR `modeCombos` may be specified, not both.
54
+
- Note that either `modeCallback` OR `modeCommands` may be specified, not both.
55
+
- Note that `commandList` is an optional parameter.
56
+
- It is used as a completion source for when `modeCallback` is specified.
57
+
- Additionally, `commandList` is IGNORED when `modeCommands` is specified since completions can be created from the dictionary keys.
58
+
- If `commandList` is not specified when `modeCallback` is, no completions will be provided for the prompt.
37
59
38
60
## Receiving Input
39
61
40
-
When a user of `libmodal` calls `libmodal#Enter`, the `modeName` parameter is used to generate a __unique global variable__ for the specific purpose of receiving said input. The variable is generated as follows:
62
+
When a user of `libmodal` calls `libmodal#Enter` or `libmodal#Prompt`, the `modeName` parameter is used to generate a unique global variable for the specific purpose of receiving said input. The variable is generated as follows:
41
63
42
64
```viml
43
65
let g:{tolower(a:modeName)}ModeInput = …
@@ -47,6 +69,8 @@ For example, if `modeName` is 'FOO', then the variable that is created is `g:foo
47
69
48
70
## Creating Modes
49
71
72
+
For an example of a plugin that uses `vim-libmodal`, see [vim-tabmode](https://github.com/Iron-E/vim-tabmode).
73
+
50
74
To define a new mode, you must first create a function to pass into `libmodal#Enter`. Example:
__Note the `funcref`__. It is important that it be present, else the call to `libmodal#Enter`will fail.
93
+
- Note the `funcref()` call. It must be there or else `libmodal#Enter`won't execute properly.
70
94
71
-
## Supressing Exit
72
-
73
-
When the `supressExit` parameter is specified, `libmodal#Enter` will ignore `<Esc>` presses and instead listen for changes to a unique variable created for the specific purpose of exiting the mode.
74
-
75
-
The variable is generated as follows:
76
-
77
-
```viml
78
-
let g:{tolower(a:modeName)}ModeExit = 0
79
-
```
80
-
81
-
When this variable becomes set to `1`, the mode will exit the next time that the `modeCallback` function returns.
82
-
83
-
## Key Combinations
95
+
### Key Combinations
84
96
85
97
While normally `libmodal` dictates that a user should define their own function for controlling a mode, there is a way to specify key combinations. If the second argument is set to a `modeCombos` dictionary, `libmodal#Enter` will automatically detect the caller's intent and pass control over to an auxilliary function built to handle pre-defined combos.
86
98
87
-
When providing `modeCombos`, it is important to note that one no longer has to receive input for themselves. Despite this, the unique variable (see `libmodal-receiving-input`) is still updated, and you can create a listener for it just like for any other variable. Note that one may still supress exit (see `libmodal-supressing-exit`) while defining key combinations.
99
+
When providing `modeCombos`, it is important to note that one no longer has to receive input for themselves. Despite this, the unique variable (see `libmodal-receiving-input`) is still updated, and you can create a listener for it just like for any other variable.
100
+
101
+
- Note that |libmodal-exit-supression| is still compatable with defining key combinations.
88
102
89
103
Here is an example that shows how to create a dictionary that defines the following actions:
90
104
@@ -106,33 +120,79 @@ And then to enter that mode, you can call:
106
120
call libmodal#Enter('BAR', s:barModeCombos)
107
121
```
108
122
109
-
`libmodal`'s internal processing of that dictionary becomes more useful the larger the dictionary is. Internally, `s:barModeCombos` is rendered into a tree-like structure that looks like this:
123
+
`libmodal`'s internal processing of that dictionary becomes more useful the larger the dictionary is. Internally, `s:barModeCombos` is rendered into a dictionary that looks like this:
110
124
111
125
![Internal Tree Structure](https://mermaid.ink/img/eyJjb2RlIjoiZ3JhcGggVEJcbnp7en0gLS0-IGZ7Zn1cbmYgLS0-IGN7Y31cbmYgLS0-IG97b31cblxuYyAtLT4gZWNob1tcImVjaG9tICZxdW90O0l0IHdvcmtzISZxdW90O1wiXVxubyAtLT4gdGFibmV3IiwibWVybWFpZCI6eyJ0aGVtZSI6ImRlZmF1bHQifSwidXBkYXRlRWRpdG9yIjpmYWxzZX0"Internal Tree Structure")
112
126
113
127
This allows `libmodal` to quickly determine which mappings are and are not part of the mode. Because of this method, modes with mappings that have similar beginnings are more efficient, and modes with more mappings get more benefit from the quick tree-like traversal.
114
128
115
-
Note that `libmodal#Enter` will only parse a `modeCombos` dict once upon entrance, so changes to the mapping dictionary that may occur while in a mode are not reflected until the mode is entered again and the dictionary is re-parsed.
129
+
- Note that |libmodal#Enter| will only parse a `modeCombos` dict once upon entrance.
130
+
- Changes to the mapping dictionary that may occur while in a mode are not reflected until the mode is entered again and the dictionary is re-parsed.
131
+
132
+
### Exit Supression
116
133
117
-
## Submodes
134
+
When the `supressExit` parameter is specified, `libmodal#Enter` will ignore `<Esc>` presses and instead listen for changes to a unique variable created for the specific purpose of exiting the mode. The variable is generated as follows:
118
135
119
-
`libmodal` has built-in support for entering additional modes while already in a `libmodal` mode.
136
+
```viml
137
+
let g:{tolower(a:modeName)}ModeExit = 0
138
+
```
139
+
140
+
When this variable becomes set to `1`, the mode will exit the next time that the `modeCallback` function returns.
141
+
142
+
## Creating Prompts
120
143
121
-
To enter another mode, one must only call`libmodal#Enter` from within a `modeCallback`. Additionally, when a user presses `<Esc>` they will automatically be taken back to the mode that they were previously inside of.
144
+
Besides accepting user input like keys in `Normal-mode`,`libmodal` is also capable of prompting the user for input like `Cmdline-mode`. To define a `Cmdline-mode`-like prompt, use `libmodal#Prompt` rather than `libmodal#Enter`.
122
145
123
-
To display this feature, one may alter the `echom 'It works!'` line from the above example, and change it to the following:
146
+
When `modeCommands` is specified, completions are provided for every key in the dictionary. See an example of this below:
124
147
125
148
```viml
126
-
call libmodal#Enter('BAR2', funcref('s:BarMode'))
149
+
let s:barModeCommands = {
150
+
\ 'new': 'tabnew',
151
+
\ 'close': 'tabclose',
152
+
\ 'last': 'tablast'
153
+
\}
127
154
```
128
155
129
-
This will trigger `libmodal#Enter` to start a new mode called 'BAR2'. When the user presses `<Esc>`, they will automatically be returned to 'BAR'.
156
+
When `modeCallback` is specified, completions must be provided separately. An equivalent to the above using a `modeCallback` would be:
157
+
158
+
```viml
159
+
" Define callback
160
+
function! s:BarMode() abort
161
+
if g:barModeInput ==# 'new'
162
+
execute 'tabnew'
163
+
elseif g:barModeInput ==# 'close'
164
+
execute 'tabclose'
165
+
elseif g:barModeInput ==# 'last'
166
+
execute 'tablast'
167
+
endif
168
+
endfunction
169
+
170
+
" Define completion list
171
+
let s:barModeCommandList = ['new', 'close', 'last']
172
+
```
173
+
174
+
You can then enter the mode using one of the following commands (depending on whether or not you used a dictionary or a callback):
- Note that if you want to create commands with arguments, you will need to use a callback.
184
+
185
+
# Submodes
186
+
187
+
`libmodal` has built-in support for entering additional modes while already in a `libmodal` mode. To enter another mode, one must only call `libmodal#Enter` from within a `modeCallback`. Additionally, when a user presses `<Esc>` they will automatically be taken back to the mode that they were previously inside of.
188
+
189
+
To display this feature, one view the [submode example](./examples/submodes.vim).
130
190
131
191
# Configuration
132
192
133
-
The following highlight groups can be configured to change the mode's colors:
193
+
The following highlight groups can be configured to change a mode's colors:
0 commit comments