`opts.plain=true` does not expand tildes in addition to environment
variables, unlike `opts.expand_env=false`.
`opts.expand_env=false` is soft-deprecated.
Problem:
Several subsystems need to derive a short, filesystem-safe identifier from an
arbitrary path, and each reinvents it ad-hoc:
- `'undodir'` and `swapfiles` encode the full path into a single filename, which
may exceed filesystem length-limits.
- `:connect ssh://` needs the SSH ControlPath socket name to stay under the
104-byte `sun_path` limit on macOS; today the path overflows it.
- the upcoming :terminal state dir.
- arbitrary plugin purposes.
Solution:
Provide `vim.fs.slug()`, which generates a bounded, one-way filename from an
arbitrary string. The input is normalized so equivalent paths produce the
same result. An 8-char hash is appended for uniqueness
Adds optional parameters to `vim.fs.abspath`:
1. `cwd` to specify directory akin to `--relative-from` in `realpath(1)`.
2. `plain` disables expansion of tilde (~) in paths.
Problem:
`vim.fs` does not provide a directory creation helper matching its
filesystem API shape.
Solution:
Add `vim.fs.mkdir()` as a thin wrapper around `vim.fn.mkdir()`, with
`parents` and `mode` options.
Problem:
vim.fs.dir() and vim.fs.find() drop errors returned by uv.fs_scandir().
Solution:
- vim.fs.dir():
- Return root scan failures as a secondary return value.
- Propagate recursive scan failures through the iterator. This allows
callers to distinguish unreadable directories from empty ones.
- vim.fs.find(): Collect errors during search, and return the list as
a second retval.
Problem:
Currently, only some filesystems (Btrfs, ext2, ext3, ext4) have full
support of accessing the `dirent` entry-type. On other filesystems,
`uv.fs_scandir_next` may return `nil` for an existing but unsupported
entry-type.
This means consumers (such as `fs.dir()`), cannot know if `nil` means
"non-existent" or "unsupported".
Solution:
Fall back to `uv.fs_lstat` when `etype` is `nil`; return "unknown" if it
fails.
Problem:
61e99217e684 replaced usages of `vim.fn`. This duplicates non-trivial
logic and may have introduced bugs like 38e38d1b401e.
Later on, b02eeb6a7281 graduated `fnamemodify` to `fast`, so avoiding it
in `vim.fs` is no longer necessary.
Solution:
Use `vim.fn` to deduplicate `vim.fs.dirname()` and `vim.fs.basename()`.
Note: the "nvim -l" test-runner switch from the original PR (#30483) is
already done by 9432e6c1e2e9 (#39676).
Problem:
Checking the extension of a file is done often, e.g. in Nvim's codebase
for differentiating Lua and Vimscript files in the runtime. The current
way to do this in Lua is (1) a Lua pattern match, which has pitfalls
such as not considering filenames starting with a dot, or (2)
fnamemodify() which is both hard to discover and hard to use / read if
not very familiar with the possible modifiers.
vim.fs.ext() returns the file extension including the leading dot of
the extension. Similar to the "file extension" implementation of many
other stdlibs (including fnamemodify(file, ":e")), a leading dot
doesn't indicate the start of the extension. E.g.: the .git folder in a
repository doesn't have the extension .git, but it simply has no
extension, similar to a folder named git or any other filename without
dot(s).
refactor(lua): add integer coercion helpers
Add vim._tointeger() and vim._ensure_integer(), including optional base
support, and switch integer-only tonumber()/assert call sites in the Lua
runtime to use them.
This also cleans up related integer parsing in LSP, health, loader, URI,
tohtml, and Treesitter code.
supported by AI
Problem:
vim.fs.joinpath treats empty string as a path segment
(it adds a path separator for each empty item):
print(vim.fs.joinpath('', 'after/lsp', '')) -- '/after/lsp/'
print(vim.fs.joinpath('', '')) -- '/'
Especially problematic if the empty segment is the first segment, as
that converts the path to an absolute path.
Solution:
Ignore empty (length of 0) path segments.
Benchmark:
local function test(func)
local t = vim.uv.hrtime()
for _ = 1, 100000, 1 do
func('', 'this/is', 'a/very/long/path', '', 'it', 'really', 'is')
end
print(math.floor((vim.uv.hrtime() - t) / 1e6), 'ms')
end
- with Iter():filter() --> 370 ms
- building new segments table --> 208 ms
- with vim.tbl_filter --> 232 ms
- Instead of gsub split on `/` in all parts --> 1870 ms
Problem: vim.fs.root uses vim.fn.fnamemodify. vim.fn table isn't
available from nvim -ll or thread contexts.
Solution: Swap out vim.fn.fnamemodify for vim.fs.abspath.
This is a temporary workaround and may be reverted since the
long-term plan is to use more fast=true "fn" functions from vim.fs
where possible.
Problem: There is currently no way to check if a given path is absolute or convert a relative path to an absolute path through the Lua stdlib. `vim.fs.joinpath` does not work when the path is absolute. There is also currently no way to resolve `C:foo\bar` style paths in Windows.
Solution: Add `vim.fs.abspath`, which allows converting any path to an absolute path. This also allows checking if current path is absolute by doing `vim.fs.abspath(path) == path`. It also has support for `C:foo\bar` style paths in Windows.
Problem:
`vim.validate()` takes two forms when it only needs one.
Solution:
- Teach the fast form all the features of the spec form.
- Deprecate the spec form.
- General optimizations for both forms.
- Add a `message` argument which can be used alongside or in place
of the `optional` argument.
Problem:
`vim.fs.dirname([[C:\User\XXX\AppData\Local]])` returns "." on
mingw/msys2.
Solution:
- Check for "mingw" when deciding `iswin`.
- Use `has("win32")` where possible, it works in "fast" contexts since
b02eeb6a7281df0561a021d7ae595c84be9a01be.
