ArgTools
Argument Handling
ArgTools.ArgRead
— TypeArgRead = Union{AbstractString, AbstractCmd, IO}
The ArgRead
types is a union of the types that the arg_read
function knows how to convert into readable IO handles. See arg_read
for details.
ArgTools.ArgWrite
— TypeArgWrite = Union{AbstractString, AbstractCmd, IO}
The ArgWrite
types is a union of the types that the arg_write
function knows how to convert into writeable IO handles, except for Nothing
which arg_write
handles by generating a temporary file. See arg_write
for details.
ArgTools.arg_read
— Functionarg_read(f::Function, arg::ArgRead) -> f(arg_io)
The arg_read
function accepts an argument arg
that can be any of these:
AbstractString
: a file path to be opened for readingAbstractCmd
: a command to be run, reading from its standard outputIO
: 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 from arg_read
and an IO
handle will be flushed but not closed before returning from arg_read
.
Note: when opening a file, ArgTools will pass lock = false
to the file open(...)
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.
ArgTools.arg_write
— Functionarg_write(f::Function, arg::ArgWrite) -> arg
arg_write(f::Function, arg::Nothing) -> tempname()
The arg_read
function accepts an argument arg
that can be any of these:
AbstractString
: a file path to be opened for writingAbstractCmd
: a command to be run, writing to its standard inputIO
: an open IO handle to be written toNothing
: 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 is nothing
then a temporary path is opened for writing and closed open completion and the path is returned from arg_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 by arg_write
for writing will be deleted, whether it's passed in as a string or a temporary path generated when arg
is nothing
.
Note: when opening a file, ArgTools will pass lock = false
to the file open(...)
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.
ArgTools.arg_isdir
— Functionarg_isdir(f::Function, arg::AbstractString) -> f(arg)
The arg_isdir
function takes arg
which must be the path to an existing directory (an error is raised otherwise) and passes that path to f
finally returning the result of f(arg)
. This is definitely the least useful tool offered by ArgTools
and mostly exists for symmetry with arg_mkdir
and to give consistent error messages.
ArgTools.arg_mkdir
— Functionarg_mkdir(f::Function, arg::AbstractString) -> arg
arg_mkdir(f::Function, arg::Nothing) -> mktempdir()
The arg_mkdir
function takes arg
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 during f(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.
Function Testing
ArgTools.arg_readers
— Functionarg_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
The arg_readers
function takes a path to be read and a single-argument do block, which is invoked once for each test reader type that arg_read
can handle. If the optional type
argument is given then the do block is only invoked for readers that produce arguments of that type.
The arg
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 function arg
can be converted into an ArgRead
instance using @arg_test arg begin ... end
.
ArgTools.arg_writers
— Functionarg_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
The arg_writers
function takes a do block, which is invoked once for each test writer type that arg_write
can handle with a temporary (non-existent) path
and arg
which can be converted into various writable argument types which write to path
. If the optional type
argument is given then the do block is only invoked for writers that produce arguments of that type.
The arg
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 function arg
can be converted into an ArgWrite
instance using @arg_test arg begin ... end
.
There is also an arg_writers
method that takes a path name like 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
This method is useful if you need to specify path
instead of using path name generated by tempname()
. Since path
is passed from outside of arg_writers
, the path is not an argument to the do block in this form.
ArgTools.@arg_test
— Macro@arg_test arg1 arg2 ... body
The @arg_test
macro is used to convert arg
functions provided by arg_readers
and arg_writers
into actual argument values. When you write @arg_test arg body
it is equivalent to arg(arg -> body)
.