ArgRead = Union{AbstractString, AbstractCmd, IO}

TheArgRead types is a union of the types that thearg_read function knows how to convert into readable IO handles. Seearg_read for details.

ArgWrite = Union{AbstractString, AbstractCmd, IO}

TheArgWrite types is a union of the types that thearg_write function knows how to convert into writeable IO handles, except forNothing whicharg_write handles by generating a temporary file. Seearg_write for details.

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

Thearg_read function accepts an argumentarg that can be any of these:

• AbstractString: a file path to be opened for reading
• AbstractCmd: a command to be run, reading from its standard output
• IO: an open IO handle to be read from

Whether the body returns normally or throws an error, a path which is opened will be closed before returning fromarg_read and anIO handle will be flushed but not closed before returning fromarg_read.

Note: when opening a file, ArgTools will passlock = false to the fileopen(...) call. Therefore, the object returned by this function should not be used from multiple threads. This restriction may be relaxed in the future, which would not break any working code.

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

Thearg_read function accepts an argumentarg that can be any of these:

• AbstractString: a file path to be opened for writing
• AbstractCmd: a command to be run, writing to its standard input
• IO: an open IO handle to be written to
• Nothing: a temporary path should be written to

If the body returns normally, a path that is opened will be closed upon completion; an IO handle argument is left open but flushed before return. If the argument isnothing then a temporary path is opened for writing and closed open completion and the path is returned fromarg_write. In all other cases,arg itself is returned. This is a useful pattern since you can consistently return whatever was written, whether an argument was passed or not.

If there is an error during the evaluation of the body, a path that is opened byarg_write for writing will be deleted, whether it's passed in as a string or a temporary path generated whenarg isnothing.

Note: when opening a file, ArgTools will passlock = false to the fileopen(...) call. Therefore, the object returned by this function should not be used from multiple threads. This restriction may be relaxed in the future, which would not break any working code.

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

Thearg_isdir function takesarg which must be the path to an existing directory (an error is raised otherwise) and passes that path tof finally returning the result off(arg). This is definitely the least useful tool offered byArgTools and mostly exists for symmetry witharg_mkdir and to give consistent error messages.

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

Thearg_mkdir function takesarg which must either be one of:

• a path to an already existing empty directory,
• a non-existent path which can be created as a directory, or
• nothing in which case a temporary directory is created.

In all cases the path to the directory is returned. If an error occurs duringf(arg), the directory is returned to its original state: if it already existed but was empty, it will be emptied; if it did not exist it will be deleted.

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

Thearg_readers function takes a path to be read and a single-argument do block, which is invoked once for each test reader type thatarg_read can handle. If the optionaltype argument is given then the do block is only invoked for readers that produce arguments of that type.

Thearg passed to the do block is not the argument value itself, because some of test argument types need to be initialized and finalized for each test case. Consider an open file handle argument: once you've used it for one test, you can't use it again; you need to close it and open the file again for the next test. This functionarg can be converted into anArgRead instance using@arg_test arg begin ... end.

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

Thearg_writers function takes a do block, which is invoked once for each test writer type thatarg_write can handle with a temporary (non-existent)path andarg which can be converted into various writable argument types which write topath. If the optionaltype argument is given then the do block is only invoked for writers that produce arguments of that type.

Thearg passed to the do block is not the argument value itself, because some of test argument types need to be initialized and finalized for each test case. Consider an open file handle argument: once you've used it for one test, you can't use it again; you need to close it and open the file again for the next test. This functionarg can be converted into anArgWrite instance using@arg_test arg begin ... end.

There is also anarg_writers method that takes a path name likearg_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

This method is useful if you need to specifypath instead of using path name generated bytempname(). Sincepath is passed from outside ofarg_writers, the path is not an argument to the do block in this form.

@arg_test arg1 arg2 ... body

The@arg_test macro is used to convertarg functions provided byarg_readers andarg_writers into actual argument values. When you write@arg_test arg body it is equivalent toarg(arg -> body).