feat: Consistent and sensible layout_config (#922)

* feat: Consistent and sensible layout_config

* [docgen] Update doc/telescope.txt
skip-checks: true

* [WIP]: Thu 17 Jun 2021 03:36:44 PM EDT

* [WIP]: Thu 17 Jun 2021 03:38:11 PM EDT

* layout_default -> layout_defaults

* remove options from bug repot

* Conni2461 suggestions: part 1

* [docgen] Update doc/telescope.txt
skip-checks: true

* Conni2461 suggestions: part 2

* [docgen] Update doc/telescope.txt
skip-checks: true

* Linting

* Improve deprecation checks

- Move `layout_defaults` handling to `deprecated.lua`
- Check for "layout keys" outside of `layout_config` on `setup`

* fixup: Just add a few more words

Co-authored-by: Luke Kershaw <35707277+l-kershaw@users.noreply.github.com>
Co-authored-by: Github Actions <actions@github>

1 files changed, 275 insertions, 94 deletions

diff --git a/lua/telescope/config.lua b/lua/telescope/config.lua
index da4c561..aecfcc6 100644
--- a/lua/telescope/config.lua
+++ b/lua/telescope/config.lua
@@ -1,11 +1,14 @@
-local strings = require('plenary.strings')
+local strings = require "plenary.strings"
+local deprecated = require "telescope.deprecated"
+local sorters = require "telescope.sorters"
+local if_nil = vim.F.if_nil
 
 -- Keep the values around between reloads
 _TelescopeConfigurationValues = _TelescopeConfigurationValues or {}
 _TelescopeConfigurationPickers = _TelescopeConfigurationPickers or {}
 
 local function first_non_null(...)
-  local n = select('#', ...)
+  local n = select("#", ...)
   for i = 1, n do
     local value = select(i, ...)
 
@@ -15,7 +18,26 @@ local function first_non_null(...)
   end
 end
 
-local sorters = require('telescope.sorters')
+-- A function that creates an amended copy of the `base` table,
+-- by replacing keys at "level 2" that match keys in "level 1" in `priority`,
+-- and then performs a deep_extend.
+-- May give unexpected results if used with tables of "depth"
+-- greater than 2.
+local smarter_depth_2_extend = function(priority, base)
+  local result = {}
+  for key, val in pairs(base) do
+    if type(val) ~= "table" then
+      result[key] = first_non_null(priority[key], val)
+    else
+      result[key] = {}
+      for k, v in pairs(val) do
+        result[key][k] = first_non_null(priority[k], v)
+      end
+    end
+  end
+  result = vim.tbl_deep_extend("keep", priority, result)
+  return result
+end
 
 -- TODO: Add other major configuration points here.
 -- selection_strategy
@@ -27,138 +49,298 @@ config.descriptions = {}
 config.pickers = _TelescopeConfigurationPickers
 
 function config.set_pickers(pickers)
-  pickers = pickers or {}
+  pickers = if_nil(pickers, {})
 
   for k, v in pairs(pickers) do
     config.pickers[k] = v
   end
 end
 
-function config.set_defaults(defaults)
-  defaults = defaults or {}
-
-  local function get(name, default_val)
-    return first_non_null(defaults[name], config.values[name], default_val)
-  end
-
-  local function set(name, default_val, description)
-    -- TODO(doc): Once we have descriptions for all of these, then we can add this back in.
-    -- assert(description, "Config values must always have a description")
-
-    config.values[name] = get(name, default_val)
-    if description then
-      config.descriptions[name] = strings.dedent(description)
-    end
-  end
-
-  set("sorting_strategy", "descending", [[
+local layout_config_defaults = {
+  width = 0.8,
+  height = 0.9,
+
+  horizontal = {
+    prompt_position = "bottom",
+    preview_cutoff = 120,
+  },
+
+  vertical = {
+    preview_cutoff = 40,
+  },
+
+  center = {
+    preview_cutoff = 40,
+  },
+}
+
+local layout_config_description = string.format([[
+    Determines the default configuration values for layout strategies.
+    See |telescope.layout| for details of the configurations options for
+    each strategy.
+
+    Allows setting defaults for all strategies as top level options and
+    for overriding for specific options.
+    For example, the default values below set the default width to 80%% of
+    the screen width for all strategies except 'center', which has width
+    of 50%% of the screen width.
+
+    Default: %s
+]], vim.inspect(
+  layout_config_defaults,
+  { newline = "\n    ", indent = "  " }
+))
+
+-- A table of all the usual defaults for telescope.
+-- Keys will be the name of the default,
+-- values will be a list where:
+-- - first entry is the value
+-- - second entry is the description of the option
+
+local telescope_defaults = {
+
+  sorting_strategy = {
+    "descending",
+    [[
     Determines the direction "better" results are sorted towards.
 
     Available options are:
     - "descending" (default)
-    - "ascending"]])
+    - "ascending"]],
+  },
 
-  set("selection_strategy", "reset", [[
+  selection_strategy = {
+    "reset",
+    [[
     Determines how the cursor acts after each sort iteration.
 
     Available options are:
     - "reset" (default)
     - "follow"
-    - "row"]])
+    - "row"]],
+  },
 
-  set("scroll_strategy", "cycle", [[
+  scroll_strategy = {
+    "cycle",
+    [[
     Determines what happens you try to scroll past view of the picker.
 
     Available options are:
     - "cycle" (default)
-    - "limit"]])
+    - "limit"]],
+  },
+
+  layout_strategy = {
+    "horizontal",
+    [[
+    Determines the default layout of Telescope pickers.
+    See |telescope.layout| for details of the available strategies.
 
-  set("layout_strategy", "horizontal")
-  set("layout_defaults", {})
+    Default: 'horizontal']],
+  },
 
-  set("width", 0.75)
-  set("winblend", 0)
-  set("prompt_position", "bottom")
-  set("preview_cutoff", 120)
+  layout_config = { layout_config_defaults, layout_config_description },
 
-  set("results_height", 1)
-  set("results_width", 0.8)
+  winblend = { 0 },
 
-  set("prompt_prefix", "> ", [[
+  prompt_prefix = { "> ", [[
     Will be shown in front of the prompt.
 
-    Default: '> ']])
-  set("selection_caret", "> ", [[
+    Default: '> ']]
+  },
+
+  selection_caret = { "> ", [[
     Will be shown in front of the selection.
 
-    Default: '> ']])
-  set("entry_prefix", "  ", [[
+    Default: '> ']]
+  },
+
+  entry_prefix = { "  ", [[
     Prefix in front of each result entry. Current selection not included.
 
-    Default: '  ']])
-  set("initial_mode", "insert")
+    Default: '  ']]
+  },
 
-  set("border", {})
-  set("borderchars", { '─', '│', '─', '│', '╭', '╮', '╯', '╰'})
+  initial_mode = { "insert" },
 
-  set("get_status_text", function(self)
-    local xx = (self.stats.processed or 0) - (self.stats.filtered or 0)
-    local yy = self.stats.processed or 0
-    if xx == 0 and yy == 0 then return "" end
+  border = { true, [[
+    Boolean defining if borders are added to Telescope windows.
 
-    return string.format("%s / %s", xx, yy)
-  end)
+    Default: true]]
+  },
 
-  -- Builtin configuration
+  borderchars = { { "─", "│", "─", "│", "╭", "╮", "╯", "╰" } },
 
-  -- List that will be executed.
-  --    Last argument will be the search term (passed in during execution)
-  set("vimgrep_arguments",
-      {'rg', '--color=never', '--no-heading', '--with-filename', '--line-number', '--column', '--smart-case'}
-  )
-  set("use_less", true)
-  set("color_devicons", true)
-
-  set("set_env", nil)
-
-  -- TODO: Add motions to keybindings
-
-  -- To disable a keymap, put [map] = false
-  --        So, to not map "<C-n>", just put
-  --
-  --            ...,
-  --            ["<C-n>"] = false,
-  --            ...,
-  --
-  --        Into your config.
-  --
-  -- Otherwise, just set the mapping to the function that you want it to be.
-  --
-  --            ...,
-  --            ["<C-i>"] = actions.select_default
-  --            ...,
-  --
-  set("mappings", {})
-  set("default_mappings", nil)
-
-  set("generic_sorter", sorters.get_generic_fuzzy_sorter)
-  set("prefilter_sorter", sorters.prefilter)
-  set("file_sorter", sorters.get_fuzzy_file)
-
-  set("file_ignore_patterns", nil)
-
-  set("dynamic_preview_title", false, [[
+  get_status_text = {
+    function(self)
+      local xx = (self.stats.processed or 0) - (self.stats.filtered or 0)
+      local yy = self.stats.processed or 0
+      if xx == 0 and yy == 0 then
+        return ""
+      end
+
+      return string.format("%s / %s", xx, yy)
+    end,
+  },
+
+  dynamic_preview_title = {
+    false,
+    [[
     Will change the title of the preview window dynamically, where it
     is supported. Means the preview window will for example show the
     full filename.
 
     Default: false
-  ]])
+    ]],
+  },
+
+  -- Builtin configuration
+
+  -- List that will be executed.
+  --    Last argument will be the search term (passed in during execution)
+  vimgrep_arguments = {
+    { "rg", "--color=never", "--no-heading", "--with-filename", "--line-number", "--column", "--smart-case" },
+  },
+
+  use_less = { true },
+
+  color_devicons = { true },
+
+  set_env = { nil },
+
+  mappings = {
+    {}, [[
+    Your mappings to override telescope's default mappings.
+
+    Format is:
+    {
+      mode = { ..keys }
+    }
+
+    where {mode} is the one character letter for a mode
+    ('i' for insert, 'n' for normal).
+
+    For example:
+
+    mappings = {
+      i = {
+        ["<esc>"] = require('telescope.actions').close,
+      },
+    }
+
+
+    To disable a keymap, put [map] = false
+      So, to not map "<C-n>", just put
+
+        ...,
+        ["<C-n>"] = false,
+        ...,
+
+      Into your config.
+
+
+    otherwise, just set the mapping to the function that you want it to be.
+
+        ...,
+        ["<C-i>"] = require('telescope.actions').select_default,
+        ...,
+
+    If the function you want is part of `telescope.actions`, then you can simply give a string.
+      For example, the previous option is equivalent to:
+
+        ...,
+        ["<C-i>"] = "select_default",
+        ...,
+
+    You can also add other mappings using tables with `type = "command"`.
+      For example:
+
+        ...,
+        ["jj"] = { "<esc>", type = "command" },
+        ["kk"] = { "<cmd>echo \"Hello, World!\"<cr>", type = "command" },)
+        ...,
+    ]],
+  },
+
+  default_mappings = {
+    nil,
+    [[
+    Not recommended to use except for advanced users.
+
+    Will allow you to completely remove all of telescope's default maps
+    and use your own.
+    ]],
+  },
+
+  generic_sorter = { sorters.get_generic_fuzzy_sorter },
+  prefilter_sorter = { sorters.prefilter },
+  file_sorter = { sorters.get_fuzzy_file },
+
+  file_ignore_patterns = { nil },
+
+  file_previewer = {
+    function(...)
+      return require("telescope.previewers").vim_buffer_cat.new(...)
+    end,
+  },
+  grep_previewer = {
+    function(...)
+      return require("telescope.previewers").vim_buffer_vimgrep.new(...)
+    end,
+  },
+  qflist_previewer = {
+    function(...)
+      return require("telescope.previewers").vim_buffer_qflist.new(...)
+    end,
+  },
+  buffer_previewer_maker = {
+    function(...)
+      return require("telescope.previewers").buffer_previewer_maker(...)
+    end,
+  },
+}
+
+-- @param user_defaults table: a table where keys are the names of options,
+--    and values are the ones the user wants
+-- @param tele_defaults table: (optional) a table containing all of the defaults
+--    for telescope [defaults to `telescope_defaults`]
+function config.set_defaults(user_defaults, tele_defaults)
+  user_defaults = if_nil(user_defaults, {})
+  tele_defaults = if_nil(tele_defaults, telescope_defaults)
+
+  -- Check if using layout keywords outside of `layout_config`
+  deprecated.picker_window_options(user_defaults)
+
+  -- Check if using `layout_defaults` instead of `layout_config`
+  user_defaults = deprecated.layout_configuration(user_defaults)
+
+  local function get(name, default_val)
+    if name == "layout_config" then
+      return smarter_depth_2_extend(
+        if_nil(user_defaults[name], {}),
+        vim.tbl_deep_extend("keep", if_nil(config.values[name], {}), if_nil(default_val, {}))
+      )
+    end
+    return first_non_null(user_defaults[name], config.values[name], default_val)
+  end
+
+  local function set(name, default_val, description)
+    -- TODO(doc): Once we have descriptions for all of these, then we can add this back in.
+    -- assert(description, "Config values must always have a description")
+
+    config.values[name] = get(name, default_val)
+    if description then
+      config.descriptions[name] = strings.dedent(description)
+    end
+  end
 
-  set("file_previewer", function(...) return require('telescope.previewers').vim_buffer_cat.new(...) end)
-  set("grep_previewer", function(...) return require('telescope.previewers').vim_buffer_vimgrep.new(...) end)
-  set("qflist_previewer", function(...) return require('telescope.previewers').vim_buffer_qflist.new(...) end)
-  set("buffer_previewer_maker", function(...) return require('telescope.previewers').buffer_previewer_maker(...) end)
+  for key, info in pairs(tele_defaults) do
+    set(key, info[1], info[2])
+  end
+
+  local M = {}
+  M.get = get
+  return M
 end
 
 function config.clear_defaults()
@@ -169,5 +351,4 @@ end
 
 config.set_defaults()
 
-
 return config