Archives
/
nvim-libmodal
mirror of https://github.com/Iron-E/nvim-libmodal
2
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #7 from Iron-E/feature/lua-function-instructions

Browse Source 
Feature/lua function instructions
pull/9/head release/0.8.0
Iron-E 4 years ago committed by GitHub
parent 38b7261a97 d35778cf91
commit ac97661680
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 385 additions and 264 deletions
Show Stats Download Patch File Download Diff File

354
doc/libmodal-lua.txt
Unescape Escape View File

@ -10,7 +10,7 @@ Any material not covered here is covered in |libmodal-usage|.
See: |libmodal-usage|, |lua|, |lua-require-example|. See: |libmodal-usage|, |lua|, |lua-require-example|.
============================================================================== ================================================================================
0. Table of Contents *libmodal-lua-toc* 0. Table of Contents *libmodal-lua-toc*
1. `libmodal` ............................. |libmodal-lua-libmodal| 1. `libmodal` ............................. |libmodal-lua-libmodal|
@ -31,15 +31,15 @@ See: |libmodal-usage|, |lua|, |lua-require-example|.
9.3. `libmodal.utils.WindowState` ........... |libmodal-lua-Windowstate| 9.3. `libmodal.utils.WindowState` ........... |libmodal-lua-Windowstate|
10. `libmodal.Vars` ........................ |libmodal-lua-Vars| 10. `libmodal.Vars` ........................ |libmodal-lua-Vars|
============================================================================== ================================================================================
1. `libmodal` *libmodal-lua-libmodal* 1. `libmodal` *libmodal-lua-libmodal*
This is the base of |libmodal|. It can be imported using: > This is the base of |libmodal|. It can be imported using: >
local libmodal = require('libmodal') local libmodal = require('libmodal')
<if |libmodal| is in your 'runtimepath'. <if |libmodal| is in your 'runtimepath'.
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
MODULES *libmodal-lua-modules* MODULES *libmodal-lua-modules*
 `libmodal`  `libmodal`
├──  `.collections` ├──  `.collections`
@ -60,8 +60,8 @@ MODULES *libmodal-lua-modules*
│ └──  `.WindowState` │ └──  `.WindowState`
└──  `.Vars` └──  `.Vars`
============================================================================== ================================================================================
2. `libmodal.classes` *libmodal-lua-classes* 2. `libmodal.classes` *libmodal-lua-classes*
`libmodal.classes` is a small library to help shorten the amount of `libmodal.classes` is a small library to help shorten the amount of
boilerplate code that it takes to set up a `metatable` and subsequent boilerplate code that it takes to set up a `metatable` and subsequent
@ -71,10 +71,10 @@ 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 into Lua, rather it is to help facilitate the emulation of
object orientation through `metatable`s. object orientation through `metatable`s.
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
FUNCTIONS *libmodal-lua-classes-functions* FUNCTIONS *libmodal-lua-classes-functions*
`classes`.new({name}, {base}) *libmodal-lua-classes.new()* `classes`.new({name}, {base}) *libmodal-lua-classes.new()*
Define a class-metatable. Define a class-metatable.
@ -88,7 +88,7 @@ FUNCTIONS *libmodal-lua-classes-functions*
Return: ~ Return: ~
A table set up to for use as a `metatable`. A table set up to for use as a `metatable`.
`classes`.type({value}) *libmodal-lua-classes.type()* `classes`.type({value}) *libmodal-lua-classes.type()*
Get the type of some {value}. Get the type of some {value}.
@ -100,24 +100,24 @@ FUNCTIONS *libmodal-lua-classes-functions*
`__type`. `__type`.
* Else, return `type(`{value}`)` * Else, return `type(`{value}`)`
============================================================================== ================================================================================
3. `libmodal.collections` *libmodal-lua-collections* 3. `libmodal.collections` *libmodal-lua-collections*
The `libmodal.collections` module consists of a few data structures that The `libmodal.collections` module consists of a few data structures that
support the rest of `libmodal`. support the rest of `libmodal`.
============================================================================== ================================================================================
3.1. `libmodal.collections.ParseTable` *libmodal-lua-ParseTable* 3.1. `libmodal.collections.ParseTable` *libmodal-lua-ParseTable*
A `ParseTable` is a pseudo-parse tree of a given user collection of A `ParseTable` is a pseudo-parse tree of a given user collection of
keybinding:expression pairs. keybinding:expression pairs.
See: |libmodal-mode| for more information. See: |libmodal-mode| for more information.
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
functions *libmodal-lua-ParseTable-functions* FUNCTIONS *libmodal-lua-ParseTable-functions*
`ParseTable`.CR *libmodal-lua-ParseTable.CR* `ParseTable`.CR *libmodal-lua-ParseTable.CR*
The character number for <CR>. The character number for <CR>.
@ -127,10 +127,10 @@ functions *libmodal-lua-ParseTable-functions*
Value: ~ Value: ~
13 13
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
FUNCTIONS *libmodal-lua-ParseTable-functions* FUNCTIONS *libmodal-lua-ParseTable-functions*
`ParseTable`.stringSplit({str}, {regex}) *libmodal-lua-ParseTable.stringSplit()* `ParseTable`.stringSplit({str}, {regex}) *libmodal-lua-ParseTable.stringSplit()*
Split some {str} into a `table` with a {regex} expression. Split some {str} into a `table` with a {regex} expression.
@ -148,7 +148,7 @@ FUNCTIONS *libmodal-lua-ParseTable-functions*
print(vim.inspect(ParseTable.stringSplit('testing split', ' '))) print(vim.inspect(ParseTable.stringSplit('testing split', ' ')))
< <
`ParseTable`.parse({key}) *libmodal-lua-ParseTable.parse()* `ParseTable`.parse({key}) *libmodal-lua-ParseTable.parse()*
Parse some {key} so that it can be stored by a `ParseTable` instance. Parse some {key} so that it can be stored by a `ParseTable` instance.
@ -175,7 +175,7 @@ FUNCTIONS *libmodal-lua-ParseTable-functions*
print(vim.inspect(ParseTable.parse('testkey'))) print(vim.inspect(ParseTable.parse('testkey')))
< <
`ParseTable`.new({userTable}) *libmodal-lua-ParseTable.new()* `ParseTable`.new({userTable}) *libmodal-lua-ParseTable.new()*
Create a new `ParseTable` from a user-defined `table` of combos. Create a new `ParseTable` from a user-defined `table` of combos.
@ -211,7 +211,7 @@ FUNCTIONS *libmodal-lua-ParseTable-functions*
|libmodal-mode| For information about {userTable}. |libmodal-mode| For information about {userTable}.
`self`:get({keyDict}) *libmodal-lua-ParseTable.get()* `self`:get({keyDict}) *libmodal-lua-ParseTable.get()*
Get a value from an instance of `ParseTable`. Get a value from an instance of `ParseTable`.
@ -243,7 +243,7 @@ FUNCTIONS *libmodal-lua-ParseTable-functions*
print(vim.inspect(tbl)) print(vim.inspect(tbl))
< <
`self`:parsePut({key}, {value}) *libmodal-lua-ParseTable.parsePut()* `self`:parsePut({key}, {value}) *libmodal-lua-ParseTable.parsePut()*
Put `value` into the parse tree as `key`. Put `value` into the parse tree as `key`.
@ -272,7 +272,7 @@ FUNCTIONS *libmodal-lua-ParseTable-functions*
|libmodal-lua-parsetable-parseputall| for how to put multiple {key}s |libmodal-lua-parsetable-parseputall| for how to put multiple {key}s
and {value}s at a time. and {value}s at a time.
`self`:parsePutAll({tableToUnite}) *libmodal-lua-ParseTable.parsePutAll()* `self`:parsePutAll({tableToUnite}) *libmodal-lua-ParseTable.parsePutAll()*
Create the union of `self` and `tableToUnite` Create the union of `self` and `tableToUnite`
@ -302,8 +302,8 @@ FUNCTIONS *libmodal-lua-ParseTable-functions*
|libmodal-lua-parsetable-parseput| For more information on |libmodal-lua-parsetable-parseput| For more information on
{tableToUnite}. {tableToUnite}.
============================================================================== ================================================================================
3.2. `libmodal.collections.Popup` *libmodal-lua-Popup* 3.2. `libmodal.collections.Popup` *libmodal-lua-Popup*
When `:enter()`ing a `Mode`, an |api-floatwin| is displayed at the bottom 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 right-hand corner of the screen. `libmodal.Mode.Popup` is responsible for
@ -325,10 +325,10 @@ opened with the following options: >
} }
< <
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
VARIABLES *libmodal-lua-Popup-variables* VARIABLES *libmodal-lua-Popup-variables*
`Popup`.config *libmodal-lua-Popup.apiOptions* `Popup`.config *libmodal-lua-Popup.apiOptions*
The options used when opening a `Popup`. The options used when opening a `Popup`.
@ -353,7 +353,7 @@ VARIABLES *libmodal-lua-Popup-variables*
} }
< <
`self`.buffer *libmodal-lua-Popup.buffer* `self`.buffer *libmodal-lua-Popup.buffer*
The scratch buffer used by `Popup` to display text. The scratch buffer used by `Popup` to display text.
@ -363,7 +363,7 @@ VARIABLES *libmodal-lua-Popup-variables*
Value: ~ Value: ~
`vim.api.nvim_create_buf(false, true)` `vim.api.nvim_create_buf(false, true)`
`self`.window *libmodal-lua-Popup.window* `self`.window *libmodal-lua-Popup.window*
The window used to display the contents of `Popup.buffer`. The window used to display the contents of `Popup.buffer`.
@ -373,16 +373,16 @@ VARIABLES *libmodal-lua-Popup-variables*
Value: ~ Value: ~
`vim.api.nvim_open_win(self.buffer, false, Popup.config)` `vim.api.nvim_open_win(self.buffer, false, Popup.config)`
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
FUNCTIONS *libmodal-lua-Popup-functions* FUNCTIONS *libmodal-lua-Popup-functions*
`self`:close() *libmodal-lua-Popup.close()* `self`:close() *libmodal-lua-Popup.close()*
Close the window that this `Popup` represents. Close the window that this `Popup` represents.
Note: All variables of `Popup` are de-initialized after this method. Note: All variables of `Popup` are de-initialized after this method.
`self`:refresh({inputBytes}) *libmodal-lua-Popup.refresh()* `self`:refresh({inputBytes}) *libmodal-lua-Popup.refresh()*
Update the content of the `Popup` using an array-like `table` of Update the content of the `Popup` using an array-like `table` of
|char2nr|s. |char2nr|s.
@ -395,19 +395,19 @@ FUNCTIONS *libmodal-lua-Popup-functions*
{inputBytes} An array-like `table` of |char2nr|s to write to the {inputBytes} An array-like `table` of |char2nr|s to write to the
`Popup`. `Popup`.
`Popup`.new() *libmodal-lua-Popup.new()* `Popup`.new() *libmodal-lua-Popup.new()*
Create a new `Popup` and immediately open it. Create a new `Popup` and immediately open it.
Return: ~ Return: ~
* A new `Popup`. * A new `Popup`.
See also: ~ See also: ~
|libmodal-lua-Popup| For the options used to spawn the window. |libmodal-lua-Popup| For the options used to spawn the window.
============================================================================== ================================================================================
4.2. `libmodal.collections.Stack` *libmodal-lua-Stack* 4.2. `libmodal.collections.Stack` *libmodal-lua-Stack*
The `libmodal.collections.Stack` is a simple implementation of a Stack data The `libmodal.collections.Stack` is a simple implementation of a Stack data
structure. It is designed with reuse of resources in mind, as structure. It is designed with reuse of resources in mind, as
@ -416,15 +416,15 @@ times.
The `#` operator in |Lua| will work on this structure. The `#` operator in |Lua| will work on this structure.
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
FUNCTIONS *libmodal-lua-Stack-functions* FUNCTIONS *libmodal-lua-Stack-functions*
`self`:peek() *libmodal-lua-Stack.peek()* `self`:peek() *libmodal-lua-Stack.peek()*
Access the value at the top of the stack without removing it. Access the value at the top of the stack without removing it.
Return: ~ Return: ~
* The value at the top of the stack. * The value at the top of the stack.
Example: ~ Example: ~
> >
@ -436,12 +436,12 @@ FUNCTIONS *libmodal-lua-Stack-functions*
print(stk:peek()) print(stk:peek())
< <
`self`:pop() *libmodal-lua-Stack.pop()* `self`:pop() *libmodal-lua-Stack.pop()*
Access the value at the top of the stack by removing it. Access the value at the top of the stack by removing it.
Return: ~ Return: ~
* The value at the top of the stack. * The value at the top of the stack.
Example: ~ Example: ~
> >
@ -455,7 +455,7 @@ FUNCTIONS *libmodal-lua-Stack-functions*
print(stk:peek()) print(stk:peek())
< <
`self`:push({value}) *libmodal-lua-Stack.push()* `self`:push({value}) *libmodal-lua-Stack.push()*
Push some {value} onto the top of the stack. Push some {value} onto the top of the stack.
@ -472,12 +472,12 @@ FUNCTIONS *libmodal-lua-Stack-functions*
print(vim.inspect(stk)) print(vim.inspect(stk))
< <
`Stack`.new() *libmodal-lua-Stack.new()* `Stack`.new() *libmodal-lua-Stack.new()*
Create a new `libmodal.collections.Stack` and return it. Create a new `libmodal.collections.Stack` and return it.
Return: ~ Return: ~
* A new `libmodal.collections.Stack`. * A new `libmodal.collections.Stack`.
Example: ~ Example: ~
> >
@ -487,16 +487,16 @@ FUNCTIONS *libmodal-lua-Stack-functions*
print(vim.inspect(stk)) print(vim.inspect(stk))
< <
============================================================================== ================================================================================
4. `libmodal.globals` *libmodal-lua-globals* 4. `libmodal.globals` *libmodal-lua-globals*
These are global functions used throughout the project. They are never These are global functions used throughout the project. They are never
modified and never meant TO be modified. modified and never meant TO be modified.
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
functions *libmodal-lua-globals-functions* FUNCTIONS *libmodal-lua-globals-functions*
`globals`.DEFAULT_ERROR_TITLE *libmodal-lua-globals.DEFAULT_ERROR_TITLE* `globals`.DEFAULT_ERROR_TITLE *libmodal-lua-globals.DEFAULT_ERROR_TITLE*
The default error message header for |libmodal| errors. The default error message header for |libmodal| errors.
@ -506,7 +506,7 @@ functions *libmodal-lua-globals-functions*
Value: ~ Value: ~
"vim-libmodal error" "vim-libmodal error"
`globals`.ESC_NR *libmodal-lua-globals.ESC_NR* `globals`.ESC_NR *libmodal-lua-globals.ESC_NR*
The byte of the <Esc> character. The byte of the <Esc> character.
@ -516,7 +516,7 @@ functions *libmodal-lua-globals-functions*
Value: ~ Value: ~
27 27
`globals`.TYPE_FUNC *libmodal-lua-globals.TYPE_FUNC* `globals`.TYPE_FUNC *libmodal-lua-globals.TYPE_FUNC*
The `string` yielded by `lua type(x)` when `x` is a `function`. The `string` yielded by `lua type(x)` when `x` is a `function`.
@ -526,7 +526,7 @@ functions *libmodal-lua-globals-functions*
Value: ~ Value: ~
"function" "function"
`globals`.TYPE_NUM *libmodal-lua-globals.TYPE_NUM* `globals`.TYPE_NUM *libmodal-lua-globals.TYPE_NUM*
The `string` yielded by `lua type(x)` when `x` is a `number`. The `string` yielded by `lua type(x)` when `x` is a `number`.
@ -536,7 +536,7 @@ functions *libmodal-lua-globals-functions*
Value: ~ Value: ~
"number" "number"
`globals`.TYPE_STR *libmodal-lua-globals.TYPE_STR* `globals`.TYPE_STR *libmodal-lua-globals.TYPE_STR*
The `string` yielded by `lua type(x)` when `x` is a `string`. The `string` yielded by `lua type(x)` when `x` is a `string`.
@ -546,7 +546,7 @@ functions *libmodal-lua-globals-functions*
Value: ~ Value: ~
"string" "string"
`globals`.TYPE_TBL *libmodal-lua-globals.TYPE_TBL* `globals`.TYPE_TBL *libmodal-lua-globals.TYPE_TBL*
The `string` yielded by `lua type(x)` when `x` is a `table`. The `string` yielded by `lua type(x)` when `x` is a `table`.
@ -556,7 +556,7 @@ functions *libmodal-lua-globals-functions*
Value: ~ Value: ~
"table" "table"
`globals`.VIM_FALSE *libmodal-lua-globals.VIM_FALSE* `globals`.VIM_FALSE *libmodal-lua-globals.VIM_FALSE*
The value Vimscript uses to return `false` (besides |v:false|). The value Vimscript uses to return `false` (besides |v:false|).
@ -566,7 +566,7 @@ functions *libmodal-lua-globals-functions*
Value: ~ Value: ~
0 0
`globals`.VIM_TRUE *libmodal-lua-globals.VIM_TRUE* `globals`.VIM_TRUE *libmodal-lua-globals.VIM_TRUE*
Type: ~ Type: ~
`number` `number`
@ -574,10 +574,10 @@ functions *libmodal-lua-globals-functions*
Value: ~ Value: ~
1 1
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
FUNCTIONS *libmodal-lua-globals-functions* FUNCTIONS *libmodal-lua-globals-functions*
`globals`.is_false({val}) *libmodal-lua-globals.is_false()* `globals`.is_false({val}) *libmodal-lua-globals.is_false()*
Determine whether or not some {val} is equal to `globals.VIM_FALSE`, Determine whether or not some {val} is equal to `globals.VIM_FALSE`,
|v:false|, or `false`. |v:false|, or `false`.
@ -587,9 +587,9 @@ FUNCTIONS *libmodal-lua-globals-functions*
expression. expression.
Return: ~ Return: ~
* `true` if {val} is equal to `globals.VIM_FALSE`, |v:false|, or - `true` if {val} is equal to `globals.VIM_FALSE`, |v:false|, or
`false`. `false`.
* `false` otherwise. - `false` otherwise.
Example: ~ Example: ~
> >
@ -618,7 +618,7 @@ FUNCTIONS *libmodal-lua-globals-functions*
print(libmodal.globals.is_false(vim_trueValue)) print(libmodal.globals.is_false(vim_trueValue))
< <
`globals`.is_true({val}) *libmodal-lua-globals.is_true()* `globals`.is_true({val}) *libmodal-lua-globals.is_true()*
Determine whether or not some {val} is equal to `globals.VIM_TRUE`, Determine whether or not some {val} is equal to `globals.VIM_TRUE`,
|v:true|, or `true`. |v:true|, or `true`.
@ -628,8 +628,8 @@ FUNCTIONS *libmodal-lua-globals-functions*
expression. expression.
Return: ~ Return: ~
* `true` if {val} is equal to `globals.VIM_TRUE`, |v:true|, or `true`. - `true` if {val} is equal to `globals.VIM_TRUE`, |v:true|, or `true`.
* `false` otherwise. - `false` otherwise.
Example: ~ Example: ~
> >
@ -658,15 +658,15 @@ FUNCTIONS *libmodal-lua-globals-functions*
print(libmodal.globals.is_true(vim_trueValue)) print(libmodal.globals.is_true(vim_trueValue))
< <
============================================================================== ================================================================================
5. `libmodal.utils.Indicator` *libmodal-lua-Indicator* 5. `libmodal.utils.Indicator` *libmodal-lua-Indicator*
Provides creation sources for mode and prompt |echo| / |echohl| `string`s. Provides creation sources for mode and prompt |echo| / |echohl| `string`s.
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
FUNCTIONS *libmodal-lua-indicator-functions* FUNCTIONS *libmodal-lua-indicator-functions*
`Indicator`.mode({modeName}) *libmodal-lua-Indicator.mode()* `Indicator`.mode({modeName}) *libmodal-lua-Indicator.mode()*
Create a new `Indicator` for a mode. Create a new `Indicator` for a mode.
@ -685,7 +685,7 @@ FUNCTIONS *libmodal-lua-indicator-functions*
|libmodal-lua-api.nvim_lecho()| For effective |echo|ing of this |libmodal-lua-api.nvim_lecho()| For effective |echo|ing of this
function. function.
`Indicator`.prompt({modeName}) *libmodal-lua-Indicator.prompt()* `Indicator`.prompt({modeName}) *libmodal-lua-Indicator.prompt()*
Create a new `Indicator` for a prompt. Create a new `Indicator` for a prompt.
@ -702,8 +702,8 @@ FUNCTIONS *libmodal-lua-indicator-functions*
See also: ~ See also: ~
|libmodal-prompt| For this function's use. |libmodal-prompt| For this function's use.
============================================================================== ================================================================================
5.1. `libmodal.Indicator.HighlightSegment` *libmodal-lua-HighlightSegment* 5.1. `libmodal.Indicator.HighlightSegment` *libmodal-lua-HighlightSegment*
The `HighlightSegment` is a map describing how a particular string should be The `HighlightSegment` is a map describing how a particular string should be
highlighted by Vim. highlighted by Vim.
@ -711,28 +711,28 @@ highlighted by Vim.
These `HighlightSegment`s can be put into a list and interpreted by These `HighlightSegment`s can be put into a list and interpreted by
`libmodal.utils.api.nvim_lecho()`. `libmodal.utils.api.nvim_lecho()`.
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
functions *libmodal-lua-HighlightSegment-functions* FUNCTIONS *libmodal-lua-HighlightSegment-functions*
`self`.hl *libmodal-lua-HighlightSegment.hl* `self`.hl *libmodal-lua-HighlightSegment.hl*
Which |highlight-group| to use when |highlight|ing `HighlightSegment.str`. Which |highlight-group| to use when |highlight|ing `HighlightSegment.str`.
Type: ~ Type: ~
|highlight-group| `string`. |highlight-group| `string`.
`self`.str *libmodal-lua-HighlightSegment.str* `self`.str *libmodal-lua-HighlightSegment.str*
What this `HighlightSegment`'s string value is. What this `HighlightSegment`'s string value is.
Type: ~ Type: ~
`string` `string`
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
FUNCTIONS *libmodal-lua-HighlightSegment-Functions* FUNCTIONS *libmodal-lua-HighlightSegment-Functions*
`HighlightSegment`.new({hlgroup}, {str}) *libmodal-lua-HighlightSegment.new()*
`HighlightSegment`.new({hlgroup}, {str}) *libmodal-lua-HighlightSegment.new()*
--
Create a new `HighlightSegment`. Create a new `HighlightSegment`.
Parameters: ~ Parameters: ~
@ -740,7 +740,7 @@ FUNCTIONS *libmodal-lua-HighlightSegment-Functions*
{str} The {str} to |highlight|. {str} The {str} to |highlight|.
Return: ~ Return: ~
* A new `HighlightSegment`. - A new `HighlightSegment`.
Example: ~ Example: ~
> >
@ -755,8 +755,8 @@ FUNCTIONS *libmodal-lua-HighlightSegment-Functions*
}) })
< <
============================================================================== ================================================================================
6. `libmodal.Layer` *libmodal-lua-Layer* 6. `libmodal.Layer` *libmodal-lua-Layer*
The libmodal `Layer` class provides many additional features to the base The libmodal `Layer` class provides many additional features to the base
`libmodal.layer.enter()`. `libmodal.layer.enter()`.
@ -766,10 +766,10 @@ 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, reference to a `Layer`, one can use the other `function`s that are provided,
and extend was is possible. and extend was is possible.
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
FUNCTIONS *libmodal-lua-Layer-functions* FUNCTIONS *libmodal-lua-Layer-functions*
`self`:enter() *libmodal-lua-Layer.enter()* `self`:enter() *libmodal-lua-Layer.enter()*
Enter the `Layer`. Enter the `Layer`.
@ -795,7 +795,7 @@ FUNCTIONS *libmodal-lua-Layer-functions*
See also: ~ See also: ~
|libmodal-lua-Layer.exit()| How to enter the `Layer`. |libmodal-lua-Layer.exit()| How to enter the `Layer`.
`self`:map({mode}, {lhs}, {rhs}, {options}) *libmodal-lua-Layer.enter()* `self`:map({mode}, {lhs}, {rhs}, {options}) *libmodal-lua-Layer.enter()*
Add a mapping to the `Layer`. Add a mapping to the `Layer`.
@ -836,7 +836,7 @@ FUNCTIONS *libmodal-lua-Layer-functions*
See also: ~ See also: ~
|nvim_buf_set_keymap()| For more information about the parameters. |nvim_buf_set_keymap()| For more information about the parameters.
`self`:unmap({mode}, {lhs}) *libmodal-lua-Layer.unmap()* `self`:unmap({mode}, {lhs}) *libmodal-lua-Layer.unmap()*
Remove a mapping from the `Layer`. Remove a mapping from the `Layer`.
@ -879,7 +879,7 @@ FUNCTIONS *libmodal-lua-Layer-functions*
See also: ~ See also: ~
|nvim_buf_del_keymap()| For more information about the parameters. |nvim_buf_del_keymap()| For more information about the parameters.
`self`:exit() *libmodal-lua-Layer.exit()* `self`:exit() *libmodal-lua-Layer.exit()*
Exit the `Layer`. Exit the `Layer`.
@ -910,7 +910,7 @@ FUNCTIONS *libmodal-lua-Layer-functions*
See also: ~ See also: ~
|libmodal-lua-Layer.enter()| How to enter the `Layer`. |libmodal-lua-Layer.enter()| How to enter the `Layer`.
`Layer`.new({keymap}) *libmodal-lua-Layer.new()* `Layer`.new({keymap}) *libmodal-lua-Layer.new()*
Create a new `Layer` for `mappings`. Create a new `Layer` for `mappings`.
@ -918,13 +918,13 @@ FUNCTIONS *libmodal-lua-Layer-functions*
{keymap} The list of |map|pings to replace. {keymap} The list of |map|pings to replace.
Returns: ~ Returns: ~
* A new `Layer`. - A new `Layer`.
See also: ~ See also: ~
|libmodal-layer| For more information about the parameters. |libmodal-layer| For more information about the parameters.
============================================================================== ================================================================================
7. `libmodal.Mode` *libmodal-lua-Mode* 7. `libmodal.Mode` *libmodal-lua-Mode*
While `libmodal.mode.enter()` may enter a mode, it silently creates a `Mode` While `libmodal.mode.enter()` may enter a mode, it silently creates a `Mode`
underneath: > underneath: >
@ -957,10 +957,10 @@ want to for their mode specifically. >
< (The specifications for these functions can be found at other places in this < (The specifications for these functions can be found at other places in this
document.) document.)
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
functions *libmodal-lua-Mode-functions* FUNCTIONS *libmodal-lua-Mode-functions*
`self`.exit *libmodal-lua-Mode.exit* `self`.exit *libmodal-lua-Mode.exit*
A liason to the `g:`{name}`ModeExit` variable. A liason to the `g:`{name}`ModeExit` variable.
@ -970,7 +970,7 @@ functions *libmodal-lua-Mode-functions*
Value: ~ Value: ~
`libmodal.Vars.new('exit', `{name}`)` `libmodal.Vars.new('exit', `{name}`)`
`self`.indicator *libmodal-lua-Mode.indicator* `self`.indicator *libmodal-lua-Mode.indicator*
The message that is shown in the bottom-left corner of the screen while the The message that is shown in the bottom-left corner of the screen while the
mode is active. mode is active.
@ -986,7 +986,7 @@ functions *libmodal-lua-Mode-functions*
Value: ~ Value: ~
`libmodal.Indicator.mode(`{name}`)` `libmodal.Indicator.mode(`{name}`)`
`self`.input *libmodal-lua-Mode.input* `self`.input *libmodal-lua-Mode.input*
A liason to `g:`{name}`ModeInput`. A liason to `g:`{name}`ModeInput`.
@ -999,7 +999,7 @@ functions *libmodal-lua-Mode-functions*
Value: ~ Value: ~
`libmodal.Vars.new('input', `{name}`)` `libmodal.Vars.new('input', `{name}`)`
`self`.inputBytes *libmodal-lua-Mode.inputBytes* `self`.inputBytes *libmodal-lua-Mode.inputBytes*
The history of user input, stored as |char2nr|s. The history of user input, stored as |char2nr|s.
@ -1011,10 +1011,10 @@ functions *libmodal-lua-Mode-functions*
array-like `table` of |char2nr|s. array-like `table` of |char2nr|s.
Value: ~ Value: ~
* `nil` => {instruction} is a `function`. - `nil` => {instruction} is a `function`.
* `{}` => {instruction} is a `table`. - `{}` => {instruction} is a `table`.
`self`.mappings *libmodal-lua-Mode.mappings* `self`.mappings *libmodal-lua-Mode.mappings*
The mappings that have been processed by a `Mode` when The mappings that have been processed by a `Mode` when
`libmodal.Mode.new()`'s {instruction} parameter is a `table`. `libmodal.Mode.new()`'s {instruction} parameter is a `table`.
@ -1032,10 +1032,10 @@ functions *libmodal-lua-Mode-functions*
|libmodal-lua-ParseTable| For information about how to use this |libmodal-lua-ParseTable| For information about how to use this
variable. variable.
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
FUNCTIONS *libmodal-lua-Mode-functions* FUNCTIONS *libmodal-lua-Mode-functions*
`self`:enter() *libmodal-lua-Mode.enter()* `self`:enter() *libmodal-lua-Mode.enter()*
Enter the `Mode` that was created. Enter the `Mode` that was created.
@ -1047,7 +1047,7 @@ FUNCTIONS *libmodal-lua-Mode-functions*
fooMode:enter() fooMode:enter()
< <
`Mode`.new({name}, {instruction} [, {supressExit}]) *libmodal-lua-Mode.new()* `Mode`.new({name}, {instruction} [, {supressExit}]) *libmodal-lua-Mode.new()*
Create a new `Mode` with a given {name}, using an {instruction} to perform 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. whenever a key is pressed, and whether or not to {supressExit} handling.
@ -1059,8 +1059,8 @@ FUNCTIONS *libmodal-lua-Mode-functions*
|libmodal-mode| For more information, as all of the parameters are |libmodal-mode| For more information, as all of the parameters are
the same. the same.
============================================================================== ================================================================================
8. `libmodal.Prompt` *libmodal-lua-Prompt* 8. `libmodal.Prompt` *libmodal-lua-Prompt*
While `libmodal.prompt.enter()` may enter a |libmodal-prompt|, itilently While `libmodal.prompt.enter()` may enter a |libmodal-prompt|, itilently
creates a `Mode` underneath: > creates a `Mode` underneath: >
@ -1072,10 +1072,10 @@ creates a `Mode` underneath: >
See |libmodal-lua-Mode| for more information about the possibilities that are See |libmodal-lua-Mode| for more information about the possibilities that are
enabled by using such a "class". enabled by using such a "class".
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
VARIABLES *libmodal-lua-Prompt-variables* VARIABLES *libmodal-lua-Prompt-variables*
`self`.indicator *libmodal-lua-Prompt.indicator* `self`.indicator *libmodal-lua-Prompt.indicator*
The message that is shown in the bottom-left corner of the screen while the The message that is shown in the bottom-left corner of the screen while the
mode is active. mode is active.
@ -1089,7 +1089,7 @@ VARIABLES *libmodal-lua-Prompt-variables*
Value: ~ Value: ~
`libmodal.Indicator.prompt(`{name}`)` `libmodal.Indicator.prompt(`{name}`)`
`self`.input *libmodal-lua-Prompt.input* `self`.input *libmodal-lua-Prompt.input*
A liason to `g:`{name}`ModeInput`. A liason to `g:`{name}`ModeInput`.
@ -1102,10 +1102,10 @@ VARIABLES *libmodal-lua-Prompt-variables*
Value: ~ Value: ~
`libmodal.Vars.new('input', `{name}`)` `libmodal.Vars.new('input', `{name}`)`
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
FUNCTIONS *libmodal-lua-Prompt-functions* FUNCTIONS *libmodal-lua-Prompt-functions*
`self`:enter() *libmodal-lua-Prompt.enter()* `self`:enter() *libmodal-lua-Prompt.enter()*
Enter the `Prompt` that was created. Enter the `Prompt` that was created.
@ -1117,7 +1117,7 @@ FUNCTIONS *libmodal-lua-Prompt-functions*
fooMode:enter() fooMode:enter()
< <
*libmodal-lua-Prompt.new()* *libmodal-lua-Prompt.new()*
`Prompt`.new({name}, {instruction} [, {completions}]) `Prompt`.new({name}, {instruction} [, {completions}])
User input is taken using |input()|. It is passed through a |g:var| User input is taken using |input()|. It is passed through a |g:var|
@ -1131,15 +1131,15 @@ FUNCTIONS *libmodal-lua-Prompt-functions*
|libmodal-prompt| For more information, as all of the parameters are |libmodal-prompt| For more information, as all of the parameters are
the same. the same.
============================================================================== ================================================================================
9. `libmodal.utils` *libmodal-lua-utils* 9. `libmodal.utils` *libmodal-lua-utils*
Provides extra utilities to the |libmodal| library. Provides extra utilities to the |libmodal| library.
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
FUNCTIONS *libmodal-lua-utils-functions* FUNCTIONS *libmodal-lua-utils-functions*
`utils`.show_error({pcall_err}) *libmodal-lua-utils.show_error()* `utils`.show_error({pcall_err}) *libmodal-lua-utils.show_error()*
Show an error from `pcall()`. Show an error from `pcall()`.
@ -1164,16 +1164,50 @@ FUNCTIONS *libmodal-lua-utils-functions*
< <
============================================================================= =============================================================================
9.1. `libmodal.utils.api` *libmodal-lua-api* 9.1. `libmodal.utils.api` *libmodal-lua-api*
Provides extensions to the `vim.api` |Lua| library. Provides extensions to the `vim.api` |Lua| library.
See: |API|. See: |API|.
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
FUNCTIONS *libmodal-lua-api-functions* 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()* `api`.nvim_bell() *libmodal-lua-api.nvim_bell()*
Make vim ring the visual/audio bell, if it is enabled. Make vim ring the visual/audio bell, if it is enabled.
@ -1181,7 +1215,7 @@ FUNCTIONS *libmodal-lua-api-functions*
> >
local libmodal = require('libmodal') local libmodal = require('libmodal')
libmoal.utils.api.nvim_bell() libmodal.utils.api.nvim_bell()
< <
See also: ~ See also: ~
@ -1189,7 +1223,7 @@ FUNCTIONS *libmodal-lua-api-functions*
'errorbells' For bell settings. 'errorbells' For bell settings.
'visualbell' For bell settings. 'visualbell' For bell settings.
`api`.nvim_exists({scope}, {var}) *libmodal-lua-api.nvim_exists()* `api`.nvim_exists({scope}, {var}) *libmodal-lua-api.nvim_exists()*
Check whether or not some |variable| exists. Check whether or not some |variable| exists.
@ -1209,7 +1243,7 @@ FUNCTIONS *libmodal-lua-api-functions*
print(libmodal.utils.api.nvim_exists('g', 'foo')) -- false print(libmodal.utils.api.nvim_exists('g', 'foo')) -- false
< <
`api`.nvim_input() *libmodal-lua-api.nvim_input()* `api`.nvim_input() *libmodal-lua-api.nvim_input()*
Gets one character of user input, as a number. Gets one character of user input, as a number.
@ -1231,7 +1265,7 @@ FUNCTIONS *libmodal-lua-api-functions*
print(char) print(char)
< <
`api`.nvim_lecho({hlTables}) *libmodal-lua-api.nvim_lecho()* `api`.nvim_lecho({hlTables}) *libmodal-lua-api.nvim_lecho()*
Echo an `Indicator`. Echo an `Indicator`.
Meant to be read as "nvim list echo". Meant to be read as "nvim list echo".
@ -1250,7 +1284,7 @@ FUNCTIONS *libmodal-lua-api-functions*
libmodal.utils.api.nvim_lecho(indicator) libmodal.utils.api.nvim_lecho(indicator)
< <
`api`.nvim_redraw() *libmodal-lua-api.nvim_redraw()* `api`.nvim_redraw() *libmodal-lua-api.nvim_redraw()*
Run |mode| to refresh the screen. Run |mode| to refresh the screen.
@ -1270,7 +1304,7 @@ FUNCTIONS *libmodal-lua-api-functions*
libmodal.utils.api.nvim_redraw() libmodal.utils.api.nvim_redraw()
< <
`api`.nvim_show_err({title}, {msg}) *libmodal-lua-api.nvim_show_err()* `api`.nvim_show_err({title}, {msg}) *libmodal-lua-api.nvim_show_err()*
Show a {title}-error with a given {msg}. Show a {title}-error with a given {msg}.
@ -1291,18 +1325,18 @@ FUNCTIONS *libmodal-lua-api-functions*
) )
< <
============================================================================== ================================================================================
9.2. `libmodal.utils.Help` *libmodal-lua-Help* 9.2. `libmodal.utils.Help` *libmodal-lua-Help*
Allows for the creation of a default "Help" table. Allows for the creation of a default "Help" table.
By default, this "Help" is shown by pressing `?` in a |libmodal-mode| or by By default, this "Help" is shown by pressing `?` in a |libmodal-mode| or by
entering "help" into a |libmodal-prompt|. entering "help" into a |libmodal-prompt|.
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
FUNCTIONS *libmodal-lua-Help-functions* FUNCTIONS *libmodal-lua-Help-functions*
`Help`.new({commandsOrMaps}, {title}) *libmodal-lua-Help.new()* `Help`.new({commandsOrMaps}, {title}) *libmodal-lua-Help.new()*
Create a default help table with `commandsOrMaps` and vim expressions. Create a default help table with `commandsOrMaps` and vim expressions.
@ -1333,7 +1367,7 @@ FUNCTIONS *libmodal-lua-Help-functions*
local mapsHelp = libmodal.utils.Help.new(maps, 'MAPS') local mapsHelp = libmodal.utils.Help.new(maps, 'MAPS')
< <
`self`:show() *libmodal-lua-Help.show()* `self`:show() *libmodal-lua-Help.show()*
Show the contents of this `Help`. Show the contents of this `Help`.
@ -1360,16 +1394,16 @@ FUNCTIONS *libmodal-lua-Help-functions*
mapsHelp:show() mapsHelp:show()
< <
============================================================================== ================================================================================
9.3. `libmodal.utils.WindowState` *libmodal-lua-WindowState* 9.3. `libmodal.utils.WindowState` *libmodal-lua-WindowState*
Tracks 'winheight' and 'winwidth' when created, so that it can be modified Tracks 'winheight' and 'winwidth' when created, so that it can be modified
freely and then restored later. freely and then restored later.
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
FUNCTIONS *libmodal-lua-WindowState-functions* FUNCTIONS *libmodal-lua-WindowState-functions*
`WindowState`.new() *libmodal-lua-WindowState.new()* `WindowState`.new() *libmodal-lua-WindowState.new()*
Create a table representing the size of the current window. Create a table representing the size of the current window.
@ -1387,7 +1421,7 @@ FUNCTIONS *libmodal-lua-WindowState-functions*
'winheight' The `height` property of a `WindowState`. 'winheight' The `height` property of a `WindowState`.
'winwidth' The `width` property of a `WindowState`. 'winwidth' The `width` property of a `WindowState`.
`self`:restore() *libmodal-lua-WindowState.restore()* `self`:restore() *libmodal-lua-WindowState.restore()*
Restore the state of this `WindowState`. Restore the state of this `WindowState`.
@ -1415,16 +1449,16 @@ FUNCTIONS *libmodal-lua-WindowState-functions*
print_height() print_height()
< <
============================================================================== ================================================================================
10. `libmodal.Vars` *libmodal-lua-Vars* 10. `libmodal.Vars` *libmodal-lua-Vars*
A `Var`'s purpose is to act as an intermediary between |global-variables| and A `Var`'s purpose is to act as an intermediary between |global-variables| and
the modes that use them. the modes that use them.
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
FUNCTIONS *libmodal-lua-Vars.functions* FUNCTIONS *libmodal-lua-Vars.functions*
`self`:name() *libmodal-lua-Vars.name()* `self`:name() *libmodal-lua-Vars.name()*
Get the name of `modeName`s global setting. Get the name of `modeName`s global setting.
@ -1432,7 +1466,7 @@ FUNCTIONS *libmodal-lua-Vars.functions*
{modeName} The name of the mode. {modeName} The name of the mode.
Return: ~ Return: ~
* The name of the vimscript variable that this `Var` corresponds to. - The name of the vimscript variable that this `Var` corresponds to.
Example: ~ Example: ~
> >
@ -1442,7 +1476,7 @@ FUNCTIONS *libmodal-lua-Vars.functions*
print(input:name()) -- 'fooModeInput' print(input:name()) -- 'fooModeInput'
< <
`self`:nvimGet() *libmodal-lua-Vars.nvimGet()* `self`:nvimGet() *libmodal-lua-Vars.nvimGet()*
Retrieve a variable value. Retrieve a variable value.
@ -1461,7 +1495,7 @@ FUNCTIONS *libmodal-lua-Vars.functions*
print(input:nvimGet()) print(input:nvimGet())
< <
`self`:nvimSet({val}) *libmodal-lua-Vars.nvimSet()* `self`:nvimSet({val}) *libmodal-lua-Vars.nvimSet()*
Set a |variable| value. Set a |variable| value.
@ -1478,7 +1512,7 @@ FUNCTIONS *libmodal-lua-Vars.functions*
print(input:nvimGet()) print(input:nvimGet())
< <
`Vars`.new(keyName, modeName) *libmodal-lua-Vars.new()* `Vars`.new(keyName, modeName) *libmodal-lua-Vars.new()*
Create a new `Var`. Create a new `Var`.
@ -1489,5 +1523,5 @@ FUNCTIONS *libmodal-lua-Vars.functions*
Return: ~ Return: ~
* A new `Var`. * A new `Var`.
============================================================================== ================================================================================
vim:tw=78:ts=4:ft=help:norl: vim:tw=80:ts=4:ft=help:norl:

153
doc/libmodal.txt
Unescape Escape View File

@ -1,9 +1,9 @@
*libmodal.txt* Create modes for Neovim *libmodal.txt* Create modes for Neovim
*libmodal* *libmodal*
*nvim-libmodal* *nvim-libmodal*
============================================================================= ================================================================================
0. Table of Contents *libmodal-toc* 0. Table of Contents *libmodal-toc*
1. About ................ |libmodal-about| 1. About ................ |libmodal-about|
2. Usage ................ |libmodal-usage| 2. Usage ................ |libmodal-usage|
@ -15,8 +15,8 @@
8. Changelog ............ |libmodal-changelog| 8. Changelog ............ |libmodal-changelog|
9. Credits .............. |libmodal-credits| 9. Credits .............. |libmodal-credits|
============================================================================== ================================================================================
1. About *libmodal-about* 1. About *libmodal-about*
|nvim-libmodal|: |nvim-libmodal|:
- Author, Iron-E @ https://github.com/Iron-E & https://gitlab.com/Iron_E - Author, Iron-E @ https://github.com/Iron-E & https://gitlab.com/Iron_E
@ -33,8 +33,8 @@ modes is also creator-defined, and is outlined in |libmodal-usage|.
See: |vim-modes| See: |vim-modes|
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
USE CASE *libmodal-use-case-example* USE CASE *libmodal-use-case-example*
As an |init.vim| configuration grows, it becomes harder to create keybindings As an |init.vim| configuration grows, it becomes harder to create keybindings
that alphabetically represent the action that they perform. To get around that alphabetically represent the action that they perform. To get around
@ -69,8 +69,8 @@ buffers persevere).
See: |libmodal-usage| See: |libmodal-usage|
============================================================================== ================================================================================
2. Usage *libmodal-usage* 2. Usage *libmodal-usage*
The |libmodal| interface is designed completely in |Lua|. It is compatable The |libmodal| interface is designed completely in |Lua|. It is compatable
with Vimscript, and so one may either: with Vimscript, and so one may either:
@ -92,8 +92,8 @@ Note: Examples for all topics covered here can be found in the "examples"
See: |api|, |lua-api|, https://github.com/Iron-E/nvim-tabmode, See: |api|, |lua-api|, https://github.com/Iron-E/nvim-tabmode,
https://gist.github.com/Iron-E/f36116e8862ea03fd195e4e0a48cb05d https://gist.github.com/Iron-E/f36116e8862ea03fd195e4e0a48cb05d
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
FUNCTIONS *libmodal-usage-functions* FUNCTIONS *libmodal-usage-functions*
*libmodal-mode* *libmodal#Enter()* *libmodal.mode.enter()* *libmodal-mode* *libmodal#Enter()* *libmodal.mode.enter()*
`libmodal.mode`.enter({name}, {instruction} [, {supressExit}]) `libmodal.mode`.enter({name}, {instruction} [, {supressExit}])
@ -127,7 +127,8 @@ FUNCTIONS *libmodal-usage-functions*
local modeInstruction = { local modeInstruction = {
['zf'] = 'split', ['zf'] = 'split',
['zfo'] = 'vsplit', ['zfo'] = 'vsplit',
['zfc'] = 'tabnew' -- You can also use lua functions
['zfc'] = function() return 'tabnew' end
} }
" VIMSCRIPT " VIMSCRIPT
@ -286,8 +287,8 @@ FUNCTIONS *libmodal-usage-functions*
|libmodal-examples-prompt| For examples of this function. |libmodal-examples-prompt| For examples of this function.
============================================================================== ================================================================================
3. Examples *libmodal-examples* 3. Examples *libmodal-examples*
Below are examples written in |Lua| to help show how specific features of Below are examples written in |Lua| to help show how specific features of
|libmodal| may be implemented. In each example, the name of the mode is |libmodal| may be implemented. In each example, the name of the mode is
@ -300,8 +301,8 @@ all be tested using the |luafile| |command|.
See: |libmodal-usage|, |libmodal-use-case|, |lua-require-example|. See: |libmodal-usage|, |libmodal-use-case|, |lua-require-example|.
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
MODES *libmodal-examples-modes* MODES *libmodal-examples-modes*
Using a callback `function`: > Using a callback `function`: >
local api = vim.api local api = vim.api
@ -356,7 +357,7 @@ Using a |key-mapping| `table`: >
< <
Exit Supression ~ Exit Supression ~
*libmodal-examples-supress-exit* *libmodal-examples-supress-exit*
Using a callback `function`: > Using a callback `function`: >
local libmodal = require('libmodal') local libmodal = require('libmodal')
@ -399,7 +400,7 @@ Using a |key-mapping| `table`: >
< <
Submodes ~ Submodes ~
*libmodal-examples-submodes* *libmodal-examples-submodes*
Using a callback `function`: > Using a callback `function`: >
local libmodal = require('libmodal') local libmodal = require('libmodal')
@ -457,8 +458,8 @@ Using a |key-mapping| `table`: >
fooMode() fooMode()
< <
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
LAYERS *libmodal-examples-layers* LAYERS *libmodal-examples-layers*
> >
local libmodal = require('libmodal') local libmodal = require('libmodal')
@ -481,8 +482,8 @@ LAYERS *libmodal-examples-layers*
vim.schedule_wrap(exitFunc) vim.schedule_wrap(exitFunc)
) )
< <
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
PROMPTS *libmodal-examples-prompts* PROMPTS *libmodal-examples-prompts*
Using a callback `function`: > Using a callback `function`: >
local libmodal = require('libmodal') local libmodal = require('libmodal')
@ -524,14 +525,14 @@ Using a |command| `table`: >
libmodal.prompt.enter('BAR', commands) libmodal.prompt.enter('BAR', commands)
< <
============================================================================== ================================================================================
4. Configuration *libmodal-configuration* 4. Configuration *libmodal-configuration*
The following specifies what settings may be used to configure The following specifies what settings may be used to configure
|libmodal-mode|s and |libmodal-prompt|s. |libmodal-mode|s and |libmodal-prompt|s.
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
HIGHLIGHT GROUPS *libmodal-highlight-groups* HIGHLIGHT GROUPS *libmodal-highlight-groups*
The following |highlight-groups| can be |config|ured to change a mode's |color|s: The following |highlight-groups| can be |config|ured to change a mode's |color|s:
@ -548,8 +549,8 @@ Note: `LibmodalStar`'s name — while not indicative of its use — is used for
when Neovim 0.5 launches that will introduce interoperaability between when Neovim 0.5 launches that will introduce interoperaability between
the two. the two.
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
TIMEOUTS *libmodal-timeouts* *g:libmodalTimeouts* TIMEOUTS *libmodal-timeouts* *g:libmodalTimeouts*
When `libmodal.mode.enter()`'s {instruction} argument is a `table`, mode When `libmodal.mode.enter()`'s {instruction} argument is a `table`, mode
creators may also enable the use of Vim's built-in 'timeout' feature. creators may also enable the use of Vim's built-in 'timeout' feature.
@ -631,8 +632,8 @@ then reset it upon exit. Example:
Mode creators who use `function` {instruction}s may define timeouts manually Mode creators who use `function` {instruction}s may define timeouts manually
using |timers|, which is how |libmodal| implements them internally. using |timers|, which is how |libmodal| implements them internally.
============================================================================== ================================================================================
5. License *libmodal-license* 5. License *libmodal-license*
`nvim-libmodal` – Create new "modes" for Neovim. `nvim-libmodal` – Create new "modes" for Neovim.
Copyright © 2020 Iron-E Copyright © 2020 Iron-E
@ -650,57 +651,57 @@ GNU General Public License for more details.
You should have received a copy of the GNU General Public License You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>. along with this program. If not, see <http://www.gnu.org/licenses/>.
============================================================================== ================================================================================
6. Bugs *libmodal-bugs* 6. Bugs *libmodal-bugs*
* `libmodal#Enter()` does not work when {instruction} is a |funcref|. * `libmodal#Enter()` does not work when {instruction} is a |funcref|.
* See |E5004|. * See |E5004|.
* `libmodal#Prompt()` does not work when {instruction} is a |funcref|. * `libmodal#Prompt()` does not work when {instruction} is a |funcref|.
* See |E5004|. * See |E5004|.
============================================================================== ================================================================================
7. Contributing *libmodal-contributing* 7. Contributing *libmodal-contributing*
The following describes what should be done if an individual wishes to The following describes what should be done if an individual wishes to
contribute something to the `Iron-E/nvim-libmodal` repository. contribute something to the `Iron-E/nvim-libmodal` repository.
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
CODE *libmodal-contributing-code* CODE *libmodal-contributing-code*
Bugfixes ~ Bugfixes ~
If you discover a bug and believe you know the solution to fixing it, then If you discover a bug and believe you know the solution to fixing it, then
submit a bug report and state that you are working on a fix (and what that submit a bug report and state that you are working on a fix (and what that
fix might be), and what general timeframe the fix may be completed in fix might be), and what general timeframe the fix may be completed in
(months, weeks, days, etc.). (months, weeks, days, etc.).
When the fix is complete, submit a PR that references the issue you When the fix is complete, submit a PR that references the issue you
submitted. submitted.
Features ~ Features ~
If there is a feature you would like to be a part of |libmodal|, the best If there is a feature you would like to be a part of |libmodal|, the best
thing you can do is submit a feature request, and then state that you are thing you can do is submit a feature request, and then state that you are
working on a pull request (PR) so others don't attempt to do the same work working on a pull request (PR) so others don't attempt to do the same work
at the same time. at the same time.
When you believe your feature is complete, write some examples for it in When you believe your feature is complete, write some examples for it in
the `examples/lua` folder, and add them to |libmodal-examples| as the `examples/lua` folder, and add them to |libmodal-examples| as
appropriate. appropriate.
Assure that all existing |libmodal-examples| continue to work with your Assure that all existing |libmodal-examples| continue to work with your
feature, unless a breaking change was discussed on the feature request. feature, unless a breaking change was discussed on the feature request.
If you need help getting them to pass, you can ask for help on the PR. If you need help getting them to pass, you can ask for help on the PR.
Reference the issue you submitted on the PR so that the two show up Reference the issue you submitted on the PR so that the two show up
together when looking back at the history. together when looking back at the history.
Contributing documentation is not necessary but appreciated, since the Contributing documentation is not necessary but appreciated, since the
person who knows the most about the feature being implemented is most person who knows the most about the feature being implemented is most
likely the one implementing it. likely the one implementing it.
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
DOCUMENTATION *libmodal-contributing-documentation* DOCUMENTATION *libmodal-contributing-documentation*
If there is a problem with the documentation, or you see an area where it If there is a problem with the documentation, or you see an area where it
could be improved, don't hesitate to submit an issue and a PR. At the very could be improved, don't hesitate to submit an issue and a PR. At the very
@ -708,8 +709,8 @@ least it will exist in history if such an issue comes up again, and likely it
will serve to help yourself and others with more clear and concise wording, or will serve to help yourself and others with more clear and concise wording, or
with more helpful and practical examples. with more helpful and practical examples.
------------------------------------------------------------------------------ --------------------------------------------------------------------------------
ISSUES *libmodal-contributing-issues* ISSUES *libmodal-contributing-issues*
Issues are greatly welcomed on the GitHub repository, whether they are bug Issues are greatly welcomed on the GitHub repository, whether they are bug
reports, feature requests, documentation improvements, or misunderstandings: reports, feature requests, documentation improvements, or misunderstandings:
@ -724,8 +725,18 @@ When submitting an issue, please describe the following:
4. Expected behavior (if applicable). 4. Expected behavior (if applicable).
5. Attached media (screenshots, logs, etc.) (if applicable). 5. Attached media (screenshots, logs, etc.) (if applicable).
============================================================================== ================================================================================
8. Changelog *libmodal-changelog* 8. Changelog *libmodal-changelog*
0.8.0 ~
Additions: ~
* Ability to use |lua| `function`s as values in a |libmodal-mode|
{instruction} `table` .
* Ability to use |lua| `function`s as values in a |libmodal-prompt|
{instruction} `table` .
* Add |libmodal-mode| and |libmodal-prompt| kill functions
(|libmodal-lua-utils-exit|).
0.7.0 ~ 0.7.0 ~
@ -837,8 +848,8 @@ When submitting an issue, please describe the following:
0.3.1 ~ 0.3.1 ~
Fixes: ~ Fixes: ~
* Fix bug where everytime `api.nvim_lecho()` was called, its {hlTables} would * Fix bug where everytime `api.nvim_lecho()` was called, its {hlTables}
infinitely grow with placeholder "None" entries. would infinitely grow with placeholder "None" entries.
0.3.0 ~ 0.3.0 ~
@ -866,8 +877,8 @@ When submitting an issue, please describe the following:
Additions: ~ Additions: ~
* |libmodal-mode| implementation from |vim-libmodal|. * |libmodal-mode| implementation from |vim-libmodal|.
============================================================================== ================================================================================
9. Credits *libmodal-credits* 9. Credits *libmodal-credits*
Credit Reason Credit Reason
--------------------- ---------------------------------- --------------------- ----------------------------------
@ -883,5 +894,5 @@ u/oryiesis Inspiration.
www.lua-users.org |Lua| reference. www.lua-users.org |Lua| reference.
www.stackoverflow.com Vimscript and |Lua| reference. www.stackoverflow.com Vimscript and |Lua| reference.
============================================================================== ================================================================================
vim:tw=78:ts=4:ft=help:norl: vim:tw=80:ts=4:ft=help:norl:

3
examples/lua/key-combos-submode.lua
Unescape Escape View File

@ -15,5 +15,8 @@ function FooMode()
fooModeRecurse = fooModeRecurse - 1 fooModeRecurse = fooModeRecurse - 1
end end
-- Define the character 'f' as the function we defined— but directly through lua, instead of vimL.
fooModeCombos['f'] = FooMode
-- Call FooMode() initially to begin the demo. -- Call FooMode() initially to begin the demo.
FooMode() FooMode()

10
examples/lua/key-combos.lua
Unescape Escape View File

@ -1,11 +1,19 @@
-- Imports -- Imports
local libmodal = require('libmodal') local libmodal = require('libmodal')
-- A function which will split the window both horizontally and vertically.
local function _split_twice()
local cmd = vim.api.nvim_command
cmd('split')
cmd('vsplit')
end
-- Register key combos for splitting windows and then closing windows -- Register key combos for splitting windows and then closing windows
local fooModeCombos = { local fooModeCombos = {
['zf'] = 'split', ['zf'] = 'split',
['zfo'] = 'vsplit', ['zfo'] = 'vsplit',
['zfc'] = 'q' ['zfc'] = 'q',
['zff'] = _split_twice
} }
-- Enter the mode using the key combos. -- Enter the mode using the key combos.

3
examples/lua/prompt-commands.lua
Unescape Escape View File

@ -5,7 +5,8 @@ local libmodal = require('libmodal')
local commands = { local commands = {
['new'] = 'tabnew', ['new'] = 'tabnew',
['close'] = 'tabclose', ['close'] = 'tabclose',
['last'] = 'tablast' ['last'] = 'tablast',
['exit'] = libmodal.utils.api.mode_exit
} }
-- Begin the prompt. -- Begin the prompt.

22
lua/libmodal/src/Mode.lua
Unescape Escape View File

@ -49,6 +49,22 @@ local _metaInputBytes = classes.new(nil, {
classes = nil classes = nil
-----------------------------------------------------------
--[[ SUMMARY:
* Execute some `selection` according to a set of determined logic.
]]
--[[ REMARKS:
* Only provides logic for when `self._instruction` is a table of commands.
]]
--[[ PARAMS:
* `selection` => The instruction that is desired to be executed.
]]
-----------------------------------------------------------
function _metaMode._commandTableExecute(instruction)
if type(instruction) == globals.TYPE_FUNC then instruction()
else api.nvim_command(instruction) end
end
----------------------------------------------- -----------------------------------------------
--[[ SUMMARY: --[[ 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.
@ -79,8 +95,6 @@ function _metaMode:_checkInputForMapping()
elseif commandType == globals.TYPE_TBL elseif commandType == globals.TYPE_TBL
and globals.is_true(self._timeouts.enabled) and globals.is_true(self._timeouts.enabled)
then then
-- Create a new timer
-- start the timer -- start the timer
self._flushInputTimer:start( self._flushInputTimer:start(
_TIMEOUT.LEN, 0, vim.schedule_wrap(function() _TIMEOUT.LEN, 0, vim.schedule_wrap(function()
@ -88,7 +102,7 @@ function _metaMode:_checkInputForMapping()
_TIMEOUT:SEND() _TIMEOUT:SEND()
-- if there is a command, execute it. -- if there is a command, execute it.
if cmd[ParseTable.CR] then if cmd[ParseTable.CR] then
api.nvim_command(cmd[ParseTable.CR]) self._commandTableExecute(cmd[ParseTable.CR])
end end
-- clear input -- clear input
inputBytes:clear() inputBytes:clear()
@ -98,7 +112,7 @@ function _metaMode:_checkInputForMapping()
-- The command was an actual vim command. -- The command was an actual vim command.
else else
api.nvim_command(cmd) self._commandTableExecute(cmd)
inputBytes:clear() inputBytes:clear()
end end

49
lua/libmodal/src/Prompt.lua
Unescape Escape View File

@ -36,6 +36,38 @@ end
local _metaPrompt = require('libmodal/src/classes').new(Prompt.TYPE) local _metaPrompt = require('libmodal/src/classes').new(Prompt.TYPE)
---------------------------------------------------
--[[ SUMMARY:
* Execute the specified instruction based on user input.
]]
--[[ PARAMS:
* `userInput` => the input from the user, used to determine how to execute the `self._instruction`.
]]
---------------------------------------------------
function _metaPrompt:_executeInstruction(userInput)
-- get the instruction for the mode.
local instruction = self._instruction
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.
local to_execute = instruction[userInput]
if type(to_execute) == globals.TYPE_FUNC then
to_execute()
else
api.nvim_command(instruction[userInput])
end
elseif userInput == _HELP then -- The user did not define a 'help' command, so use the default.
self._help:show()
else -- show an error.
utils.api.nvim_show_err(globals.DEFAULT_ERROR_TITLE, 'Unknown command')
end
elseif type(instruction) == globals.TYPE_STR and vim.fn then -- The instruction is a function. Works on Neovim 0.5+.
vim.fn[instruction]()
else -- attempt to call the instruction.
instruction()
end
end
--------------------------------- ---------------------------------
--[[ SUMMARY: --[[ SUMMARY:
* Loop to get user input with `input()`. * Loop to get user input with `input()`.
@ -61,25 +93,10 @@ function _metaPrompt:_inputLoop()
api.nvim_call_function('input', {self.indicator}) api.nvim_call_function('input', {self.indicator})
end end
-- get the instruction for the mode.
local instruction = self._instruction
-- determine what to do with the input -- determine what to do with the input
if string.len(userInput) > 0 then -- The user actually entered something. 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. self:_executeInstruction(userInput)
if instruction[userInput] then -- There is a defined command for the input.
api.nvim_command(instruction[userInput])
elseif userInput == _HELP then -- The user did not define a 'help' command, so use the default.
self._help:show()
else -- show an error.
utils.api.nvim_show_err(globals.DEFAULT_ERROR_TITLE, 'Unknown command')
end
elseif type(instruction) == globals.TYPE_STR and vim.fn then -- The instruction is a function. Works on Neovim 0.5+.
vim.fn[instruction]()
else -- attempt to call the instruction.
instruction()
end
else -- indicate we want to leave the prompt else -- indicate we want to leave the prompt
return false return false
end end

10
lua/libmodal/src/collections/ParseTable.lua
Unescape Escape View File

@ -106,7 +106,7 @@ local function _get(parseTable, splitKey)
else else
return _get(val, splitKey) return _get(val, splitKey)
end end
elseif valType == globals.TYPE_STR and #splitKey < 1 then elseif valType == globals.TYPE_STR or valType == globals.TYPE_FUNC and #splitKey < 1 then
return val return val
end end
end end
@ -129,9 +129,11 @@ local function _put(parseTable, splitKey, value)
if #splitKey > 0 then -- there are still characters left in the key. if #splitKey > 0 then -- there are still characters left in the key.
if not parseTable[k] then parseTable[k] = {} if not parseTable[k] then parseTable[k] = {}
-- If there is a previous command mapping in place -- If there is a previous command mapping in place
elseif type(parseTable[k]) == globals.TYPE_STR then else local valueType = type(parseTable[k])
-- Swap the mapping to a `CR` if valueType == globals.TYPE_STR or valueType == globals.TYPE_FUNC then
parseTable[k] = {[ParseTable.CR] = parseTable[k]} -- Swap the mapping to a `CR`
parseTable[k] = {[ParseTable.CR] = parseTable[k]}
end
end end
-- run _update() again -- run _update() again

25
lua/libmodal/src/utils/Help.lua
Unescape Escape View File

@ -1,3 +1,11 @@
--[[
/*
* IMPORTS
*/
--]]
local vim = vim
local globals = require('libmodal/src/globals')
--[[ --[[
/* /*
* MODULE * MODULE
@ -75,18 +83,21 @@ function Help.new(commandsOrMaps, title)
---------------------- ----------------------
local function tabAlign(tbl) local function tabAlign(tbl)
local toPrint = {} local toPrint = {}
for k, v in pairs(tbl) do for key, value in pairs(tbl) do
toPrint[#toPrint + 1] = k toPrint[#toPrint + 1] = key
local len = string.len(k) local len = string.len(key)
local byte = string.byte(k) local byte = string.byte(key)
-- account for ASCII chars that take up more space. -- account for ASCII chars that take up more space.
if byte <= 32 or byte == 127 then len = len + 1 if byte <= 32 or byte == 127 then len = len + 1 end
end
for _ = len, longestKeyLen do for _ = len, longestKeyLen do
toPrint[#toPrint + 1] = ' ' toPrint[#toPrint + 1] = ' '
end end
toPrint[#toPrint + 1] = table.concat(SEPARATOR_TEMPLATE, v)
toPrint[#toPrint + 1] = table.concat(
SEPARATOR_TEMPLATE,
(type(value) == globals.TYPE_STR) and value or '<lua function>'
)
end end
return toPrint return toPrint
end end

20
lua/libmodal/src/utils/api.lua
Unescape Escape View File

@ -5,8 +5,28 @@
--]] --]]
local api = {} local api = {}
local globals = require('libmodal/src/globals')
local vim_api = vim.api local vim_api = vim.api
---------------------------------
--[[ SUMMARY:
* Send a character to exit a mode.
]]
--[[ PARAMS:
* `exit_char` => the character used to exit the mode, or ESCAPE if none was provided.
]]
---------------------------------
function api.mode_exit(exit_char)
-- If there was no provided `exit_char`, or it is a character code.
if not exit_char or type(exit_char) == globals.TYPE_NUM then
-- Translate the character code or default to escape.
exit_char = string.char(exit_char or globals.ESC_NR)
end
-- Exit the prompt by sending an escape key.
vim_api.nvim_feedkeys(exit_char, 'nt', false)
end
------------------------ ------------------------
--[[ SUMMARY: --[[ SUMMARY:
* Make vim ring the visual/audio bell, if it is enabled. * Make vim ring the visual/audio bell, if it is enabled.

Write Preview
Loading…
Cancel
Save