ArgTools

Argument Handling

ArgTools.ArgRead — Type
ArgRead = Union{AbstractString, AbstractCmd, IO}

ArgRead 型は、arg_read 関数が読み取り可能な IO ハンドルに変換できる型のユニオンです。詳しくは arg_read を参照してください。

source
ArgTools.ArgWrite — Type
ArgWrite = Union{AbstractString, AbstractCmd, IO}

ArgWrite型は、arg_write関数が書き込み可能なIOハンドルに変換できる型の和集合です。ただし、arg_writeが一時ファイルを生成して処理するNothingは除きます。詳しくはarg_writeを参照してください。

source
ArgTools.arg_read — Function
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 を渡します。そのため、この関数が返すオブジェクトを複数のスレッドから使用してはいけません。将来、この制限が緩和される可能性がありますが、その場合も既存の動作するコードに影響はありません。

source
ArgTools.arg_write — Function
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 を渡します。そのため、この関数が返すオブジェクトを複数のスレッドから使用してはいけません。この制限は将来緩和される可能性がありますが、その場合も既存の動作するコードに影響はありません。

source
ArgTools.arg_isdir — Function
arg_isdir(f::Function, arg::AbstractString) -> f(arg)

arg_isdir 関数は、既存のディレクトリへのパスでなければならない arg を受け取り(そうでない場合はエラーが発生します)、そのパスを f に渡し、最終的に f(arg) の結果を返します。これは、ArgTools が提供するツールの中で間違いなく最も役に立たないもので、主に arg_mkdir との対称性を保ち、一貫したエラーメッセージを表示するために存在します。

source
ArgTools.arg_mkdir — Function
arg_mkdir(f::Function, arg::AbstractString) -> arg
arg_mkdir(f::Function, arg::Nothing) -> mktempdir()

arg_mkdir 関数は arg を受け取ります。これは次のいずれかでなければなりません。

  • すでに存在する空のディレクトリへのパス
  • ディレクトリとして作成可能な、まだ存在しないパス
  • nothing。この場合、一時ディレクトリが作成されます。

いずれの場合も、ディレクトリへのパスが返されます。f(arg) 中にエラーが発生した場合、ディレクトリは元の状態に戻されます。すでに存在していて空だった場合は空にされ、存在していなかった場合は削除されます。

source

Function Testing

ArgTools.arg_readers — Function
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 関数は、読み込むパスと、引数を1つ取る do ブロックを受け取ります。この do ブロックは、arg_read が処理できる各テストリーダー型に対して1回ずつ呼び出されます。省略可能な type 引数を指定すると、その型の引数を生成するリーダーに対してのみ do ブロックが呼び出されます。

do ブロックに渡される arg は、引数の値そのものではありません。テスト引数型によっては、テストケースごとに初期化と終了処理が必要だからです。たとえば、開いたファイルハンドルを引数として使う場合、1つのテストで使用した後は再利用できません。次のテストでは、ファイルを閉じてから再度開く必要があります。この関数 arg は、@arg_test arg begin ... end を使って ArgRead インスタンスに変換できます。

source
ArgTools.arg_writers — Function
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 と、path に書き込むさまざまな書き込み可能な引数型に変換できる arg を使って処理できる、各テストライター型に対して一度ずつ呼び出します。省略可能な type 引数を指定すると、その型の引数を生成するライターに対してのみ do ブロックが呼び出されます。

do ブロックに渡される arg は、引数の値そのものではありません。テスト用の引数型の中には、テストケースごとに初期化と終了処理が必要なものがあるためです。たとえば、ファイルハンドルを引数として使う場合、あるテストで使った後は再利用できません。次のテストでは、ファイルを閉じて再度開く必要があります。この関数 arg は、@arg_test arg begin ... end を使って ArgWrite インスタンスに変換できます。

パス名(arg_readers など)を受け取る arg_writers メソッドもあります。

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

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

source
ArgTools.@arg_test — Macro
@arg_test arg1 arg2 ... body

@arg_test マクロは、arg_readers と arg_writers が提供する arg 関数を、実際の引数値に変換するために使用します。@arg_test arg body と記述することは、arg(arg -> body) と同じです。

source