ArgTools

ArgRead = Union{AbstractString, AbstractCmd, IO}

ArgRead 類型是 arg_read 函式知道如何轉換為可讀 IO 處理的類型聯集。請參閱 arg_read 以取得詳細資料。

ArgWrite = Union{AbstractString, AbstractCmd, IO}

ArgWrite 類型是 arg_write 函數知道如何轉換成可寫入 IO 句柄的類型聯集，除了 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 會將 lock = false 傳遞給檔案 open(...) 呼叫。因此，此函數傳回的物件不應從多個執行緒使用。此限制可能會在未來放寬，這不會中斷任何運作中的程式碼。

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 會將 lock = false 傳遞給檔案 open(...) 呼叫。因此，此函數傳回的物件不應從多個執行緒使用。此限制可能會在未來放寬，這不會中斷任何運作中的程式碼。

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 可使用 @arg_test arg begin ... end 轉換成 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 可使用 @arg_test arg begin ... end 轉換成 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)。