nvim-libmodal/doc/libmodal-lua.txt

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

=============================================================================
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*

Modules: ~

* `libmodal`
	* `libmodal.base`
		* `libmodal.base.globals`
	* `libmodal.mode`
		* `libmodal.mode.ParseTable`
	* `libmodal.prompt`
	* `libmodal.utils`
		* `libmodal.utils.api`
		* `libmodal.utils.Help`
		* `libmodal.utils.Indicator`
		* `libmodal.utils.vars`
		* `libmodal.utils.WindowState`

==============================================================================
2. `libmodal.base.globals`                                *libmodal-lua-globals*

TODO.

==============================================================================
3. `libmodal.mode.ParseTable`                          *libmodal-lua-ParseTable*

A `ParseTable` is a pseudo-parse tree of a given user collection of
keybinding:expression pairs.

See: |libmodal-mode| for more information.

Variables ~
                                           *libmodal-lua-ParseTable-variables*

`ParseTable`.CR                                     *libmodal-lua-ParseTable-CR*

	The character number for <CR>.

	Value: ~
		13


Functions ~
                                           *libmodal-lua-ParseTable-functions*

`ParseTable`.new({userTable})                    *libmodal-lua-ParseTable.new()*

	Create a new `ParseTable` from a user-defined `table` of combos.

	All keys of a `ParseTable` are numbers of characters.

	Parameters: ~
		{userTable}  the table of combos defined by the user (see
		             `libmodal.mode.enter()`)

	Return: ~
		A new `ParseTable`.

	Example: ~
>
		local libmodal = require('libmodal')
		local userTable = {
			['zf'] = "echo 'Hello!'"
			['zfo'] = "tabnew"
		}

		local parseTable = libmodal.mode.ParseTable.new(userTable)
		print(vim.inspect(parseTable))
<

	See Also: ~
		|char2nr|, |nr2char|  For character to number conversion and vice
		                      versa.

		|libmodal-mode|       For information about {userTable}.


`self`:get({keyDict})                            *libmodal-lua-ParseTable.get()*

	Get a value from an instance of `ParseTable`.

	Parameters: ~
		{keyDict}  a string of key characters as bytes.

	Return: ~
		A `function`  {keyDict} is a full match.
		A `table`     the {keyDict} partially matches.
		* `false`     {keyDict} is not ANYWHERE.

	Example: ~
>
		-- Simulate user input.
		local userInput = {122, 102} -- {'z', 'f'}

		-- Create a dummy `ParseTable`.
		local parseTable = libmodal.mode.ParseTable.new({
			['zfo'] = 'echo "Hello!"'
		})
		-- Inspect it.
		print(vim.inspect(parseTable))

		-- this will return a `table`
		local tbl = parseTable:get(userInput)
		-- Inspect it to show the difference.
		print(vim.inspect(tbl))
<


`self`:parsePut({key}, {value})             *libmodal-lua-ParseTable.parsePut()*

	Put `value` into the parse tree as `key`.

	Parameters: ~
		{key}    the key that {value} is reffered to by. A `char`, not a
		         `byte`.

		{value}  the value to store as {key}. A `string` to |execute|.

	Example: ~
>
		-- Create a dummy `ParseTable`.
		local parseTable = libmodal.mode.ParseTable.new({
			['zfo'] = 'echo "Hello!"'
		})
		-- Inspect it.
		print(vim.inspect(parseTable))

		-- this will return a `table`
		parseTable:parsePut({'zfc', 'split'})
		-- Inspect it to show the difference.
		print(vim.inspect(parseTable))
<

	See also: ~
		|libmodal-lua-parsetable-parseputall| for how to put multiple {key}s
		                                      and {value}s at a time.


`self`:parsePutAll({tableToUnite})       *libmodal-lua-ParseTable.parsePutAll()*

	Create the union of `self` and `tableToUnite`

	Interally calls |libmodal-lua-parsetable-parseput| on every key:value pair
	in {tableToUnite}.

	Parameters: ~
		{tableToUnite}  the table to unite with `self.`

	Example: ~
>
		-- Create an empty `ParseTable`.
		local parseTable = libmodal.mode.ParseTable.new({})
		-- Create some dummy keybindings.
		local unparsedUserKeybinds = {
			['zfo'] = 'echo "Hello!"',
			['zfc'] = 'split'
		}

		-- Add the dummy keybindings.
		parseTable:parsePut(unparsedUserKeybinds)

		-- Inspect it to show the difference.
		print(vim.inspect(parseTable))
<

	See also: ~
		|libmodal-lua-parsetable-parseput|  For more information on
		                                    {tableToUnite}.

=============================================================================
4. `libmodal.utils`                                        *libmodal-lua-utils*

Provides extra utilities to the |libmodal| library.

Functions ~

`utils`.showError({pcallErr})                    *libmodal-lua-utils.showError*

	Show an error from `pcall()`.

	Parameters: ~
		{pcallErr}  the error generated by `pcall()`.

=============================================================================
4.1. `libmodal.utils.api`                                    *libmodal-lua-api*

Functions ~

`api`.nvim_bell()                                *libmodal-lua-api.nvim_bell()*

	Make vim ring the visual/audio bell, if it is enabled.

	See also: ~
		'belloff'     For bell settings.
		'errorbells'  For bell settings.
		'visualbell'  For bell settings.


`api`.nvim_exists({scope}, {var})              *libmodal-lua-api.nvim_exists()*

	Check whether or not some |variable| exists.

	Parameters: ~
		{scope}  The scope of the |variable| (i.e. `g:`, `l:`, etc.)
		{var}    The |variable| to check for.

	Example: ~
>
		local libmodal = require('libmodal')
		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
<

`api`.nvim_input()                               *libmodal-lua-api.nvim_input()*

	Gets one character of user input, as a number.

	Uses |getchar()|.

	Return: ~
		One character of user input, as a number (byte).

	Example: ~
>
		local libmodal = require('libmodal')
		local char = string.char(libmodal.utils.api.nvim_input())

		-- … wait for user to press a 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.
]]

`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.
]]

`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.
]]

==============================================================================
4.2. `libmodal.utils.Help`                                   *libmodal-lua-Help*

TODO.

==============================================================================
4.3. `libmodal.utils.Indicator`                         *libmodal-lua-Indicator*

Functions ~

`Indicator`.mode({modeName})                     *libmodal-lua-Indicator.mode()*

	Create a new `Indicator` for a mode.

	Parameters: ~
		{modeName}  The name of the mode that this `Indicator` is for.

	Example: ~
>
		local libmodal = require('libmodal')
		local indicator = libmodal.utils.Indicator.new('FOO')
		libmodal.utils.api.nvim_lecho(indicator)
<

	See also: ~
		|libmodal-mode|                 For this function's use.
		|libmodal-lua-api.nvim_lecho()| For effective |echo|ing of this
		                                function.

`Indicator`.prompt({modeName})                 *libmodal-lua-Indicator.prompt()*

	Create a new `Indicator` for a prompt.

	Parameters: ~
		{modeName}  The name of the mode that this `Indicator` is for.

	Example: ~
>
		local libmodal = require('libmodal')
		local indicator = libmodal.utils.Indicator.new('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*

Functions ~

`Entry`.new({hlgroup}, {str})                         *libmodal-lua-Entry.new()*

	Create a new `Indicator.Entry`.

	Parameters: ~
		{hlgroup}  The |highlight-group| to be used for this `Indicator.Entry`.
		{str}      The text for this `Indicator.Entry`.

	Return: ~
		A new `Indicator.Entry`.

	Example: ~
>
		local libmodal = require('libmodal')
		local entry = libmodal.utils.Indicator.Entry.new('Error', 'EXAMPLE!')
		print(vim.inspect(entry))
<

==============================================================================
4.4. `libmodal.utils.vars`                                   *libmodal-lua-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*

`WindowState`.new()                             *libmodal-lua-WindowState.new()*

	Create a table representing the size of the current window.

	Return: ~
		The new `WindowState`.

	Example: ~
>
		local libmodal = require('libmodal')
		local windowState = libmodal.utils.WindowState.new()
		print(vim.inspect(windowState))
<

	See also: ~
		'winheight'  The `height` property of a `WindowState`.
		'winwidth'   The `width` property of a `WindowState`.

`self`:restore()                            *libmodal-lua-WindowState.restore()*

	Restore the state of this `WindowState`.

==============================================================================
 vim:tw=78:ts=4:ft=help:norl: