Added `ui.command_entry.append_history()` for manually appending history.

Normally history is auto-appended by the default '\n' key handler, but some
custom modes may have their own '\n' handlers and did not have a way to append
history.

6 files changed, 55 insertions, 3 deletions

diff --git a/docs/api.md b/docs/api.md
index b601efad..f3f8b180 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -7996,6 +7996,16 @@ The height in pixels of the command entry.
 
 ### Functions defined by `ui.command_entry`
 
+<a id="ui.command_entry.append_history"></a>
+#### `ui.command_entry.append_history`(*text*)
+
+Appends the given text to the history for the current or most recent command
+entry mode.
+
+Parameters:
+
+* *`text`*: String text to append to history.
+
 <a id="ui.command_entry.focus"></a>
 #### `ui.command_entry.focus`()
 
diff --git a/docs/manual.md b/docs/manual.md
index 4fce4653..1efe9acc 100644
--- a/docs/manual.md
+++ b/docs/manual.md
@@ -1916,6 +1916,7 @@ N/A                        |Added   |[highlight_all_matches][]
 bufstatusbar\_text         |Renamed |[buffer_statusbar_text][]
 **ui.command_entry**       |        |
 N/A                        |Added   |[active][]
+N/A                        |Added   |[append_history][]
 **ui.dialogs**             |        |
 N/A                        |Added   |[progressbar()][]
 **ui.find**                |        |
@@ -1962,6 +1963,7 @@ section below.
 [paths]: api.html#textadept.snippets.paths
 [buffer_statusbar_text]: api.html#ui.buffer_statusbar_text
 [active]: api.html#ui.command_entry.active
+[append_history]: api.html#ui.command_entry.append_history
 [progressbar()]: api.html#ui.dialogs.progressbar
 
 ##### Buffer Indexing Changes
diff --git a/modules/lua/ta_api b/modules/lua/ta_api
index 3d9a9b7f..a7db7a60 100644
--- a/modules/lua/ta_api
+++ b/modules/lua/ta_api
@@ -333,6 +333,7 @@ ansi_c _G.snippets.ansi_c (table)\nTable of C-specific snippets.
 ansi_c _M.ansi_c (module)\nThe ansi_c module.\nIt provides utilities for editing C code.
 any lexer.any (pattern)\nA pattern that matches any single character.
 api_files textadept.editing.api_files (table)\nMap of lexer names to API documentation file tables.\nFile tables contain API file paths or functions that return such paths.\nEach line in an API file consists of a symbol name (not a fully qualified\nsymbol name), a space character, and that symbol's documentation. "\\n"\nrepresents a newline character.\n@see show_documentation
+append_history ui.command_entry.append_history(text)\nAppends the given text to the history for the current or most recent command\nentry mode.\n@param text String text to append to history.
 append_text buffer.append_text(buffer, text)\nAppends string *text* to the end of the buffer without modifying any existing\nselections or scrolling the text into view.\n@param buffer A buffer.\n@param text The text to append.
 arg _G.arg (table)\nTable of command line parameters passed to Textadept.\n@see args
 args _G.args (module)\nProcesses command line arguments for Textadept.
diff --git a/modules/lua/ta_tags b/modules/lua/ta_tags
index b0634779..a213f6ef 100644
--- a/modules/lua/ta_tags
+++ b/modules/lua/ta_tags
@@ -335,6 +335,7 @@ ansi_c	_HOME/modules/ansi_c/init.lua	/^module('_M.ansi_c')]]$/;"	m	class:_M
 ansi_c	_HOME/modules/ansi_c/init.lua	/^snippets.ansi_c = {$/;"	t	class:snippets
 any	_HOME/lexers/lexer.lua	/^module('lexer')]=]$/;"	F	class:lexer
 api_files	_HOME/modules/textadept/editing.lua	/^M.api_files = setmetatable({}, {__index = function(t, k)$/;"	t	class:textadept.editing
+append_history	_HOME/modules/textadept/command_entry.lua	/^function M.append_history(text)$/;"	f	class:ui.command_entry
 append_text	_HOME/core/.buffer.luadoc	/^function append_text(buffer, text) end$/;"	f	class:buffer
 arg	_HOME/core/init.lua	/^local arg$/;"	t	
 args	_HOME/core/args.lua	/^module('args')]]$/;"	m	
diff --git a/modules/textadept/command_entry.lua b/modules/textadept/command_entry.lua
index 594b1e81..5c30394e 100644
--- a/modules/textadept/command_entry.lua
+++ b/modules/textadept/command_entry.lua
@@ -35,6 +35,18 @@ local function cycle_history(prev)
 end
 
 ---
+-- Appends the given text to the history for the current or most recent command
+-- entry mode.
+-- @param text String text to append to history.
+-- @name append_history
+function M.append_history(text)
+  if not history.mode then return end
+  local mode_history = history[history.mode]
+  mode_history[#mode_history + 1] = assert_type(text, 'string', 1)
+  mode_history.pos = #mode_history
+end
+
+---
 -- A metatable with typical platform-specific key bindings for text entries.
 -- This metatable may be used to add basic editing and movement keys to command
 -- entry modes. It is automatically added to command entry modes unless a
@@ -217,9 +229,7 @@ function M.run(f, keys, lang, height)
       if M:auto_c_active() then return false end -- allow Enter to autocomplete
       M.focus() -- hide
       if not f then return end
-      local mode_history = history[history.mode]
-      mode_history[#mode_history + 1] = M:get_text()
-      mode_history.pos = #mode_history
+      M.append_history(M:get_text())
       f(M:get_text())
     end
   end
diff --git a/test/test.lua b/test/test.lua
index ec45165f..2d26293d 100644
--- a/test/test.lua
+++ b/test/test.lua
@@ -1332,6 +1332,34 @@ function test_command_entry_history()
   events.emit(events.KEYPRESS, not CURSES and 0xFF1B or 7) -- esc
 end
 
+function test_command_entry_history_append()
+  local f, keys = function() end, {['\n'] = ui.command_entry.focus}
+
+  ui.command_entry.run(f, keys)
+  ui.command_entry:set_text('foo')
+  events.emit(events.KEYPRESS, not CURSES and 0xFF0D or 343) -- \n
+
+  ui.command_entry.run(f, keys)
+  events.emit(events.KEYPRESS, not CURSES and 0xFF52 or 301) -- up
+  assert_equal(ui.command_entry:get_text(), '') -- no prior history
+  events.emit(events.KEYPRESS, not CURSES and 0xFF54 or 300) -- down
+  assert_equal(ui.command_entry:get_text(), '') -- no further history
+  events.emit(events.KEYPRESS, not CURSES and 0xFF0D or 343) -- \n
+  ui.command_entry.append_history('bar')
+
+  ui.command_entry.run(f, keys)
+  assert_equal(ui.command_entry:get_text(), 'bar')
+  assert_equal(ui.command_entry.selection_start, 1)
+  assert_equal(ui.command_entry.selection_end, 4)
+  events.emit(events.KEYPRESS, not CURSES and 0xFF52 or 301) -- up
+  assert_equal(ui.command_entry:get_text(), 'bar') -- no prior history
+  events.emit(events.KEYPRESS, not CURSES and 0xFF54 or 300) -- down
+  assert_equal(ui.command_entry:get_text(), 'bar') -- no further history
+  events.emit(events.KEYPRESS, not CURSES and 0xFF0D or 343) -- \n
+
+  assert_raises(function() ui.command_entry:append_history('text') end, 'string expected, got table')
+end
+
 function test_command_entry_mode_restore()
   local mode = 'test_mode'
   keys.mode = mode