ArgTools

ArgRead = Union{AbstractString, AbstractCmd, IO}

Le type ArgRead est une union des types que la fonction arg_read sait comment convertir en poignées IO lisibles. Voir arg_read pour plus de détails.

ArgWrite = Union{AbstractString, AbstractCmd, IO}

Le type ArgWrite est une union des types que la fonction arg_write sait comment convertir en des poignées IO écrites, sauf pour Nothing que arg_write gère en générant un fichier temporaire. Voir arg_write pour plus de détails.

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

La fonction arg_read accepte un argument arg qui peut être l'un de ceux-ci :

• AbstractString : un chemin de fichier à ouvrir pour la lecture
• AbstractCmd : une commande à exécuter, lisant à partir de sa sortie standard
• IO : un handle IO ouvert à lire

Que le corps retourne normalement ou lance une erreur, un chemin qui est ouvert sera fermé avant de retourner de arg_read et un handle IO sera vidé mais pas fermé avant de retourner de arg_read.

Remarque : lors de l'ouverture d'un fichier, ArgTools passera lock = false à l'appel de fichier open(...). Par conséquent, l'objet retourné par cette fonction ne doit pas être utilisé depuis plusieurs threads. Cette restriction peut être assouplie à l'avenir, ce qui ne casserait aucun code fonctionnel.

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

La fonction arg_read accepte un argument arg qui peut être l'un de ceux-ci :

• AbstractString : un chemin de fichier à ouvrir pour l'écriture
• AbstractCmd : une commande à exécuter, écrivant dans son entrée standard
• IO : un handle IO ouvert à écrire
• Nothing : un chemin temporaire doit être écrit

Si le corps retourne normalement, un chemin qui est ouvert sera fermé à l'achèvement ; un argument de handle IO est laissé ouvert mais vidé avant le retour. Si l'argument est nothing, alors un chemin temporaire est ouvert pour l'écriture et fermé à l'achèvement, et le chemin est retourné par arg_write. Dans tous les autres cas, arg lui-même est retourné. C'est un modèle utile puisque vous pouvez retourner de manière cohérente ce qui a été écrit, que ce soit un argument passé ou non.

S'il y a une erreur lors de l'évaluation du corps, un chemin qui est ouvert par arg_write pour l'écriture sera supprimé, qu'il soit passé en tant que chaîne ou qu'il s'agisse d'un chemin temporaire généré lorsque arg est nothing.

Remarque : lors de l'ouverture d'un fichier, ArgTools passera lock = false à l'appel de fichier open(...). Par conséquent, l'objet retourné par cette fonction ne doit pas être utilisé depuis plusieurs threads. Cette restriction pourrait être assouplie à l'avenir, ce qui ne casserait aucun code fonctionnel.

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

La fonction arg_isdir prend arg qui doit être le chemin vers un répertoire existant (une erreur est levée sinon) et passe ce chemin à f, retournant finalement le résultat de f(arg). C'est définitivement l'outil le moins utile proposé par ArgTools et existe principalement pour la symétrie avec arg_mkdir et pour fournir des messages d'erreur cohérents.

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

La fonction arg_mkdir prend arg qui doit être l'un des éléments suivants :

• un chemin vers un répertoire vide déjà existant,
• un chemin inexistant qui peut être créé en tant que répertoire, ou
• nothing dans ce cas un répertoire temporaire est créé.

Dans tous les cas, le chemin vers le répertoire est retourné. Si une erreur se produit lors de f(arg), le répertoire est retourné à son état d'origine : s'il existait déjà mais était vide, il sera vidé ; s'il n'existait pas, il sera supprimé.

arg_readers(arg :: AbstractString, [ type = ArgRead ]) do arg::Function
    ## configuration avant le test ##
    @arg_test arg begin
        arg :: ArgRead
        ## test utilisant `arg` ##
    end
    ## nettoyage après le test ##
end

La fonction arg_readers prend un chemin à lire et un bloc do à un argument, qui est invoqué une fois pour chaque type de lecteur de test que arg_read peut gérer. Si l'argument optionnel type est donné, alors le bloc do n'est invoqué que pour les lecteurs qui produisent des arguments de ce type.

L'arg passé au bloc do n'est pas la valeur de l'argument elle-même, car certains types d'arguments de test doivent être initialisés et finalisés pour chaque cas de test. Considérez un argument de gestionnaire de fichier ouvert : une fois que vous l'avez utilisé pour un test, vous ne pouvez pas l'utiliser à nouveau ; vous devez le fermer et ouvrir le fichier à nouveau pour le test suivant. Cette fonction arg peut être convertie en une instance ArgRead en utilisant @arg_test arg begin ... end.

arg_writers([ type = ArgWrite ]) do path::String, arg::Function
    ## configuration avant le test ##
    @arg_test arg begin
        arg :: ArgWrite
        ## test utilisant `arg` ##
    end
    ## nettoyage après le test ##
end

La fonction arg_writers prend un bloc do, qui est invoqué une fois pour chaque type d'écrivain de test que arg_write peut gérer avec un path temporaire (inexistant) et arg qui peut être converti en divers types d'arguments écrits qui écrivent dans path. Si l'argument optionnel type est donné, alors le bloc do n'est invoqué que pour les écrivains qui produisent des arguments de ce type.

L'arg passé au bloc do n'est pas la valeur de l'argument elle-même, car certains types d'arguments de test doivent être initialisés et finalisés pour chaque cas de test. Considérez un argument de gestionnaire de fichier ouvert : une fois que vous l'avez utilisé pour un test, vous ne pouvez pas l'utiliser à nouveau ; vous devez le fermer et ouvrir le fichier à nouveau pour le test suivant. Cette fonction arg peut être convertie en une instance ArgWrite en utilisant @arg_test arg begin ... end.

Il existe également une méthode arg_writers qui prend un nom de chemin comme arg_readers :

arg_writers(path::AbstractString, [ type = ArgWrite ]) do arg::Function
    ## configuration avant le test ##
    @arg_test arg begin
        # ici `arg :: ArgWrite`
        ## test utilisant `arg` ##
    end
    ## nettoyage après le test ##
end

Cette méthode est utile si vous devez spécifier path au lieu d'utiliser un nom de chemin généré par tempname(). Puisque path est passé de l'extérieur de arg_writers, le chemin n'est pas un argument du bloc do dans cette forme.

@arg_test arg1 arg2 ... corps

Le macro @arg_test est utilisé pour convertir les fonctions arg fournies par arg_readers et arg_writers en valeurs d'argument réelles. Lorsque vous écrivez @arg_test arg corps, cela équivaut à arg(arg -> corps).