ArgTools

ArgRead = Union{AbstractString, AbstractCmd, IO}

ArgRead 类型是一个联合类型，包含 arg_read 函数知道如何转换为可读的 IO 句柄的类型。有关详细信息，请参见 arg_read。

ArgWrite = Union{AbstractString, AbstractCmd, IO}

ArgWrite 类型是一个联合类型，包含 arg_write 函数知道如何转换为可写的 IO 句柄的类型，除了 Nothing，arg_write 通过生成临时文件来处理 Nothing。有关详细信息，请参见 arg_write。

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

arg_read 函数接受一个参数 arg，该参数可以是以下任意一种：

• AbstractString：要打开以进行读取的文件路径
• AbstractCmd：要运行的命令，从其标准输出读取
• IO：要读取的打开的 IO 句柄

无论函数体是正常返回还是抛出错误，打开的路径将在从 arg_read 返回之前关闭，而 IO 句柄将在从 arg_read 返回之前被刷新但不会关闭。

注意：在打开文件时，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
    ## 预测试设置 ##
    @arg_test arg begin
        arg :: ArgRead
        ## 使用 `arg` 进行测试 ##
    end
    ## 后测试清理 ##
end

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

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

arg_writers([ type = ArgWrite ]) do path::String, arg::Function
    ## 测试前设置 ##
    @arg_test arg begin
        arg :: ArgWrite
        ## 使用 `arg` 进行测试 ##
    end
    ## 测试后清理 ##
end

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

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

还有一个 arg_writers 方法，它接受一个路径名称，类似于 arg_readers：

arg_writers(path::AbstractString, [ type = ArgWrite ]) do arg::Function
    ## 测试前设置 ##
    @arg_test arg begin
        # 这里 `arg :: ArgWrite`
        ## 使用 `arg` 进行测试 ##
    end
    ## 测试后清理 ##
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)。