diff --git a/doc/libmodal-lua.txt b/doc/libmodal-lua.txt index 4909338..bfe804c 100644 --- a/doc/libmodal-lua.txt +++ b/doc/libmodal-lua.txt @@ -13,21 +13,22 @@ See: |libmodal-usage|, |lua|, |lua-require-example|. ============================================================================== 0. Table of Contents *libmodal-lua-toc* - 1. `libmodal` ............................. |libmodal-lua-libmodal| - 2. `libmodal.collections` ................. |libmodal-lua-collections| - 3.1. `libmodal.collections.ParseTable` ...... |libmodal-lua-ParseTable| - 4.2. `libmodal.collections.Stack` ........... |libmodal-lua-Stack| - 5. `libmodal.globals` ..................... |libmodal-lua-globals| - 6. `libmodal.Indicator` ................... |libmodal-lua-Indicator| - 7.1. `libmodal.Indicator.HighlightSegment` .. |libmodal-lua-HighlightSegment| - 8. `libmodal.Mode` ........................ |libmodal-lua-Mode| - 9.1. `libmodal.Mode.Popup` .................. |libmodal-lua-Popup| -10. `libmodal.Prompt` ...................... |libmodal-lua-Prompt| -11. `libmodal.utils` ....................... |libmodal-lua-utils| -12.1. `libmodal.utils.api` ................... |libmodal-lua-api| -13.2. `libmodal.utils.Help` .................. |libmodal-lua-Help| -14.3. `libmodal.utils.WindowState` ........... |libmodal-lua-Windowstate| -15. `libmodal.Vars` ........................ |libmodal-lua-Vars| +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.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.Mode` ........................ |libmodal-lua-Mode| +6.1. `libmodal.Mode.Popup` .................. |libmodal-lua-Popup| +7. `libmodal.Prompt` ...................... |libmodal-lua-Prompt| +8. `libmodal.utils` ....................... |libmodal-lua-utils| +8.1. `libmodal.utils.api` ................... |libmodal-lua-api| +8.2. `libmodal.utils.Help` .................. |libmodal-lua-Help| +8.3. `libmodal.utils.WindowState` ........... |libmodal-lua-Windowstate| +9. `libmodal.Vars` ........................ |libmodal-lua-Vars| ============================================================================== 1. `libmodal` *libmodal-lua-libmodal* @@ -59,13 +60,255 @@ MODULES *libmodal-lua-modules* └──  `.Vars` ============================================================================== -2. `libmodal.base.globals` *libmodal-lua-globals* +3. `libmodal.collections` *libmodal-lua-collections* -These are global variables used throughout the project. They are never +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. + +------------------------------------------------------------------------------ +functions *libmodal-lua-ParseTable-functions* + +`ParseTable`.CR *libmodal-lua-ParseTable.CR* + + The character number for . + + 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`:parseGet({keyDict}) *libmodal-lua-ParseTable.parseGet()* + + 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:parseGet(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.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* +functions *libmodal-lua-globals-functions* `globals`.DEFAULT_ERROR_TITLE *libmodal-lua-globals.DEFAULT_ERROR_TITLE* @@ -219,193 +462,389 @@ FUNCTIONS *libmodal-lua-globals-functions* local vim_falseValue = libmodal.globals.VIM_FALSE local vim_trueValue = libmodal.globals.VIM_TRUE - --[[ Test the function. ]] + --[[ 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.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.) + +------------------------------------------------------------------------------ +functions *libmodal-lua-Mode-functions* + +`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}`)` - print(libmodal.globals.is_true(falseValue)) - print(libmodal.globals.is_true(v_falseValue)) - print(libmodal.globals.is_true(vim_falseValue)) +`self`.inputBytes *libmodal-lua-Mode.inputBytes* - print(libmodal.globals.is_true(trueValue)) - print(libmodal.globals.is_true(v_trueValue)) - print(libmodal.globals.is_true(vim_trueValue)) -< + The history of user input, stored as |char2nr|s. -============================================================================== -3. `libmodal.mode.ParseTable` *libmodal-lua-ParseTable* + 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. -A `ParseTable` is a pseudo-parse tree of a given user collection of -keybinding:expression pairs. + Type: ~ + array-like `table` of |char2nr|s. -See: |libmodal-mode| for more information. + Value: ~ + * `nil` => {instruction} is a `function`. + * `{}` => {instruction} is a `table`. ------------------------------------------------------------------------------- -VARIABLES *libmodal-lua-ParseTable-variables* +`self`.mappings *libmodal-lua-Mode.mappings* -`ParseTable`.CR *libmodal-lua-ParseTable.CR* + The mappings that have been processed by a `Mode` when + `libmodal.Mode.new()`'s {instruction} parameter is a `table`. - The character number for . + Users may add or remove mappings at any time, and they will be reflected + in the next keypress. Type: ~ - `number` + `libmodal.collections.ParseTable` Value: ~ - 13 + `libmodal.collections.ParseTable.new(`{instruction}`)` + + See also: ~ + |libmodal-lua-ParseTable| For information about how to use this + variable. ------------------------------------------------------------------------------ -FUNCTIONS *libmodal-lua-ParseTable-functions* +FUNCTIONS *libmodal-lua-Mode-functions* -`ParseTable`.new({userTable}) *libmodal-lua-ParseTable.new()* +`self`:enter() *libmodal-lua-Mode.enter()* - Create a new `ParseTable` from a user-defined `table` of combos. + Enter the `Mode` that was created. - All keys of a `ParseTable` are numbers of characters. + Example: ~ +> + local Mode = require('libmodal').Mode - Parameters: ~ - {userTable} the table of combos defined by the user (see - `libmodal.mode.enter()`) + local fooMode = Mode.new('FOO', {zz = 'tabnew', gg = 'tabclose'}) + fooMode:enter() +< - Return: ~ - A new `ParseTable`. +`Mode`.new({name}, {instruction} [, {supressExit}]) *libmodal-lua-Mode.new()* - Example: ~ -> - local libmodal = require('libmodal') + 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. - -- Create a mock set of user mappings. - local userTable = { - ['zf'] = "echo 'Hello!'", - ['zfo'] = "tabnew" - } + Return: ~ + A new `Mode`. - -- Create a new `ParseTable` - local parseTable = libmodal.mode.ParseTable.new(userTable) + See also: ~ + |libmodal-mode| For more information, as all of the parameters are + the same. - -- Print the `parseTable`. - print(vim.inspect(parseTable)) +============================================================================== +6.1. `libmodal.Mode.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'] = api.nvim_get_option('columns') - 1, + ['focusable'] = false, + ['height'] = 1, + ['relative'] = 'editor', + ['row'] = api.nvim_get_option('lines') + - api.nvim_get_option('cmdheight') + - 1, + ['style'] = 'minimal', + ['width'] = 25, + } < - See Also: ~ - |char2nr|, |nr2char| For character to number conversion and vice - versa. +------------------------------------------------------------------------------ +FUNCTIONS *libmodal-lua-Popup-functions* - |libmodal-mode| For information about {userTable}. +`self`:close() *libmodal-lua-Popup.close()* + Close the window that this `Popup` represents. -`self`:get({keyDict}) *libmodal-lua-ParseTable.get()* + Note: All variables of `Popup` are de-initialized after this method. - Get a value from an instance of `ParseTable`. +`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: ~ - {keyDict} a string of key characters as bytes. + {inputBytes} An array-like `table` of |char2nr|s to write to the + `Popup`. - Return: ~ - A `function` {keyDict} is a full match. - A `table` the {keyDict} partially matches. - * `false` {keyDict} is not ANYWHERE. +`Popup`.new() *libmodal-lua-Popup.new()* - Example: ~ -> - local libmodal = require('libmodal') + Create a new `Popup` and immediately open it. - -- Simulate user input. - local userInput = {122, 102} -- {'z', 'f'} + Return: ~ + * A new `Popup`. - -- Create a dummy `ParseTable`. - local parseTable = libmodal.mode.ParseTable.new({ - ['zfo'] = 'echo "Hello!"' - }) - -- Inspect it. - print(vim.inspect(parseTable)) + See also: ~ + |libmodal-lua-Popup| For the options used to spawn the window. - -- this will return a `table` - local tbl = parseTable:get(userInput) - -- Inspect it to show the difference. - print(vim.inspect(tbl)) +============================================================================== +7. `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". -`self`:parsePut({key}, {value}) *libmodal-lua-ParseTable.parsePut()* +------------------------------------------------------------------------------ +VARIABLES *libmodal-lua-Prompt-variables* - Put `value` into the parse tree as `key`. +`self`.indicator *libmodal-lua-Prompt.indicator* - Parameters: ~ - {key} the key that {value} is reffered to by. A `char`, not a - `byte`. + The message that is shown in the bottom-left corner of the screen while the + mode is active. - {value} the value to store as {key}. A `string` to |execute|. + Note: this value may be replaced with any `HighlightSegment`. That will + allow you to change the message to something else. - Example: ~ -> - -- Create a dummy `ParseTable`. - local parseTable = libmodal.mode.ParseTable.new({ - ['zfo'] = 'echo "Hello!"' - }) - -- Inspect it. - print(vim.inspect(parseTable)) + Type: ~ + `HighlightSegment` - -- this will return a `table` - parseTable:parsePut('zfc', 'split') - -- Inspect it to show the difference. - print(vim.inspect(parseTable)) -< + Value: ~ + `libmodal.Indicator.prompt(`{name}`)` - See also: ~ - |libmodal-lua-parsetable-parseputall| for how to put multiple {key}s - and {value}s at a time. +`self`.input *libmodal-lua-Prompt.input* + A liason to `g:`{name}`ModeInput`. -`self`:parsePutAll({tableToUnite}) *libmodal-lua-ParseTable.parsePutAll()* + Note: you may use {ModeInstance}`.input:nvimGet()` and `:nvimSet()` to + consistently read and write to the mode's unique variable. - Create the union of `self` and `tableToUnite` + Type: ~ + `libmodal.Vars` - Interally calls |libmodal-lua-parsetable-parseput| on every key:value pair - in {tableToUnite}. + Value: ~ + `libmodal.Vars.new('input', `{name}`)` - Parameters: ~ - {tableToUnite} the table to unite with `self.` +------------------------------------------------------------------------------ +FUNCTIONS *libmodal-lua-Prompt-functions* + +`self`:enter() *libmodal-lua-Prompt.enter()* + + Enter the `Prompt` that was created. Example: ~ > - -- Create an empty `ParseTable`. - local parseTable = libmodal.mode.ParseTable.new({}) - -- Create some dummy keybindings. - local unparsedUserKeybinds = { - ['zfo'] = 'echo "Hello!"', - ['zfc'] = 'split' - } + local Prompt = require('libmodal').Prompt - -- Add the dummy keybindings. - parseTable:parsePutAll(unparsedUserKeybinds) - - -- Inspect it to show the difference. - print(vim.inspect(parseTable)) + local fooMode = Prompt.new('FOO', {new = 'tabnew', close = 'tabclose'}) + fooMode:enter() < + *libmodal-lua-Prompt.new()* +`Prompt`.new({name}, {instruction} [, {completions}]) + + 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-lua-parsetable-parseput| For more information on - {tableToUnite}. + |libmodal-prompt| For more information, as all of the parameters are + the same. -============================================================================= -4. `libmodal.utils` *libmodal-lua-utils* +============================================================================== +8. `libmodal.utils` *libmodal-lua-utils* Provides extra utilities to the |libmodal| library. ------------------------------------------------------------------------------ FUNCTIONS *libmodal-lua-utils-functions* -`utils`.showError({pcallErr}) *libmodal-lua-utils.showError()* +`utils`.show_error({pcall_err}) *libmodal-lua-utils.show_error()* Show an error from `pcall()`. Parameters: ~ - {pcallErr} the error generated by `pcall()`. + {pcall_err} the error generated by `pcall()`. Example: ~ > local libmodal = require('libmodal') -- Run `pcall` on an anonymous function. - local noErrors, pcallErr = pcall(function() + local noErrors, pcall_err = pcall(function() -- This will always produce an error. return "" .. true end) @@ -413,12 +852,12 @@ FUNCTIONS *libmodal-lua-utils-functions* -- If there were errors… if not noErrors then -- Show the error. - libmodal.utils.showError(pcallErr) + libmodal.utils.show_error(pcall_err) end < ============================================================================= -4.1. `libmodal.utils.api` *libmodal-lua-api* +8.1. `libmodal.utils.api` *libmodal-lua-api* Provides extensions to the `vim.api` |Lua| library. @@ -549,7 +988,7 @@ FUNCTIONS *libmodal-lua-api-functions* < ============================================================================== -4.2. `libmodal.utils.Help` *libmodal-lua-Help* +8.2. `libmodal.utils.Help` *libmodal-lua-Help* Allows for the creation of a default "Help" table. @@ -618,208 +1057,7 @@ FUNCTIONS *libmodal-lua-Help-functions* < ============================================================================== -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([[ -   - <<<<<>>>>> -   - ]]) - print_vars() -< - - -============================================================================== -4.5 `libmodal.utils.WindowState` *libmodal-lua-WindowState* +8.3. `libmodal.utils.WindowState` *libmodal-lua-WindowState* Tracks 'winheight' and 'winwidth' when created, so that it can be modified freely and then restored later. @@ -873,5 +1111,10 @@ FUNCTIONS *libmodal-lua-WindowState-functions* print_height() < +============================================================================= +9. `libmodal.Vars` *libmodal-lua-Vars* + +TODO. + ============================================================================== vim:tw=78:ts=4:ft=help:norl: diff --git a/lua/libmodal/init.lua b/lua/libmodal/init.lua index 7785cce..0d78360 100644 --- a/lua/libmodal/init.lua +++ b/lua/libmodal/init.lua @@ -6,6 +6,21 @@ local libmodal = require('libmodal/src') +--[[ + /* + * MIRRORS + */ +--]] + +libmodal.mode = {['enter'] = function(name, instruction, ...) + libmodal.Mode.new(name, instruction, ...):enter() +end} + +libmodal.prompt = {['enter'] = function(name, instruction, ...) + libmodal.Prompt.new(name, instruction, ...):enter() +end} + + --[[ /* * PUBLICIZE MODULE diff --git a/lua/libmodal/src/Mode/Popup.lua b/lua/libmodal/src/Mode/Popup.lua index 03b96bc..a88bfc1 100644 --- a/lua/libmodal/src/Mode/Popup.lua +++ b/lua/libmodal/src/Mode/Popup.lua @@ -36,22 +36,18 @@ local _winOpenOpts = { local _metaPopup = classes.new({}) -_metaPopup._buffer = nil -_metaPopup._inputChars = nil -_metaPopup.window = nil - --------------------------- --[[ SUMMARY: - * Close `self.window` + * Close `self._window` * The `self` is inert after calling this. ]] --------------------------- function _metaPopup:close() - api.nvim_win_close(self.window, false) + api.nvim_win_close(self._window, false) self._buffer = nil self._inputChars = nil - self.window = nil + self._window = nil end --------------------------------- diff --git a/lua/libmodal/src/Mode/init.lua b/lua/libmodal/src/Mode/init.lua index c09517c..3803f12 100644 --- a/lua/libmodal/src/Mode/init.lua +++ b/lua/libmodal/src/Mode/init.lua @@ -51,7 +51,7 @@ local _metaInputBytes = classes.new({ ----------------------------------------------- --[[ SUMMARY: - * Parse `self._mappings` and see if there is any command to execute. + * Parse `self.mappings` and see if there is any command to execute. ]] ----------------------------------------------- function _metaMode:_checkInputForMapping() @@ -59,12 +59,12 @@ function _metaMode:_checkInputForMapping() self._flushInputTimer:stop() -- Append the latest input to the locally stored input history. - local inputBytes = self._inputBytes + local inputBytes = self.inputBytes - inputBytes[#inputBytes + 1] = self._input:nvimGet() + inputBytes[#inputBytes + 1] = self.input:nvimGet() -- Get the command based on the users input. - local cmd = self._mappings:parseGet(inputBytes) + local cmd = self.mappings:parseGet(inputBytes) -- Get the type of the command. local commandType = type(cmd) @@ -127,7 +127,7 @@ function _metaMode:enter() -- If there were errors, handle them. if not noErrors then - utils.showError(modeResult) + utils.show_error(modeResult) continueMode = false else continueMode = modeResult @@ -151,10 +151,10 @@ function _metaMode:_initMappings() self._help = utils.Help.new(self._instruction, 'KEY MAP') end - self._inputBytes = setmetatable({}, _metaInputBytes) + self.inputBytes = setmetatable({}, _metaInputBytes) -- Build the parse tree. - self._mappings = collections.ParseTable.new(self._instruction) + self.mappings = collections.ParseTable.new(self._instruction) -- Create a table for mode-specific data. self._popups = collections.Stack.new() @@ -188,7 +188,7 @@ function _metaMode:_inputLoop() end -- Echo the indicator. - api.nvim_lecho(self._indicator) + api.nvim_lecho(self.indicator) -- Capture input. local userInput = api.nvim_input() @@ -199,7 +199,7 @@ function _metaMode:_inputLoop() end -- Set the global input variable to the new input. - self._input:nvimSet(userInput) + self.input:nvimSet(userInput) -- Make sure that the user doesn't want to exit. if not self._exit.supress @@ -222,7 +222,7 @@ end function _metaMode:_tearDown() if type(self._instruction) == globals.TYPE_TBL then self._flushInputTimer:stop() - self._inputBytes = nil + self.inputBytes = nil self._popups:pop():close() end @@ -252,7 +252,7 @@ function Mode.new(name, instruction, ...) local self = setmetatable( { ['_exit'] = Vars.new('exit', name), - ['_indicator'] = Indicator.mode(name), + ['indicator'] = Indicator.mode(name), ['_input'] = Vars.new('input', name), ['_instruction'] = instruction, ['_name'] = name, diff --git a/lua/libmodal/src/Prompt.lua b/lua/libmodal/src/Prompt.lua index 9b4ec93..745126a 100644 --- a/lua/libmodal/src/Prompt.lua +++ b/lua/libmodal/src/Prompt.lua @@ -51,16 +51,16 @@ function _metaPrompt:_inputLoop() local userInput = '' -- echo the highlighting - api.nvim_command('echohl ' .. self._indicator.hl) + api.nvim_command('echohl ' .. self.indicator.hl) -- set the user input variable if self._completions then userInput = api.nvim_call_function('libmodal#_inputWith', { - self._indicator.str, self._completions + self.indicator.str, self._completions }) else userInput = - api.nvim_call_function('input', {self._indicator}) + api.nvim_call_function('input', {self.indicator}) end -- get the instruction for the mode. @@ -68,7 +68,7 @@ function _metaPrompt:_inputLoop() -- determine what to do with the input if string.len(userInput) > 0 then -- the user actually entered something - self._input:nvimSet(userInput) + self.input:nvimSet(userInput) if type(instruction) == globals.TYPE_TBL then -- the instruction is a command table. if instruction[userInput] then -- there is a defined command for the input. api.nvim_command(instruction[userInput]) @@ -100,7 +100,7 @@ function _metaPrompt:enter() -- if there were errors. if not noErrors then - utils.showError(promptResult) + utils.show_error(promptResult) continueMode = false else continueMode = promptResult diff --git a/lua/libmodal/src/init.lua b/lua/libmodal/src/init.lua index 9a931ac..22b6196 100644 --- a/lua/libmodal/src/init.lua +++ b/lua/libmodal/src/init.lua @@ -6,27 +6,13 @@ local libmodal = {} -libmodal.classes = require('libmodal/src/classes') -libmodal.collection = require('libmodal/src/collections') -libmodal.globals = require('libmodal/src/globals') -libmodal.Indicator = require('libmodal/src/Indicator') -libmodal.Mode = require('libmodal/src/Mode') -libmodal.Prompt = require('libmodal/src/Prompt') -libmodal.utils = require('libmodal/src/utils') - ---[[ - /* - * MIRRORS - */ ---]] - -libmodal.mode = {['enter'] = function(name, instruction, ...) - libmodal.Mode.new(name, instruction, ...):enter() -end} - -libmodal.prompt = {['enter'] = function(name, instruction, ...) - libmodal.Prompt.new(name, instruction, ...):enter() -end} +libmodal.classes = require('libmodal/src/classes') +libmodal.collections = require('libmodal/src/collections') +libmodal.globals = require('libmodal/src/globals') +libmodal.Indicator = require('libmodal/src/Indicator') +libmodal.Mode = require('libmodal/src/Mode') +libmodal.Prompt = require('libmodal/src/Prompt') +libmodal.utils = require('libmodal/src/utils') --[[ /* diff --git a/lua/libmodal/src/utils/init.lua b/lua/libmodal/src/utils/init.lua index 9c05f34..4ba4956 100644 --- a/lua/libmodal/src/utils/init.lua +++ b/lua/libmodal/src/utils/init.lua @@ -29,10 +29,10 @@ utils.WindowState = require('libmodal/src/utils/WindowState') * Show an error from `pcall()`. ]] --[[ PARAMS: - `pcallErr` => the error generated by `pcall()`. + `pcall_err` => the error generated by `pcall()`. ]] ---------------------------------- -function utils.showError(pcallErr) +function utils.show_error(pcall_err) utils.api.nvim_bell() utils.api.nvim_show_err( globals.DEFAULT_ERROR_TITLE, @@ -40,7 +40,7 @@ function utils.showError(pcallErr) .. '\n' .. api.nvim_get_vvar('exception') .. '\n' .. - tostring(pcallErr) + tostring(pcall_err) ) end