feat: v0.1 of extensions (#278)

README.md

@@ -428,6 +428,32 @@ Themes should work with every `telescope.builtin` function.  If you wish to
 make theme, check out `lua/telescope/themes.lua`. If you need more features,
 make an issue :).
 
+
+## Extensions
+
+Telescope provides the capabilties to create & register extensions, which improve telescope in a variety of ways.
+
+Some extensions provide integration with external tools, outside of the scope of `builtins`. Others provide performance
+enhancements by using compiled C and interfacing directly with Lua.
+
+For example:
+- [fzy-native](https://github.com/nvim-telescope/telescope-fzy-native.nvim) : WIP native FZY sorter that uses compiled C to do the matching.
+- [nvim-dap integration](https://github.com/nvim-telescope/telescope-dap.nvim) : WIP nvim-dap integration.
+
+Extensions can be refenced by doing the following:
+
+```lua
+-- Run the `configurations` picker from nvim-dap (not yet implemented)
+require('telescope').extensions.dap.configurations()
+```
+
+To pre-load an extension (so that it will override default configurations), you can do:
+
+```lua
+-- This will load fzy_native and have it override the default file sorter
+require('telescope').load_extension('fzy_native')
+```
+
 ## API
 <!-- TODO: need to provide working examples for every api -->
 

lua/telescope/_extensions/init.lua

@@ -0,0 +1,62 @@
+local extensions = {}
+
+extensions._loaded = {}
+extensions._config = {}
+
+extensions.manager = setmetatable({}, {
+  __index = function(t, k)
+    -- See if this extension exists.
+    local ok, ext = pcall(require, 'telescope._extensions.' .. k)
+    if not ok then
+      error("This extenion doesn't exist or is not installed: " .. k .. "\n" .. ext)
+    end
+
+    if ext.setup then
+      ext.setup(extensions._config[k] or {}, require('telescope.config').values)
+    end
+
+    t[k] = ext.exports or {}
+
+    return t[k]
+  end,
+})
+
+--- Register an extension module.
+---
+--- Extensions have several important keys.
+---     - setup:
+---         function(ext_config, config) -> nil
+---
+---         Called when first loading the extension.
+---         The first parameter is the config passed by the user
+---             in telescope setup. The second parameter is the resulting
+---             config.values after applying the users setup defaults.
+---
+---         It is acceptable for a plugin to override values in config,
+---         as some plugins will be installed simply to manage some setup,
+---         install some sorter, etc.
+---
+---     - exports:
+---         table
+---
+---         Only the items in `exports` will be exposed on the  resulting
+---         module that users can access via require('telescope').extensions.foo
+---
+---         Other things in the module will not be accessible. This is the public API
+---         for your extension. Consider not breaking it a lot :laugh:
+---
+--- TODO:
+---     - actions
+extensions.register = function(mod)
+  return mod
+end
+
+extensions.load = function(name)
+  return extensions.manager[name]
+end
+
+extensions.set_config = function(extensions_config)
+  extensions._config = extensions_config or {}
+end
+
+return extensions

lua/telescope/builtin/init.lua

@@ -26,7 +26,6 @@ end
 
 local actions = require('telescope.actions')
 local finders = require('telescope.finders')
-local log = require('telescope.log')
 local make_entry = require('telescope.make_entry')
 local path = require('telescope.path')
 local pickers = require('telescope.pickers')

lua/telescope/extensions/vimgrep.lua

@@ -1,13 +0,0 @@
-local vimgrep = {}
-
-vimgrep.parse_line = function(line)
-  local sections = vim.split(line, ":")
-
-  return {
-    filename = sections[1],
-    row = tonumber(sections[2]),
-    col = tonumber(sections[3]),
-  }
-end
-
-return vimgrep

lua/telescope/init.lua

@@ -1,56 +1,29 @@
 require('telescope._compat')
 
+local _extensions = require('telescope._extensions')
+
 local telescope = {}
 
---[[
-local actions = require('telescope.actions')
-
-require('telescope').setup {
-  defaults = {
-    -- Picker Configuration
-    border = {},
-    borderchars = { '─', '│', '─', '│', '┌', '┐', '┘', '└'},
-    preview_cutoff = 120,
-    selection_strategy = "reset",
-
-    -- Can choose EITHER one of these:
-    layout_strategy = "horizontal",
-
-    get_window_options = function(...) end,
-
-    default_mappings = {
-      i = {
-        ["<C-n>"] = actions.move_selection_next,
-        ["<C-p>"] = actions.move_selection_previous,
-      },
-
-      n = {
-        ["<esc>"] = actions.close,
-        ["<CR>"] = actions.goto_file_selection_edit,
-      },
-    },
-
-    shorten_path = true,
-
-    winblend = 10, -- help winblend
-
-    winblend = {
-      preview = 0,
-      prompt = 20,
-      results = 20,
-    },
-
-  },
-}
-
---]]
-
 function telescope.setup(opts)
+  opts = opts or {}
+
   if opts.default then
     error("'default' is not a valid value for setup. See 'defaults'")
   end
 
   require('telescope.config').set_defaults(opts.defaults)
+  _extensions.set_config(opts.extensions)
 end
 
+function telescope.register_extension(mod)
+  return _extensions.register(mod)
+end
+
+function telescope.load_extension(name)
+  return _extensions.load(name)
+end
+
+--- Use telescope.extensions to reference any extensions within your configuration.
+telescope.extensions = require('telescope._extensions').manager
+
 return telescope

lua/telescope/pickers.lua

@@ -901,7 +901,6 @@ end
 
 function Picker:close_existing_pickers()
   for _, prompt_bufnr in ipairs(state.get_existing_prompts()) do
-    log.debug("Prompt bufnr was left open:", prompt_bufnr)
     pcall(actions.close, prompt_bufnr)
   end
 end

lua/telescope/sorters.lua

@@ -366,8 +366,9 @@ sorters.fuzzy_with_index_bias = function(opts)
 end
 
 -- Sorter using the fzy algorithm
-sorters.get_fzy_sorter = function()
+sorters.get_fzy_sorter = function(opts)
-  local fzy = require('telescope.algos.fzy')
+  opts = opts or {}
+  local fzy = opts.fzy_mod or require('telescope.algos.fzy')
   local OFFSET = -fzy.get_score_floor()
 
   return sorters.Sorter:new{