nvim-libmodal/doc/libmodal-lua.txt

*libmodal-lua.txt*     Create modes for Neovim – Lua Referenc
*libmodal-lua*
*nvim-libmodal-lua*

1.   libmodal ............................. |libmodal-lua-libmodal|
2.   libmodal.mode ........................ |libmodal-lua-mode|
2.1. libmodal.mode.ParseTable ............. |libmodal-lua-parsetable|
3.   libmodal.prompt ...................... |libmodal-lua-prompt|
4.   libmodal.utils ....................... |libmodal-lua-utils|
4.1. libmodal.utils.api ................... |libmodal-lua-api|
4.2. libmodal.utils.Indicator ............. |libmodal-lua-indicator|
4.3. libmodal.utils.Indicator.Entry ....... |libmodal-lua-entry|
4.4. libmodal.utils.vars .................. |libmodal-lua-vars|
4.5. libmodal.utils.WindowState ........... |libmodal-lua-windowstate|


============================================================================

--[[
	/*
	 * MODULE `libmodal`
	 */
--]]

libmodal         = require('libmodal/src')
libmodal.mode    = require('libmodal/src/mode')
libmodal.prompt  = require('libmodal/src/prompt')
libmodal.utils   = require('libmodal/src/utils')

--[[
	/*
	 * MODULE `libmodal.mode` %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	 */
--]]

mode.ParseTable = require('libmodal/src/mode/ParseTable')

local _TIMEOUT_CHAR = 'ø'
local _TIMEOUT_NR = string.byte(_TIMEOUT_CHAR)
local _TIMEOUT_LEN = api.nvim_get_option('timeoutlen')

========================
--[[ SUMMARY:
	* Enter a mode.
]]
--[[ PARAMS:
	* `args[1]` => the mode name.
	* `args[2]` => the mode callback, or mode combo table.
	* `args[3]` => optional exit supresion flag.
]]
------------------------
function mode.enter(...)

--[[
	/*
	 * MODULE `libmodal.mode.ParseTable` %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	 */
--]]

-- The number corresponding to <CR> in vim.
ParseTable.CR = 13

==================================
--[[ SUMMARY:
	* Create a new parse table from a user-defined table.
]]
--[[ PARAMS:
	* `userTable` => the table of combos defined by the user.
]]
----------------------------------
function ParseTable.new(userTable)

================================
--[[ SUMMARY:
	* Get a value from this `ParseTable`.
]]
--[[ PARAMS:
	* `key` => the PARSED key to get.
]]
--[[
	* `function` => when `key` is a full match.
	* `table`    => when the `key` partially mathes.
	* `false`    => when `key` is not ANYWHERE.
]]
--------------------------------
function parseTable:get(keyDict)

========================================
--[[ SUMMARY:
	* Put `value` into the parse tree as `key`.
]]
--[[ PARAMS:
	* `key` => the key that `value` is reffered to by.
	* `value` => the value to store as `key`.
]]
----------------------------------------
function parseTable:parsePut(key, value)

=============================================
--[[ SUMMARY:
	* Create the union of `self` and `tableToUnite`
]]
--[[ PARAMS:
	* `tableToUnite` => the table to unite with `self.`
]]
---------------------------------------------
function parseTable:parsePutAll(tableToUnite)

--[[
	/*
	 * MODULE `libmodal.prompt` %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	 */
--]]

==========================
--[[ SUMMARY:
	* Enter a prompt.
]]
--[[ PARAMS:
	* `args[1]` => the prompt name.
	* `args[2]` => the prompt callback, or mode command table.
	* `args[3]` => a completions table.
]]
--------------------------
function prompt.enter(...)

--[[
	/*
	 * MODULE `libmodal.utils`  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	 */
--]]

local utils       = {}
utils.api         = require('libmodal/src/utils/api')
utils.Indicator   = require('libmodal/src/utils/Indicator')
utils.vars        = require('libmodal/src/utils/vars')
utils.WindowState = require('libmodal/src/utils/WindowState')

--[[
	/*
	 * FUNCTIONS
	 */
--]]

====================================
--[[ SUMMARY:
	* Show a default help table with `commands` and vim expressions.
]]
--[[ PARAMS:
	* `commands` => the table of commands to vim expressions.
]]
------------------------------------
function utils.commandHelp(commands)


==================================
--[[ SUMMARY:
	* Show an error from `pcall()`.
]]
--[[ PARAMS:
	`pcallErr` => the error generated by `pcall()`.
]]
----------------------------------
function utils.showError(pcallErr)

--[[
	/*
	 * MODULE `libmodal.utils.api` %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	 */
--]]

local api = vim.api

========================
--[[ SUMMARY:
	* Make vim ring the visual/audio bell, if it is enabled.
]]
------------------------
function api.nvim_bell()

===========================
--[[ SUMMARY:
	* Echo a string to Vim.
]]
--[[ PARAMS:
	* `str` => the string to echo.
]]
---------------------------
function api.nvim_echo(str)

====================================
--[[ SUMMARY:
	* Check whether or not some variable exists.
]]
--[[ PARAMS:
	* `scope` => The scope of the variable (i.e. `g`, `l`, etc.)
	* `var` => the variable to check for.
]]
------------------------------------
function api.nvim_exists(scope, var)

=========================
--[[ SUMMARY:
	* Gets one character of user input, as a number.
]]
--[[ REMARKS:
	* This could also be:
	```lua
	local cmd = {
		'"while 1"',
			'"let c = getchar(0)"',
			'"if empty(c)"',
				'"sleep 20m"',
			'"else"',
				'"echo c"',
				'"break"',
			'"endif"',
		'"endwhile"'
	}

	return tonumber(vim.api.nvim_call_function("execute",cmd))
	```
	However, I'm not sure if it would accidentally affect text.
]]
-------------------------
function api.nvim_input()

=================================
--[[ SUMMARY:
	* Echo a table of {`hlgroup`, `str`} tables.
	* Meant to be read as "nvim list echo".
]]
--[[ PARAMS:
	* `hlTables` => the tables to echo with highlights.
]]
---------------------------------
function api.nvim_lecho(hlTables)

==========================
--[[ 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.
]]
--------------------------
function api.nvim_redraw()

======================================
--[[ SUMMARY:
	* Show a `title` error.
]]
--[[ PARAMS:
	* `title` => the title of the error.
	* `msg` => the message of the error.
]]
--------------------------------------
function api.nvim_show_err(title, msg)

--[[
	/*
	 * MODULE `libmodal.utils.Indicator` %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	 */
--]]

=================================
--[[ SUMMARY:
	* Create a new `Indicator` for a mode.
]]
--[[ PARAMS:
	* `modeName` => the name of the mode that this `Indicator` is for.
]]
---------------------------------
function Indicator.mode(modeName)

===================================
--[[ SUMMARY:
	* Create a new `Indicator` for a prompt.
]]
--[[ PARAMS:
	* `modeName` => the name of the mode that this `Indicator` is for.
]]
-----------------------------------
function Indicator.prompt(modeName)

--[[
	/*
	 * MODULE `libmodal.utils.Indicator.Entry` %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	 */
--]]

================================
--[[ SUMMARY:
	* Create a new `Indicator.Entry`.
]]
--[[ PARAMS:
	* `hlgroup` => The `highlight-group` to be used for this `Indicator.Entry`.
	* `str` => The text for this `Indicator.Entry`.
]]
--------------------------------
function Entry.new(hlgroup, str)

--[[
	/*
	 * 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'     )

--[[
	/*
	 * MODULE `libmodal.utils.WindowState` %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
	 */
--]]

==========================
--[[ SUMMARY:
	* Create a table representing the size of the current window.
]]
--[[ RETURNS:
	* The new `WindowState`.
]]
--------------------------
function WindowState.new()

===========================
--[[ SUMMARY
	* Restore the state of `self`.
]]
---------------------------
function winState:restore()