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 から戻る前に閉じられ、IO ハンドルは arg_read から戻る前にフラッシュされますが、閉じられません。

注意：ファイルを開くとき、ArgTools はファイル open(...) 呼び出しに lock = false を渡します。したがって、この関数から返されるオブジェクトは複数のスレッドから使用されるべきではありません。この制限は将来的に緩和される可能性がありますが、動作しているコードを壊すことはありません。

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

arg_write 関数は、次のいずれかの引数 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 は、@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_readersのようにパス名を受け取るarg_writersメソッドもあります：

arg_writers(path::AbstractString, [ type = ArgWrite ]) do arg::Function
    ## テスト前のセットアップ ##
    @arg_test arg begin
        # ここで `arg :: ArgWrite`
        ## `arg`を使ったテスト ##
    end
    ## テスト後のクリーンアップ ##
end

このメソッドは、tempname()によって生成されたパス名を使用するのではなく、pathを指定する必要がある場合に便利です。pathはarg_writersの外部から渡されるため、この形式ではdoブロックへの引数ではありません。

@arg_test arg1 arg2 ... body

@arg_test マクロは、arg_readers および arg_writers によって提供される arg 関数を実際の引数値に変換するために使用されます。@arg_test arg body と書くと、arg(arg -> body) と同等です。