Archives
/
nvim-libmodal
mirror of https://github.com/Iron-E/nvim-libmodal
2
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update documentation

Browse Source
pull/9/head release/0.9.0
Iron-E 4 years ago
parent f335c7c142
commit 636c8bfe75
No known key found for this signature in database
GPG Key ID: 19B71B7B7B021D22
2 changed files with 199 additions and 96 deletions
Show Stats Download Patch File Download Diff File

96
README.md
Unescape Escape View File

@ -10,6 +10,15 @@ Unfortunately, during `vim-libmodal`'s development several problems with Vimscri
Note that cross-compatability does not mean that `vim-libmodal` and `nvim-libmodal` can be installed at the same time— as a matter of fact, they are developed specifically to replace each other for specific platforms. If you use Vim, use `vim-libmodal`. If you use Neovim, use `nvim-libmodal`. If you are a plugin creator, all code that works for `vim-libmodal` will work with `nvim-libmodal`, but the reverse is not true.
# Requirements
* Neovim 0.4+.
* For compatability with `vim-libmodal`, Neovim 0.5+.
* For statusbar integration, Neovim 0.5+.
* `vim-libmodal` is _not_ installed.
[libmodal]: https://github.com/Iron-E/vim-libmodal
# Usage
The following plugins have been constructed using `nvim-libmodal`:
@ -26,10 +35,87 @@ The following samples have been constructed using `nvim-libmodal`:
See [vim-libmodal][libmodal] and the [docs](./doc) for more information.
# Requirements
## Statusline
* Neovim 0.4+.
* For compatability with `vim-libmodal`, Neovim 0.5+.
* `vim-libmodal` is _not_ installed.
You can add `libmodal` modes to your status line by using [galaxyline.nvim](https://github.com/glepnir/galaxyline.nvim.git). Here is an example configuration:
[libmodal]: https://github.com/Iron-E/vim-libmodal
```lua
local _COLORS =
{
black = {'#202020', 0, 'black'},
red = {'#ee4a59', 196, 'red'},
orange = {'#ff8900', 208, 'darkyellow'},
yellow = {'#f0df33', 220, 'yellow'},
green = {'#77ff00', 72, 'green'},
blue = {'#7090ff', 63, 'darkblue'},
purple = {'#cf55f0', 129, 'magenta'},
}
-- Statusline color
_COLORS.bar = {middle=_COLORS.gray_dark, side=_COLORS.black}
-- Text color
_COLORS.text = _COLORS.gray_light
-- Table which gets hex values from _COLORS.
local _HEX_COLORS = setmetatable(
{['bar'] = setmetatable({}, {['__index'] = function(_, key) return _COLORS.bar[key] and _COLORS.bar[key][1] or nil end})},
{['__index'] = function(_, key) local color = _COLORS[key] return color and color[1] or nil end}
)
local _MODES =
{
['c'] = {'COMMAND-LINE', _COLORS.red},
['ce'] = {'NORMAL EX', _COLORS.red},
['cv'] = {'EX', _COLORS.red},
['i'] = {'INSERT', _COLORS.green},
['ic'] = {'INS-COMPLETE', _COLORS.green},
['n'] = {'NORMAL', _COLORS.purple},
['no'] = {'OPERATOR-PENDING', _COLORS.purple},
['r'] = {'HIT-ENTER', _COLORS.blue},
['r?'] = {':CONFIRM', _COLORS.blue},
['rm'] = {'--MORE', _COLORS.blue},
['R'] = {'REPLACE', _COLORS.red},
['Rv'] = {'VIRTUAL', _COLORS.red},
['s'] = {'SELECT', _COLORS.blue},
['S'] = {'SELECT', _COLORS.blue},
['t'] = {'TERMINAL', _COLORS.orange},
['v'] = {'VISUAL', _COLORS.blue},
['V'] = {'VISUAL LINE', _COLORS.blue},
['!'] = {'SHELL', _COLORS.yellow},
-- libmodal
['TABS'] = _COLORS.tan,
['BUFFERS'] = _COLORS.teal,
['TABLES'] = _COLORS.orange_light,
}
require('galaxyline').section.left =
{
{ViMode = {
provider = function() -- auto change color according the vim mode
local mode_color = nil
local mode_name = nil
if vim.b.libmodalActiveModeName then
mode_name = vim.b.libmodalActiveModeName
mode_color = _MODES[mode_name]
else
local current_mode = _MODES[vim.fn.mode(true)]
mode_name = current_mode[1]
mode_color = current_mode[2]
end
-- If you have Iron-E/nvim-highlite, use this step.
-- If not, just manually highlight it with vim.cmd()
require('highlite').highlight('GalaxyViMode', {fg=mode_color, style='bold'})
return '▊ '..mode_name..' '
end,
highlight = {_HEX_COLORS.bar.side, _HEX_COLORS.bar.side},
separator = _SEPARATORS.right,
separator_highlight = {_HEX_COLORS.bar.side, get_file_icon_color}
}}
}
```

199
doc/libmodal.txt
Unescape Escape View File

@ -3,7 +3,7 @@
*nvim-libmodal*
================================================================================
0. Table of Contents *libmodal-toc*
0. Table of Contents *libmodal-toc*
1. About ................ |libmodal-about|
2. Usage ................ |libmodal-usage|
@ -16,7 +16,7 @@
9. Credits .............. |libmodal-credits|
================================================================================
1. About *libmodal-about*
1. About *libmodal-about*
|nvim-libmodal|:
- Author, Iron-E @ https://github.com/Iron-E & https://gitlab.com/Iron_E
@ -34,7 +34,7 @@ modes is also creator-defined, and is outlined in |libmodal-usage|.
See: |vim-modes|
--------------------------------------------------------------------------------
USE CASE *libmodal-use-case-example*
USE CASE *libmodal-use-case-example*
As an |init.vim| configuration grows, it becomes harder to create keybindings
that alphabetically represent the action that they perform. To get around
@ -60,7 +60,7 @@ Finally, there could be a help key, `?`, which would show exactly which keys
have been mapped and what they do.
You can see such a mode here:
* https://gist.github.com/Iron-E/f36116e8862ea03fd195e4e0a48cb05d
- https://gist.github.com/Iron-E/f36116e8862ea03fd195e4e0a48cb05d
Outside of the |libmodal-mode|, `n` still searches for the |last-pattern|, and
the buffers are not visibly numbered. Any setup that a |libmodal-mode| does to
@ -70,16 +70,16 @@ buffers persevere).
See: |libmodal-usage|
================================================================================
2. Usage *libmodal-usage*
2. Usage *libmodal-usage*
The |libmodal| interface is designed completely in |Lua|. It is compatable
with Vimscript, and so one may either:
1. Define a |Lua| interface for your mode (see |libmodal-examples|).
* Use |lua-require| as a |user-command|.
* See |lua-require-example| for information about how to do this.
* See `Iron-E/nvim-tabmode` for a complete example.
* See `Iron-E/mode-fugidiff.lua` on GitHub Gists for another example.
- Use |lua-require| as a |user-command|.
- See |lua-require-example| for information about how to do this.
- See `Iron-E/nvim-tabmode` for a complete example.
- See `Iron-E/mode-fugidiff.lua` on GitHub Gists for another example.
2. |call| `libmodal#Enter()` or `libmodal#Prompt()` from Vimscript.
The following is a reference for high-level functions meant to be used by mode
@ -93,9 +93,28 @@ See: |api|, |lua-api|, https://github.com/Iron-E/nvim-tabmode,
https://gist.github.com/Iron-E/f36116e8862ea03fd195e4e0a48cb05d
--------------------------------------------------------------------------------
FUNCTIONS *libmodal-usage-functions*
VARIABLES *libmodal-usage-variables*
*libmodal-mode* *libmodal#Enter()* *libmodal.mode.enter()*
`vim.b`.libmodalActiveModeName
The name of the currently active |libmodal-mode|.
Note: only available on Neovim 0.5+
Type: ~
`string`
Default Value: ~
`nil`
See also: ~
|b:| For more information about buffer variables.
|vim.b| For info about accessing |b:| from lua.
--------------------------------------------------------------------------------
FUNCTIONS *libmodal-usage-functions*
*libmodal-mode* *libmodal#Enter()* *libmodal.mode.enter()*
`libmodal.mode`.enter({name}, {instruction} [, {supressExit}])
`libmodal`#Enter({name}, {instruction} [, {supressExit}])
@ -210,7 +229,7 @@ FUNCTIONS *libmodal-usage-functions*
Return: ~
* The `function` used to undo changes made by the layer.
- The `function` used to undo changes made by the layer.
See also: ~
|libmodal-examples-layers| For an example.
@ -286,9 +305,8 @@ FUNCTIONS *libmodal-usage-functions*
|lua-eval| For type conversions between Vimscript to |Lua|.
|libmodal-examples-prompt| For examples of this function.
================================================================================
3. Examples *libmodal-examples*
3. Examples *libmodal-examples*
Below are examples written in |Lua| to help show how specific features of
|libmodal| may be implemented. In each example, the name of the mode is
@ -302,7 +320,7 @@ all be tested using the |luafile| |command|.
See: |libmodal-usage|, |libmodal-use-case|, |lua-require-example|.
--------------------------------------------------------------------------------
MODES *libmodal-examples-modes*
MODES *libmodal-examples-modes*
Using a callback `function`: >
local api = vim.api
@ -357,7 +375,7 @@ Using a |key-mapping| `table`: >
<
Exit Supression ~
*libmodal-examples-supress-exit*
*libmodal-examples-supress-exit*
Using a callback `function`: >
local libmodal = require('libmodal')
@ -400,7 +418,7 @@ Using a |key-mapping| `table`: >
<
Submodes ~
*libmodal-examples-submodes*
*libmodal-examples-submodes*
Using a callback `function`: >
local libmodal = require('libmodal')
@ -459,7 +477,7 @@ Using a |key-mapping| `table`: >
<
--------------------------------------------------------------------------------
LAYERS *libmodal-examples-layers*
LAYERS *libmodal-examples-layers*
>
local libmodal = require('libmodal')
@ -483,7 +501,7 @@ LAYERS *libmodal-examples-layers*
)
<
--------------------------------------------------------------------------------
PROMPTS *libmodal-examples-prompts*
PROMPTS *libmodal-examples-prompts*
Using a callback `function`: >
local libmodal = require('libmodal')
@ -526,13 +544,13 @@ Using a |command| `table`: >
<
================================================================================
4. Configuration *libmodal-configuration*
4. Configuration *libmodal-configuration*
The following specifies what settings may be used to configure
|libmodal-mode|s and |libmodal-prompt|s.
--------------------------------------------------------------------------------
HIGHLIGHT GROUPS *libmodal-highlight-groups*
HIGHLIGHT GROUPS *libmodal-highlight-groups*
The following |highlight-groups| can be |config|ured to change a mode's |color|s:
@ -550,7 +568,7 @@ Note: `LibmodalStar`'s name — while not indicative of its use — is used for
the two.
--------------------------------------------------------------------------------
TIMEOUTS *libmodal-timeouts* *g:libmodalTimeouts*
TIMEOUTS *libmodal-timeouts* *g:libmodalTimeouts*
When `libmodal.mode.enter()`'s {instruction} argument is a `table`, mode
creators may also enable the use of Vim's built-in 'timeout' feature.
@ -633,7 +651,7 @@ Mode creators who use `function` {instruction}s may define timeouts manually
using |timers|, which is how |libmodal| implements them internally.
================================================================================
5. License *libmodal-license*
5. License *libmodal-license*
`nvim-libmodal` – Create new "modes" for Neovim.
Copyright © 2020 Iron-E
@ -652,21 +670,21 @@ You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
================================================================================
6. Bugs *libmodal-bugs*
6. Bugs *libmodal-bugs*
* `libmodal#Enter()` does not work when {instruction} is a |funcref|.
* See |E5004|.
* `libmodal#Prompt()` does not work when {instruction} is a |funcref|.
* See |E5004|.
- `libmodal#Enter()` does not work when {instruction} is a |funcref|.
- See |E5004|.
- `libmodal#Prompt()` does not work when {instruction} is a |funcref|.
- See |E5004|.
================================================================================
7. Contributing *libmodal-contributing*
7. Contributing *libmodal-contributing*
The following describes what should be done if an individual wishes to
contribute something to the `Iron-E/nvim-libmodal` repository.
--------------------------------------------------------------------------------
CODE *libmodal-contributing-code*
CODE *libmodal-contributing-code*
Bugfixes ~
@ -701,7 +719,7 @@ person who knows the most about the feature being implemented is most
likely the one implementing it.
--------------------------------------------------------------------------------
DOCUMENTATION *libmodal-contributing-documentation*
DOCUMENTATION *libmodal-contributing-documentation*
If there is a problem with the documentation, or you see an area where it
could be improved, don't hesitate to submit an issue and a PR. At the very
@ -710,7 +728,7 @@ will serve to help yourself and others with more clear and concise wording, or
with more helpful and practical examples.
--------------------------------------------------------------------------------
ISSUES *libmodal-contributing-issues*
ISSUES *libmodal-contributing-issues*
Issues are greatly welcomed on the GitHub repository, whether they are bug
reports, feature requests, documentation improvements, or misunderstandings:
@ -726,159 +744,158 @@ When submitting an issue, please describe the following:
5. Attached media (screenshots, logs, etc.) (if applicable).
================================================================================
8. Changelog *libmodal-changelog*
8. Changelog *libmodal-changelog*
0.8.0 ~
Additions: ~
* Ability to use |lua| `function`s as values in a |libmodal-mode|
- Ability to use |lua| `function`s as values in a |libmodal-mode|
{instruction} `table` .
* Ability to use |lua| `function`s as values in a |libmodal-prompt|
- Ability to use |lua| `function`s as values in a |libmodal-prompt|
{instruction} `table` .
* Add |libmodal-mode| and |libmodal-prompt| kill functions
- Add |libmodal-mode| and |libmodal-prompt| kill functions
(|libmodal-lua-api.mode_exit()|).
0.7.0 ~
Additions: ~
* Ability to pass `function`s into |libmodal-mode| from Vimscript.
* Ability to pass `function`s into |libmodal-prompt| from Vimscript.
* Add examples for doing almost everything that this plugin can do, from
- Ability to pass `function`s into |libmodal-mode| from Vimscript.
- Ability to pass `function`s into |libmodal-prompt| from Vimscript.
- Add examples for doing almost everything that this plugin can do, from
Vimscript (although I still think Lua makes it easier).
0.6.3 ~
Fixes: ~
* Fix being unable to paste into Vim's command line after importing
- Fix being unable to paste into Vim's command line after importing
the `libmodal.util.api` table.
0.6.2 ~
Fixes: ~
* Remove unused variables
- Remove unused variables
0.6.1 ~
Fixes: ~
* Mode names with spaces or underscores are now represented correctly
- Mode names with spaces or underscores are now represented correctly
by |libmodal-lua-Vars.name()|.
0.6.0 ~
Additions: ~
* New module: |libmodal-layer|s.
* Allows for use of built-in modes with overwriting of keymaps.
* New class `libmodal.Layer`.
* New function `libmodal.layer.enter()`.
* New examples for new additions.
* `libmodal.collections.ParseTable`:
* Added new `:parseGet()` method to replace the `:get()`
- New module: |libmodal-layer|s.
- Allows for use of built-in modes with overwriting of keymaps.
- New class `libmodal.Layer`.
- New function `libmodal.layer.enter()`.
- New examples for new additions.
- `libmodal.collections.ParseTable`:
- Added new `:parseGet()` method to replace the `:get()`
implementation.
*
* Added new `libmodal.collections.ParseTable.parse()` method.
* You can override it to change how the `ParseTable` parses its keys.
* Added `ParseTable.stringSplit()`.
- Added new `libmodal.collections.ParseTable.parse()` method.
- You can override it to change how the `ParseTable` parses its keys.
- Added `ParseTable.stringSplit()`.
Breaking Changes: ~
* Moved `libmodal.Mode.Popup` to `libmodal.collections.Popup`.
* Changed `libmodal.collections.ParseTable.parseGet()` back to
- Moved `libmodal.Mode.Popup` to `libmodal.collections.Popup`.
- Changed `libmodal.collections.ParseTable.parseGet()` back to
`libmodal.collections.ParseTable.get()`.
* `:get()` requires that keys have been parsed according to
- `:get()` requires that keys have been parsed according to
`.parse()`.
Changes: ~
* Exposed more functionality of `libmodal.collections.Popup`.
- Exposed more functionality of `libmodal.collections.Popup`.
0.5.0 ~
Additions: ~
* New class `libmodal.collections.Stack`.
* New class `libmodal.Mode`.
* New class `libmodal.Mode.Popup`.
* New class `libmodal.Prompt`.
* New class `libmodal.Vars`.
- New class `libmodal.collections.Stack`.
- New class `libmodal.Mode`.
- New class `libmodal.Mode.Popup`.
- New class `libmodal.Prompt`.
- New class `libmodal.Vars`.
Breaking Changes: ~
* Moved `libmodal.mode.ParseTable` to `libmodal.collections.ParseTable`.
* Removed `libmodal.utils.vars`.
* Moved `libmodal.utils.Indicator` to `libmodal.Indicator`.
* Moved `libmodal.utils.Indicator.Entry` to
- Moved `libmodal.mode.ParseTable` to `libmodal.collections.ParseTable`.
- Removed `libmodal.utils.vars`.
- Moved `libmodal.utils.Indicator` to `libmodal.Indicator`.
- Moved `libmodal.utils.Indicator.Entry` to
`libmodal.Indicator.HighlightSegment`.
Changes: ~
* Allow creation of |libmodal-mode| and |libmodal-prompt| table-objects.
* Call `libmodal.Mode.new()` or `libmodal.Prompt.new()` to create one.
* Call `{mode}:enter()` to enter the mode.
* More consistent mode recursion with `libmodal.collections.Stack`.
* Mode creators can now override specific functionality by copying
- Allow creation of |libmodal-mode| and |libmodal-prompt| table-objects.
- Call `libmodal.Mode.new()` or `libmodal.Prompt.new()` to create one.
- Call `{mode}:enter()` to enter the mode.
- More consistent mode recursion with `libmodal.collections.Stack`.
- Mode creators can now override specific functionality by copying
portions of the source code, or changing the values that are
referenced by the mode directly.
* This allows for finer control over how a mode behaves.
* It also allows for modes to inherit each other through
- This allows for finer control over how a mode behaves.
- It also allows for modes to inherit each other through
`setmetatable()`.
* Removed program logic from `libmodal.mode.enter()`.
* Now internally calls `libmodal.Mode.new(…):enter()` instead.
* Removed program logic from `libmodal.prompt.enter()`.
* Now internally calls `libmodal.Prompt.new(…):enter()` instead.
- Removed program logic from `libmodal.mode.enter()`.
- Now internally calls `libmodal.Mode.new(…):enter()` instead.
- Removed program logic from `libmodal.prompt.enter()`.
- Now internally calls `libmodal.Prompt.new(…):enter()` instead.
Fixes: ~
* Fix unexpected behavior when repeating `libmodal.mode.enter()` calls
- Fix unexpected behavior when repeating `libmodal.mode.enter()` calls
with the from within themselves.
* Mode popup windows may be closed prematurely by entering two different
- Mode popup windows may be closed prematurely by entering two different
modes and then exiting them in reverse order, among other things. All
previously known mysterious behavior is corrected.
0.4.1 ~
Fixes: ~
* Fix reference to `libmodal/src/prompt` as `libmodal/src/path`.
- Fix reference to `libmodal/src/prompt` as `libmodal/src/path`.
0.4.0 ~
Additions: ~
* Add partial support for |vim-libmodal|.
- Add partial support for |vim-libmodal|.
Fixes: ~
* Fix bad reference to `vars.windows`.
* Fix bug where help was always shown upon entering an invalid key-combo in
- Fix bad reference to `vars.windows`.
- Fix bug where help was always shown upon entering an invalid key-combo in
`libmodal.mode.enter()`.
0.3.1 ~
Fixes: ~
* Fix bug where everytime `api.nvim_lecho()` was called, its {hlTables}
- Fix bug where everytime `api.nvim_lecho()` was called, its {hlTables}
would infinitely grow with placeholder "None" entries.
0.3.0 ~
Additions: ~
* Generate `?` mapping for |libmodal-mode|s.
- Generate `?` mapping for |libmodal-mode|s.
Fixes: ~
* Fix |libmodal-timeouts| not being respected.
- Fix |libmodal-timeouts| not being respected.
0.2.1 ~
Fixes: ~
* Fix `help` command completion being shown during an {instruction}
- Fix `help` command completion being shown during an {instruction}
callback `function` when none should be shown.
0.2.0 ~
Additions: ~
* |libmodal-prompt| implemetation from |vim-libmodal|.
* |libmodal-prompt|s now automatically generate `help` command if none is
- |libmodal-prompt| implemetation from |vim-libmodal|.
- |libmodal-prompt|s now automatically generate `help` command if none is
provided.
0.1.0 ~
Additions: ~
* |libmodal-mode| implementation from |vim-libmodal|.
- |libmodal-mode| implementation from |vim-libmodal|.
================================================================================
9. Credits *libmodal-credits*
9. Credits *libmodal-credits*
Credit Reason
--------------------- ----------------------------------

Write Preview
Loading…
Cancel
Save