ArgTools

ArgRead = Union{AbstractString, AbstractCmd, IO}

Типы ArgRead представляют собой объединение типов, которые функция arg_read умеет преобразовывать в читаемые дескрипторы ввода-вывода. См. 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 передаст 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
    ## преднастройка теста ##
    @arg_test arg begin
        arg :: ArgRead
        ## тест с использованием `arg` ##
    end
    ## очистка после теста ##
end

Функция arg_readers принимает путь для чтения и блок do с одним аргументом, который вызывается один раз для каждого типа тестового считывателя, который может обрабатывать arg_read. Если указан необязательный аргумент type, то блок do вызывается только для считывателей, которые производят аргументы этого типа.

Аргумент arg, переданный в блок do, не является самим значением аргумента, потому что некоторые типы тестовых аргументов необходимо инициализировать и завершать для каждого тестового случая. Рассмотрим аргумент открытого дескриптора файла: как только вы использовали его для одного теста, вы не можете использовать его снова; вам нужно закрыть его и снова открыть файл для следующего теста. Эта функция arg может быть преобразована в экземпляр ArgRead с помощью @arg_test arg begin ... end.

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 вызывается только для писателей, которые производят аргументы этого типа.

arg, переданный в блок do, не является самим значением аргумента, потому что некоторые типы тестовых аргументов необходимо инициализировать и завершать для каждого тестового случая. Рассмотрим аргумент открытого дескриптора файла: как только вы использовали его для одного теста, вы не можете использовать его снова; вам нужно закрыть его и снова открыть файл для следующего теста. Эта функция arg может быть преобразована в экземпляр ArgWrite с помощью @arg_test arg begin ... end.

Существует также метод arg_writers, который принимает имя пути, как и arg_readers:

arg_writers(path::AbstractString, [ type = ArgWrite ]) do arg::Function
    ## подготовка к тесту ##
    @arg_test arg begin
        # здесь `arg :: ArgWrite`
        ## тест с использованием `arg` ##
    end
    ## очистка после теста ##
end

Этот метод полезен, если вам нужно указать path вместо использования имени пути, сгенерированного tempname(). Поскольку path передается извне arg_writers, путь не является аргументом для блока do в этой форме.

@arg_test arg1 arg2 ... body

Макрос @arg_test используется для преобразования функций arg, предоставляемых arg_readers и arg_writers, в фактические значения аргументов. Когда вы пишете @arg_test arg body, это эквивалентно arg(arg -> body).