ArgTools

ArgRead = Union{AbstractString, AbstractCmd, IO}

ArgRead 类型是 arg_read 函数知道如何转换为可读 IO 处理程序的类型的并集。有关详细信息，请参阅 arg_read。

ArgWrite = Union{AbstractString, AbstractCmd, IO}

ArgWrite 类型是 arg_write 函数知道如何转换为可写入 IO 处理程序的类型的并集，除了 Nothing，arg_write 通过生成临时文件来处理它。有关详细信息，请参阅 arg_write。

arg_read(f::Function, arg::ArgRead) -> f(arg_io)

arg_read 函数接受一个参数 arg，它可以是以下任何一种

• AbstractString：要打开以供读取的文件路径
• AbstractCmd：要运行的命令，从其标准输出读取
• IO：要从中读取的打开的 IO 处理程序

无论代码块是否正常返回或抛出错误，在从 arg_read 返回之前，将关闭打开的路径，并且在从 arg_read 返回之前，将刷新 IO 处理程序，但不会关闭它。

注意：在打开文件时，ArgTools 将向文件 open(...) 调用传递 lock = false。因此，此函数返回的对象不应从多个线程中使用。此限制可能会在将来放宽，这不会破坏任何有效的代码。

arg_write(f::Function, arg::ArgWrite) -> arg
arg_write(f::Function, arg::Nothing) -> tempname()

arg_read 函数接受一个参数 arg，它可以是以下任何一种

• AbstractString：要打开以供写入的文件路径
• AbstractCmd：要运行的命令，写入其标准输入
• IO：要写入的打开的 IO 处理程序
• Nothing：应写入临时路径

如果代码块正常返回，则打开的路径将在完成时关闭；IO 处理程序参数保持打开状态，但在返回之前被刷新。如果参数是 nothing，则会打开一个临时路径以供写入，并在完成时关闭，路径将从 arg_write 返回。在所有其他情况下，将返回 arg 本身。这是一个有用的模式，因为您可以始终返回写入的内容，无论是否传递了参数。

如果在评估代码块期间发生错误，则由 arg_write 打开以供写入的路径将被删除，无论它是作为字符串传递还是作为 arg 为 nothing 时生成的临时路径。

注意：在打开文件时，ArgTools 将向文件 open(...) 调用传递 lock = false。因此，此函数返回的对象不应从多个线程中使用。此限制可能会在将来放宽，这不会破坏任何有效的代码。

arg_isdir(f::Function, arg::AbstractString) -> f(arg)

arg_isdir 函数接受 arg，它必须是现有目录的路径（否则会引发错误），并将该路径传递给 f，最后返回 f(arg) 的结果。这绝对是 ArgTools 提供的最不实用的工具，并且主要存在是为了与 arg_mkdir 对称，并提供一致的错误消息。

arg_mkdir(f::Function, arg::AbstractString) -> arg
arg_mkdir(f::Function, arg::Nothing) -> mktempdir()

arg_mkdir 函数接受 arg，它必须是以下之一

• 现有空目录的路径，
• 可以创建为目录的非现有路径，或
• nothing，在这种情况下将创建一个临时目录。

在所有情况下，都会返回目录的路径。如果在 f(arg) 期间发生错误，则目录将恢复到其原始状态：如果它已经存在但为空，则将清空它；如果它不存在，则将删除它。

arg_readers(arg :: AbstractString, [ type = ArgRead ]) do arg::Function
    ## pre-test setup ##
    @arg_test arg begin
        arg :: ArgRead
        ## test using `arg` ##
    end
    ## post-test cleanup ##
end

arg_readers 函数接受要读取的路径和一个单参数 do 块，该块将为 arg_read 可以处理的每个测试读取器类型调用一次。如果提供了可选的 type 参数，则只为生成该类型参数的读取器调用 do 块。

传递给 do 块的 arg 不是参数值本身，因为某些测试参数类型需要为每个测试用例初始化和最终确定。考虑一个打开的文件句柄参数：一旦将其用于一个测试，你就无法再次使用它；你需要关闭它并再次打开文件以进行下一个测试。可以使用 @arg_test arg begin ... end 将此函数的 arg 转换为 ArgRead 实例。

arg_writers([ type = ArgWrite ]) do path::String, arg::Function
    ## pre-test setup ##
    @arg_test arg begin
        arg :: ArgWrite
        ## test using `arg` ##
    end
    ## post-test cleanup ##
end

arg_writers 函数接受一个 do 块，该块将为 arg_write 可以处理的每个测试写入器类型调用一次，使用一个临时（不存在的）path 和 arg，它可以转换为各种可写入参数类型，这些参数类型写入 path。如果提供了可选的 type 参数，则只为生成该类型参数的写入器调用 do 块。

传递给 do 块的 arg 不是参数值本身，因为某些测试参数类型需要为每个测试用例初始化和最终确定。考虑一个打开的文件句柄参数：一旦将其用于一个测试，你就无法再次使用它；你需要关闭它并再次打开文件以进行下一个测试。可以使用 @arg_test arg begin ... end 将此函数的 arg 转换为 ArgWrite 实例。

还有一个 arg_writers 方法接受类似于 arg_readers 的路径名

arg_writers(path::AbstractString, [ type = ArgWrite ]) do arg::Function
    ## pre-test setup ##
    @arg_test arg begin
        # here `arg :: ArgWrite`
        ## test using `arg` ##
    end
    ## post-test cleanup ##
end

此方法在需要指定 path 而不是使用 tempname() 生成的路径名时很有用。由于 path 是从 arg_writers 外部传递的，因此路径不是此形式 do 块的参数。

@arg_test arg1 arg2 ... body

@arg_test 宏用于将 arg_readers 和 arg_writers 提供的 arg 函数转换为实际的参数值。当你编写 @arg_test arg body 时，它等同于 arg(arg -> body)。