Repository: neovim
Issue: API: clean up "meta info" functions for buf/win/tabpage
Labels: enhancement,api,ux,code-standards

# Problem

Related: https://github.com/neovim/neovim/issues/30450

Currently there are lots of single-purpose APIs to get what may be called "editor metadata" about:

- a buffer (not its text contents, nor extmarks (which is a big topic), nor its scripting state such as `b:`/`w:`/etc.)
- a window (not highlight state or other "big topics")
- a tabpage

Besides just ergonomics (simpler interface + documentation), there are technical reasons why the above isn't ideal:

- The `nvim_buf_x` paradigm was intended to behave like "object methods", but each call on such an "object" would invoke a separate RPC request (`buf.line_count`, `buf.is_valid`). That's not a great tradeoff, because metadata is very cheap, thus it's better to put all metadata into one response instead of requiring multiple RPC calls.
    - Calculating this metadata is cheap so there's no reason to require separate calls.
- Functions such as `nvim_buf_set_name` can trigger the swapfile ATTENTION dialog, yet there's currently no way to run it "noswapfile".

# Expected behavior

## For buffers:

- Deprecate the API `buf_x` meta functions in favor of the existing `getbufinfo()`.
    - *Or* provide `nvim_buf_get(filter:table)` which returns a superset (except `b:`) of `getbufinfo()`.
- Introduce `nvim_buf_set(buf: int, info: dict, with: dict)`, which works like `nvim_open_win` on existing windows?
    - ~~Doesn't look useful, only `name` would make sense.~~
        - But `nvim_buf_set_name` has some side-effects which the caller may not want:
            - can trigger the swapfile ATTENTION dialog, yet there's currently no way to run it "noswapfile".
            - sets the alternate buffer
    - The `with:dict` parameter would allow overriding and restoring various flags/options (internally uses `vim._with()`).
- Eliminates:
  ```
  nvim_buf_is_loaded
  nvim_buf_is_valid
  nvim_buf_line_count
  nvim_buf_get_name
  nvim_buf_set_name
  ```

## For windows:

- Deprecate the API `win_x` meta functions in favor of the existing `getwininfo(filter:table)`.
    - *Or* provide `nvim_win_get(filter:table)` which returns a superset (except `w:`) of `getwininfo()`.
    - *Or* augment `nvim_win_get_config(filter:table)` to provide any missing meta fields.
- `nvim_win_set_config`, already exists, can we add a new optional `with: dict` param?
- Eliminates:
  ```
  nvim_win_get_buf
  nvim_win_get_cursor
  nvim_win_get_height
  nvim_win_get_number
  nvim_win_get_position
  nvim_win_get_width
  nvim_win_is_valid
  nvim_win_set_buf
  nvim_win_set_height
  nvim_win_set_width
  ```
- TODO: Not sure if we can eliminate:
  ```
  nvim_win_set_cursor
  nvim_win_text_height
  ```


## For tabpages:

- Deprecate the API `tabpage_x` meta functions in favor of the existing `gettabinfo(filter:table)`.
    - *Or* provide `nvim_tabpage_get(filter:table)` which returns a superset (except `t:`) of `gettabinfo()`.
- Introduce `nvim_tabpage_set(tab: int, info: dict, with: dict)`
  ```
  info {
    name
    curwin // current window
  }
  ```
  - layout? https://github.com/neovim/neovim/pull/24507
- Eliminates:
  ```
  nvim_tabpage_list_wins
  nvim_tabpage_get_win
  nvim_tabpage_set_win
  nvim_tabpage_get_number
  nvim_tabpage_is_valid
  ```