feat: add support for wrapping history on reaching history begin or end (#2349)

doc/telescope.txt

@@ -402,6 +402,11 @@ telescope.setup({opts})                                    *telescope.setup()*
 
                         Default:
                         require('telescope.actions.history').get_simple_history
+          - cycle_wrap: Indicates whether the cycle_history_next and
+                        cycle_history_prev functions should wrap around to the
+                        beginning or end of the history entries on reaching
+                        their respective ends
+                        Default: false
 
                                           *telescope.defaults.cache_picker*
     cache_picker: ~
@@ -3637,14 +3642,17 @@ histories.History()                      *telescope.actions.history.History()*
 
 
     Fields: ~
-        {enabled} (boolean)  Will indicate if History is enabled or disabled
+        {enabled}    (boolean)  Will indicate if History is enabled or
+                                disabled
         {path}       (string)   Will point to the location of the history file
-        {limit}   (string)   Will have the limit of the history. Can be nil,
-                             if limit is disabled.
+        {limit}      (string)   Will have the limit of the history. Can be
+                                nil, if limit is disabled.
         {content}    (table)    History table. Needs to be filled by your own
                                 History implementation
-        {index}   (number)   Used to keep track of the next or previous index.
-                             Default is #content + 1
+        {index}      (number)   Used to keep track of the next or previous
+                                index. Default is #content + 1
+        {cycle_wrap} (boolean)  Controls if history will wrap on reaching
+                                beginning or end
 
 
 histories.History:new({opts})        *telescope.actions.history.History:new()*

lua/telescope/actions/history.lua

@@ -53,6 +53,7 @@ local histories = {}
 ---@field limit string: Will have the limit of the history. Can be nil, if limit is disabled.
 ---@field content table: History table. Needs to be filled by your own History implementation
 ---@field index number: Used to keep track of the next or previous index. Default is #content + 1
+---@field cycle_wrap boolean: Controls if history will wrap on reaching beginning or end
 histories.History = {}
 histories.History.__index = histories.History
 
@@ -75,6 +76,7 @@ function histories.History:new(opts)
   obj.path = vim.fn.expand(conf.history.path)
   obj.content = {}
   obj.index = 1
+  obj.cycle_wrap = conf.history.cycle_wrap
 
   opts.init(obj)
   obj._reset = opts.reset
@@ -125,6 +127,10 @@ function histories.History:get_next(line, picker)
   end
 
   local next_idx = self.index + 1
+  if next_idx > #self.content and self.cycle_wrap then
+    next_idx = 1
+  end
+
   if next_idx <= #self.content then
     self.index = next_idx
     return self.content[next_idx]
@@ -150,6 +156,10 @@ function histories.History:get_prev(line, picker)
   end
 
   local next_idx = self.index - 1
+  if next_idx < 1 and self.cycle_wrap then
+    next_idx = #self.content
+  end
+
   if self.index == #self.content + 1 then
     if line ~= "" then
       self:append(line, picker, true)

lua/telescope/config.lua

@@ -454,6 +454,7 @@ append(
     handler = function(...)
       return require("telescope.actions.history").get_simple_history(...)
     end,
+    cycle_wrap = false,
   },
   [[
   This field handles the configuration for prompt history.
@@ -482,7 +483,12 @@ append(
                   which allows context sensitive (cwd + picker) history.
 
                   Default:
-               require('telescope.actions.history').get_simple_history]]
+                  require('telescope.actions.history').get_simple_history
+    - cycle_wrap: Indicates whether the cycle_history_next and
+                  cycle_history_prev functions should wrap around to the
+                  beginning or end of the history entries on reaching
+                  their respective ends
+                  Default: false]]
 )
 
 append(