feat: Action improvements (#472)

* feat: replace_map

* feat: Add action_set and action_state

* fix: Move all actions.get_ to action_state.get_

* fix: replace all internal references of _goto_file_selection_edit

* feat: add some docs

* fix: lint

* feat: actions.select

* remove mentions and usage of goto_file_selection APIs

* feat: special case attach_mappings to be overridable and defaultable

* Having goto_file_selection mappings will cause a error

as well as replacing deprecated goto_file_selection methodes

For config and replacing use this instead:
- actions.select_default
- actions.select_horizonal
- actions.select_vertical
- actions.select_tab

Only replacing:
- actions.set.edit -- for replacing all select functions

* adds actions.state.select_key_to_edit_key

Co-authored-by: Simon Hauser <Simon-Hauser@outlook.de>

lua/tests/automated/action_spec.lua

@@ -1,3 +1,6 @@
+local actions = require('telescope.actions')
+local action_set = require('telescope.actions.set')
+
 local transform_mod = require('telescope.actions.mt').transform_mod
 
 local eq = function(a, b)
@@ -51,6 +54,69 @@ describe('actions', function()
     eq("x", a.x())
   end)
 
+  it('allows overriding an action only in specific cases with if', function()
+    local a = transform_mod {
+      x = function(e) return e * 10 end,
+      y = function() return "y" end,
+    }
+
+    -- actions.file_goto_selection_edit:replace(...)
+    a.x:replace_if(
+      function(e) return e > 0 end,
+      function(e) return (e / 10) end
+    )
+    eq(-100, a.x(-10))
+    eq(10, a.x(100))
+    eq(1, a.x(10))
+
+    a._clear()
+    eq(100, a.x(10))
+  end)
+
+  it('allows overriding an action only in specific cases with mod', function()
+    local a = transform_mod {
+      x = function(e) return e * 10 end,
+      y = function() return "y" end,
+    }
+
+    -- actions.file_goto_selection_edit:replace(...)
+    a.x:replace_map {
+      [function(e) return e > 0 end] = function(e) return (e / 10) end,
+      [function(e) return e == 0 end] = function(e) return (e + 10) end,
+    }
+
+    eq(-100, a.x(-10))
+    eq(10, a.x(100))
+    eq(1, a.x(10))
+    eq(10, a.x(0))
+
+    a._clear()
+    eq(100, a.x(10))
+  end)
+
+  it('continuous replacement', function()
+    local a = transform_mod {
+      x = function() return "cleared" end,
+      y = function() return "y" end,
+    }
+
+    -- Replace original, which becomes new fallback
+    a.x:replace(function() return "negative" end)
+
+    -- actions.file_goto_selection_edit:replace(...)
+    a.x:replace_map {
+      [function(e) return e > 0 end] = function(e) return "positive" end,
+      [function(e) return e == 0 end] = function(e) return "zero" end,
+    }
+
+    eq("positive", a.x(10))
+    eq("zero"    , a.x(0))
+    eq("negative", a.x(-10))
+
+    a._clear()
+    eq("cleared", a.x(10))
+  end)
+
   it('enhance.pre', function()
     local a = transform_mod {
       x = function() return "x" end,
@@ -159,4 +225,27 @@ describe('actions', function()
     a.x:replace(function(bufnr) return string.format("modified: %s", bufnr) end)
     eq("modified: 5", a.x(5))
   end)
+
+  describe('action_set', function()
+    it('can replace `action_set.edit`', function()
+      action_set.edit:replace(function(_, arg) return "replaced:" .. arg end)
+      eq("replaced:edit", actions.file_edit())
+      eq("replaced:vnew", actions.file_vsplit())
+    end)
+
+    it('handles backwards compat with select and edit files', function()
+      -- Reproduce steps:
+      --  In config, we have { ["<CR>"] = actions.select, ... }
+      --  In caller, we have actions._goto:replace(...)
+      --  Person calls `select`, does not see update
+      action_set.edit:replace(function(_, arg) return "default_to_edit:" .. arg end)
+      eq("default_to_edit:edit", actions.select_default())
+
+      action_set.select:replace(function(_, arg) return "override_with_select:" .. arg end)
+      eq("override_with_select:default", actions.select_default())
+
+      -- Sometimes you might want to change the default selection...
+      --  but you don't want to prohibit the ability to edit the code...
+    end)
+  end)
 end)