API: tree.resize

[alex-courtis]

Background: #2595

Add API similar to :NvimTreeResize.

tree.resize({opts})                              *nvim-tree-api.tree.resize()*
    Resize the tree, persisting the new size.
    Resets to |nvim-tree.view.width| when no {opts} provided.
    See |:NvimTreeResize|

    Parameters: ~
      • {opts} (table) optional parameters

    Options: ~
      • {width}    (table)  new |nvim-tree.view.width| value
      • {absolute} (number) set the width
      • {relative} (number) increase or decrease the width

    Only one option is supported, in the priority order above.
    {absolute} and {relative} do nothing when {width} is a function.

It may be best to have 3 methods due to the exclusive nature of the options. Look at api.txt and lua.txt for guidance.

[aminnairi]

If I'm correct, the type of the width option should reflect the one that is used in the nvim-tree.view.width as below.

      • {width} (string | number | table | function())  new |nvim-tree.view.width| value

Feel free to correct me if I'm being wrong here!

Also, I think the delta would be easier to work with if it is a number, since numbers can also be signed, and it will be much easier to apply a positive or negative delta if this is a number (IMO).

From my local tests, adding a string with a number works, but adding a non-number string would throw an error.

> "a" + 1
stdin:1: attempt to add a 'string' with a 'number'
stack traceback:
        [C]: in metamethod 'add'
        stdin:1: in main chunk
        [C]: in ?

Whereas adding a string-number with a number does work as intended.

> "-10" + 30
20

But this feels safer and more natural to do this with numbers. Your call here!

Also, I would have called this option offset since this is more of a widerly used term to talk about absolute/relative units. And after some brainstorming with myself, I think absolute and relative would make a lot more sense for a beginner trying to use this API, or even when reading back our code after some time.

require("nvim-tree.api").resize({absolute = 30}) -- For a width that is equal to 30

require("nvim-tree.api").resize({relative = -10}) -- For a width that is decreased by 10

require("nvim-tree.api").resize({relative = +5}) -- For a width that is increased by 5

require("nvim-tree.api").resize({relative = 5}) -- Same thing, since positive numbers do not need signs

Other than that, this looks good to me for a future PR. Thank you for your valuable work!

[alex-courtis]

If I'm correct, the type of the width option should reflect the one that is used in the nvim-tree.view.width as below.

Thank you.

Also, I think the delta would be easier to work with if it is a number, since numbers can also be signed, and it will be much easier to apply a positive or negative delta if this is a number (IMO).

Of course.

I think absolute and relative would make a lot more sense for a beginner trying to use this API, or even when reading back our code after some time.

That could work. It's not necessary, however it would be easier.