Add comments to examples

examples/key-combos-manually.vim

@@ -1,5 +1,7 @@
+" Keep track of the user's input history manually.
 let s:inputHistory = []
 
+" Clear the input history if it grows too long for our usage.
 function! s:clear(indexToCheck) abort
 	if len(s:inputHistory) > a:indexToCheck
 		for i in range(len(s:inputHistory))
@@ -8,9 +10,12 @@ function! s:clear(indexToCheck) abort
 	endif
 endfunction
 
+" This is the function that will be called whenever the user presses a button.
 function! s:fooMode() abort
-	let s:inputHistory = add(s:inputHistory, nr2char(g:fooModeInput))
+	" Append to the input history, the latest button press.
+	let s:inputHistory = add(s:inputHistory, nr2char(g:fooModeInput)) " The input is a character number.
 
+	" Custom logic to test for each character index to see if it matches the 'zfo' mapping.
 	let l:index = 0
 	if s:inputHistory[0] == 'z'
 		if get(s:inputHistory, 1, v:null) == 'f'
@@ -27,4 +32,5 @@ function! s:fooMode() abort
 	call s:clear(l:index)
 endfunction
 
+" Enter the mode to begin the demo.
 lua require('libmodal').mode.enter('FOO', 's:fooMode')

examples/key-combos-submode.vim

@@ -1,14 +1,18 @@
+" Recurse counter.
 let s:barModeRecurse = 0
 
+" Register 'z' as the map for recursing further (by calling the BarMode function again).
 let s:barModeCombos = {
 \	'z': 'BarModeEnter',
 \}
 
+" define the BarMode() function which is called whenever the user presses 'z'
 function! s:BarMode()
 	let s:barModeRecurse += 1
 	call libmodal#Enter('BAR' . s:barModeRecurse, s:barModeCombos)
 	let s:barModeRecurse -= 1
 endfunction
 
+" Call BarMode() initially to begin the demo.
 command! BarModeEnter call s:BarMode()
 execute 'BarModeEnter'

examples/key-combos-supress-exit.vim

@@ -1,7 +1,11 @@
+" Register key commands and what they do.
 let s:barModeCombos = {
 \	'': 'echom "You cant exit using escape."',
 \	'q': 'let g:barModeExit = 1'
 \}
 
+" Tell the mode not to exit automatically.
 let g:barModeExit = 0
+
+" Enter the mode using the key combos created before.
 call libmodal#Enter('BAR', s:barModeCombos, 1)

examples/key-combos.vim

@@ -1,7 +1,9 @@
+" Register key combos for splitting windows and then closing windows
 let s:barModeCombos = {
 \	'zf': 'split',
 \	'zfo': 'vsplit',
 \	'zfc': 'q'
 \}
 
+" Enter the mode using the key combos.
 call libmodal#Enter('BAR', s:barModeCombos)

examples/lua/key-combos-manually.lua

@@ -1,8 +1,11 @@
+-- Imports
 local api      = vim.api
 local libmodal = require('libmodal')
 
+-- Keep track of the user's input history manually.
 local _inputHistory = {}
 
+-- Clear the input history if it grows too long for our usage.
 function _inputHistory:clear(indexToCheck)
 	if #self >= indexToCheck then
 		for i, _ in ipairs(self) do
@@ -11,11 +14,15 @@ function _inputHistory:clear(indexToCheck)
 	end
 end
 
+-- This is the function that will be called whenever the user presses a button.
 local function fooMode()
+	-- Append to the input history, the latest button press.
 	_inputHistory[#_inputHistory + 1] = string.char(
+		-- The input is a character number.
 		api.nvim_get_var('fooModeInput')
 	)
 
+	-- Custom logic to test for each character index to see if it matches the 'zfo' mapping.
 	local index = 1
 	if _inputHistory[1] == 'z' then
 		if _inputHistory[2] == 'f' then
@@ -30,4 +37,5 @@ local function fooMode()
 	_inputHistory:clear(index)
 end
 
+-- Enter the mode to begin the demo.
 libmodal.mode.enter('FOO', fooMode)

examples/lua/key-combos-submode.lua

@@ -1,14 +1,19 @@
+-- Imports
 local libmodal = require('libmodal')
 
+-- Recurse counter.
 local fooModeRecurse = 0
+-- Register 'z' as the map for recursing further (by calling the FooMode function again).
 local fooModeCombos  = {
 	['z'] = 'lua FooMode()'
 }
 
+-- define the FooMode() function which is called whenever the user presses 'z'
 function FooMode()
 	fooModeRecurse = fooModeRecurse + 1
 	libmodal.mode.enter('FOO' .. fooModeRecurse, fooModeCombos)
 	fooModeRecurse = fooModeRecurse - 1
 end
 
+-- Call FooMode() initially to begin the demo.
 FooMode()

examples/lua/key-combos-supress-exit.lua

@@ -1,8 +1,14 @@
+-- Imports
 local libmodal = require('libmodal')
+
+-- Register key commands and what they do.
 local fooModeCombos = {
 	[''] = 'echom "You cant exit using escape."',
 	['q'] = 'let g:fooModeExit = 1'
 }
 
+-- Tell the mode not to exit automatically.
 vim.api.nvim_set_var('fooModeExit', 0)
+
+-- Enter the mode using the key combos created before.
 libmodal.mode.enter('FOO', fooModeCombos, true)

examples/lua/key-combos.lua

@@ -1,8 +1,12 @@
+-- Imports
 local libmodal = require('libmodal')
+
+-- Register key combos for splitting windows and then closing windows
 local fooModeCombos = {
 	['zf'] = 'split',
 	['zfo'] = 'vsplit',
 	['zfc'] = 'q'
 }
 
+-- Enter the mode using the key combos.
 libmodal.mode.enter('FOO', fooModeCombos)

examples/lua/layer-simple.lua

@@ -1,3 +1,4 @@
+-- Imports
 local libmodal = require('libmodal')
 
 -- create a new layer.
@@ -14,7 +15,7 @@ local exitFunc = libmodal.layer.enter({
 	}
 })
 
--- the layer will deactivate in 5 seconds.
+-- The layer will deactivate in 5 seconds for this demo.
 vim.loop.new_timer():start(5000, 0, vim.schedule_wrap(
 	function() exitFunc(); print('EXITED.') end
 ))

examples/lua/layer.lua

@@ -1,3 +1,4 @@
+-- Imports
 local libmodal = require('libmodal')
 
 -- create a new layer.

examples/lua/prompt-callback.lua

@@ -1,7 +1,11 @@
+-- Imports
 local libmodal = require('libmodal')
 local api = vim.api
+
+-- The list of commands. Providing this will allow for autocomplete.
 local commandList = {'new', 'close', 'last'}
 
+-- The function which will be called whenever the user enters a command.
 function FooMode()
 	local userInput = vim.api.nvim_get_var('fooModeInput')
 	if userInput == 'new' then
@@ -13,4 +17,5 @@ function FooMode()
 	end
 end
 
+-- Enter the prompt.
 libmodal.prompt.enter('FOO', FooMode, commandList)

examples/lua/prompt-commands.lua

@@ -1,8 +1,12 @@
+-- Import
 local libmodal = require('libmodal')
+
+-- Define commands through a dictionary.
 local commands = {
 	['new']   = 'tabnew',
 	['close'] = 'tabclose',
 	['last']  = 'tablast'
 }
 
+-- Begin the prompt.
 libmodal.prompt.enter('FOO', commands)

examples/lua/submodes.lua

@@ -1,11 +1,18 @@
+-- Imports
 local libmodal = require('libmodal')
+
+-- Recurse counter
 local fooModeRecurse = 1
 
+-- Function which is called whenever the user presses a button
 function FooMode()
+	-- Append to the input history, the latest button press.
 	local userInput = string.char(vim.api.nvim_get_var(
+		-- The input is a character number.
 		'foo' .. tostring(fooModeRecurse) .. 'ModeInput'
 	))
 
+	-- If the user pressed 'z', then increase the counter and recurse.
 	if userInput == 'z' then
 		fooModeRecurse = fooModeRecurse + 1
 		Enter()
@@ -13,8 +20,10 @@ function FooMode()
 	end
 end
 
+-- Function to wrap around entering the mode so it can be recursively called.
 function Enter()
 	libmodal.mode.enter('FOO' .. fooModeRecurse, FooMode)
 end
 
+-- Initially call the function to begin the demo.
 Enter()

examples/lua/supress-exit.lua

@@ -1,17 +1,25 @@
+-- Imports
 local api = vim.api
 local libmodal = require('libmodal')
 
+-- Function which is called whenever the user presses a button
 local function fooMode()
+	-- Append to the input history, the latest button press.
 	local userInput = string.char(
+		-- The input is a character number.
 		api.nvim_get_var('fooModeInput')
 	)
 
 	if userInput == '' then
 		api.nvim_command("echom 'You cant leave using <Esc>.'")
 	elseif userInput == 'q' then
+		-- If the user presses 'q', libmodal will exit the mode.
 		api.nvim_set_var('fooModeExit', true)
 	end
 end
 
+-- Tell libmodal not to exit the mode immediately.
 api.nvim_set_var('fooModeExit', 0)
+
+-- Enter the mode.
 libmodal.mode.enter('FOO', fooMode, true)

examples/prompt-callback.vim

@@ -1,5 +1,7 @@
+" This is the list of commands— used for auto completion.
 let s:commandList = ['new', 'close', 'last']
 
+" This function will be called whenever a command is entered.
 function! s:fooMode() abort
 	let l:userInput = g:fooModeInput
 	if userInput == 'new'
@@ -11,4 +13,5 @@ function! s:fooMode() abort
 	endif
 endfunction
 
+" You have to convert s:commandList from a Vimscript list to a lua table using luaeval().
 call luaeval("require('libmodal').prompt.enter('FOO', 's:fooMode', _A)", s:commandList)

examples/submodes.vim

@@ -1,5 +1,7 @@
+" This is a counter.
 let s:fooModeRecurse = 1
 
+" This is a function to increase the counter every time that 'z' is pressed.
 function! s:fooMode() abort
 	let l:userInput = nr2char(g:foo{s:fooModeRecurse}ModeInput)
 
@@ -10,8 +12,10 @@ function! s:fooMode() abort
 	endif
 endfunction
 
+" This function wraps around calling libmodal so that the other function can recursively call it.
 function! s:enter() abort
 	call luaeval("require('libmodal').mode.enter('FOO'.._A, 's:fooMode')", s:fooModeRecurse)
 endfunction
 
+" Begin the recursion.
 call s:enter()

examples/supress-exit.vim

@@ -1,17 +1,15 @@
-local api = vim.api
+" Function which is called every time the user presses a button.
-local libmodal = require('libmodal')
+function! s:fooMode() abort
+	let l:userInput = nr2char(g:fooModeInput)
 
-local function fooMode()
+	if l:userInput == ''
-	local userInput = string.char(
+		echom 'You cant leave using <Esc>.'
-		api.nvim_get_var('fooModeInput')
+	elseif l:userInput == 'q'
-	)
+		let g:fooModeExit = v:true
+	endif
+endfunction
 
-	if userInput == '' then
+" Tell the mode not to exit automatically.
-		api.nvim_command("echom 'You cant leave using <Esc>.'")
+let g:fooModeExit = v:false
-	elseif userInput == 'q' then
+" Begin the mode.
-		api.nvim_set_var('fooModeExit', true)
+lua require('libmodal').mode.enter('FOO', 's:fooMode', true)
-	end
-end
-
-api.nvim_set_var('fooModeExit', 0)
-libmodal.mode.enter('FOO', fooMode, true)