symbol post process API: review comments

lua/aerial/backends/init.lua

@@ -163,6 +163,12 @@ M.set_symbols = function(bufnr, items, ctx)
 
   if config.post_add_all_symbols then
     items = config.post_add_all_symbols(bufnr, items, ctx)
+    if items == nil then
+      vim.notify_once(
+        "aerial.config.post_add_all_symbols should return the symbols to display, but you returned nil or didn't return anything.",
+        vim.log.levels.WARN
+      )
+    end
   end
 
   local had_symbols = data.has_symbols(bufnr)

lua/aerial/backends/lsp/callbacks.lua

@@ -90,7 +90,7 @@ local function process_symbols(symbols, bufnr, fix_start_col, client_name)
             item.children = _process_symbols(symbol.children, item, {}, level + 1)
           end
           if
-            config.post_parse_symbol == nil
+            not config.post_parse_symbol
             or config.post_parse_symbol(bufnr, item, {
                 backend_name = "lsp",
                 lang = client_name,

lua/aerial/backends/man.lua

@@ -38,7 +38,7 @@ M.fetch_symbols_sync = function(bufnr)
         col = 0,
       }
       if
-        config.post_parse_symbol == nil
+        not config.post_parse_symbol
         or config.post_parse_symbol(bufnr, item, {
             backend_name = "man",
             lang = "man",
@@ -60,7 +60,7 @@ M.fetch_symbols_sync = function(bufnr)
         end_col = line:len(),
       }
       if
-        config.post_parse_symbol == nil
+        not config.post_parse_symbol
         or config.post_parse_symbol(bufnr, item, {
             backend_name = "man",
             lang = "man",

lua/aerial/backends/markdown.lua

@@ -39,7 +39,7 @@ M.fetch_symbols_sync = function(bufnr)
         table.insert(parent.children, item)
       else
         if
-          config.post_parse_symbol == nil
+          not config.post_parse_symbol
           or config.post_parse_symbol(bufnr, item, {
               backend_name = "markdown",
               lang = "markdown",

lua/aerial/config.lua

@@ -196,6 +196,37 @@ local default_options = {
   -- Run this command after jumping to a symbol (false will disable)
   post_jump_cmd = "normal! zz",
 
+  -- Invoked after each symbol is parsed, can be used to modify the parsed item,
+  -- or to filter it by returning false.
+  --
+  -- bufnr: a neovim buffer number
+  -- item: of type aerial.Symbol
+  -- ctx: a record containing the following fields:
+  --   * backend_name: treesitter, lsp, man...
+  --   * lang: info about the language
+  --   * symbols?: specific to the lsp backend
+  --   * symbol?: specific to the lsp backend
+  --   * syntax_tree?: specific to the treesitter backend
+  --   * match?: specific to the treesitter backend, TS query match
+  post_parse_symbol = function(bufnr, item, ctx)
+    return true
+  end,
+
+  -- Invoked after all symbols have been parsed and post-processed,
+  -- allows to modify the symbol structure before final display
+  --
+  -- bufnr: a neovim buffer number
+  -- items: a collection of aerial.Symbol items, organized in a tree,
+  --        with 'parent' and 'children' fields
+  -- ctx: a record containing the following fields:
+  --   * backend_name: treesitter, lsp, man...
+  --   * lang: info about the language
+  --   * symbols?: specific to the lsp backend
+  --   * syntax_tree?: specific to the treesitter backend
+  post_add_all_symbols = function(bufnr, items, ctx)
+    return items
+  end,
+
   -- When true, aerial will automatically close after jumping to a symbol
   close_on_select = false,