feat(#2789): add optional function expand_until to api.tree.expand_all and api.node.expand

[ghostbuster91]

This closes #2789

It took me a while but here I am :) I decided to create a fresh one as it was easier then resolving conflicts on the old one.

For now bare minimum of the changes that makes it work. Once we agree how the api will look like I will add docs following what we did in #2790

[ghostbuster91]

note: this is actually what I would like to achieve in the end. The edit part is wrong as nodes are not getting collapsed after hitting enter for the second time. Can you advise? fixed

question: how should the end user api look like?

[alex-courtis]

This will be very useful, however it needs a bit of thought.

Can we please do this in a future PR? The functionality for the API expands is working and we can merge that now.

What should it look like? This isn't something the user should have to do; it should be core functionality.

It could go into node.open.edit, as a new member of NodeEditOpts

[ghostbuster91]

Doing it in a separate PR makes perfect sense 👍

[alex-courtis]

Thanks for getting back to this one @ghostbuster91

My time is limited, however I will get to reviewing next weekend.

FYI the nightly CI failure has been resolved on master: #3167

[alex-courtis]

The descend filter functionality working beautifully for api.tree.expand_all and api.node.expand

Small issue: When the nodes are grouped, the arrow indicates open for a directory that is not traversed e.g.

#!/bin/sh

rm -rfv foo

mkdir -pv foo/bar foo/baz foo/stop foo/baz/stop

touch foo/bar/1
touch foo/bar/2

touch foo/stop/3
touch foo/stop/4

touch foo/baz/stop/5
touch foo/baz/stop/6

---@type ApiTreeExpandAllOpts
local expand_all_opts = {
  descend_until = function(i, node)
    print(i .. " " .. node.name)
    return node.name ~= "stop" and node.name ~= ".git" and node.name ~= "7"
  end
}

  vim.keymap.set("n", "A", function()
    api.tree.expand_all(nil, expand_all_opts)
  end, opts("expand"))

  vim.keymap.set("n", "N", function()
    api.node.expand(nil, expand_all_opts)
  end, opts("expand"))

[alex-courtis]

Looking good, let's merge the expand functionality now.

Please:

• revert the ordering changes in api.lua
• rename ApiTreeExpandOpts
• rename expand_until
• revert toggle_descend_until for a future PR
• add :help for
  • api.tree.expand_all
  • api.node.expand

[alex-courtis]

This will be very useful, however it needs a bit of thought.

Can we please do this in a future PR? The functionality for the API expands is working and we can merge that now.

What should it look like? This isn't something the user should have to do; it should be core functionality.

It could go into node.open.edit, as a new member of NodeEditOpts

[ghostbuster91]

All comments have been addressed. Ready for the final review

[alex-courtis]

We're getting really close.

• Expand all does not expand grouped nodes
• expand.lua expects descend_until from the user, not expand_until
• Help needs to document expand_until; I'll do that one
• max_folder_discovery is not obeyed when using expand_until

api.tree.expand_all with no expand_until

api.tree.expand on node with no expand_until

This doesn't apply:

---@type ApiTreeExpandOpts
local expand_all_opts = {
  expand_until = function(i, node)
    print(i .. " " .. node.name)
    return node.name ~= "stop" and node.name ~= ".git" and node.name ~= "7"
  end
}

[alex-courtis]

tree.expand_all({node}, {opts})              *nvim-tree-api.tree.expand_all()*
    Recursively expand all nodes under the tree root or specified folder.

    Parameters: ~
      • {node} (Node|nil) folder
      • {opts} (ApiTreeExpandOpts) optional parameters

    Options: ~
      • {expand_until} ((fun(expansion_count: integer, node: Node?): boolean)?)
            Return true if {node} should be expanded.
            {expansion_count} is the total number of folders expanded.

node.expand({node}, {opts})                      *nvim-tree-api.node.expand()*
    Recursively expand all nodes under a directory or a file's parent
    directory.

    Parameters: ~
      • {node} (Node|nil) file or folder
      • {opts} (ApiTreeExpandOpts) optional parameters

    Options: ~
      • {expand_until} ((fun(expansion_count: integer, node: Node?): boolean)?)
            Return true if {node} should be expanded.
            {expansion_count} is the total number of folders expanded.

[alex-courtis]

Many thanks for all your work on this one @ghostbuster91 , it's not been easy.

In the interest of speed, I'm applying the nits and merging.

[alex-courtis]

The max folder discovery test above does not appear to be necessary as limit_folder_discovery does the job.

Commenting this out results in the correct number of folders being expanded, just no message.

Having the same test twice in two locations is fragile and unclear.

Proposal: limit_folder_discovery prints the warning and gen_iterator's function returns nothing.

[ghostbuster91]

thanks @alex-courtis for the reviews and tests. I appreciate the effort.