---@meta archive

--------------------------------------------------------------------------------
-- libarchive C 绑定模块
--------------------------------------------------------------------------------

---@alias archive_read_format 'all'|'ar'|'cpio'|'empty'|'gnutar'|'iso9660'|'mtree'|'tar'|'zip'|string
---@alias archive_read_compression 'all'|'bzip2'|'compress'|'gzip'|'lzma'|'none'|'xz'|string
---@alias archive_write_format 'ar'|'arbsd'|'argnu'|'arsvr4'|'cpio'|'mtree'|'newc'|'odc'|'pax'|'posix'|'shar'|'shardump'|'ustar'|'ar_bsd'|'ar_svr4'|'cpio_newc'|'pax_restricted'|'shar_dump'|string
---@alias archive_write_compression 'bzip2'|'compress'|'gzip'|'lzma'|'xz'|string
---@alias archive_reader_callback fun(ar:archive_reader*):string?
---@alias archive_writer_callback fun(ar:archive_writer*, data:string?):integer?
---@alias archive_time integer[]|{[1]:integer,[2]:integer}

---@class archive_read_options*
---@field reader archive_reader_callback 读取回调；返回 nil 表示结束
---@field format? archive_read_format 支持的格式列表文本，默认 all
---@field compression? archive_read_compression 支持的压缩列表文本，默认 none
---@field options? string libarchive 选项字符串

---@class archive_write_skip_file*
---@field dev integer 设备号
---@field ino integer inode

---@class archive_write_options*
---@field writer archive_writer_callback 写入回调；关闭时以 nil 调用
---@field format? archive_write_format 写入格式，默认 posix
---@field compression? archive_write_compression 压缩格式
---@field options? string libarchive 选项字符串
---@field bytes_per_block? integer 每块字节数
---@field bytes_in_last_block? integer 最后一块字节数
---@field skip_file? archive_write_skip_file* 跳过指定文件

---@class archive_entry_options*
---@field fflags? string file flags
---@field dev? integer 设备号
---@field ino? integer inode
---@field mode? integer 文件 mode
---@field nlink? integer 硬链接数
---@field uid? integer user id
---@field uname? string user name
---@field gid? integer group id
---@field gname? string group name
---@field rdev? integer special device id
---@field atime? archive_time access time
---@field mtime? archive_time modification time
---@field ctime? archive_time change time
---@field birthtime? archive_time birth time
---@field size? integer 文件大小
---@field sourcepath? string 源文件路径；会复制 stat 信息
---@field symlink? string symlink 目标
---@field hardlink? string hardlink 目标
---@field pathname? string archive 内路径

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

---@param value? string
---@return string? value
function archive_entry:fflags(value) end

---@param value? integer
---@return integer value
function archive_entry:dev(value) end

---@param value? integer
---@return integer value
function archive_entry:ino(value) end

---@param value? integer
---@return integer value
function archive_entry:mode(value) end

---@param value? integer
---@return integer value
function archive_entry:nlink(value) end

---@param value? integer
---@return integer value
function archive_entry:uid(value) end

---@param value? string
---@return string? value
function archive_entry:uname(value) end

---@param value? integer
---@return integer value
function archive_entry:gid(value) end

---@param value? string
---@return string? value
function archive_entry:gname(value) end

---@param value? integer
---@return integer value
function archive_entry:rdev(value) end

---@param seconds? integer|archive_time|nil
---@param nsec? integer
---@return integer? seconds
---@return integer? nsec
function archive_entry:atime(seconds, nsec) end

---@param seconds? integer|archive_time|nil
---@param nsec? integer
---@return integer? seconds
---@return integer? nsec
function archive_entry:mtime(seconds, nsec) end

---@param seconds? integer|archive_time|nil
---@param nsec? integer
---@return integer? seconds
---@return integer? nsec
function archive_entry:ctime(seconds, nsec) end

---@param seconds? integer|archive_time|nil
---@param nsec? integer
---@return integer? seconds
---@return integer? nsec
function archive_entry:birthtime(seconds, nsec) end

---@param value? integer|nil
---@return integer? value
function archive_entry:size(value) end

---@param value? string
---@return string? value
function archive_entry:sourcepath(value) end

---@param value? string
---@return string? value
function archive_entry:symlink(value) end

---@param value? string
---@return string? value
function archive_entry:hardlink(value) end

---@param value? string
---@return string? value
function archive_entry:pathname(value) end

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

--- 读取下一个 header。
---@return archive_entry*? entry 条目；结束时为 nil
function archive_reader:next_header() end

--- 返回 header 迭代器。
---@return fun(ar:archive_reader*):archive_entry*? iter 迭代函数
---@return archive_reader* ar reader 对象
---@return nil initial 初始值
function archive_reader:headers() end

--- 读取当前条目的下一段数据。
---@return string? data 数据块；结束时为 nil
---@return integer? offset 数据偏移
function archive_reader:data() end

--- 关闭 reader。
function archive_reader:close() end

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

--- 写入条目 header。
---@param entry archive_entry* 条目
function archive_writer:header(entry) end

--- 写入条目数据。
---@param data string 数据
function archive_writer:data(data) end

--- 关闭 writer。
function archive_writer:close() end

---@class archive*
---@type archive*
local M = {}

--- 返回底层 libarchive 版本号组件。
---@return integer major 主版本
---@return integer minor 次版本
---@return integer patch 修订号
---@return integer? build 构建号
function M.version() end

--- 创建 archive reader。
---@param opts archive_read_options* 读取选项
---@return archive_reader* reader reader 对象
function M.read(opts) end

--- 创建 archive writer。
---@param opts archive_write_options* 写入选项
---@return archive_writer* writer writer 对象
function M.write(opts) end

--- 创建 archive entry。
---@param opts? archive_entry_options* entry 初始字段
---@return archive_entry* entry entry 对象
function M.entry(opts) end

--- 调试用 reader 引用计数。
---@return integer count 引用计数
function M._read_ref_count() end

--- 调试用 writer 引用计数。
---@return integer count 引用计数
function M._write_ref_count() end

--- 调试用 entry 引用计数。
---@return integer count 引用计数
function M._entry_ref_count() end

return M
