AnyMath 文档

焦油

该 焦油 模块提供了一个简单的界面来处理tar档案，包括创建档案、从档案中提取选定的文件以及访问元数据。

create(
    [ predicate, ] dir, [ tarball ];
    [ skeleton, ] [ portable = false ]
) -> tarball

    predicate :: String --> Bool
    dir       :: AbstractString
    tarball   :: Union{AbstractString, AbstractCmd, IO}
    skeleton  :: Union{AbstractString, AbstractCmd, IO}
    portable  :: Bool

创建目录的tar存档（"tarball"） 署长. 生成的存档将写入路径 鹿tarball 或者，如果未指定路径，则创建临时路径并由函数调用返回。 如果 鹿tarball 是一个IO对象，然后tarball内容被写入该句柄（句柄保持打开状态）。

如果一个 谓词,谓词 函数被传递，它在递归搜索时遇到的每个系统路径上调用 署长 和 路径 只有在以下情况下才包括在tarball中 谓词（路径） 是真的。 如果 谓词（路径） 对于一个目录返回false，则该目录被完全排除：该目录下的任何内容都不会包含在存档中。

如果 骨架 关键字被传递，然后给出的文件或IO句柄被用作生成tarball的"骨架"。 通过传递 骨架 关键词 提取物 命令。 如果 创建 被调用与该骨架文件和提取的文件没有改变，一个相同的tarball被重新创建。 该 骨架 和 谓词,谓词 参数不能一起使用。

如果 手提式 标志为true，然后检查路径名称在Windows上的有效性，以确保它们不包含非法字符或具有保留的名称。 见https://stackoverflow.com/a/31976060/659248 有关详情。

extract(
    [ predicate, ] tarball, [ dir ];
    [ skeleton = <none>, ]
    [ copy_symlinks = <auto>, ]
    [ set_permissions = true, ]
) -> dir

    predicate       :: Header --> Bool
    tarball         :: Union{AbstractString, AbstractCmd, IO}
    dir             :: AbstractString
    skeleton        :: Union{AbstractString, AbstractCmd, IO}
    copy_symlinks   :: Bool
    set_permissions :: Bool

提取位于路径的tar存档（"tarball"） 鹿tarball 进入目录 署长. 如果 鹿tarball 是一个IO对象而不是一个路径，那么归档内容将从该IO流中读取。 存档被提取到 署长 它必须是一个现有的空目录或一个不存在的路径，可以创建为一个新的目录。 如果 署长 未指定，存档被提取到一个临时目录中，该目录由 提取物.

如果一个 谓词,谓词 函数被传递，它被调用在每个 标题 提取时遇到的对象 鹿tarball 并且只有在 谓词(hdr) 是真的。 这可用于选择性地仅提取存档的部分，以跳过导致 提取物 抛出错误，或者记录提取过程中提取的内容。

在传递给谓词函数之前， 标题 对象是从tarball中的原始头中稍微修改的： 路径 场进行归一化去除 . 条目并用单个斜杠替换多个连续斜杠。 如果条目具有类型 :硬链接，链接目标路径以相同的方式标准化，以便它将与目标条目的路径匹配;size字段设置为目标路径的大小（必须是已经看到的文件）。

如果 骨架 传递关键字，然后将提取的tarball的"骨架"写入给出的文件或IO句柄。 这个骨架文件可以通过传递 骨架 关键词 创建 函数。 该 骨架 和 谓词,谓词 参数不能一起使用。

如果 copy_symlinks 是 真的 然后，而不是像这样提取符号链接，它们将被提取为它们链接到的内容的副本，如果它们是tarball的内部，并且如果可以这样做。 非内部符号链接，例如指向 /等/密码 不会被复制。 以任何方式循环的符号链接也不会被复制，而是被跳过。 默认情况下, 提取物 将检测是否可以在 署长 或者不是，如果无法创建符号链接，则会自动复制它们。

如果 set_permissions 是 错误，未对提取的文件设置任何权限。

list(tarball; [ strict = true ]) -> Vector{Header}
list(callback, tarball; [ strict = true ])

    callback  :: Header, [ <data> ] --> Any
    tarball   :: Union{AbstractString, AbstractCmd, IO}
    strict    :: Bool

列出位于路径的tar存档（"tarball"）的内容 鹿tarball. 如果 鹿tarball 是一个IO句柄，从该流中读取tar内容。 返回的向量 标题 结构。 见 标题详情。

如果一个 回调；回调 然后提供而不是返回标题的向量，回调被调用在每个 标题. 如果tarball中的项目数量很大，或者您希望在tarball中出现错误之前检查项目，这将非常有用。 如果 回调；回调 函数可以接受任何类型的第二个参数 向量{UInt8} 或 向量资料{Pair{Symbol, String}} 然后，它将以单个字节向量或将字段名称映射到该字段的原始数据的对向量（如果这些字段连接在一起，则结果是标题的原始数据）的原始数据的表示来调用。

默认情况下 名单 如果遇到任何tarball内容，则会出错 提取物 功能将拒绝提取。 与 严格=错误 它将跳过这些检查并列出tar文件的所有内容。 提取物 是否会提取它们。 请注意，恶意tarball可以做各种狡猾和意想不到的事情，试图欺骗你做坏事。

如果 鹿tarball 参数是一个骨架文件（参见 提取物 和 创建）然后 名单 将从文件头中检测到它，并适当地列出或迭代骨架文件的头。

rewrite(
    [ predicate, ] old_tarball, [ new_tarball ];
    [ portable = false, ]
) -> new_tarball

    predicate   :: Header --> Bool
    old_tarball :: Union{AbstractString, AbstractCmd, IO}
    new_tarball :: Union{AbstractString, AbstractCmd, IO}
    portable    :: Bool

重写 旧球/旧球 到标准格式， 创建 生成，同时还检查它不包含任何会导致 提取物 来引发错误。 这在功能上等同于做

Tar.create(Tar.extract(predicate, old_tarball), new_tarball)

但是，它从不将任何内容提取到磁盘，而是使用 寻求 功能导航旧tarball的数据。 如果没有 新球/新球 参数被传递，新的tarball被写入一个临时文件，其路径被返回。

如果一个 谓词,谓词 函数被传递，它被调用在每个 标题 提取时遇到的对象 旧球/旧球 并且该条目被跳过，除非 谓词(hdr) 是真的。 这可以用于有选择地重写存档的部分，以跳过可能导致 提取物 抛出一个错误，或者记录在重写过程中遇到了什么内容。

在传递给谓词函数之前， 标题 对象是从tarball中的原始头中稍微修改的： 路径 场进行归一化去除 . 条目并用单个斜杠替换多个连续斜杠。 如果条目具有类型 :硬链接，链接目标路径以相同的方式标准化，以便它将与目标条目的路径相匹配;size字段设置为目标路径的大小（必须是已经看到的文件）。

如果 手提式 标志为true，然后检查路径名称在Windows上的有效性，以确保它们不包含非法字符或具有保留的名称。 见https://stackoverflow.com/a/31976060/659248 有关详情。

tree_hash([ predicate, ] tarball;
          [ algorithm = "git-sha1", ]
          [ skip_empty = false ]) -> hash::String

    predicate  :: Header --> Bool
    tarball    :: Union{AbstractString, AbstractCmd, IO}
    algorithm  :: AbstractString
    skip_empty :: Bool

计算tarball包含的文件树的树哈希值。 默认情况下，它使用git的树哈希算法和SHA1安全哈希函数（如当前版本的git）。 这意味着，对于git可以表示文件树的任何tarball-即只有文件，符号链接和非空目录的tarball-此函数计算的哈希值将与git为该文件树计算的哈希值相同。 请注意，tarball可以表示带有空目录的文件树，git无法存储这些目录，并且此函数可以为这些目录生成哈希，默认情况下会生成哈希（请参阅 n.空,空 下面是如何改变这种行为的），与省略那些空目录的tarball的哈希不同。 简而言之，哈希函数在git可以表示的所有树上都与git一致，但是（以一致的方式）将可哈希树的域扩展到git无法表示的其他树。

如果一个 谓词,谓词 函数被传递，它被调用在每个 标题 处理时遇到的对象 鹿tarball 只有在以下情况下，条目才会被散列 谓词(hdr) 是真的。 这可用于选择性地仅散列存档的部分，以跳过导致 提取物 抛出错误，或者记录哈希过程中提取的内容。

在传递给谓词函数之前， 标题 对象是从tarball中的原始头中稍微修改的： 路径 场进行归一化去除 . 条目并用单个斜杠替换多个连续斜杠。 如果条目具有类型 :硬链接，链接目标路径以相同的方式标准化，以便它将与目标条目的路径匹配;size字段设置为目标路径的大小（必须是已经看到的文件）。

当前支持的值 算法 是 git-sha1 （默认）和 git-sha256，其使用与相同的基本算法 git-sha1 但将SHA1哈希函数替换为sha2-256，这是git将来会过渡到使用的哈希函数（由于对SHA1的已知攻击）。 将来可能会添加对其他文件树哈希算法的支持。

该 n.空,空 选项控制压缩包中递归不包含文件或符号链接的目录是否包含在哈希中或被忽略。 通常，如果您正在对tarball或文件树的内容进行散列，则关心所有目录，而不仅仅是非空目录，因此在计算的散列中包含这些目录是默认的。 那么为什么这个函数甚至提供跳过空目录的选项呢？ 因为git拒绝存储空目录，并且如果您尝试将它们添加到回购中，则会忽略它们。 因此，如果您通过将文件添加到git存储库来计算引用树哈希，然后向git请求树哈希，则您获得的哈希值将与通过以下方式计算的哈希值相匹配 tree_hash 与 skip_empty=真. 换句话说，此选项允许 tree_hash 模拟git如何用空目录散列一棵树。 但是，如果您正在散列可能包含空目录的树（即不是来自git回购），建议您使用不忽略空目录的工具（例如this one）对它们进行散列。

该 标题 type是表示具有此定义的tar文件中单个记录的基本元数据的结构:

struct Header
    path :: String # path relative to the root
    type :: Symbol # type indicator (see below)
    mode :: UInt16 # mode/permissions (best viewed in octal)
    size :: Int64  # size of record data in bytes
    link :: String # target path of a symlink
end

类型用下列符号表示: 档案, 硬链接, 符号链接, 夏德夫, 布洛克德夫, 目录, 先进先出，或者对于未知类型，将typeflag字符作为符号。 请注意 提取物拒绝提取除 档案, 符号链接 和 目录; 名单只会列出其他类型的记录，如果用 严格=错误.

Tar格式包括关于记录的各种其他元数据，包括用户和组Id、用户和组名称以及时间戳。 该 焦油 包，通过设计，完全忽略了这些。 创建tar文件时，这些字段始终设置为零/空。 读取tar文件时，除了验证所有字段的每个标头记录的标头校验和之外，这些字段将被忽略。