Update docs

doc/libmodal.txt

@@ -678,12 +678,26 @@ When submitting an issue, please describe the following:
 		* Call `libmodal.Mode.new()` or `libmodal.Prompt.new()` to create one.
 			* Call `{mode}:enter()` to enter the mode.
 		* More consistent mode recursion with `libmodal.collections.Stack`.
+		* Mode creators can now override specific functionality by copying
+		  portions of the source code, or changing the values that are
+		  referenced by the mode directly.
+			* This allows for finer control over how a mode behaves.
+			* It also allows for modes to inherit each other through
+			  `setmetatable()`.
 
 	* Removed program logic from `libmodal.mode.enter()`.
 		* Now internally calls `libmodal.Mode.new(…):enter()` instead.
 	* Removed program logic from `libmodal.prompt.enter()`.
 		* Now internally calls `libmodal.Prompt.new(…):enter()` instead.
 
+
+	Fixes: ~
+	* Fix unexpected behavior when repeating `libmodal.mode.enter()` calls
+	  with the from within themselves.
+	  * Mode popup windows may be closed prematurely by entering two different
+	    modes and then exiting them in reverse order, among other things. All
+	    previously known mysterious behavior is corrected.
+
 0.4.1 ~
 
 	Fixes: ~

lua/libmodal/src/Mode/init.lua

@@ -61,7 +61,7 @@ function _metaMode:_checkInputForMapping()
 	self._flushInputTimer:stop()
 
 	-- Append the latest input to the locally stored input history.
-	local inputBytes = self._modeEnterData:peek().inputBytes
+	local inputBytes = self._inputBytes
 
 	inputBytes[#inputBytes + 1] = self._input:nvimGet()
 
@@ -95,7 +95,7 @@ function _metaMode:_checkInputForMapping()
 				end
 				-- clear input
 				inputBytes:clear()
-				self._modeEnterData:peek().popup:refresh(inputBytes)
+				self._popups:peek():refresh(inputBytes)
 			end)
 		)
 
@@ -105,7 +105,7 @@ function _metaMode:_checkInputForMapping()
 		inputBytes:clear()
 	end
 
-	self._modeEnterData:peek().popup:refresh(inputBytes)
+	self._popups:peek():refresh(inputBytes)
 end
 
 --------------------------
@@ -117,13 +117,7 @@ function _metaMode:enter()
 	-- intialize variables that are needed for each recurse of a function
 	if type(self._instruction) == globals.TYPE_TBL then
 		-- Initialize the input history variable.
-		self._modeEnterData:push({
-			-- assign input
-			['inputBytes'] = setmetatable({}, _metaInputBytes),
-
-			-- create a floating window
-			['popup'] = Mode.Popup.new()
-		})
+		self._popups:push(Mode.Popup.new())
 	end
 
 
@@ -159,11 +153,13 @@ function _metaMode:_initMappings()
 		self._help = utils.Help.new(self._instruction, 'KEY MAP')
 	end
 
+	self._inputBytes = setmetatable({}, _metaInputBytes)
+
 	-- Build the parse tree.
 	self._mappings = collections.ParseTable.new(self._instruction)
 
 	-- Create a table for mode-specific data.
-	self._modeEnterData = collections.Stack.new()
+	self._popups = collections.Stack.new()
 
 	-- Create a variable for whether or not timeouts are enabled.
 	self._timeouts = Vars.new('timeouts', self._name)
@@ -228,16 +224,9 @@ end
 function _metaMode:_tearDown()
 	if type(self._instruction) == globals.TYPE_TBL then
 		self._flushInputTimer:stop()
+		self._inputBytes = nil
 
-		local modeEnterData = self._modeEnterData:pop()
-
-		for k, _ in pairs(modeEnterData.inputBytes) do
-			modeEnterData.inputBytes[k] = nil
-		end
-		modeEnterData.inputBytes = nil
-
-		modeEnterData.popup:close()
-		modeEnterData.popup = nil
+		self._popups:pop():close()
 	end
 
 	self._winState:restore()