path: root/runtime/lua/vim/fs.lua

--- @brief
--- [vim.fs.copy()]()
---
--- Use |filecopy()| or |uv.fs_copyfile()| to performantly copy an existing file.
---
--- Example:
---
--- ```lua
--- vim.fn.filecopy('foo.txt', 'bar.txt')
--- ```
---
--- [vim.fs.exists()]()
---
--- Use |uv.fs_stat()| to check a file's type, and whether it exists.
---
--- Example:
---
--- ```lua
--- if vim.uv.fs_stat(file) then
---   vim.print('file exists')
--- end
--- ```
---
--- [vim.fs.read()]()
---
--- You can use |readblob()| to get a file's contents without explicitly opening/closing it.
--- Or use |io.lines()| to iterate lines in a text file.
---
--- Example:
--- ```lua
--- vim.print(vim.fn.readblob('.git/config'))
--- ```
---
--- [vim.fs.write()]()
---
--- You can use |writefile()| to write a file without explicitly opening/closing it.
---
--- Example:
--- ```lua
--- vim.fn.writefile('foo\0bar', 'data.bin', 'b')
--- ```

local uv = vim.uv

local M = {}

-- Can't use `has('win32')` because the `nvim -ll` test runner doesn't support `vim.fn` yet.
local sysname = uv.os_uname().sysname:lower()
local iswin = not not (sysname:find('windows') or sysname:find('mingw'))
local os_sep = iswin and '\\' or '/'

--- Iterate over all the parents of the given path (not expanded/resolved, the caller must do that).
---
--- Example:
---
--- ```lua
--- local root_dir
--- for dir in vim.fs.parents(vim.api.nvim_buf_get_name(0)) do
---   if vim.fn.isdirectory(dir .. '/.git') == 1 then
---     root_dir = dir
---     break
---   end
--- end
---
--- if root_dir then
---   print('Found git repository at', root_dir)
--- end
--- ```
---
---@since 10
---@param start (string) Initial path.
---@return fun(_, dir: string): string? # Iterator
---@return nil
---@return string|nil
function M.parents(start)
  return function(_, dir)
    local parent = M.dirname(dir)
    if parent == dir then
      return nil
    end

    return parent
  end,
    nil,
    start
end

--- Gets the parent directory of the given path (not expanded/resolved, the caller must do that).
---
---@since 10
---@generic T : string|nil
---@param file T Path
---@return T Parent directory of {file}
function M.dirname(file)
  if file == nil then
    return nil
  end
  vim.validate('file', file, 'string')
  if iswin then
    file = file:gsub(os_sep, '/') --[[@as string]]
    if file:match('^%w:/?$') then
      return file
    end
  end
  if not file:match('/') then
    return '.'
  elseif file == '/' or file:match('^/[^/]+$') then
    return '/'
  end
  ---@type string
  local dir = file:match('/$') and file:sub(1, #file - 1) or file:match('^(/?.+)/')
  if iswin and dir:match('^%w:$') then
    return dir .. '/'
  end
  return dir
end

--- Gets the basename of the given path (not expanded/resolved).
---
---@since 10
---@generic T : string|nil
---@param file T Path
---@return T Basename of {file}
function M.basename(file)
  if file == nil then
    return nil
  end
  vim.validate('file', file, 'string')
  if iswin then
    file = file:gsub(os_sep, '/') --[[@as string]]
    if file:match('^%w:/?$') then
      return ''
    end
  end
  return file:match('/$') and '' or (file:match('[^/]*$'))
end

--- Concatenates partial paths (one absolute or relative path followed by zero or more relative
--- paths). Slashes are normalized: redundant slashes are removed, and (on Windows) backslashes are
--- replaced with forward-slashes. Empty segments are removed. Paths are not expanded/resolved.
---
--- Examples:
--- - "foo/", "/bar" => "foo/bar"
--- - "", "after/plugin" => "after/plugin"
--- - Windows: "a\foo\", "\bar" => "a/foo/bar"
---
---@since 12
---@param ... string
---@return string
function M.joinpath(...)
  local n = select('#', ...)
  ---@type string[]
  local segments = {}
  for i = 1, n do
    local s = select(i, ...)
    if s and #s > 0 then
      segments[#segments + 1] = s
    end
  end

  local path = table.concat(segments, '/')

  return (path:gsub(iswin and '[/\\][/\\]*' or '//+', '/'))
end

--- @class vim.fs.dir.Opts
--- @inlinedoc
---
--- How deep to traverse.
--- (default: `1`)
--- @field depth? integer
---
--- Predicate to control traversal.
--- Return false to stop searching the current directory.
--- Only useful when depth > 1
--- Return an iterator over the items located in {path}
--- @field skip? (fun(dir_name: string): boolean)
---
--- Follow symbolic links.
--- (default: `false`)
--- @field follow? boolean

---@alias Iterator fun(): string?, string?

--- Gets an iterator over items found in `path` (normalized via |vim.fs.normalize()|).
---
---@since 10
---@param path (string) Directory to iterate over, normalized via |vim.fs.normalize()|.
---@param opts? vim.fs.dir.Opts Optional keyword arguments:
---@return Iterator over items in {path}. Each iteration yields two values: "name" and "type".
---        "name" is the basename of the item relative to {path}.
---        "type" is one of the following:
---        "file", "directory", "link", "fifo", "socket", "char", "block", "unknown".
function M.dir(path, opts)
  opts = opts or {}

  vim.validate('path', path, 'string')
  vim.validate('depth', opts.depth, 'number', true)
  vim.validate('skip', opts.skip, 'function', true)
  vim.validate('follow', opts.follow, 'boolean', true)

  path = M.normalize(path)
  if not opts.depth or opts.depth == 1 then
    local fs = uv.fs_scandir(path)
    return function()
      if not fs then
        return
      end
      return uv.fs_scandir_next(fs)
    end
  end

  --- @async
  return coroutine.wrap(function()
    local dirs = { { path, 1 } }
    while #dirs > 0 do
      --- @type string, integer
      local dir0, level = unpack(table.remove(dirs, 1))
      local dir = level == 1 and dir0 or M.joinpath(path, dir0)
      local fs = uv.fs_scandir(dir)
      while fs do
        local name, t = uv.fs_scandir_next(fs)
        if not name then
          break
        end
        local f = level == 1 and name or M.joinpath(dir0, name)
        coroutine.yield(f, t)
        if
          opts.depth
          and level < opts.depth
          and (t == 'directory' or (t == 'link' and opts.follow and (
            uv.fs_stat(M.joinpath(path, f)) or {}
          ).type == 'directory'))
          and (not opts.skip or opts.skip(f) ~= false)
        then
          dirs[#dirs + 1] = { f, level + 1 }
        end
      end
    end
  end)
end

--- @class vim.fs.find.Opts
--- @inlinedoc
---
--- Path to begin searching from, defaults to |current-directory|. Not expanded.
--- @field path? string
---
--- Search upward through parent directories. Otherwise, search child directories (recursively).
--- (default: `false`)
--- @field upward? boolean
---
--- Stop searching when this directory is reached. The directory itself is not searched.
--- @field stop? string
---
--- Find only items of the given type. If omitted, all items that match {names} are included.
--- @field type? string
---
--- Stop searching after this many matches. Use `math.huge` for "unlimited".
--- (default: `1`)
--- @field limit? number
---
--- Follow symbolic links.
--- (default: `false`)
--- @field follow? boolean

--- Find files or directories (or other items as specified by `opts.type`) in the given path.
---
--- Finds items given in {names} starting from {path}. If {upward} is "true"
--- then the search traverses upward through parent directories; otherwise,
--- the search traverses downward. Note that downward searches are recursive
--- and may search through many directories! If {stop} is non-nil, then the
--- search stops when the directory given in {stop} is reached. The search
--- terminates when {limit} (default 1) matches are found. You can set {type}
--- to "file", "directory", "link", "socket", "char", "block", or "fifo"
--- to narrow the search to find only that type.
---
--- Examples:
---
--- ```lua
--- -- List all test directories under the runtime directory.
--- local dirs = vim.fs.find(
---   { 'test', 'tst', 'testdir' },
---   { limit = math.huge, type = 'directory', path = './runtime/' }
--- )
---
--- -- Get all "lib/*.cpp" and "lib/*.hpp" files, using Lua patterns.
--- -- Or use `vim.glob.to_lpeg(…):match(…)` for glob/wildcard matching.
--- local files = vim.fs.find(function(name, path)
---   return name:match('.*%.[ch]pp$') and path:match('[/\\]lib$')
--- end, { limit = math.huge, type = 'file' })
--- ```
---
---@since 10
---@param names (string|string[]|fun(name: string, path: string): boolean) Names of the items to find.
---             Must be base names, paths and globs are not supported when {names} is a string or a table.
---             If {names} is a function, it is called for each traversed item with args:
---             - name: base name of the current item
---             - path: full path of the current item
---
---             The function should return `true` if the given item is considered a match.
---
---@param opts? vim.fs.find.Opts Optional keyword arguments:
---@return (string[]) # Normalized paths |vim.fs.normalize()| of all matching items
function M.find(names, opts)
  opts = opts or {}
  vim.validate('names', names, { 'string', 'table', 'function' })
  vim.validate('path', opts.path, 'string', true)
  vim.validate('upward', opts.upward, 'boolean', true)
  vim.validate('stop', opts.stop, 'string', true)
  vim.validate('type', opts.type, 'string', true)
  vim.validate('limit', opts.limit, 'number'