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

Finish libmodal-lua docs

Browse Source
pull/3/head
Iron-E 4 years ago
parent 55629e77a0
commit 1946b0927f
No known key found for this signature in database
GPG Key ID: 19B71B7B7B021D22
9 changed files with 584 additions and 174 deletions
Show Stats Download Patch File Download Diff File

670
doc/libmodal-lua.txt
Unescape Escape View File

@ -2,24 +2,35 @@
*libmodal-lua*
*libmodal-dev*
=============================================================================
This is a document specifying the lower-level implementation of |libmodal|. If
one wishes to make use of it to more finely control their |libmodal-mode| or
|libmodal-prompt|, this document should be the primary reference.
Any material not covered here is covered in |libmodal-usage|.
See: |libmodal-usage|, |lua|, |lua-require-example|.
==============================================================================
0. Table of Contents *libmodal-lua-toc*
1. `libmodal` ............................. |libmodal-lua-libmodal|
2. `libmodal.base.globals` ................ |libmodal-lua-globals|
3. `libmodal.mode.ParseTable` ............. |libmodal-lua-ParseTable|
4. `libmodal.utils` ....................... |libmodal-lua-utils|
4.1. `libmodal.utils.api` ................... |libmodal-lua-api|
4.2. `libmodal.utils.Help` .................. |libmodal-lua-Help|
4.3. `libmodal.utils.Indicator` ............. |libmodal-lua-Indicator|
4.3.1. `libmodal.utils.Indicator.Entry` ....... |libmodal-lua-Entry|
4.4. `libmodal.utils.vars` .................. |libmodal-lua-vars|
4.5. `libmodal.utils.WindowState` ........... |libmodal-lua-Windowstate|
1. `libmodal` ............................. |libmodal-lua-libmodal|
2. `libmodal.base.globals` ................ |libmodal-lua-globals|
3. `libmodal.mode.ParseTable` ............. |libmodal-lua-ParseTable|
4. `libmodal.utils` ....................... |libmodal-lua-utils|
4.1. `libmodal.utils.api` ................... |libmodal-lua-api|
4.2. `libmodal.utils.Help` .................. |libmodal-lua-Help|
4.3. `libmodal.utils.Indicator` ............. |libmodal-lua-Indicator|
4.4. `libmodal.utils.vars` .................. |libmodal-lua-vars|
4.5. `libmodal.utils.WindowState` ........... |libmodal-lua-Windowstate|
==============================================================================
1. `libmodal` *libmodal-lua-libmodal*
Modules: ~
This is the base of |libmodal|. It can be imported using: >
local libmodal = require('libmodal')
<if |libmodal| is in your 'runtimepath'.
MODULES *libmodal-lua-modules*
* `libmodal`
* `libmodal.base`
@ -37,7 +48,172 @@ Modules: ~
==============================================================================
2. `libmodal.base.globals` *libmodal-lua-globals*
TODO.
These are global variables used throughout the project. They are never
modified and never meant TO be modified.
VARIABLES *libmodal-lua-globals-variables*
`globals`.DEFAULT_ERROR_TITLE *libmodal-lua-globals.DEFAULT_ERROR_TITLE*
The default error message header for |libmodal| errors.
Type: ~
`string`
Value: ~
"vim-libmodal error"
`globals`.ESC_NR *libmodal-lua-globals.ESC_NR*
The byte of the <Esc> character.
Type: ~
`number`
Value: ~
27
`globals`.TYPE_FUNC *libmodal-lua-globals.TYPE_FUNC*
The `string` yielded by `lua type(x)` when `x` is a `function`.
Type: ~
`string`
Value: ~
"function"
`globals`.TYPE_NUM *libmodal-lua-globals.TYPE_NUM*
The `string` yielded by `lua type(x)` when `x` is a `number`.
Type: ~
`string`
Value: ~
"number"
`globals`.TYPE_STR *libmodal-lua-globals.TYPE_STR*
The `string` yielded by `lua type(x)` when `x` is a `string`.
Type: ~
`string`
Value: ~
"string"
`globals`.TYPE_TBL *libmodal-lua-globals.TYPE_TBL*
The `string` yielded by `lua type(x)` when `x` is a `table`.
Type: ~
`string`
Value: ~
"table"
`globals`.VIM_FALSE *libmodal-lua-globals.VIM_FALSE*
The value Vimscript uses to return `false` (besides |v:false|).
Type: ~
`number`
Value: ~
0
`globals`.VIM_TRUE *libmodal-lua-globals.VIM_TRUE*
Type: ~
`number`
Value: ~
1
FUNCTIONS *libmodal-lua-globals-functions*
`globals`.isFalse({val}) *libmodal-lua-globals.isFalse()*
Determine whether or not some {val} is equal to `globals.VIM_FALSE`,
|v:false|, or `false`.
Parameters: ~
{val} The value to check. Should be a `boolean` or a `boolean`
expression.
Return: ~
* `true` if {val} is equal to `globals.VIM_FALSE`, |v:false|, or
`false`.
* `false` otherwise.
Example: ~
>
local libmodal = require('libmodal')
-- Get Lua's truth values.
local falseValue = false
local trueValue = true
-- Get Vim's `v:` truth values.
local v_falseValue = vim.api.nvim_get_vvar('false')
local v_trueValue = vim.api.nvim_get_vvar('true')
-- Get Vimscript's truth values.
local vim_falseValue = libmodal.globals.VIM_FALSE
local vim_trueValue = libmodal.globals.VIM_TRUE
--[[ Test the function. ]]
print(libmodal.globals.isFalse(falseValue))
print(libmodal.globals.isFalse(v_falseValue))
print(libmodal.globals.isFalse(vim_falseValue))
print(libmodal.globals.isFalse(trueValue))
print(libmodal.globals.isFalse(v_trueValue))
print(libmodal.globals.isFalse(vim_trueValue))
<
`globals`.isTrue({val}) *libmodal-lua-globals.isTrue()*
Determine whether or not some {val} is equal to `globals.VIM_TRUE`,
|v:true|, or `true`.
Parameters: ~
{val} The value to check. Should be a `boolean` or a `boolean`
expression.
Return: ~
* `true` if {val} is equal to `globals.VIM_TRUE`, |v:true|, or `true`.
* `false` otherwise.
Example: ~
>
local libmodal = require('libmodal')
-- Get Lua's truth values.
local falseValue = false
local trueValue = true
-- Get Vim's `v:` truth values.
local v_falseValue = vim.api.nvim_get_vvar('false')
local v_trueValue = vim.api.nvim_get_vvar('true')
-- Get Vimscript's truth values.
local vim_falseValue = libmodal.globals.VIM_FALSE
local vim_trueValue = libmodal.globals.VIM_TRUE
--[[ Test the function. ]]
print(libmodal.globals.isTrue(falseValue))
print(libmodal.globals.isTrue(v_falseValue))
print(libmodal.globals.isTrue(vim_falseValue))
print(libmodal.globals.isTrue(trueValue))
print(libmodal.globals.isTrue(v_trueValue))
print(libmodal.globals.isTrue(vim_trueValue))
<
==============================================================================
3. `libmodal.mode.ParseTable` *libmodal-lua-ParseTable*
@ -47,19 +223,20 @@ keybinding:expression pairs.
See: |libmodal-mode| for more information.
Variables ~
*libmodal-lua-ParseTable-variables*
VARIABLES *libmodal-lua-ParseTable-variables*
`ParseTable`.CR *libmodal-lua-ParseTable-CR*
`ParseTable`.CR *libmodal-lua-ParseTable.CR*
The character number for <CR>.
Type: ~
`number`
Value: ~
13
Functions ~
*libmodal-lua-ParseTable-functions*
FUNCTIONS *libmodal-lua-ParseTable-functions*
`ParseTable`.new({userTable}) *libmodal-lua-ParseTable.new()*
@ -77,12 +254,17 @@ Functions ~
Example: ~
>
local libmodal = require('libmodal')
-- Create a mock set of user mappings.
local userTable = {
['zf'] = "echo 'Hello!'"
['zf'] = "echo 'Hello!'",
['zfo'] = "tabnew"
}
-- Create a new `ParseTable`
local parseTable = libmodal.mode.ParseTable.new(userTable)
-- Print the `parseTable`.
print(vim.inspect(parseTable))
<
@ -107,6 +289,8 @@ Functions ~
Example: ~
>
local libmodal = require('libmodal')
-- Simulate user input.
local userInput = {122, 102} -- {'z', 'f'}
@ -144,7 +328,7 @@ Functions ~
print(vim.inspect(parseTable))
-- this will return a `table`
parseTable:parsePut({'zfc', 'split'})
parseTable:parsePut('zfc', 'split')
-- Inspect it to show the difference.
print(vim.inspect(parseTable))
<
@ -175,7 +359,7 @@ Functions ~
}
-- Add the dummy keybindings.
parseTable:parsePut(unparsedUserKeybinds)
parseTable:parsePutAll(unparsedUserKeybinds)
-- Inspect it to show the difference.
print(vim.inspect(parseTable))
@ -190,7 +374,7 @@ Functions ~
Provides extra utilities to the |libmodal| library.
Functions ~
FUNCTIONS *libmodal-lua-utils-functions*
`utils`.showError({pcallErr}) *libmodal-lua-utils.showError*
@ -199,15 +383,43 @@ Functions ~
Parameters: ~
{pcallErr} the error generated by `pcall()`.
Example: ~
>
local libmodal = require('libmodal')
-- Run `pcall` on an anonymous function.
local noErrors, pcallErr = pcall(function()
-- This will always produce an error.
return "" .. true
end)
-- If there were errors…
if not noErrors then
-- Show the error.
libmodal.utils.showError(pcallErr)
end
<
=============================================================================
4.1. `libmodal.utils.api` *libmodal-lua-api*
Functions ~
Provides extensions to the `vim.api` |Lua| library.
See: |API|.
FUNCTIONS *libmodal-lua-api-functions*
`api`.nvim_bell() *libmodal-lua-api.nvim_bell()*
Make vim ring the visual/audio bell, if it is enabled.
Example: ~
>
local libmodal = require('libmodal')
libmoal.utils.api.nvim_bell()
<
See also: ~
'belloff' For bell settings.
'errorbells' For bell settings.
@ -225,8 +437,12 @@ Functions ~
Example: ~
>
local libmodal = require('libmodal')
-- Set a mock variable to 3.
libmodal.utils.api.nvim_set_var('foo', 3)
print(libmodal.utils.api.nvim_exists('g', 'foo')) -- true
libmodal.utils.api.nvim_command('unlet g:foo')
-- Note that the colon should not go after the scope identifier.
print(libmodal.utils.api.nvim_exists('g', 'foo')) -- false
<
@ -242,51 +458,152 @@ Functions ~
Example: ~
>
local libmodal = require('libmodal')
-- Get one character of user input.
local char = string.char(libmodal.utils.api.nvim_input())
-- … wait for user to press a character …
-- Print the character.
print(char)
<
CONTINUE HERE
`api`.nvim_lecho({hlTables}) *libmodal-lua-api.nvim_lecho()*
--[[ SUMMARY:
* Echo a table of {`hlgroup`, `str`} tables.
* Meant to be read as "nvim list echo".
]]
--[[ PARAMS:
* `hlTables` => the tables to echo with highlights.
]]
Echo an `Indicator`.
Meant to be read as "nvim list echo".
Parameters: ~
{hlTables} The `tables` to |echo| with |highlights|.
Example: ~
>
local libmodal = require('libmodal')
-- Create an indicator.
local indicator = libmodal.utils.Indicator.mode('FOO')
-- Show the indicator.
libmodal.utils.api.nvim_lecho(indicator)
<
`api`.nvim_redraw() *libmodal-lua-api.nvim_redraw()*
--[[ SUMMARY:
* Run `mode` to refresh the screen.
* The function was not named `nvim_mode` because that would be really confusing given the name of this plugin.
]]
Run |mode| to refresh the screen.
The function was not named `nvim_mode` because that would be really
confusing given the name of this plugin.
Example: ~
>
local libmodal = require('libmodal')
local api = vim.api
-- Echo hello and prompt for input before continuing.
api.nvim_command("echo 'Hello!'")
api.nvim_call_function('getchar', {})
-- Clear the screen.
libmodal.utils.api.nvim_redraw()
<
`api`.nvim_show_err({title}, {msg}) *libmodal-lua-api.nvim_show_err()*
--[[ SUMMARY:
* Show a `title` error.
]]
--[[ PARAMS:
* `title` => the title of the error.
* `msg` => the message of the error.
]]
Show a {title}-error with a given {msg}.
Parameters: ~
{title} The title of the error.
{msg} The message of the error.
Example: ~
>
local libmodal = require('libmodal')
-- Show an error.
libmodal.utils.api.nvim_show_err(
-- Use the default error title.
libmodal.globals.DEFAULT_ERROR_TITLE,
-- Use a custom error message.
'This is a test error!'
)
<
==============================================================================
4.2. `libmodal.utils.Help` *libmodal-lua-Help*
TODO.
Allows for the creation of a default "Help" table.
By default, this "Help" is shown by pressing `?` in a |libmodal-mode| or by
entering "help" into a |libmodal-prompt|.
FUNCTIONS *libmodal-lua-Help-functions*
`Help`.new({commandsOrMaps}, {title}) *libmodal-lua-Help.new()*
Create a default help table with `commandsOrMaps` and vim expressions.
Parameters: ~
{commandsOrMaps} The `table` of |command|s or |map|pings to Vim |expression|s.
{title} The leftmost table column's title.
Return: ~
A new `Help`.
Example: ~
>
local libmodal = require('libmodal')
-- Create a table of mock user commands.
local commands = {
['close'] = 'tabclose',
['new'] = 'tabnew'
}
-- Create a table of mock user maps.
local maps = {
['zf'] = 'split',
['zfo'] = 'echo "Hello!"'
}
local commandHelp = libmodal.utils.Help.new(commands, 'COMMANDS')
local mapsHelp = libmodal.utils.Help.new(maps, 'MAPS')
<
`self`:show() *libmodal-lua-Help.show()*
Show the contents of this `Help`.
Example: ~
>
local libmodal = require('libmodal')
-- Create a table of mock user commands.
local commands = {
['close'] = 'tabclose',
['new'] = 'tabnew'
}
-- Create a table of mock user maps.
local maps = {
['zf'] = 'split',
['zfo'] = 'echo "Hello!"'
}
local commandHelp = libmodal.utils.Help.new(commands, 'COMMANDS')
local mapsHelp = libmodal.utils.Help.new(maps, 'MAPS')
commandHelp:show()
mapsHelp:show()
<
==============================================================================
4.3. `libmodal.utils.Indicator` *libmodal-lua-Indicator*
Functions ~
Provides creation sources for mode and prompt |echo| / |echohl| `string`s.
FUNCTIONS *libmodal-lua-indicator-functions*
`Indicator`.mode({modeName}) *libmodal-lua-Indicator.mode()*
@ -298,7 +615,7 @@ Functions ~
Example: ~
>
local libmodal = require('libmodal')
local indicator = libmodal.utils.Indicator.new('FOO')
local indicator = libmodal.utils.Indicator.mode('FOO')
libmodal.utils.api.nvim_lecho(indicator)
<
@ -317,121 +634,176 @@ Functions ~
Example: ~
>
local libmodal = require('libmodal')
local indicator = libmodal.utils.Indicator.new('FOO')
local indicator = libmodal.utils.Indicator.prompt('FOO')
print(indicator) -- you can't use `nvim_lecho` with this one.
<
See also: ~
|libmodal-prompt| For this function's use.
==============================================================================
4.3.1. `libmodal.utils.Indicator.Entry` *libmodal-lua-Entry*
4.4. `libmodal.utils.vars` *libmodal-lua-vars*
Provides an interface between Vimscript and Lua instance variables that are
created during a |libmodal-mode| or |libmodal-prompt|'s execution.
Several `vars` are created by default:
Name Use
------------------ -----------------------------------------------------
`vars.buffers` Buffers that hold |nvim_open_win()| text.
`vars.combos` `ParseTable`s when |libmodal-mode|'s {instruction} is a
`table`.
`vars.completions` |libmodal-prompt| completions.
`vars.exit` |libmodal-mode|'s {supressExit}.
`vars.input` Keeping user input history during |libmodal-mode|.
`vars.timeouts` Tracks if |libmodal-timeouts| are enabled for a mode.
`vars.timer` Tracks if there is an active |timer| for a mode.
`vars.windows` Tracks |nvim_open_win()| handles.
VARIABLES *libmodal-lua-vars-variables*
`vars`.libmodalTimeouts
Functions ~
The value of `g:libmodalTimeouts`.
`Entry`.new({hlgroup}, {str}) *libmodal-lua-Entry.new()*
Type: ~
`boolean`/`number`
Create a new `Indicator.Entry`.
Value: ~
`vim.api.nvim_get_var('libmodalTimeouts')`
`self`.instances
Instances of variables pertaining to a certain mode.
Type: ~
`table`
Value: ~
Starts as `{}`.
FUNCTIONS *libmodal-lua-vars-functions*
`self`:name({modeName}) *libmodal-lua-vars.name()*
Get the name of this variable's global setting for a specific {modeName}.
Note: not all variables have a global setting. See |libmodal-usage| and
|libmodal-configuration| for what is pertinent.
Note: This function is case insensitive. {modeName} will always come out
lower case.
Parameters: ~
{hlgroup} The |highlight-group| to be used for this `Indicator.Entry`.
{str} The text for this `Indicator.Entry`.
{modeName} The name of the mode that this global setting is for.
Return: ~
A new `Indicator.Entry`.
The name of this variable's global setting for a specific {modeName}.
Example: ~
>
local libmodal = require('libmodal')
local entry = libmodal.utils.Indicator.Entry.new('Error', 'EXAMPLE!')
print(vim.inspect(entry))
-- Get the |libmodal-timeouts| variable for `FOO` mode.
print(libmodal.utils.vars.exit:name('FOO'))
<
==============================================================================
4.4. `libmodal.utils.vars` *libmodal-lua-vars*
`vars`.nvim_get({var}, {modeName}) *libmodal-lua-vars.nvim_get()*
Retrieve a {var} value for {modeName} from |nvim_get_var()|.
Parameters: ~
{var} The `vars` table to retrieve the value of.
(e.g. `vars.input`)
{modeName} The mode name this value is being retrieved for.
Return: ~
`vim.api.nvim_get_var( {var}:name({modeName}) )`
Example: ~
>
local libmodal = require('libmodal')
-- Set the 'g:fooModeExit' variable.
vim.api.nvim_set_var('fooModeExit', 1)
-- Get the `g:fooModeExit` variable.
print( libmodal.utils.vars.nvim_get(libmodal.utils.vars.exit, 'FOO') )
<
`vars`.nvim_set({var}, {modeName}, {val}) *libmodal-lua-vars.nvim_set()*
Set a {var} {val} for {modeName} with |nvim_set_var()|.
Parameters: ~
{var} The `vars` table to retrieve the value of.
(e.g. `vars.input`)
{modeName} The mode name this value is being retrieved for.
{val} The value to set {var} to.
Example: ~
>
local libmodal = require('libmodal')
-- Set the 'g:fooModeExit' variable.
libmodal.utils.vars.nvim_set(libmodal.utils.vars.exit, 'FOO', 1)
-- Get the `g:fooModeExit` variable.
print(vim.api.nvim_get_var('fooModeExit'))
<
`vars`:tearDown({modeName}) *libmodal-lua-vars.tearDown()*
Remove temporary variables created by the |libmodal-mode| {modeName}.
Parameters: ~
{modeName} The name of the |libmodal-mode| that created the variables.
Example: ~
>
local libmodal = require('libmodal')
-- Create a mock name for a mode.
local mode = 'foo'
-- Define a function to display all of the `vars`.
function print_vars()
for k, v in pairs(libmodal.utils.vars) do
if type(v) == libmodal.globals.TYPE_TBL and v['instances'] then
print(k)
print(vim.inspect(v))
print('===============')
end
end
end
-- Add some variable values for the mode.
libmodal.utils.vars.input.instances[mode] = {}
libmodal.utils.vars.timeouts.instances[mode] = true
libmodal.utils.vars.timer.instances[mode] = vim.loop.new_timer()
-- Print the `vars` with our new assigned values.
print_vars()
libmodal.utils.vars:tearDown(mode)
-- Print the `vars` after `tearDown`.
print([[
 
<<<<<<AFTER TEARDOWN.>>>>>>
 
]])
print_vars()
<
CONTINUE HERE.
--[[
/*
* MODULE `libmodal.utils.vars` %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
*/
--]]
local vars = {}
vars.libmodalTimeout = api.nvim_get_var('libmodalTimeouts')
====================================
--[[ SUMMARY:
* Create a new entry in `vars`
]]
--[[ PARAMS:
* `keyName` => the name of the key used to refer to this variable in `vars`.
* `varName` => the name of the variable as it is stored in vim.
]]
------------------------------------
local function new(keyName)
vars[keyName] = {
-- Instances of variables pertaining to a certain mode.
instances = {},
_varName = 'Mode'
.. string.upper(string.sub(keyName, 0, 1))
.. string.sub(keyName, 2),
---------------------------------
--[[ SUMMARY:
* Get the name of `modeName`s global setting.
]]
--[[ PARAMS:
* `modeName` => the name of the mode.
]]
---------------------------------
name = function(__self, modeName)
return modeName .. __self._varName
end,
}
end
====================================
--[[ SUMMARY:
* Retrieve a variable value.
]]
--[[ PARAMS:
* `var` => the `vars.*` table to retrieve the value of.
* `modeName` => the mode name this value is being retrieved for.
]]
------------------------------------
function vars.nvim_get(var, modeName)
return api.nvim_get_var(var:name(modeName))
end
function vars.nvim_set(var, modeName, val)
api.nvim_set_var(var:name(modeName), val)
end
================================
--[[ SUMMARY:
* Remove temporary variables created by `modeName`.
]]
--[[ PARAMS:
* `modeName` => the name of the mode that created the variables.
]]
--------------------------------
function vars:tearDown(modeName)
new('buffers' )
new('combos' )
new('completions' )
new('exit' )
new('input' )
new('timeout' )
new('timer' )
new('windows' )
==============================================================================
4.5 `libmodal.utils.WindowState` *libmodal-lua-WindowState*
Tracks 'winheight' and 'winwidth' when created, so that it can be modified
freely and then restored later.
FUNCTIONS *libmodal-lua-WindowState-functions*
`WindowState`.new() *libmodal-lua-WindowState.new()*
Create a table representing the size of the current window.
@ -454,5 +826,29 @@ new('windows' )
Restore the state of this `WindowState`.
Example: ~
>
local libmodal = require('libmodal')
local api = vim.api
-- Create a new `WindowState`.
local windowState = libmodal.utils.WindowState.new()
-- Set the 'winheight' to a new value.
api.nvim_set_option('winheight', 100)
-- Define a function to print the 'winheight' value.
local print_height = function()
api.nvim_command('echo &winheight')
end
-- Print the 'winheight' prior to `restore()`.
print_height()
-- Restore the `windowState`.
windowState:restore()
-- Print the 'winheight' after `restore()`ing.
print_height()
<
==============================================================================
vim:tw=78:ts=4:ft=help:norl:

54
doc/libmodal.txt
Unescape Escape View File

@ -33,8 +33,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
@ -109,10 +108,10 @@ Note: Examples for all topics covered here can be found in the "examples"
See: |api|, |lua-api|, https://github.com/Iron-E/nvim-tabmode
Functions ~
FUNCTIONS *libmodal-usage-functions*
*libmodal-mode* *libmodal.mode.enter()*
libmodal.mode.enter({name}, {instruction} [, {handleExit}])
`libmodal.mode`.enter({name}, {instruction} [, {handleExit}])
Enter a new |vim-mode| using {instruction} to determine what actions will
be taken upon specific user inputs.
@ -178,7 +177,7 @@ libmodal.mode.enter({name}, {instruction} [, {handleExit}])
*libmodal-prompt* *libmodal.prompt.enter()*
libmodal.prompt.enter({name}, {instruction} [, {completions}])
`libmodal.prompt`.enter({name}, {instruction} [, {completions}])
Besides accepting user input like keys in |Normal-mode|, |libmodal| is
also capable of prompting the user for |input| like |Cmdline-mode|. To
@ -241,8 +240,7 @@ all be tested using the |luafile| |command|.
See: |libmodal-usage|, |libmodal-use-case|, |lua-require-example|.
libmodal.mode.enter() ~
*libmodal-examples-mode*
MODES *libmodal-examples-mode*
Using a callback `function`: >
local api = vim.api
@ -286,6 +284,7 @@ Using a |key-mapping| `table`: >
libmodal.mode.enter('FOO', fooModeCombos)
<
Exit Supression ~
*libmodal-examples-supress-exit*
Using a callback `function`: >
@ -318,6 +317,7 @@ Using a |key-mapping| `table`: >
libmodal.mode.enter('FOO', fooModeCombos, true)
<
Submodes ~
*libmodal-examples-submodes*
Using a callback `function`: >
@ -360,8 +360,7 @@ Using a |key-mapping| `table`: >
<
libmodal.prompt.enter() ~
*libmodal-examples-prompt*
PROMPTS *libmodal-examples-prompt*
Using a callback `function`: >
local libmodal = require('libmodal')
@ -396,16 +395,15 @@ Using a |command| `table`: >
==============================================================================
4. Configuration *libmodal-configuration*
Highlighting ~
*libmodal-highlight-groups*
HIGHLIGHT GROUPS *libmodal-highlight-groups*
The following |highlight-groups| can be |config|ured to change a mode's |color|s:
Name Default Description
---- ------- -----------
`LibmodalPrompt` `ModeMsg` Color for the mode text.
`LibmodalStar` `StatusLine` Color for the prompt text.
Name Default Description
---------------- ------------ --------------------------
`LibmodalPrompt` `ModeMsg` Color for the mode text.
`LibmodalStar` `StatusLine` Color for the prompt text.
Note: `LibmodalStar`'s name — while not indicative of its use — is used for
the sake of backwards compatability.
@ -414,23 +412,32 @@ Note: `LibmodalStar`'s name — while not indicative of its use — is used for
when Neovim 0.5 launches that will introduce interoperaability between
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.
To enable 'timeout's, one may set the following |variables|:
Lua: ~
>
" Set libmodal modes to turn timeouts on.
vim.api.nvim_set_var('libmodalTimeouts', true)
" Enable timeouts for specific mode.
vim.api.nvim_set_var('{name}ModeTimeouts', true)
<
Vimscript: ~
>
" Set libmodal modes to turn timeouts on.
let g:libmodalTimeouts = 1
" Enable timeouts for specific mode.
let g:{name}ModeTimeout = 1
let g:{name}ModeTimeouts = 1
<
Similarly, to disable them, one may set them to `0`.
When `g:libmodalTimeouts` or `g:{name}ModeTimeout` is set to `1`, |libmodal|
When `g:libmodalTimeouts` or `g:{name}ModeTimeouts` is set to `1`, |libmodal|
will automatically execute commands that have mappings that might also be
longer mappings. For example:
If a mode specifies `zf` and `zfo` as mappings,
@ -517,7 +524,7 @@ along with this program. If not, see <http://www.gnu.org/licenses/>.
==============================================================================
7. Contributing *libmodal-contributing*
Code ~
CODE *libmodal-contributing-code*
Bugfixes ~
@ -551,7 +558,7 @@ Code ~
person who knows the most about the feature being implemented is most
likely the one implementing it.
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
@ -559,7 +566,7 @@ least it will exist in history if such an issue comes up again, and likely it
will serve to help yourself and others with more clear and concise wording, or
with more helpful and practical examples.
Issues ~
ISSUES *libmodal-contributing-issues*
Issues are greatly welcomed on the GitHub repository, whether they are bug
reports, feature requests, documentation improvements, or misunderstandings:
@ -580,6 +587,7 @@ When submitting an issue, please describe the following:
0.3.0 ~
* Generate `?` mapping for |libmodal-mode|s.
* Fix |libmodal-timeouts| not being respected.
0.2.1 ~

2
lua/libmodal/src/base/globals.lua
Unescape Escape View File

@ -12,7 +12,7 @@ local globals = {}
*/
--]]
globals.DEFAULT_ERROR_MESSAGE = 'vim-libmodal error'
globals.DEFAULT_ERROR_TITLE = 'vim-libmodal error'
globals.ESC_NR = 27
globals.TYPE_FUNC = 'function'
globals.TYPE_NUM = 'number'

14
lua/libmodal/src/mode/init.lua
Unescape Escape View File

@ -96,7 +96,9 @@ local function _comboSelect(modeName)
end
clearUserInput = true
-- The command was a table, meaning that it MIGHT match.
elseif commandType == globals.TYPE_TBL then
elseif commandType == globals.TYPE_TBL
and globals.isTrue(vars.timeouts.instances[modeName])
then
-- Create a new timer
vars.timer.instances[modeName] = vim.loop.new_timer()
@ -140,12 +142,14 @@ local function _initCombos(modeName, comboTable)
local doTimeout = nil
-- Read the correct timeout variable.
if api.nvim_exists('g', vars.timeout:name(modeName)) then
doTimeout = vars.nvim_get(vars.timeout, modeName)
else doTimeout = vars.libmodalTimeout end
if api.nvim_exists('g', vars.timeouts:name(modeName)) then doTimeout =
vars.nvim_get(vars.timeouts, modeName)
else doTimeout =
vars.libmodalTimeouts
end
-- Assign the timeout variable according to `doTimeout`
vars.timeout.instances[modeName] = doTimeout
vars.timeouts.instances[modeName] = doTimeout
-- create a floating window
local buf = api.nvim_create_buf(false, true)

2
lua/libmodal/src/prompt/init.lua
Unescape Escape View File

@ -147,7 +147,7 @@ function prompt.enter(...)
elseif userInput == _HELP then -- the user did not define a 'help' command, so use the default.
vars.help.instances[modeName]:show()
else -- show an error.
api.nvim_show_err(globals.DEFAULT_ERROR_MESSAGE, 'Unknown command')
api.nvim_show_err(globals.DEFAULT_ERROR_TITLE, 'Unknown command')
end
else
args[2]()

4
lua/libmodal/src/utils/Help/init.lua
Unescape Escape View File

@ -72,9 +72,11 @@ function Help.new(commandsOrMaps, title)
[1] = ' ',
[2] = table.concat(tabAlign({
[title] = 'VIM EXPRESSION',
})),
[3] = table.concat(tabAlign({
[helpSeparator] = '--------------'
})),
[3] = table.concat(tabAlign(commandsOrMaps)),
[4] = table.concat(tabAlign(commandsOrMaps)),
-----------------------
--[[ SUMMARY:
* Show the contents of this `Help`.

4
lua/libmodal/src/utils/api.lua
Unescape Escape View File

@ -106,12 +106,12 @@ end
* `msg` => the message of the error.
]]
--------------------------------------
local returnEntry = Entry.new('Question', '\nPress any key to return.')
-- local returnEntry = Entry.new('Question', '\nPress any key to return.')
function api.nvim_show_err(title, msg)
api.nvim_lecho({
Entry.new('Title', tostring(title) .. '\n'),
Entry.new('Error', tostring(msg)),
returnEntry
-- returnEntry
})
api.nvim_call_function('getchar', {})
end

2
lua/libmodal/src/utils/init.lua
Unescape Escape View File

@ -37,7 +37,7 @@ utils.WindowState = require('libmodal/src/utils/WindowState')
function utils.showError(pcallErr)
utils.api.nvim_bell()
utils.api.nvim_show_err(
globals.DEFAULT_ERROR_MESSAGE,
globals.DEFAULT_ERROR_TITLE,
api.nvim_get_vvar('throwpoint')
.. '\n' ..
api.nvim_get_vvar('exception')

6
lua/libmodal/src/utils/vars.lua
Unescape Escape View File

@ -14,7 +14,7 @@ local api = vim.api
--]]
local vars = {}
vars.libmodalTimeout = api.nvim_get_var('libmodalTimeouts')
vars.libmodalTimeouts = api.nvim_get_var('libmodalTimeouts')
--[[
/*
@ -48,7 +48,7 @@ local function new(keyName)
]]
---------------------------------
name = function(__self, modeName)
return modeName .. __self._varName
return string.lower(modeName) .. __self._varName
end,
}
end
@ -90,7 +90,7 @@ new('completions' )
new('exit' )
new('help' )
new('input' )
new('timeout' )
new('timeouts' )
new('timer' )
new('windows' )

Write Preview
Loading…
Cancel
Save