nvim-libmodal/doc/libmodal-lua.txt

*libmodal-lua.txt*     Create modes for Neovim - Lua Reference
*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.4. `libmodal.utils.vars` .................. |libmodal-lua-vars|
4.5. `libmodal.utils.WindowState` ........... |libmodal-lua-Windowstate|

==============================================================================
1. `libmodal`                                            *libmodal-lua-libmodal*

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

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*

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

	Type: ~
		`number`

	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')

		-- Create a mock set of user mappings.
		local userTable = {
			['zf'] = "echo 'Hello!'",
			['zfo'] = "tabnew"
		}

		-- Create a new `ParseTable`
		local parseTable = libmodal.mode.ParseTable.new(userTable)

		-- Print the `parseTable`.
		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: ~
>
		local libmodal = require('libmodal')

		-- 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:parsePutAll(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                                       *libmodal-lua-utils-functions*

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

	Show an error from `pcall()`.

	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*

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.
		'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')

		-- 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')
		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')

		-- 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)
<

`api`.nvim_lecho({hlTables})                     *libmodal-lua-api.nvim_lecho()*

	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()*

	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()*

	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*

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*

Provides creation sources for mode and prompt |echo| / |echohl| `string`s.

------------------------------------------------------------------------------
FUNCTIONS                                   *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.mode('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.prompt('FOO')
		print(indicator) -- you can't use `nvim_lecho` with this one.
<

	See also: ~
		|libmodal-prompt|  For this function's use.

==============================================================================
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                     *libmodal-lua-vars.libmodalTimeouts*

	The value of `g:libmodalTimeouts`.

	Type: ~
		`boolean`/`number`

	Value: ~
		`vim.api.nvim_get_var('libmodalTimeouts')`

`self`.instances                                   *libmodal-lua-vars.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: ~
		{modeName}  The name of the mode that this global setting is for.

	Return: ~
		The name of this variable's global setting for a specific {modeName}.

	Example: ~
>
		local libmodal = require('libmodal')
		-- Get the |libmodal-timeouts| variable for `FOO` mode.
		print(libmodal.utils.vars.exit:name('FOO'))
<

`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()
<


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

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

	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: