ArgTools

ArgRead = Union{AbstractString, AbstractCmd, IO}

El tipo ArgRead es una unión de los tipos que la función arg_read sabe cómo convertir en manejadores de IO legibles. Consulta arg_read para más detalles.

ArgWrite = Union{AbstractString, AbstractCmd, IO}

El tipo ArgWrite es una unión de los tipos que la función arg_write sabe cómo convertir en manejadores de IO escribibles, excepto por Nothing, que arg_write maneja generando un archivo temporal. Consulta arg_write para más detalles.

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

La función arg_read acepta un argumento arg que puede ser cualquiera de estos:

• AbstractString: una ruta de archivo que se abrirá para lectura
• AbstractCmd: un comando que se ejecutará, leyendo desde su salida estándar
• IO: un manejador de IO abierto del que se leerá

Ya sea que el cuerpo devuelva normalmente o lance un error, una ruta que se abra se cerrará antes de devolver de arg_read y un manejador de IO se vaciará pero no se cerrará antes de devolver de arg_read.

Nota: al abrir un archivo, ArgTools pasará lock = false a la llamada de archivo open(...). Por lo tanto, el objeto devuelto por esta función no debe ser utilizado desde múltiples hilos. Esta restricción puede relajarse en el futuro, lo que no rompería ningún código funcional.

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

La función arg_read acepta un argumento arg que puede ser cualquiera de estos:

• AbstractString: una ruta de archivo que se abrirá para escritura
• AbstractCmd: un comando que se ejecutará, escribiendo en su entrada estándar
• IO: un manejador de IO abierto al que se escribirá
• Nothing: se debe escribir en una ruta temporal

Si el cuerpo retorna normalmente, una ruta que está abierta se cerrará al completarse; un argumento de manejador de IO se deja abierto pero se vacía antes de retornar. Si el argumento es nothing, entonces se abre una ruta temporal para escritura y se cierra al completarse, y la ruta se devuelve desde arg_write. En todos los demás casos, se devuelve el propio arg. Este es un patrón útil ya que puedes devolver consistentemente lo que se escribió, ya sea que se haya pasado un argumento o no.

Si hay un error durante la evaluación del cuerpo, una ruta que se abrió con arg_write para escritura será eliminada, ya sea que se pase como una cadena o como una ruta temporal generada cuando arg es nothing.

Nota: al abrir un archivo, ArgTools pasará lock = false a la llamada de archivo open(...). Por lo tanto, el objeto devuelto por esta función no debe ser utilizado desde múltiples hilos. Esta restricción puede ser relajada en el futuro, lo que no rompería ningún código funcional.

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

La función arg_isdir toma arg, que debe ser la ruta a un directorio existente (se genera un error de lo contrario) y pasa esa ruta a f, devolviendo finalmente el resultado de f(arg). Esta es definitivamente la herramienta menos útil ofrecida por ArgTools y existe principalmente por simetría con arg_mkdir y para proporcionar mensajes de error consistentes.

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

La función arg_mkdir toma arg que debe ser uno de:

• una ruta a un directorio vacío ya existente,
• una ruta no existente que puede ser creada como un directorio, o
• nothing, en cuyo caso se crea un directorio temporal.

En todos los casos, se devuelve la ruta al directorio. Si ocurre un error durante f(arg), el directorio se devuelve a su estado original: si ya existía pero estaba vacío, se vaciará; si no existía, se eliminará.

arg_readers(arg :: AbstractString, [ type = ArgRead ]) do arg::Function
    ## configuración previa a la prueba ##
    @arg_test arg begin
        arg :: ArgRead
        ## prueba usando `arg` ##
    end
    ## limpieza posterior a la prueba ##
end

La función arg_readers toma una ruta a ser leída y un bloque do de un solo argumento, que se invoca una vez para cada tipo de lector de prueba que arg_read puede manejar. Si se proporciona el argumento opcional type, entonces el bloque do solo se invoca para los lectores que producen argumentos de ese tipo.

El arg pasado al bloque do no es el valor del argumento en sí, porque algunos de los tipos de argumentos de prueba necesitan ser inicializados y finalizados para cada caso de prueba. Considera un argumento de manejador de archivo abierto: una vez que lo has usado para una prueba, no puedes usarlo de nuevo; necesitas cerrarlo y abrir el archivo nuevamente para la siguiente prueba. Esta función arg puede convertirse en una instancia de ArgRead usando @arg_test arg begin ... end.

arg_writers([ type = ArgWrite ]) do path::String, arg::Function
    ## configuración previa a la prueba ##
    @arg_test arg begin
        arg :: ArgWrite
        ## prueba usando `arg` ##
    end
    ## limpieza posterior a la prueba ##
end

La función arg_writers toma un bloque do, que se invoca una vez para cada tipo de escritor de prueba que arg_write puede manejar con un path temporal (inexistente) y arg que puede convertirse en varios tipos de argumentos escribibles que escriben en path. Si se proporciona el argumento opcional type, entonces el bloque do solo se invoca para escritores que producen argumentos de ese tipo.

El arg pasado al bloque do no es el valor del argumento en sí, porque algunos de los tipos de argumentos de prueba necesitan ser inicializados y finalizados para cada caso de prueba. Considera un argumento de manejador de archivo abierto: una vez que lo has usado para una prueba, no puedes usarlo de nuevo; necesitas cerrarlo y abrir el archivo nuevamente para la siguiente prueba. Esta función arg puede convertirse en una instancia de ArgWrite usando @arg_test arg begin ... end.

También hay un método arg_writers que toma un nombre de ruta como arg_readers:

arg_writers(path::AbstractString, [ type = ArgWrite ]) do arg::Function
    ## configuración previa a la prueba ##
    @arg_test arg begin
        # aquí `arg :: ArgWrite`
        ## prueba usando `arg` ##
    end
    ## limpieza posterior a la prueba ##
end

Este método es útil si necesitas especificar path en lugar de usar un nombre de ruta generado por tempname(). Dado que path se pasa desde fuera de arg_writers, la ruta no es un argumento para el bloque do en esta forma.

@arg_test arg1 arg2 ... cuerpo

El macro @arg_test se utiliza para convertir las funciones arg proporcionadas por arg_readers y arg_writers en valores de argumento reales. Cuando escribes @arg_test arg cuerpo, es equivalente a arg(arg -> cuerpo).