[Feature Request] An API to output symbols structure for the current cursor position

[rockyzhang24]

Hello,

I know this plugin provides a lualine component for displaying the symbols structure for the current cursor position. It's fantastic, however, it is only available in lualine. I am wondering whether it is possible to expose an API (a function) so that we can get this symbols structure by calling the function. If so, we can integrate in any other plugins. For example, I can show this symbols structure in the winbar (a new feature merged this morning https://github.com/neovim/neovim/pull/18562) instead of the statusline.

I know there are some plugins offering a similar feature such as nvim-treesitter and nvim-gps. But they display the symbols structure via treesitter, not LSP. If aerial could expose such a API, we can display the symbols structure via LSP by setting its backends option.

Any thoughts on this?

Thank you very much.

---

Update:

Currently I try to implement this via aerial builtin function aerial.get_location() (https://github.com/stevearc/aerial.nvim/blob/master/lua/aerial/init.lua#L127) and the function format_status() for the lualine component (https://github.com/stevearc/aerial.nvim/blob/master/lua/lualine/components/aerial.lua#L53).

The implemented API is output_symbols_structure(depth, separator, icons_enabled).

local aerial = require('aerial')

local function format_status(symbols, depth, separator, icons_enabled)
  local parts = {}
  depth = depth or #symbols

  if depth > 0 then
    symbols = { unpack(symbols, 1, depth) }
  else
    symbols = { unpack(symbols, #symbols + 1 + depth) }
  end

  for _, symbol in ipairs(symbols) do
    if icons_enabled then
      table.insert(parts, string.format("%s %s", symbol.icon, symbol.name))
    else
      table.insert(parts, symbol.name)
    end
  end

  return table.concat(parts, separator)
end

-- The API to output the symbols structure
function output_symbols_structure(depth, separator, icons_enabled)
  local symbols = aerial.get_location(true)
  local symbols_structure = format_status(symbols, depth, separator, icons_enabled)
  print(symbols_structure)
end

Then we call the API by lua output_symbols_structure(nil, ' > ', true) and it will output the symbols structure shown below. This is really what I need.

Any thoughts? Thank you so much.

[stevearc]

You seem to have found it! The aerial.get_location function was added specifically to enable these sorts of integrations.

[rockyzhang24]

Wow, nice. So actually all exported functions in lua/aerial/init.lua (i.e., those M.xxx in init.lua) are the public APIs you offer to users, right? If so, it is very hard to find them for some inexperienced neovim users, do you think it will be better to add documents for them, or at least mention them in the README?

Thank you.

[stevearc]

Yep, I treat everything exposed in init.lua as part of the API, and try to avoid breaking changes. The lack of documentation is intentional. For most users, they just want plugin to do what it does and to know how to customize it to work how they want. If they require anything other than setup() and the exposed commands, then I've done something wrong.

The lua API is there for people such as yourself that have needs beyond the normal uses of aerial. I think those people will generally be able to find what they need, as you did, or they can post an issue/discussion question.

[rockyzhang24]

Got it. Thank you so much for your explanation. I think you can also enable the "Wiki" page that is good place as well to share some useful snippets.

I use winbar to show the path of the file and the symbol path like what VSCode does. I attached the snippets in the discussion (https://github.com/stevearc/aerial.nvim/discussions/106). Thanks.

Feel free to close this. :P