Add custom formatting functions.

The custom formatters allow users to intercept the data in different
places, providing the option for them to re-format text or change
how/what data is getting displayed. (fixes #209)

Author: elkowar

README.md

@@ -326,6 +326,39 @@ vim.api.nvim_set_keymap("s", "<S-Tab>", "v:lua.s_tab_complete()", {expr = true})
 
 Use `compe#confirm()` mapping, as described in section [Mappings](#mappings).
 
+## Advanced configuration
+
+If you want to customize how compe displays completion options, compe allows you
+to run custom formatting code before the list get's displayed.
+For this, use the `formatting_functions` configuration option.
+Here you can functions for each provider to change the displayed data along the way.
+Currently, there are two formatters you can set: 
+
+- `results`: Change the list of completion results.
+- `documentation`: Change the documentation text.
+
+For example, you could use a results formatter to show the type information
+and other details in the completion list. 
+(Note that the `details` feature used here is not supported by many language servers.)
+
+```lua
+formatting_functions = {
+  nvim_lsp = {
+    results = function(items)
+      local max_col_width = 0
+      for _, item in ipairs(items) do
+        max_col_width = math.max(max_col_width, vim.fn.strwidth(item.abbr))
+      end
+      for _, item in ipairs(items) do
+        local padding = string.rep(" ", max_col_width - vim.fn.strwidth(item.abbr) + 1)
+        item.abbr = item.abbr .. padding .. item.user_data.compe.completion_item.detail
+      end
+      return items
+    end
+  }
+}
+```
+
 ## Demo
 
 ### Auto Import

doc/compe.txt

@@ -302,6 +302,40 @@ source ~
           For dictionary, see |compe-source| for the list of source options.
 
 
+formatting_functions ~
+    Custom output formatting functions. Optional.
+      Type: |Dictionary| of:
+        Key: |String|
+          Source name.
+          For the list of builtin sources, see |compe-sources|.
+        Value: |Dictionary| of:
+          results ~
+            This function get's called with the list of completion results
+            before displaying the list.
+            It takes and returns the list of completion results,
+            and may transform it.
+              Type: |Function|
+              Takes 1 argument:
+                completion_items:
+                  Type: |Table| of completion items.
+              Returns:
+                The transformed list.
+                Type: |Table| of completion items.
+
+          documentation ~
+              This function get's called with the documentation of the
+              currently selected completion item, and may return the text
+              changed in any way.
+              Type: |Function|
+              Takes 1 argument:
+                document:
+                  Type: |Table| of lines of the documentation text.
+              Returns:
+                The transformed documentation.
+                Type: |Table| of lines of the documentation text.
+
+
+
 ------------------------------------------------------------------------------
 HIGHLIGHT                                                    *compe-highlight*
 

lua/compe/config.lua

@@ -32,6 +32,12 @@ Config.get = function()
   return Config._bufnrs[vim.api.nvim_get_current_buf()] or Config._config
 end
 
+-- get_formatter
+Config.get_formatter = function(source_name, subject)
+  local source_functions = Config.get().formatting_functions[source_name]
+  return source_functions and source_functions[subject]
+end
+
 --- get_metadata
 Config.get_metadata = function(source_name)
   return Config.get().source[source_name]
@@ -60,6 +66,7 @@ Config._normalize = function(config)
   config.max_menu_width = config.max_menu_width or 100
   config.autocomplete = Boolean.get(config.autocomplete, true)
   config.documentation = Boolean.get(config.documentation, true)
+  config.formatting_functions = config.formatting_functions or {}
 
   -- normalize source metadata
   if config.source then

lua/compe/source.lua

@@ -171,6 +171,11 @@ Source.trigger = function(self, context, callback)
       self.trigger_character_offset = state.trigger_character_offset
       self.items = self:_normalize_items(context, result.items or {})
 
+      local formatter = Config.get_formatter(self.name, "results")
+      if formatter then
+        self.items = formatter(self.items)
+      end
+
       if #self.items == 0 then
         self:clear()
       end
@@ -225,6 +230,11 @@ Source.documentation = function(self, completed_item)
           context = Context.new({}, {});
           callback = Async.guard('Source.documentation#callback', vim.schedule_wrap(function(document)
             if document and #document ~= 0 then
+
+              local formatter = Config.get_formatter(self.name, "documentation")
+              if formatter then
+                document = formatter(document)
+              end
               vim.call('compe#documentation#open', document)
             else
               vim.call('compe#documentation#close')