IntenseFinance/neovim
3
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2026-08-17 20:24:48 -05:00
Code Issues Packages Projects Releases Wiki Activity

Merge #41113 from justinmk/doc2

Browse Source
This commit is contained in:
Justin M. Keyes
2026-08-06 04:38:40 -04:00
committed by GitHub
parent 8b0f33a1ab 9a93ac6533
commit 7ce7a8d58c
19 changed files with 223 additions and 219 deletions
Download Patch File Download Diff File Expand all files Collapse all files
runtime/autoload/README.txt
-25
View File
@@ -1,25 +0,0 @@
The autoload directory is for standard Vim autoload scripts.
These are functions used by plugins and for general use. They will be loaded
automatically when the function is invoked. See ":help autoload".
gzip.vim for editing compressed files
netrw*.vim browsing (remote) directories and editing remote files
tar.vim browsing tar files
zip.vim browsing zip files
paste.vim common code for mswin.vim and menu.vim
spellfile.vim downloading of a missing spell file
Omni completion files:
adacomplete.vim Ada
beancount.vim Beancount
ccomplete.vim C
csscomplete.vim HTML / CSS
htmlcomplete.vim HTML
javascriptcomplete.vim Javascript
phpcomplete.vim PHP
pythoncomplete.vim Python
python3complete.vim Python
rubycomplete.vim Ruby
syntaxcomplete.vim from syntax highlighting
xmlcomplete.vim XML (uses files in the xml directory)
runtime/doc/api.txt
+13 -8
View File
@@ -85,16 +85,16 @@ Nvim instance:
sock.write([0, 0, 'nvim_command', ['echo "hello world!"']].to_msgpack)
p MessagePack::Unpacker.new(sock).read.last
<
Another way is to use the Python REPL with the "pynvim" package,
where API functions can be called interactively, or create a script:
(requires `pip install pynvim` or `uv add pynvim` or another python package manager)
>
Another way is to use the Python REPL with the "pynvim" package, where API
functions can be called interactively (requires `pip install pynvim` or
`uv add pynvim`): >
>>> from pynvim import attach
>>> nvim = attach('socket', path='[address]')
>>> nvim.command('echo "hello world!"')
<
You can also embed Nvim via |jobstart()|, and communicate using |rpcrequest()|
and |rpcnotify()| in Vimscript :e hello.vim, copy below content and then :so %:
and |rpcnotify()|:
>vim
let nvim = jobstart(['nvim', '--embed'], {'rpc': v:true})
echo rpcrequest(nvim, 'nvim_eval', '"Hello " . "world!"')
@@ -4048,10 +4048,15 @@ nvim_open_win({buf}, {enter}, {config}) *nvim_open_win()*
(`integer`) |window-ID|, or 0 on error
nvim_win_get_config({win}) *nvim_win_get_config()*
Gets window configuration in the form of a dict which can be passed as the
`config` parameter of |nvim_open_win()|.
Gets window config as a dict which can be passed to |nvim_open_win()| as
the `config` parameter.
For non-floating windows, `relative` is empty.
For non-floating windows, `relative` is empty, thus you can check that
field to detect if a window is a floatwin: >lua
vim.print(vim.api.nvim_win_get_config(0).relative == '' and 'non-float' or 'float')
-- Or use win_gettype().
vim.print(vim.fn.win_gettype())
<
Attributes: ~
Since: 0.4.0
runtime/doc/autocmd.txt
+1 -1
View File
@@ -1989,7 +1989,7 @@ and "++ff=" argument that are effective. These should be used for the command
that reads/writes the file. The |v:cmdbang| variable is one when "!" was
used, zero otherwise.
See the $VIMRUNTIME/pack/dist/opt/netrw/plugin/netrwPlugin.vim for examples.
See $VIMRUNTIME/plugin/net.lua for examples.
==============================================================================
11. Disabling autocommands *autocmd-disable*
runtime/doc/editing.txt
+24 -2
View File
@@ -275,8 +275,8 @@ CTRL-^ Edit the alternate file. Mostly the alternate file is
'includeexpr' to the filename.
- If a [count] is given, the count'th file that is
found in the 'path' is edited.
- If the name is a URL ("type://machine/path"), you
need the |netrw| plugin.
- If the name is a URL ("type://machine/path"), it is
handled by $VIMRUNTIME/plugin/net.lua
- Environment variables are expanded. |expand-env|.
- On unix: "~" is expanded.
@@ -1488,6 +1488,28 @@ a:test and not write a:vim/test. But if you do ":w test" the file a:vim/test
will be written, because you gave a new file name and did not refer to a
filename before the ":cd".
PROJECT DIRECTORY *project-dir* *workspace-dir*
You can use |:bcd| to assign a "workspace" (or "project directory") to each
buffer, so commands like |:make|, |:grep| and |:terminal| always run relative
to the buffer's "workspace".
Example: change to the project root (found by |vim.fs.root()|) of each buffer: >lua
vim.api.nvim_create_autocmd('BufReadPost', {
callback = function(ev)
local root = vim.fs.root(ev.buf, { '.git', 'Makefile' })
if root then
vim.cmd.bcd(root)
end
end,
})
<
See also:
- |lsp-buf-working-dir|
- |terminal-osc7|
==============================================================================
8. Editing binary files *edit-binary*
runtime/doc/lsp.txt
+16
View File
@@ -331,6 +331,22 @@ Example: Enable auto-completion and auto-formatting ("linting"): >lua
end
end,
})
<
*lsp-buf-working-dir*
The LSP server decides the "workspace root" (|lsp-root_dir()|) of a buffer,
but the Nvim |current-directory| does not follow it, so commands like |:make|,
|:grep| and |:terminal| do not run from the workspace root. You can use |:bcd|
to sync each buffer's directory to its LSP workspace root: >lua
vim.api.nvim_create_autocmd('LspAttach', {
group = vim.api.nvim_create_augroup('my.lsp.bufdir', {}),
callback = function(ev)
local client = assert(vim.lsp.get_client_by_id(ev.data.client_id))
if client.root_dir then
vim.cmd.bcd(client.root_dir)
end
end,
})
<
To see the capabilities for a given server, try this in a LSP-enabled buffer: >vim
runtime/doc/lua.txt
+17 -25
View File
@@ -2952,46 +2952,38 @@ vim.fs.root({source}, {marker}) *vim.fs.root()*
if no directory was found.
vim.fs.slug({path}, {opts}) *vim.fs.slug()*
Generates a bounded, filesystem-safe filename from an arbitrary identity
string.
• The input is normalized via |vim.fs.normalize()| so that equivalent
paths produce the same result (e.g., `~/foo` and `/home/username/foo`).
• `$HOME` is replaced with `~`. On Windows, UNC paths are replaced with
`=unc-`.
• An 8-character hex hash (|sha256()|) of the normalized input is appended
to prevent collisions.
• Unsafe characters (`/ \ : * ? " < > |`, whitespace, control characters)
are replaced with `-`, and trailing `-` and `.` are stripped.
Gets a filesystem-safe, mnemonic slug (readable prefix + short hash) of an
arbitrary filepath or other "identity string".
• The input is normalized so equivalent paths produce the same result.
• A hash of the normalized input is appended to prevent collisions.
• Unsafe chars are replaced with "-".
• `$HOME` is replaced with "~".
• UNC paths (Windows) are prefixed with "=unc-".
• If `opts.maxlen` is exceeded, the result will be truncated to
`{head}~~~{tail}-{hash8}`.
• If the sanitized name is empty, the reserved label `=special` will be
used.
Examples: >lua
vim.fs.slug('/tmp/test/foo.md')
--> "tmp-test-foo.md-{hash}"
vim.fs.slug('C:/src/project/main.c')
--> "C--src-project-main.c-{hash}"
vim.fs.slug(('/a/very/long/path'):rep(10) .. '/file.txt', { maxlen = 60 })
vim.print(vim.fs.slug('/tmp/test/foo.md')) --> "tmp-test-foo.md-{hash}"
vim.print(vim.fs.slug('C:/src/project/main.c')) --> "C--src-project-main.c-{hash}"
vim.print(vim.fs.slug(vim.fn.expand('~/file.txt'))) --> "~-file.txt-{hash}"
vim.print(vim.fs.slug('---')) --> "=special-{hash}"
vim.print(vim.fs.slug(('/a/very/long/path'):rep(10) .. '/file.txt', { maxlen = 60 }))
--> "a-very-long-~~~-path-a-very-long-path-file.txt-{hash}"
vim.fs.slug('home/username/file.txt')
--> "~-file.txt-{hash}"
<
Attributes: ~
Since: 0.13.0
Parameters: ~
• {path} (`string`) a string that is not filesystem-safe.
• {opts} (`table?`) Optional parameters:
• maxlen: (integer) Max byte length of the result. Default is
180. Value must be at least 8.
• {path} (`string`) Filepath (or other identity string).
• {opts} (`table?`)
• maxlen: (integer, default: 180) Max length (bytes) of the
result.
Return: ~
(`string`) Filesystem-safe file name
(`string`) Filesystem-safe, mnemonic slug.
==============================================================================
runtime/doc/news-0.10.txt
+1
View File
@@ -405,6 +405,7 @@ These existing features changed their behavior.
• Editor:
• |gx| now uses |vim.ui.open()| and not netrw. To customize, you can redefine
`vim.ui.open` or remap `gx`. To continue using netrw (deprecated): >vim
:packadd netrw
:call netrw#BrowseX(expand(exists("g:netrw_gx") ? g:netrw_gx : '<cfile>'), netrw#CheckIfRemote())<CR>
• LSP:
runtime/doc/news.txt
+2 -2
View File
@@ -195,6 +195,8 @@ API
-- After:
vim.print(vim.api.nvim_get_mark('A'))
• |nvim_buf_call()| and |nvim_win_call()| now preserve multiple return values.
• |nvim_del_keymap()|, |nvim_buf_del_keymap()| and |vim.keymap.del()| can
match only {lhs}, not {rhs}, with `opts.lhs=true`.
• |nvim_set_hl()| supports "font" key.
• |nvim_open_win()| `zindex` controls whether the UI will use a dimmed cursor
shape when an unfocused float is on top of the cursor.
@@ -486,8 +488,6 @@ These existing features changed their behavior.
• |vim.lsp.util.open_floating_preview()| windows (e.g. |vim.lsp.buf.hover()|)
converted to normal windows (e.g. with |CTRL-W_H|) are no longer closed
automatically.
• |nvim_del_keymap()|, |nvim_buf_del_keymap()| and |vim.keymap.del()| can
match only {lhs}, not {rhs}, with `opts.lhs=true`.
• |vim.fs.normalize()| `opts.expand_env=false` key was renamed to
`opts.plain=true` and now does not expand leading tildes ("~") in addition
to environment variables ("expand_env" is still accepted, for backwards
runtime/doc/plugins.txt
+36 -32
View File
@@ -25,7 +25,7 @@ Help-link Loaded Short description ~
|man.lua| Yes View manpages in Nvim
|matchit| Yes Extended |%| matching
|matchparen| Yes Highlight matching pairs
|netrw| Yes Reading and writing files over a network
|netrw| No Reading and writing files over a network
|zip| Yes Read-only zip archive browser
|package-cfilter| No Filtering quickfix/location list
|package-justify| No Justify text
@@ -46,21 +46,28 @@ Help-link Loaded Short description ~
==============================================================================
Builtin plugin: dir *dir*
Nvim opens a directory listing when |:edit| is used with a directory path. The
listing is a buffer with 'filetype' set to "directory".
Nvim opens a directory listing when you |:edit| a directory path, handled by
the builtin "dir" plugin. The listing is read-only, dir.lua does not provide
actions which modify the filesystem.
Each "dir" buffer is initialized as follows:
- Sets 'filetype' to "directory".
- Sets |current-directory| via |:bcd|, so |gf|, |:!| and friends work as
expected.
- Keeps |alternate-file|, so |CTRL-^| returns to the buffer you came from.
*g:loaded_nvim_dir_plugin*
To disable the built-in directory browser, set this before startup: >lua
vim.g.loaded_nvim_dir_plugin = 1
vim.g.loaded_nvim_dir_plugin = 1
<
Mappings: *dir-mappings*
GLOBAL MAPPINGS *dir-mappings*
• - opens the parent directory of the current file or directory.
• {count}- is like -, but a count of 1 opens the current working directory,
and a higher count goes up that many levels.
Directory buffer mappings: *dir-buffer-mappings*
BUFFER-LOCAL MAPPINGS *dir-buffer-mappings*
• <CR> opens the file or directory under the cursor.
• - opens the parent directory.
@@ -71,18 +78,10 @@ These keys map to <Plug>(nvim-dir-open), <Plug>(nvim-dir-up), and
skipped when the target <Plug> mapping is already mapped. The default global and
directory-buffer "-" mappings are also skipped when "-" is already mapped.
The listing is read-only and does not modify the filesystem.
Opening an entry leaves the |alternate-file| on the buffer you came from, so
that |CTRL-^| returns to it rather than to the listing.
The listed directory is the buffer's directory (|:bcd|), so entry names resolve
without a prefix for |gf|, |:!|, and friends. Being buffer-local it is not
"sticky": it does not follow you out of the listing.
*dir-config*
Directory buffers follow the global 'hidden' option by default. To delete them
after use: >vim
autocmd FileType directory setlocal bufhidden=delete
autocmd FileType directory setlocal bufhidden=delete
<
A discarded listing is rebuilt on the next visit, so the cursor starts at the
first entry instead of the one it was left on. "wipe" discards the buffer
@@ -92,23 +91,28 @@ itself, leaving no |alternate-file|; see 'bufhidden'.
Replacing the directory browser *dir-disable*
To use another directory browser for the current session, delete the
`nvim.dir` autocommand group on or after |VimEnter| and handle |FileType| "directory":
>lua
vim.api.nvim_del_augroup_by_name('nvim.dir')
vim.api.nvim_create_autocmd('FileType', {
pattern = 'directory',
callback = function(args)
require('my_browser').open(args.buf, vim.api.nvim_buf_get_name(args.buf))
end,
})
<
This stops the built-in directory-opening autocommands. The plugin and its
mappings remain loaded.
`nvim.dir` autocommand group on or after |VimEnter| and handle |FileType| "directory".
This clears the built-in directory-opening autocommands. >lua
Define replacement keymaps explicitly, for example: >lua
vim.keymap.set('n', '-', function()
require('my_browser').open_parent()
end)
vim.api.nvim_del_augroup_by_name('nvim.dir')
vim.api.nvim_create_autocmd('FileType', {
pattern = 'directory',
callback = function(args)
require('my_browser').open(args.buf, vim.api.nvim_buf_get_name(args.buf))
end,
})
<
To enable the legacy "netrw" plugin: >vim
:packadd netrw
The plugin and its mappings remain loaded (it is a core component used by
other features such as |zip|). Define replacement keymaps explicitly, for
example: >lua
vim.keymap.set('n', '-', function()
require('my_browser').open_parent()
end)
<
==============================================================================
runtime/doc/terminal.txt
+4 -7
View File
@@ -170,10 +170,10 @@ To configure bash to emit OSC 7: >bash
PROMPT_COMMAND='print_osc7'
Having ensured that your shell emits OSC 7, you can now handle it in Nvim. The
following code will run :lcd whenever your shell CWD changes in a :terminal
buffer: >lua
following code runs |:bcd| whenever your shell CWD changes, so the :terminal
buffer-local directory always follows the shell: >lua
vim.api.nvim_create_autocmd({ 'TermRequest' }, {
vim.api.nvim_create_autocmd('TermRequest', {
desc = 'Handles OSC 7 dir change requests',
callback = function(ev)
local val, n = string.gsub(ev.data.sequence, '\027]7;file://[^/]*', '')
@@ -184,10 +184,7 @@ buffer: >lua
vim.notify('invalid dir: '..dir)
return
end
vim.b[ev.buf].osc7_dir = dir
if vim.api.nvim_get_current_buf() == ev.buf then
vim.cmd.lcd(dir)
end
vim.cmd.bcd(dir)
end
end
})
runtime/doc/vi_diff.txt
+1 -1
View File
@@ -258,7 +258,7 @@ Extended search patterns. |pattern|
"x\{2,4}" matches "x" 2 to 4 times.
"\s" matches a white space character.
Directory, remote and archive browsing. |netrw|
Directory, remote and archive browsing. |dir|
Vim can browse the file system. Simply edit a directory. Move around
in the list with the usual commands and press <Enter> to go to the
directory or file under the cursor.
runtime/doc/vimfn.txt
+18 -20
View File
@@ -964,8 +964,7 @@ changenr() *changenr()*
(`integer`)
chansend({id}, {data}) *chansend()*
Lua: Prefer |nvim_chan_send()| for string data; list input and
the return value differ.
Lua: Prefer |nvim_chan_send()| for string (binary) data.
Send data to channel {id}. For a job, it writes it to the
stdin of the process. For the stdio channel |channel-stdio|,
@@ -974,9 +973,12 @@ chansend({id}, {data}) *chansend()*
See |channel-bytes| for more information.
{data} may be a string, string convertible, |Blob|, or a list.
If {data} is a list, the items will be joined by newlines; any
newlines in an item will be sent as NUL. To send a final
newline, include a final empty string. Example: >vim
newlines in an item will be sent as NUL; to send a final
newline, include a final empty string. |NL-used-for-Nul|
Example: >vim
call chansend(id, ["abc", "123\n456", ""])
< will send "abc<NL>123<NUL>456<NL>".
@@ -989,7 +991,7 @@ chansend({id}, {data}) *chansend()*
• {data} (`string|string[]`)
Return: ~
(`0|1`)
(`integer`)
char2nr({string} [, {utf8}]) *char2nr()*
Lua: Prefer |string.byte()|: only works with ASCII.
@@ -12699,22 +12701,18 @@ win_getid([{win} [, {tab}]]) *win_getid()*
(`integer`)
win_gettype([{nr}]) *win_gettype()*
Return the type of the window:
"autocmd" autocommand window. Temporary window
used to execute autocommands.
"command" command-line window |cmdwin|
(empty) normal window
"loclist" |location-list-window|
"popup" floating window |api-floatwin|
"preview" preview window |preview-window|
"quickfix" |quickfix-window|
"unknown" window {nr} not found
Gets the type of the given window, or current window if {nr}
is omitted:
- (empty) Normal window
- "autocmd" Internal "context-switch" window.
- "command" Command-line window |cmdwin|
- "loclist" |location-list-window|
- "popup" Floating window |api-floatwin|
- "preview" Preview window |preview-window|
- "quickfix" |quickfix-window|
- "unknown" Window {nr} not found
When {nr} is omitted return the type of the current window.
When {nr} is given (|window-number| or |window-ID|) return the
type of that window.
Also see the 'buftype' option.
See also the 'buftype' option.
Parameters: ~
• {nr} (`integer?`)
runtime/lua/vim/_meta/api.gen.lua
Generated
+8 -3
View File
@@ -2415,10 +2415,15 @@ function vim.api.nvim_win_del_var(win, name) end
--- @return integer # Buffer id
function vim.api.nvim_win_get_buf(win) end
--- Gets window configuration in the form of a dict which can be passed as the `config` parameter of
--- `nvim_open_win()`.
--- Gets window config as a dict which can be passed to `nvim_open_win()` as the `config` parameter.
---
--- For non-floating windows, `relative` is empty.
--- For non-floating windows, `relative` is empty, thus you can check that field to detect if
--- a window is a floatwin:
--- ```lua
--- vim.print(vim.api.nvim_win_get_config(0).relative == '' and 'non-float' or 'float')
--- -- Or use win_gettype().
--- vim.print(vim.fn.win_gettype())
--- ```
---
--- @param win integer `window-ID`, or 0 for current window
--- @return vim.api.keyset.win_config_ret # Map defining the window configuration, see |nvim_open_win()|
runtime/lua/vim/_meta/vimfn.gen.lua
Generated
+18 -19
View File
@@ -827,7 +827,7 @@ function vim.fn.chanclose(id, stream) end
--- @return integer
function vim.fn.changenr() end
--- Lua: Prefer |nvim_chan_send()| for string data; list input and the return value differ.
--- Lua: Prefer |nvim_chan_send()| for string (binary) data.
---
--- Send data to channel {id}. For a job, it writes it to the
--- stdin of the process. For the stdio channel |channel-stdio|,
@@ -836,9 +836,12 @@ function vim.fn.changenr() end
--- See |channel-bytes| for more information.
---
--- {data} may be a string, string convertible, |Blob|, or a list.
---
--- If {data} is a list, the items will be joined by newlines; any
--- newlines in an item will be sent as NUL. To send a final
--- newline, include a final empty string. Example: >vim
--- newlines in an item will be sent as NUL; to send a final
--- newline, include a final empty string. |NL-used-for-Nul|
---
--- Example: >vim
--- call chansend(id, ["abc", "123\n456", ""])
--- <will send "abc<NL>123<NUL>456<NL>".
---
@@ -848,7 +851,7 @@ function vim.fn.changenr() end
---
--- @param id number
--- @param data string|string[]
--- @return 0|1
--- @return integer
function vim.fn.chansend(id, data) end
--- Lua: Prefer |string.byte()|: only works with ASCII.
@@ -11355,22 +11358,18 @@ function vim.fn.win_findbuf(bufnr) end
--- @return integer
function vim.fn.win_getid(win, tab) end
--- Return the type of the window:
--- "autocmd" autocommand window. Temporary window
--- used to execute autocommands.
--- "command" command-line window |cmdwin|
--- (empty) normal window
--- "loclist" |location-list-window|
--- "popup" floating window |api-floatwin|
--- "preview" preview window |preview-window|
--- "quickfix" |quickfix-window|
--- "unknown" window {nr} not found
--- Gets the type of the given window, or current window if {nr}
--- is omitted:
--- - (empty) Normal window
--- - "autocmd" Internal "context-switch" window.
--- - "command" Command-line window |cmdwin|
--- - "loclist" |location-list-window|
--- - "popup" Floating window |api-floatwin|
--- - "preview" Preview window |preview-window|
--- - "quickfix" |quickfix-window|
--- - "unknown" Window {nr} not found
---
--- When {nr} is omitted return the type of the current window.
--- When {nr} is given (|window-number| or |window-ID|) return the
--- type of that window.
---
--- Also see the 'buftype' option.
--- See also the 'buftype' option.
---
--- @param nr? integer
--- @return 'autocmd'|'command'|''|'loclist'|'popup'|'preview'|'quickfix'|'unknown'
runtime/lua/vim/fs.lua
+22 -34
View File
@@ -147,49 +147,40 @@ function M.joinpath(...)
return (path:gsub(iswin and '[/\\][/\\]*' or '//+', '/'))
end
--- Generates a bounded, filesystem-safe filename from an arbitrary identity string.
--- Gets a filesystem-safe, mnemonic slug (readable prefix + short hash) of an arbitrary filepath or
--- other "identity string".
---
--- - The input is normalized via |vim.fs.normalize()| so that equivalent paths produce the same
--- result (e.g., `~/foo` and `/home/username/foo`).
--- - `$HOME` is replaced with `~`. On Windows, UNC paths are replaced with `=unc-`.
--- - An 8-character hex hash (|sha256()|) of the normalized input is appended to prevent
--- collisions.
--- - Unsafe characters (`/ \ : * ? " < > |`, whitespace, control characters) are replaced with
--- `-`, and trailing `-` and `.` are stripped.
--- - The input is normalized so equivalent paths produce the same result.
--- - A hash of the normalized input is appended to prevent collisions.
--- - Unsafe chars are replaced with "-".
--- - `$HOME` is replaced with "~".
--- - UNC paths (Windows) are prefixed with "=unc-".
--- - If `opts.maxlen` is exceeded, the result will be truncated to `{head}~~~{tail}-{hash8}`.
--- - If the sanitized name is empty, the reserved label `=special` will be used.
---
--- Examples:
---
--- ```lua
--- vim.fs.slug('/tmp/test/foo.md')
--- --> "tmp-test-foo.md-{hash}"
---
--- vim.fs.slug('C:/src/project/main.c')
--- --> "C--src-project-main.c-{hash}"
---
--- vim.fs.slug(('/a/very/long/path'):rep(10) .. '/file.txt', { maxlen = 60 })
--- vim.print(vim.fs.slug('/tmp/test/foo.md')) --> "tmp-test-foo.md-{hash}"
--- vim.print(vim.fs.slug('C:/src/project/main.c')) --> "C--src-project-main.c-{hash}"
--- vim.print(vim.fs.slug(vim.fn.expand('~/file.txt'))) --> "~-file.txt-{hash}"
--- vim.print(vim.fs.slug('---')) --> "=special-{hash}"
--- vim.print(vim.fs.slug(('/a/very/long/path'):rep(10) .. '/file.txt', { maxlen = 60 }))
--- --> "a-very-long-~~~-path-a-very-long-path-file.txt-{hash}"
---
--- vim.fs.slug('home/username/file.txt')
--- --> "~-file.txt-{hash}"
--- ```
---
---@since 15
---@param path string a string that is not filesystem-safe.
---@param opts? table Optional parameters:
--- - maxlen: (integer) Max byte length of the result. Default is 180. Value must be at least 8.
---@return string # Filesystem-safe file name
---@param path string Filepath (or other identity string).
---@param opts? table
--- - maxlen: (integer, default: 180) Max length (bytes) of the result.
---@return string # Filesystem-safe, mnemonic slug.
function M.slug(path, opts)
vim.validate('path', path, 'string')
opts = opts or {}
vim.validate('maxlen', opts.maxlen, function(v)
if v == nil then
return true
end
return type(v) == 'number' and v >= 8
end, '`opt.maxlen` must be at least 8')
opts.maxlen = opts.maxlen or 180
end, true, '`opts.maxlen` must be >= 8')
local maxlen = opts.maxlen or 180
-- Normalize before computing the hash so equivalent paths produce the same result
path = vim.fs.normalize(path, { plain = true })
@@ -227,7 +218,6 @@ function M.slug(path, opts)
end
-- Within maxlen: "{name}-{hash8}"
local maxlen = opts.maxlen
if #s + 1 + #hash8 <= maxlen then
return s .. '-' .. hash8
end
@@ -235,8 +225,8 @@ function M.slug(path, opts)
-- "{head}~~~{tail}-{hash8}"
local budget = maxlen - 12 -- 3 for "~~~", 1 for "-", 8 for hash
if budget < 1 then
-- No room for a readable form: degrade to a plain hash
return hash8:sub(1, maxlen)
-- No room for a readable form: degrade to a plain hash (maxlen >= 8 == #hash8).
return hash8
end
local head_len = math.floor(budget / 3)
local h = s:sub(1, head_len):match('^.*()-') or head_len -- byte position where {head} ends
@@ -249,13 +239,11 @@ function M.slug(path, opts)
h = char_start - 1
end
end
-- Always in [h + 4, #s]: the "{name}-{hash8}" case above handled #s <= budget + 3.
local tail_start = #s - budget + h + 1
if tail_start < 1 then
tail_start = 1
end
local t = s:find('-', tail_start, true) or tail_start -- byte position where {tail} starts
-- If we fall back to a byte position, step forward past a split character
if t == tail_start and t <= #s then
if t == tail_start then
local offset_start = vim.str_utf_start(s, t)
if offset_start < 0 then
local char_start = t + offset_start ---@type integer
scripts/vim_na_files.txt
+1
View File
@@ -5,6 +5,7 @@ LICENSE
Makefile
SECURITY.md
configure
runtime/autoload/README.txt
runtime/bugreport.vim
runtime/defaults.vim
runtime/doc/channel.txt
src/nvim/api/win_config.c
+8 -3
View File
@@ -829,10 +829,15 @@ static void config_put_bordertext(Dict(win_config) *config, WinConfig *fconfig,
}
}
/// Gets window configuration in the form of a dict which can be passed as the `config` parameter of
/// |nvim_open_win()|.
/// Gets window config as a dict which can be passed to |nvim_open_win()| as the `config` parameter.
///
/// For non-floating windows, `relative` is empty.
/// For non-floating windows, `relative` is empty, thus you can check that field to detect if
/// a window is a floatwin:
/// ```lua
/// vim.print(vim.api.nvim_win_get_config(0).relative == '' and 'non-float' or 'float')
/// -- Or use win_gettype().
/// vim.print(vim.fn.win_gettype())
/// ```
///
/// @param win |window-ID|, or 0 for current window
/// @param[out] err Error details, if any
src/nvim/eval.lua
+18 -19
View File
@@ -1113,9 +1113,12 @@ M.funcs = {
See |channel-bytes| for more information.
{data} may be a string, string convertible, |Blob|, or a list.
If {data} is a list, the items will be joined by newlines; any
newlines in an item will be sent as NUL. To send a final
newline, include a final empty string. Example: >vim
newlines in an item will be sent as NUL; to send a final
newline, include a final empty string. |NL-used-for-Nul|
Example: >vim
call chansend(id, ["abc", "123\n456", ""])
<will send "abc<NL>123<NUL>456<NL>".
@@ -1125,9 +1128,9 @@ M.funcs = {
]=],
name = 'chansend',
params = { { 'id', 'number' }, { 'data', 'string|string[]' } },
returns = '0|1',
returns = 'integer',
signature = 'chansend({id}, {data})',
see_lua = { '|nvim_chan_send()| for string data; list input and the return value differ' },
see_lua = { '|nvim_chan_send()| for string (binary) data' },
},
char2nr = {
args = { 1, 2 },
@@ -13629,22 +13632,18 @@ M.funcs = {
args = { 0, 1 },
base = 1,
desc = [=[
Return the type of the window:
"autocmd" autocommand window. Temporary window
used to execute autocommands.
"command" command-line window |cmdwin|
(empty) normal window
"loclist" |location-list-window|
"popup" floating window |api-floatwin|
"preview" preview window |preview-window|
"quickfix" |quickfix-window|
"unknown" window {nr} not found
Gets the type of the given window, or current window if {nr}
is omitted:
- (empty) Normal window
- "autocmd" Internal "context-switch" window.
- "command" Command-line window |cmdwin|
- "loclist" |location-list-window|
- "popup" Floating window |api-floatwin|
- "preview" Preview window |preview-window|
- "quickfix" |quickfix-window|
- "unknown" Window {nr} not found
When {nr} is omitted return the type of the current window.
When {nr} is given (|window-number| or |window-ID|) return the
type of that window.
Also see the 'buftype' option.
See also the 'buftype' option.
]=],
name = 'win_gettype',
test/functional/lua/fs_spec.lua
+15 -18
View File
@@ -678,13 +678,12 @@ describe('vim.fs', function()
eq('a-ca978112', vim.fs.slug('a/.'))
end)
it('works without args', function()
it('works', function()
-- `=special`
eq('=special-8a5edab2', vim.fs.slug('/'))
eq('=special-ab5df625', vim.fs.slug('...'))
eq('=special-11d925ec', vim.fs.slug('-------'))
eq('src-foo-init.lua-cf05d2fe', vim.fs.slug('/src/foo/init.lua'))
-- Windows paths normalize differently on Windows vs Unix
eq('C--src-project-main.c-3b0eb5f5', vim.fs.slug('C:/src/project/main.c'))
eq('con.txt-d3bde286', vim.fs.slug('con.txt'))
-- Windows reserved names.
@@ -699,11 +698,23 @@ describe('vim.fs', function()
local p = vim.uv.os_homedir() .. '/my-project'
local hash8_2 = vim.fn.sha256(vim.fs.normalize(p)):sub(1, 8)
eq('~-my-project-' .. hash8_2, vim.fs.slug(p))
-- Windows-only cases.
if is_os('win') then
eq('=unc-foo-dir-file-549fb6e7', vim.fs.slug([[\\foo\dir\file]]))
-- `\\?\` and `\\.\`
eq(
'---Volume{a1b2c3d4-aa00-4000-a111-1a2b3c4d5e6f}-dir-file-cfda6a98',
vim.fs.slug([[\\?\Volume{a1b2c3d4-aa00-4000-a111-1a2b3c4d5e6f}\dir\file]])
)
eq('---C--dir-file-e8f30888', vim.fs.slug([[\\?\C:\dir\file]]))
eq('-.-COM1-e0e5710d', vim.fs.slug([[\\.\COM1]]))
end
end)
it('works with `opt.maxlen`', function()
it('`opts.maxlen`', function()
-- maxlen < 8 is an error
t.matches('`opt.maxlen` must be at least 8', t.pcall_err(vim.fs.slug, 'foo', { maxlen = 7 }))
t.matches('`opts.maxlen` must be >= 8', t.pcall_err(vim.fs.slug, 'foo', { maxlen = 7 }))
eq('2c26b46b', vim.fs.slug('foo', { maxlen = 8 }))
eq('2c26b46b', vim.fs.slug('foo', { maxlen = 11 }))
@@ -723,20 +734,6 @@ describe('vim.fs', function()
eq('~~~d-473a1da7', vim.fs.slug('foo/bar/longlonglong.md', { maxlen = 13 }))
eq('f~~~md-473a1da7', vim.fs.slug('foo/bar/longlonglong.md', { maxlen = 15 }))
end)
it('works on Windows', function()
if t.skip(not is_os('win'), 'N/A Windows only') then
return
end
eq('=unc-foo-dir-file-549fb6e7', vim.fs.slug([[\\foo\dir\file]]))
-- `\\?\` and `\\.\`
eq(
'---Volume{a1b2c3d4-aa00-4000-a111-1a2b3c4d5e6f}-dir-file-cfda6a98',
vim.fs.slug([[\\?\Volume{a1b2c3d4-aa00-4000-a111-1a2b3c4d5e6f}\dir\file]])
)
eq('---C--dir-file-e8f30888', vim.fs.slug([[\\?\C:\dir\file]]))
eq('-.-COM1-e0e5710d', vim.fs.slug([[\\.\COM1]]))
end)
end)
describe('normalize()', function()