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.classes` ..................... |libmodal-lua-classes|
 3.   `libmodal.collections` ................. |libmodal-lua-collections|
 3.1. `libmodal.collections.ParseTable` ...... |libmodal-lua-ParseTable|
 3.2. `libmodal.collections.Popup` ........... |libmodal-lua-Popup|
 3.3. `libmodal.collections.Stack` ........... |libmodal-lua-Stack|
 4.   `libmodal.globals` ..................... |libmodal-lua-globals|
 5.   `libmodal.Indicator` ................... |libmodal-lua-Indicator|
 5.1. `libmodal.Indicator.HighlightSegment` .. |libmodal-lua-HighlightSegment|
 6.   `libmodal.Layer` ....................... |libmodal-lua-Layer|
 7.   `libmodal.Mode` ........................ |libmodal-lua-Mode|
 8.   `libmodal.Prompt` ...................... |libmodal-lua-Prompt|
 9.   `libmodal.utils` ....................... |libmodal-lua-utils|
 9.1. `libmodal.utils.api` ................... |libmodal-lua-api|
 9.2. `libmodal.utils.Help` .................. |libmodal-lua-Help|
 9.3. `libmodal.utils.WindowState` ........... |libmodal-lua-Windowstate|
10.   `libmodal.Vars` ........................ |libmodal-lua-Vars|

================================================================================
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`
├──   `.collections`
│   ├──   `.ParseTable`
│   └──   `.Stack`
├──   `.globals`
├──   init.lua
│   ├── `.mode.enter()`
│   └── `.prompt.enter()`
├──   `.Indicator`
│   └──   `.HighlightSegment`
├──   `.Mode`
│   └──   `.Popup`
├──   `.Prompt`
├──   `.utils`
│   ├──   `.api`
│   ├──   `.Help`
│   └──   `.WindowState`
└──   `.Vars`

================================================================================
2. `libmodal.classes`                                       *libmodal-lua-classes*

`libmodal.classes` is a small library to help shorten the amount of
boilerplate code that it takes to set up a `metatable` and subsequent
subtables.

There aren't an astounding amount of functions: the intent is not to implement
object orientation into Lua, rather it is to help facilitate the emulation of
object orientation through `metatable`s.

--------------------------------------------------------------------------------
FUNCTIONS                                       *libmodal-lua-classes-functions*

`classes`.new({name}, {base})                         *libmodal-lua-classes.new()*

	Define a class-metatable.

	Parameters: ~
		{name}  The name of the class.

			Note: this value is used for `classes.type()`.

		{base}  Optional. The base class to use.

	Return: ~
		A table set up to for use as a `metatable`.

`classes`.type({value})                              *libmodal-lua-classes.type()*

	Get the type of some {value}.

	Parameters: ~
		{value}  The value to get the type of.

	Return: ~
		* If {value} is a `table` and it has a `__type` attribute, return
		  `__type`.
		* Else, return `type(`{value}`)`

================================================================================
3. `libmodal.collections`                               *libmodal-lua-collections*

The `libmodal.collections` module consists of a few data structures that
support the rest of `libmodal`.

================================================================================
3.1. `libmodal.collections.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`.stringSplit({str}, {regex})   *libmodal-lua-ParseTable.stringSplit()*

	Split some {str} into a `table` with a {regex} expression.

	Parameters: ~
		{str}    The `string` to split.
		{regex}  The regex expression to split {str} with.

	Return: ~
		* The split {str} as a `table`.

	Example: ~
>
		local ParseTable = require('libmodal').collections.ParseTable

		print(vim.inspect(ParseTable.stringSplit('testing split', ' ')))
<

`ParseTable`.parse({key})                        *libmodal-lua-ParseTable.parse()*

	Parse some {key} so that it can be stored by a `ParseTable` instance.

	Note: this method can be locally overridden in order to change the
	      `ParseTable`'s behavior. Example:
>
		local ParseTable = require('libmodal').collections.ParseTable

		ParseTable.parse = function(key)
			return ParseTable.splitString(key, ' ')
		end
<

	Parameters: ~
		{key}  The key of the `table` to parse.

	Return: ~
		* The parsed {key}. Should be a `table`.

	Example: ~
>
		local ParseTable = require('libmodal').collections.ParseTable

		print(vim.inspect(ParseTable.parse('testkey')))
<

`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.
		* `nil`       {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}.

================================================================================
3.2. `libmodal.collections.Popup`                             *libmodal-lua-Popup*

When `:enter()`ing a `Mode`, an |api-floatwin| is displayed at the bottom
right-hand corner of the screen. `libmodal.Mode.Popup` is responsible for
opening it and keeping updated.

Whenever a `Popup` is created, it is immediately opened. Additionally, it is
opened with the following options: >
	local _winOpenOpts = {
		anchor    = 'SW',
		col       = vim.go.columns - 1,
		focusable = false,
		height    = 1,
		relative  = 'editor',
		row       = vim.go.lines - vim.go.cmdheight - 1,
		style     = 'minimal',
		width     = 25,
	}
<

--------------------------------------------------------------------------------
VARIABLES                                         *libmodal-lua-Popup-variables*

`Popup`.config                                         *libmodal-lua-Popup.config*

	The options used when opening a `Popup`.

	Note: this can be overwritten to change the default behavior of `Popup`.

	Type: ~
		|nvim_open_win| {config} `table`.

	Value: ~
>
	{
		anchor    = 'SW',
		col       = vim.go.columns - 1,
		focusable = false,
		height    = 1,
		relative  = 'editor',
		row       = vim.go.lines - vim.go.cmdheight - 1,
		style     = 'minimal',
		width     = 1
	}
<

`self`.buffer                                          *libmodal-lua-Popup.buffer*

	The scratch buffer used by `Popup` to display text.

	Type: ~
		|nvim_create_buf| handle.

	Value: ~
		`vim.api.nvim_create_buf(false, true)`

`self`.window                                          *libmodal-lua-Popup.window*

	The window used to display the contents of `Popup.buffer`.

	Type: ~
		|nvim_open_win| handle.

	Value: ~
		`vim.api.nvim_open_win(self.buffer, false, Popup.config)`

--------------------------------------------------------------------------------
FUNCTIONS                                         *libmodal-lua-Popup-functions*

`self`:close({keepBuffer})                            *libmodal-lua-Popup.close()*

	Close the |Popup.window|.

	Note: Variables of |Popup| are de-initialized after this method.

	Parameters: ~
		{keepBuffer}  A `boolean` that (when `true`) indicates the underlying
		              |scratch-buffer| should be kept

`self`:open({config})                                  *libmodal-lua-Popup.open()*

	Open the |Popup.window|.

	Note: if the |Popup.window| is already open, then it will be reopened in
	      case the |current_tabpage| has changed.

	      In this case, it will also override the default options with the
	      options in the window so there is no need to pass in {config} a
	      second time.

	Parameters: ~
		{config}  Same as |nvim_open_win| {config}.

`self`:refresh({inputBytes})                        *libmodal-lua-Popup.refresh()*

	Update the content of the `Popup` using an array-like `table` of
	|char2nr|s.

	Note: This is normally used to add what the user is typing. If you have a
	      `function` `Mode` {instruction}, then you can use `Popup` and this
		  function to manually show user input as it is typed.

	Parameters: ~
		{inputBytes}  An array-like `table` of |char2nr|s to write to the
		              `Popup`.

`Popup`.new({config})                                   *libmodal-lua-Popup.new()*

	Create a new `Popup` and immediately open it.

	Parameters: ~
		{config}  Same as |nvim_open_win| {config}.
		          Note: defaults to |Popup.config|.

	Return: ~
		  * A new `Popup`.

	See also: ~
		|libmodal-lua-Popup|  For the options used to spawn the window.


================================================================================
4.2. `libmodal.collections.Stack`                             *libmodal-lua-Stack*

The `libmodal.collections.Stack` is a simple implementation of a Stack data
structure. It is designed with reuse of resources in mind, as
commonly-accessed pieces of data are locally stored for faster reference
times.

The `#` operator in |Lua| will work on this structure.

--------------------------------------------------------------------------------
FUNCTIONS                                         *libmodal-lua-Stack-functions*

`self`:peek()                                          *libmodal-lua-Stack.peek()*

	Access the value at the top of the stack without removing it.

	Return: ~
		  * The value at the top of the stack.

	Example: ~
>
		local Stack = require('libmodal').collections.Stack

		local stk = Stack.new()
		stk:push('foo')
		stk:push('bar')
		print(stk:peek())
<

`self`:pop()                                            *libmodal-lua-Stack.pop()*

	Access the value at the top of the stack by removing it.

	Return: ~
		  * The value at the top of the stack.

	Example: ~
>
		local Stack = require('libmodal').collections.Stack

		local stk = Stack.new()
		stk:push('foo')
		stk:push('bar')
		print(stk:peek())
		local _ = stk:pop()
		print(stk:peek())
<

`self`:push({value})                                   *libmodal-lua-Stack.push()*

	Push some {value} onto the top of the stack.

	Parameters: ~
		{value}  The value to put on top of the stack.

	Example: ~
>
		local Stack = require('libmodal').collections.Stack

		local stk = Stack.new()
		stk:push('foo')
		stk:push('bar')
		print(vim.inspect(stk))
<

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

	Create a new `libmodal.collections.Stack` and return it.

	Return: ~
		  * A new `libmodal.collections.Stack`.

	Example: ~
>
		local Stack = require('libmodal').collections.Stack

		local stk = Stack.new()
		print(vim.inspect(stk))
<

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

These are global functions 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`.is_false({val})                        *libmodal-lua-globals.is_false()*

	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 Vimscript's truth values.
		local vim_falseValue = libmodal.globals.VIM_FALSE
		local vim_trueValue  = libmodal.globals.VIM_TRUE

		--[[ Test the function. ]]

		print(libmodal.globals.is_false(falseValue))
		print(libmodal.globals.is_false(v_falseValue))
		print(libmodal.globals.is_false(vim_falseValue))

		print(libmodal.globals.is_false(trueValue))
		print(libmodal.globals.is_false(v_trueValue))
		print(libmodal.globals.is_false(vim_trueValue))
<

`globals`.is_true({val})                          *libmodal-lua-globals.is_true()*

	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 Vimscript's truth values.
		local vim_falseValue = libmodal.globals.VIM_FALSE
		local vim_trueValue  = libmodal.globals.VIM_TRUE

		--[[ Test the function. ]]

		print(libmodal.globals.is_true(falseValue))
		print(libmodal.globals.is_true(v_falseValue))
		print(libmodal.globals.is_true(vim_falseValue))

		print(libmodal.globals.is_true(trueValue))
		print(libmodal.globals.is_true(v_trueValue))
		print(libmodal.globals.is_true(vim_trueValue))
<

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

================================================================================
5.1. `libmodal.Indicator.HighlightSegment`         *libmodal-lua-HighlightSegment*

The `HighlightSegment` is a map describing how a particular string should be
highlighted by Vim.

These `HighlightSegment`s can be put into a list and interpreted by
`libmodal.utils.api.nvim_lecho()`.

--------------------------------------------------------------------------------
FUNCTIONS                              *libmodal-lua-HighlightSegment-functions*

`self`.hl                                       *libmodal-lua-HighlightSegment.hl*

	Which |highlight-group| to use when |highlight|ing `HighlightSegment.str`.

	Type: ~
		|highlight-group| `string`.

`self`.str                                     *libmodal-lua-HighlightSegment.str*

	What this `HighlightSegment`'s string value is.

	Type: ~
		`string`

--------------------------------------------------------------------------------
FUNCTIONS                              *libmodal-lua-HighlightSegment-Functions*

`HighlightSegment`.new({hlgroup}, {str})     *libmodal-lua-HighlightSegment.new()*
--
	Create a new `HighlightSegment`.

	Parameters: ~
		{hlgroup}  The |highlight-group| to use when |highlight|ing {str}.
		{str}      The {str} to |highlight|.

	Return: ~
		- A new `HighlightSegment`.

	Example: ~
>
		local libmodal         = require 'libmodal'
		local api              = libmodal.utils.api
		local HighlightSegment = libmodal.Indicator.HighlightSegment

		api.nvim_lecho({
			HighlightSegment.new('ModeMsg', '-- '),
			HighlightSegment.new('None', 'FOO')
			HighlightSegment.new('ModeMsg', ' --'),
		})
<

================================================================================
6. `libmodal.Layer`                                           *libmodal-lua-Layer*

The libmodal `Layer` class provides many additional features to the base
`libmodal.layer.enter()`.

As there is no default mapping to leave a `Layer`, `libmodal.layer.enter()`
returns an anonymous `Layer`'s `:exit()` `function`. By directly having a
reference to a `Layer`, one can use the other `function`s that are provided,
and extend was is possible.

--------------------------------------------------------------------------------
FUNCTIONS                                           *libmodal-lua-Layer-functions*

`self`:enter()                                        *libmodal-lua-Layer.enter()*

	Enter the `Layer`.

	Note: mappings only get replaced for the current buffer.

	*Error	when the Layer has been entered previously but hasn't been exited.

	Example: ~
>
		local libmodal = require 'libmodal'
		local layer = libmodal.Layer.new({
			n = {
				gg = {
					rhs = G
				}
			}
		})

		-- use `layer:exit()` or close the buffer to exit.
		layer:enter()
<

	See also: ~
		|libmodal-lua-Layer.exit()|  How to enter the `Layer`.

`self`:map({mode}, {lhs}, {rhs}, {options})           *libmodal-lua-Layer.map()*

	Add a mapping to the `Layer`.

	Note: if the layer has been `:enter()`ed, then the current buffer's
	      mappings will be updated.

	Parameters: ~
		{mode}     The |mode| that this mapping for.

			Note: |libmodal-mode| support is coming.

		{lhs}      The left hand side of the mapping.
		{rhs}      The right hand side of the mapping.
		{options}  Options for the mapping.

	Example: ~
>
		local libmodal = require 'libmodal'
		local layer = libmodal.Layer.new({
			n = {
				gg = {
					rhs = G
				}
			}
		})

		-- this adds a binding for `G` to `gg` in normal mode.
		layer:map('n', 'G', 'gg', {noremap = true})

		-- use `layer:exit()` or close the buffer to exit.
		layer:enter()

		-- you can also call `:map()` after entering.
		-- this adds a binding for `o` to `gg` in visual mode.
		layer:map('v', 'o', 'gg', {noremap = true})
<

	See also: ~
		|nvim_buf_set_keymap()|  For more information about the parameters.

`self`:unmap({mode}, {lhs})                           *libmodal-lua-Layer.unmap()*

	Remove a mapping from the `Layer`.

	Parameters: ~
		{mode}  The |mode| that this mapping for.

			Note: |libmodal-mode| support is coming.

		{lhs}   The left hand side of the mapping.

	Example: ~
>
		local libmodal = require 'libmodal'
		local layer = libmodal.Layer.new({
			n = {
				gg = {
					rhs = G
				}
			}
		})

		-- This adds a binding for `G` to `gg` in normal mode.
		layer:map('n', 'G', 'gg', {noremap = true})

		-- Unmap the initial `gg`.
		layer:unmap('n', 'gg')

		-- Use `layer:exit()` or close the buffer to exit.
		layer:enter()

		-- Start a timer for five seconds.
		vim.loop.new_timer():start(5000, 0, vim.schedule_wrap(
			-- You can also call `:unmap()` after entering.
			function() layer:unmap('n', 'G') end
			-- No bindings should be active now.
		))

<

	See also: ~
		|nvim_buf_del_keymap()|  For more information about the parameters.

`self`:exit()                                          *libmodal-lua-Layer.exit()*

	Exit the `Layer`.

	*Error	when the Layer has not been entered yet.

	Example: ~
>
		local libmodal = require 'libmodal'
		local layer = libmodal.Layer.new({
			n = {
				gg = {
					rhs = G
				}
			}
		})

		-- Enter the layer.
		layer:enter()

		-- Start a timer for five seconds.
		vim.loop.new_timer():start(5000, 0,
			-- Exit the layer. `gg` should return to normal.
			vim.schedule_wrap(layer:exit())
		)

<

	See also: ~
		|libmodal-lua-Layer.enter()|  How to enter the `Layer`.

`Layer`.new({keymap})                                   *libmodal-lua-Layer.new()*

	Create a new `Layer` for `mappings`.

	Parameters: ~
		{keymap}  The list of |map|pings to replace.

	Returns: ~
		- A new `Layer`.

	See also: ~
		|libmodal-layer|  For more information about the parameters.

================================================================================
7. `libmodal.Mode`                                             *libmodal-lua-Mode*

While `libmodal.mode.enter()` may enter a mode, it silently creates a `Mode`
underneath: >
	function mode.enter(...)
		Mode.new(...):enter()
	end
<

If you wish to have more control over a mode, such as the text of an
`Indicator`, one may manually create a `Mode` with `Mode.new()` and then
change some of the properties in order to make the mode do what you want.

Additionally, one may alter the actual `function`s that are used by a `Mode`
without forking |libmodal|. By using `setmetatable`, and `vim.inspect()`, one
can grab code from the |nvim-libmodal| repository and change whatever they
want to for their mode specifically. >
	local libmodal         = require 'libmodal'
	local Mode             = libmodal.Mode
	local HighlightSegment = libmodal.Indicator.HighlightSegment

	local fooMode = Mode.new(…)
	fooMode.indicator = {
		HighlightSegment.new('Error', '*'),
		HighlightSegment.new('None', ' Something a duck walks on '),
		HighlightSegment.new('Error', '>'),
		HighlightSegment.new('None', ' ')
	}
	fooMode
	fooMode:enter()
< (The specifications for these functions can be found at other places in this
  document.)

--------------------------------------------------------------------------------
VARIABLES                                          *libmodal-lua-Mode-variables*

`self`.exit                                               *libmodal-lua-Mode.exit*

	A liason to the `g:`{name}`ModeExit` variable.

	Type: ~
		`libmodal.Vars`

	Value: ~
		`libmodal.Vars.new('exit', `{name}`)`

`self`.indicator                                     *libmodal-lua-Mode.indicator*

	The message that is shown in the bottom-left corner of the screen while the
	mode is active.

	Note: this value may be replaced with any `table` of `HighlightSegment`s
	      (as shown in |libmodal-lua-Mode|). That will allow you to change the
		  message that a mode has from the vim-default "-- {name} --" to
		  something else.

	Type: ~
		`libmodal.Indicator`/array-like `table` of `HighlightSegment`s.

	Value: ~
		`libmodal.Indicator.mode(`{name}`)`

`self`.input                                             *libmodal-lua-Mode.input*

	A liason to `g:`{name}`ModeInput`.

	Note: you may use {ModeInstance}`.input:nvimGet()` and `:nvimSet()` to
	      consistently read and write to the mode's unique variable.

	Type: ~
		`libmodal.Vars`

	Value: ~
		`libmodal.Vars.new('input', `{name}`)`

`self`.inputBytes                                   *libmodal-lua-Mode.inputBytes*

	The history of user input, stored as |char2nr|s.

	Note: This variable is inert when `libmodal.Mode.new()`'s {instruction}
	      parameter is a `function`. Feel free to use it rather than creating
		  your own, to make your code more familiar to others.

	Type: ~
		array-like `table` of |char2nr|s.

	Value: ~
		- `nil` => {instruction} is a `function`.
		- `{}` => {instruction} is a `table`.

`self`.mappings                                       *libmodal-lua-Mode.mappings*

	The mappings that have been processed by a `Mode` when
	`libmodal.Mode.new()`'s {instruction} parameter is a `table`.

	Users may add or remove mappings at any time, and they will be reflected
	in the next keypress.

	Type: ~
		`libmodal.collections.ParseTable`

	Value: ~
		`libmodal.collections.ParseTable.new(`{instruction}`)`

	See also: ~
		|libmodal-lua-ParseTable|  For information about how to use this
		                         variable.

--------------------------------------------------------------------------------
FUNCTIONS                                          *libmodal-lua-Mode-functions*

`self`:enter()                                         *libmodal-lua-Mode.enter()*

	Enter the `Mode` that was created.

	Example: ~
>
		local Mode = require('libmodal').Mode

		local fooMode = Mode.new('FOO', {zz = 'tabnew', gg = 'tabclose'})
		fooMode:enter()
<

`Mode`.new({name}, {instruction} [, {supressExit}])      *libmodal-lua-Mode.new()*

	Create a new `Mode` with a given {name}, using an {instruction} to perform
	whenever a key is pressed, and whether or not to {supressExit} handling.

	Return: ~
		A new `Mode`.

	See also: ~
		|libmodal-mode|  For more information, as all of the parameters are
		                 the same.

================================================================================
8. `libmodal.Prompt`                                         *libmodal-lua-Prompt*

While `libmodal.prompt.enter()` may enter a |libmodal-prompt|, itilently
creates a `Mode` underneath: >
	function prompt.enter(...)
		Prompt.new(...):enter()
	end
<

See |libmodal-lua-Mode| for more information about the possibilities that are
enabled by using such a "class".

--------------------------------------------------------------------------------
VARIABLES                                        *libmodal-lua-Prompt-variables*

`self`.indicator                                   *libmodal-lua-Prompt.indicator*

	The message that is shown in the bottom-left corner of the screen while the
	mode is active.

	Note: this value may be replaced with any `HighlightSegment`. That will
	      allow you to change the message to something else.

	Type: ~
		`HighlightSegment`

	Value: ~
		`libmodal.Indicator.prompt(`{name}`)`

`self`.input                                           *libmodal-lua-Prompt.input*

	A liason to `g:`{name}`ModeInput`.

	Note: you may use {ModeInstance}`.input:nvimGet()` and `:nvimSet()` to
	      consistently read and write to the mode's unique variable.

	Type: ~
		`libmodal.Vars`

	Value: ~
		`libmodal.Vars.new('input', `{name}`)`

--------------------------------------------------------------------------------
FUNCTIONS                                        *libmodal-lua-Prompt-functions*

`self`:enter()                                       *libmodal-lua-Prompt.enter()*

	Enter the `Prompt` that was created.

	Example: ~
>
		local Prompt = require('libmodal').Prompt

		local fooMode = Prompt.new('FOO', {new = 'tabnew', close = 'tabclose'})
		fooMode:enter()
<

                                                     *libmodal-lua-Prompt.new()*
`Prompt`.new({name}, {instruction} [, {completions}, {supressExit}])

	User input is taken using |input()|. It is passed through a |g:var|
	determined by the {name} of the mode. For example, if {name} is "FOO"
	then the |g:var| is `g:fooModeInput`.

	Return: ~
		A new `Mode`.

	See also: ~
		|libmodal-prompt|  For more information, as all of the parameters are
		                 the same.

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

Provides extra utilities to the |libmodal| library.

--------------------------------------------------------------------------------
FUNCTIONS                                         *libmodal-lua-utils-functions*

`utils`.show_error({pcall_err})                   *libmodal-lua-utils.show_error()*

	Show an error from `pcall()`.

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

	Example: ~
>
		local libmodal = require 'libmodal'

		-- Run `pcall` on an anonymous function.
		local noErrors, pcall_err = pcall(function()
			-- This will always produce an error.
			return "" .. true
		end)

		-- If there were errors…
		if not noErrors then
			-- Show the error.
			libmodal.utils.show_error(pcall_err)
		end
<

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

Provides extensions to the `vim.api` |Lua| library.

See: |API|.

--------------------------------------------------------------------------------
FUNCTIONS                                           *libmodal-lua-api-functions*

`api`.mode_exit({exit_char})                        *libmodal-lua-api.mode_exit()*

	Use |feedkeys()| to send an {exit_char} which signals a |libmodal-mode| or
	|libmodal-prompt| to stop listening for input.

	It is not usually necessary to specify {exit_char}. It is only necessary
	to do so when |libmodal-mode|'s {supressExit} flag is active, because
	it is possible that the user has set up some non-default character which
	should be used to exit the mode (see |libmodal-examples-supress-exit|).

	Parameters: ~
		{exit_char}  (Optional) The character used to exit the mode, or
		             |libmodal-lua-globals.ESC_NR| by default.

		             Can be a character number (see |char2nr()|) or a string.

	Example: ~
>
		local libmodal = require 'libmodal'

		-- This function is called every time the user presses a key.
		local function _instruction()
			-- Exit the mode after pressing any key.
			libmodal.utils.api.mode_exit()
		end

		libmodal.mode.enter('Press any key to exit.', _instruction)
<

	See also: ~
		|char2nr()|      For more information about character numbers.
		|libmodal-mode|  For more information about {supressExit}.
		|feedkeys()|     For information about how this method is implemented.

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

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

	Example: ~
>
		local libmodal = require 'libmodal'

		libmodal.utils.api.nvim_bell()
<

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

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

		-- Echo hello and prompt for input before continuing.
		vim.api.nvim_command "echo 'Hello!'"
		vim.fn.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!'
		)
<

================================================================================
9.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()
<

================================================================================
9.3. `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'

		-- Create a new `WindowState`.
		local windowState = libmodal.utils.WindowState.new()

		-- Set the 'winheight' to a new value.
		vim.go.winheight = 100

		-- Define a function to print the 'winheight' value.
		local print_height = function()
			vim.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()
<

================================================================================
10. `libmodal.Vars`                                            *libmodal-lua-Vars*

A `Var`'s purpose is to act as an intermediary between |global-variables| and
the modes that use them.

--------------------------------------------------------------------------------
FUNCTIONS                                          *libmodal-lua-Vars.functions*

`self`:name()                                           *libmodal-lua-Vars.name()*

	Get the name of `modeName`s global setting.

	Parameters: ~
		{modeName}  The name of the mode.

	Return: ~
		- The name of the vimscript variable that this `Var` corresponds to.

	Example: ~
>
		local libmodal = require 'libmodal'

		local input = libmodal.Vars('input', 'FOO')
		print(input:name()) -- 'fooModeInput'
<

`self`:nvimGet()                                     *libmodal-lua-Vars.nvimGet()*

	Retrieve a variable value.

	Parameters: ~
		{modeName}  The mode name this value is being retrieved for.

	Return: ~
		* The |global-variable| value that this `Var` represents

	Example: ~
>
		local libmodal = require 'libmodal'

		local input = libmodal.Vars('input', 'FOO')
		vim.g[input:name()] = 'test'
		print(input:nvimGet())
<

`self`:nvimSet({val})                                *libmodal-lua-Vars.nvimSet()*

	Set a |variable| value.

	Parameters: ~
		{modeName}  The mode name this value is being retrieved for.
		{val}       The value to set `self`'s Vimscript var to.

	Example: ~
>
		local libmodal = require 'libmodal'

		local input = libmodal.Vars('input', 'FOO')
		input:nvimSet('test')
		print(input:nvimGet())
<

`Vars`.new(keyName, modeName)                            *libmodal-lua-Vars.new()*

	Create a new `Var`.

	Parameters: ~
		{keyName}   The name of the key used to refer to this variable in `Vars`.
		{modeName}  The name of the mode that this `Variable` is for.

	Return: ~
		* A new `Var`.

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