---@meta lfs

--------------------------------------------------------------------------------
-- LuaFileSystem C module
--------------------------------------------------------------------------------

---@alias lfs_mode 'file'|'directory'|'link'|'socket'|'named pipe'|'char device'|'block device'|'other'
---@alias lfs_attribute_name 'mode'|'dev'|'ino'|'nlink'|'uid'|'gid'|'rdev'|'access'|'modification'|'change'|'size'|'permissions'|'blocks'|'blksize'
---@alias lfs_lock_mode 'r'|'w'
---@alias lfs_setmode 'binary'|'text'

---@class lfs_attributes*
---@field mode lfs_mode File type
---@field dev integer Device number
---@field ino integer inode
---@field nlink integer Number of hard links
---@field uid integer owner user id
---@field gid integer owner group id
---@field rdev integer Special device number
---@field access integer last access time
---@field modification integer last modified time
---@field change integer Status change time
---@field size integer file size
---@field permissions string permission string
---@field blocks? integer Number of allocation blocks
---@field blksize? integer Optimal I/O block size

---@class lfs_dir*
local lfs_dir = {}

--- Get the next directory entry.
---@return string? name Catalog item name
---@return string? errMsg error message
function lfs_dir:next() end

--- Close directory iterator.
function lfs_dir:close() end

---@class lfs_lock*
local lfs_lock = {}

--- Release directory lock.
function lfs_lock:free() end

---@class lfs*
---@field _COPYRIGHT string Copyright information
---@field _DESCRIPTION string Module description
---@field _VERSION string version
---@type lfs*
local M = {}

--- Get file attributes.
---@param filepath string file path
---@param request? lfs_attribute_name|lfs_attributes* Attribute name or reuse result table
---@return lfs_attributes*|string|integer? value attribute table or individual attribute value
---@return string? errMsg error message
---@return integer? errNo System error code
function M.attributes(filepath, request) end

--- Switch the current directory.
---@param path string directory path
---@return boolean? ok true on success
---@return string? errMsg error message
function M.chdir(path) end

--- Get the current directory.
---@return string? path current directory
---@return string? errMsg error message
---@return integer? errNo System error code
function M.currentdir() end

--- Create a directory iterator.
---@param path string directory path
---@return fun(dir:lfs_dir*):string? iter iterative function
---@return lfs_dir* dir directory object
function M.dir(path) end

--- Create a hard link or symbolic link.
---@param oldpath string target path
---@param newpath string link path
---@param symbolic? boolean Whether to create symbolic links
---@return boolean? ok true on success
---@return string? errMsg error message
---@return integer? errNo System error code
function M.link(oldpath, newpath, symbolic) end

--- Lock file area.
---@param file file* file object
---@param mode lfs_lock_mode lock mode
---@param start? integer start offset
---@param length? integer length
---@return boolean? ok true on success
---@return string? errMsg error message
function M.lock(file, mode, start, length) end

--- Create directory.
---@param path string directory path
---@return boolean? ok true on success
---@return string? errMsg error message
---@return integer? errNo System error code
function M.mkdir(path) end

--- Delete the directory.
---@param path string directory path
---@return boolean? ok true on success
---@return string? errMsg error message
---@return integer? errNo System error code
function M.rmdir(path) end

--- Get the properties of the symbolic link itself.
---@param filepath string file path
---@param request? lfs_attribute_name|lfs_attributes* Attribute name or reuse result table
---@return lfs_attributes*|string|integer? value attribute table or individual attribute value
---@return string? errMsg error message
---@return integer? errNo System error code
function M.symlinkattributes(filepath, request) end

--- Set file text/binary mode.
---@param file file* file object
---@param mode lfs_setmode mode
---@return boolean? ok true on success
---@return lfs_setmode|string? previous Previous mode or error message
---@return integer? errNo System error code
function M.setmode(file, mode) end

--- Modify file access and modification times.
---@param filepath string file path
---@param accessTime? integer Access time; if not passed, the current time is used
---@param modificationTime? integer Modification time; use accessTime if not passed
---@return boolean? ok true on success
---@return string? errMsg error message
---@return integer? errNo System error code
function M.touch(filepath, accessTime, modificationTime) end

--- Unlock file area.
---@param file file* file object
---@param start? integer start offset
---@param length? integer length
---@return boolean? ok true on success
---@return string? errMsg error message
function M.unlock(file, start, length) end

--- Create directory lock.
---@param path string directory path
---@return lfs_lock*? lock lock object
---@return string? errMsg error message
function M.lock_dir(path) end

return M
