Wikifunctions:Comment créer des implémentations

This page is a translated version of the page Wikifunctions:How to create implementations and the translation is 100% complete.

Cette page fournit un guide plus détaillé pour créer des implémentations, au delà de l’explication générale de Wikifunctions:Introduction.

Types d'implémentations

Dans Wikifunctions, une implémentation peut prendre la forme d'un code ou d'une composition. Une implémentation sous forme de code exprime directement la logique de la fonction dans tout langage de programmation disponible (actuellement, Python3 ou JavaScript). Cela sert principalement quand le comportement de la fonction ne peut pas se construire facilement à partir des Wikifunctions existantes, ou quand un contrôle précis du traitement des données est nécessaire.

Une implémentation sous forme de composition, en revanche, définit la fonction entièrement par une combinaison d'autres fonctions existantes, sans écrire de code. Les compositions sont plus faciles à comprendre, à réutiliser et à traduire automatiquement dans d'autres langues, mais elles dépendent des blocs de construction appropriés déjà disponibles et sont souvent moins performantes. En général, commencez par vérifier si votre objectif peut être atteint avec des compositions; si ce n'est pas le cas, ou si la performance ou la logique du détail sont importantes, choisissez plutôt une mise en œuvre sous forme de code.

Un troisième type d'implémentation existe : built-ins. Il est exécuté par le code interne du système et n'est pas modifiable. En général chaque fonction prédéfinie aura déjà une implémentation interne. Si c'est le cas, vous verrez un message disant "Ceci est une mise en œuvre intégrée dans le logiciel cœur et n’est pas visible ici." lorsque vous afficherez la page d'implémentation.

Développement pratique dirigé par les tests

Le TDD (Test-Driven Development) est un principe où l'on décrit le logiciel en partant de l'écriture des tests avant celle du code actuel. Les tests sont juste une manière de comprendre ce que votre fonction doit réaliser en fournissant des exemples et la façon dont ils doivent fonctionner.

Dans Wikifunctions, l'écriture des tests offre d'abord des bénéfices significatifs. Si vous travaillez sur une implémentation, vous pouvez exécuter votre code avec les tests existants pour vérifier qu'il se comporte comme attendu. Cela facilite la détection des erreurs très tôt, bien avant même que de publier votre implémentation. Les tests sont aussi un moyen puissant de décrire la fonction dont vous avez besoin. En décrivant ces tests, vous indiquez clairement le comportement attendu, et la communauté peut poursuivre en aidant à l'implémentation ou à la création d'implementations alternatives.

Imaginez que vous voulez mettre en œuvre une fonction qui combine deux chaînes avec un espace entre elles. Un test de base pour cela pourrait être :

join_with_space( "Hello", "world" ) => "Hello world"

Une fois le comportement de base défini, il est important de penser aux cas aux limites—ce sont des situations où les entrées nécessitent un comportement particulier.

Par exemple, que faire si votre première chaîne se termine par un espace, ou que votre deuxième chaîne commence avec un espace ? La fonction doit-elle conserver tous les espaces existants et en ajouter un autre ? ou doit-elle renvoyer un résultat espacé effectivement avec un seul espace entre les mots ? Selon vos besoins, vous devez écrire un test pour ce type de situation. Par exemple, un test pour ce cas aux limites pourrait être l'un des deux suivants — mais pas les deux simultanément ! :

join_with_space( "Hello   ",  "  world") => "Hello world"

ou ...

join_with_space( "Hello   ",  "  world") => "Hello      world"

Assurez-vous que tous les cas spéciaux possibles sont couverts par vos tests et dès que vous les avez rassemblés, vérifiez qu'ils sont tous conectés à la Fonction en les sélectionnant et en cliquant sur Connect.

Implémentations du code

Lorsque vous créez une implementation en code, l'interface utilisateur de Wikifunctions vous configure l'éditeur de code qui correspond au langage actif pour la mise en valeur de la syntaxe et la validation. Lorsque la fonction à implémenter et le langage de programmation sont sélectionnés, cet éditeur est configuré avec le modèle correct de fonction : ne supprimez pas, ni ne modifiez pas cela ! Conservez votre code à l'intérieur de la signature de cette fonction : si vous avez besoin de fonctions annexes, il suffit de les déclarer simplement à l'intérieur de la déclaration de la fonction de niveau principal.

Utiliser des types d'entrées dans votre code

Les types Wikifunctions String (Z6) et Boolean (Z40) peuvent être utilisés comme s'ils étaient des types natifs en JavaScript et en Python3. Par exemple, une entrée chaîne de caractères peut être concatenée ou un booléan peut être directement utilisé dans une expression logique. Pour utiliser d'autres types dans vos implémentations de code, vous devrez regarder le type plus précisément, déterminer s'il a une conversion en un équivalent natif, et le traiter en conséquence.

Supposons par exemple que l'on veuille écrire du code Python qui traite une entrée de type Gregorian calendar date (Z20420). Sur la page de ce type, nous cherchons les convertisseurs de type en code et en choisissons un pour Python. Le convertisseur Python converter from Gregorian calendar date (Z20424) est appliqué à notre entrée date avant le code, donc en cherchant le type natif nous voyons que notre entrée est un dict Python et l'implémentation nous donne les clés attendues :

return {
    'K1': year,
    'K2': month,
    'K3': day
}

Quand un type n'a pas de convertisseur, vous devez accéder à ses composants directement à l'aide de ses clés. Par exemple, supposons que votre fonction Z30000 a une entrée Z30000K1 de type Monolingual text (Z11). Ce type a deux clés : Z11K1 pour le langage (lui-même un objet de type Natural language (Z60)), et Z11K2 pour la valeur de la chaîne. De même, l'objet language a une clé Z60K1 pour le code de langue. Donc, pour obtenir une chaîne avec le code de la langue et le texte, vous pouvez écrire :

function Z30000( Z30000K1 ) {
	// par exemple "fr: placez votre texte en français ici"
	return Z30000K1.Z11K1.Z60K1 + ": " + Z30000K1.Z11K2;
}

Pour une référence rapide des conversions de type, voir la table de conversion du type par défaut.

Renvoyer les bonnes sorties

De la même façon que vous traitez les entrées, les sorties doivent correspondre au type spécifié dans la définition de la fonction. Certains peuvent être traités comme des types natifs, de sorte que toute sortie de chaîne sera convertie en un objet Wikifunctions String (Z6) et tout booléen natif renvoyé par votre implémentation sera converti en un objet wikifunctions Boolean (Z40) .

Ces types qui disposent de convertisseurs de type à partir du code appliquent la fonction appropriée à la sortie, afin de construire le type requis. Suivant l'exemple de Gregorian calendar date (Z20420), le Python converter to Gregorian calendar date (Z20443) transformera la sortie de implémentation – dicté par les clés K1, K2 et K3 – en sa représentation ZObject correcte.

Pour les types qui n'ont pas de convertisseur de code, vous pouvez construire soigneusement et renvoyer les objets en sortie. Par exemple, si notre fonction Z30000 prend deux entrées de chaîne : le code de langue et un texte, et doit renvoyer un objet Monolingual text (Z11). Vous pouvez faire cela en Python en utilisant le constructeur ZObject :

def Z30000(Z30000K1, Z30000K2):
    lang_object = ZObject(
        {"Z1K1": "Z9", "Z9K1": "Z60"},
        Z60K1 = Z30000K1
    )
    return ZObject(
        {"Z1K1": "Z9", "Z9K1": "Z11"},
        Z11K1 = lang_object,
        Z11K2 = Z30000K2
    )

Ou en JavaScript :

function Z30000( Z30000K1, Z30000K2 ) {
  const langObject = new ZObject(
    new Map( [ [ "Z60K1", Z30000K1 ] ] ),
    { "Z1K1": "Z9", "Z9K1": "Z60" }
  );

  const monolingualKeys = new Map( [
    [ "Z11K1", langObject ],
    [ "Z11K2", Z30000K2 ]
  ] );
  return new ZObject(
    monolingualKeys,
    { "Z1K1": "Z9", "Z9K1": "Z11" }
  );
}

Vous trouverez des informations complémentaires sur la classe ZObject et d'autres constructeurs utiles dans Wikifunctions:Execution_targets#Custom_and_non-built-in_type_conversion.

Code Python

Dans cette section nous donnons ci-dessous un exemple concret de la façon de créer une implémentation sous la forme de code Python. Supposons que nous voulons créer une implémentation pour une fonction qui combine deux chaînes d'entrée en mettant un espace entre-elles et qui renvoie le résultat. Supposons que le ZID de cette fonction est Z30000.

L’implémentation est définie en utilisant le ZID de la fonction. Il en va de même pour les arguments de la fonction. Donc, dans le cas de la fonction Z300000 avec ses deux arguments, le modèle de la fonction devrait ressembler à :

def Z30000(Z30000K1, Z30000K2):

Comme nous l'avons décrit précédemment, nous savons que les arguments (Z30000K1 et Z30000K2) sont des chaînes, donc nous pouvons les traiter aussi simplement que nous utilisons les chaînées natives en Python. De plus, la fonction doit renvoyer une chaîne. Pour notre exemple, nous renvoyons simplement les deux arguments concatenés avec un espace entre eux deux :

def Z30000(Z30000K1, Z30000K2):
    return Z30000K1 + " " + Z30000K2

Comme il s’agit de Python, n’oubliez pas d’indenter cette ligne.

Si vous avez suivi notre conseil pour pratiquer le TDD vous disposez déjà d'un ensemble de tests dont vous savez qu'ils fonctionnent. Si c'est la cas, tout en construisant votre immplémentation vous pouvez cliquer sur la flèche circulaire du panneau Tests pour voir si votre implémentation les vérifie tous.

Rappelez-vous que le temps d’exécution n'a pas d'état. Ne supposez pas que les valeurs sont des variables globales ou statiques. Si vous avez d’autres questions sur ce que vous pouvez et ne pouvez pas faire en Python, demandez à Wikifunctions:Python implementations.

Code JavaScript

Nous donnons ci-dessous un exemple concret de la façon de créer une implémentation sous la forme de code JavaScript. Supposons que nous voulons créer une implémentation pour une fonction qui combine deux chaînes d'entrée en mettant un espace entre-elles et qui renvoie le résultat. Supposons que le ZID de cette fonction est Z30000.

L’implémentation est définie en utilisant le ZID de la fonction. Il en va de même pour les arguments de la fonction. Donc, dans le cas de la fonction Z30000 avec ses deux arguments, le modèle de la fonction devrait ressembler à :

function Z30000( Z30000K1, Z30000K2 ) {

}

Nous savons que les arguments (Z30000K1 et Z30000K2) sont des chaînes, donc nous pouvons les traiter comme des chaînées natives en JavaScript. De plus, la fonction doit renvoyer une chaîne. Pour compléter notre fonction, vous pouvez ensuite ajouter une ligne qui concatène les chaînes d'entrée, comme ceci :

function Z30000( Z30000K1, Z30000K2 ) {
  return Z30000K1 + " " + Z30000K2;
}

Si vous avez des tests comme cela a été recommandé dans la section TDD ci-dessus, cliquez sur la flèche circulaire du panneau Tests pour voir si votre implémentation les vérifie tous.

Rappelez-vous que le runtime n'a pas d'état. Ne présumez pas des valeurs des variables globales ou statiques. Si vous avez d'autres questions sur ce que vous pouvez ou ne pouvez pas faire en JavaScript, posez-les sur Wikifunctions:JavaScript implementations.

Composition

Nous donnons ci-dessous un exemple concret de la façon de créer une implémentation sous la forme de composition. Supposons que nous voulons créer une implémentation pour une fonction qui combine deux chaînes d'entrée en mettant un espace entre-elles et qui renvoie le résultat. Supposons que le ZID de cette fonction est Z30000.

Il est généralement bon de réfléchir d'abord à la façon de combiner les fonctions existantes afin de créer la sortie souhaitée. Parfois, cela peut être trivial, et vous pouvez simplement continuer en utilisant les fonctions de composition, mais dans de nombreux cas, cela vaut la peine de détailler la composition souhaitée.

Par exemple, pour la fonction donnée, nous pourrions utiliser la fonction existante join two strings (Z10000). Cette fonction prend deux chaînes de caractères et en fait une chaîne résultat. Mais nous devons ajouter un espace entre les deux. Donc nous concaténons d'abord un espace à la fin de la première chaîne, puis concatenons la deuxième chaîne au résultat de la première concatenation. Notre composition pourrait donc se noter ainsi :

join_strings( join_strings( Z30000K1, " " ), Z30000K2 )

Il existe différentes façons d'écrire une composition; notez que la même chose peut être réalisée avec :

join_strings( Z30000K1, join_strings( " ", Z30000K2 ) )

Une implémentation alternative pourrait également utiliser la fonction existante join two strings with separator (Z15175), de sorte que votre composition pourrait être :

join_with_separator( Z30000K1, Z30000K2, " " )

Comme vous pouvez le voir, il y a plusieurs façons d'y parvenir, alors prenez votre temps et explorez les fonctions existantes disponibles dans le Wikifunctions:Catalogue.

Essayons de créer le second exemple, join_strings(Z30000K1, join_strings(" ", Z30000K2)).

Pour créer ceci :

Commencez par ajouter une implémentation en cliquant sur le bouton + dans la table Implémentations de votre page Fonction.
Vérifier que l'option composition sous Implémentation est sélectionnée.
Cliquez sur l'icône › ou cliquez sur le lien Sélectionner une fonction pour développer les détails de la fonction.
Sous "fonction" chercher le nom de la fonction la plus extérieure que vous voulez utiliser, qui dans cet exemple est joindre deux chaînes. Ensuite, sélectionner la fonction souhaitée dans la liste déroulante.
Vous verrez deux nouveaux champs, un pour chacun des arguments nécessaires à la fonction sélectionnée.
Pour le premier argument, nous voulons sélectionner la première entrée de notre fonction :
1. À côté de première chaîne, cliquer sur le bouton ... et sélectionnez Référence d'argument.
2. Sous key id vous pouvez maintenant sélectionner la première chaîne de votre fonction dans la liste déroulante, qui contient toutes les entrées possibles.
Pour le deuxième argument, nous voulons utiliser le résultat d'un autre appel à joindre deux chaînes :
1. À côté de seconde chaîne, cliquer sur le bouton ... et sélectionner Appel de fonction.
2. Sous fonction, chercher et sélectionner la fonction que vous voulez appeler, et qui est encore joindre deux chaînes.
3. Pour cet appel de fonction interne, configurer la première chaîne en tapant simplement un espace blanc dans le champ de texte, et configurer la seconde chaîne comme vous l'avez fait pour l'étape 6 : changez-le en mettant le bouton ... à Référence d'argument, puis sélectionner le deuxième argument dans la zone déroulante.

Votre composition est maintenant terminée !

Vous pouvez développer ou replier les détails en utilisant les boutons avec des chevrons pour voir à quoi cela ressemble. Si vous disposez déjà des tests comme il vous l'a été indiqué dans la section TDD ci-dessus, cliquer sur la flèche circulaire du panneau Tests et vérifier si votre implementation passe les tests. Dès que votre composition réussit les tests, avancez et publiez-la.

Implémentation d'une composition Wikifunctions dans sa vue étendue

Implémentation d'une composition Wikifunctions dans sa vue repliée

Gestion des erreurs Wikifunctions

En tant que créateur de fonctions Wikifunctions, vous voudrez peut-être avertir l'utilisateur qui appelle votre fonction lorsque quelque chose ne va pas dans le code, ou lorsque les entrées ne correspondent pas à un certain critère. Par exemple, si votre fonction s'attend à ce qu'une chaîne de saisie contienne un nom, vous voudrez peut-être vérifier que le nom n'est pas vide et, si c'est le cas, afficher un message d'erreur compréhensible par la personne qui utilise votre fonction.

Pour cela, vous pouvez utiliser Wikifunctions.Error() de vos implémentations de code ou la fonction Throw Error (Z851) de vos compositions.

Dans cette section nous aprrendrons :

Comment générer des erreurs provenant à la fois par les implémentations du code et par les compositions,
comment écrire les tests pour les cas d'erreur, et
comment récupérer et gérer les erreurs causées par les fonctions que vous utilisez dans vos compositions.

Générer des erreurs à partir de l'implémentation du code

Lorsque vous écrivez du code, à la fois à partir de JavaScript ou de Python, vous pouvez utiliser Wikifunctions.Error() pour terminer l'exécution avec une erreur souhaitée.

Wikifunctions.Error() a deux paramètres :

Type d'erreur : une chaîne contenant le ZID du type d'erreur à renvoyer.
Arguments d'erreur : liste d'arguments de chaîne pour construire l'erreur.

Procédons par étape :

Type d'erreur

Un type d'erreur est un objet qui décrit une sorte d'erreur pouvant se produire dans le système. Il existe un certain nombre de types d'erreur intégrés mais vous pouvez aussi construire d'autres types d'erreur plus adaptés à votre cas d'utilisation. Si vous utilisez les erreurs, le mieux est de parcourir les types d'erreur disponibles que vous pouvez retrouver dans cette liste.

S'il n'y a pas d'erreurs qui puissent correspondre à votre cas, créez-en une nouvelle en allant sur la page de création et en sélectionnant type d'erreur dans le sélecteur de type. Ensuite, définissez les champs nécessaires :

Label – c'est le titre principal de l'erreur qui doit contenir un message bref mais suffisamment descriptif. Initialiser le libellé d'erreur dans la boîte About, à droite.

Keys – les clés contiennent des informations supplémentaires à propos de ce qui a causé l'erreur. Par exemple, si une entrée a un mauvais format, vous pouvez informer l'utilisateur en donnant son contenu au moment de l'erreur. Pour pouvoir utiliser les clés dans vos implémentations, elles doivent être des chaînes. Pour créer une clé, cliquer sur l'icône [+] sous keys, sélectionner String sous value type et ajouter un libellé suffisamment descriptif, par exemple entrée actuelle. Une fois toutes les clés nécessaires en votre possession, vous pouvez publier votre type d'erreur et conserver l'ID du nouvel objet créé.

Arguments des erreurs

Les arguments des erreurs correspondent aux clés du type d'erreur et doivent fournir des informations supplémentaires pour comprendre l'erreur. Les arguments d'erreur doivent toujours être des String.

Utiliser Wikifunctions.Error()

Supposons que vous voulez qu'une erreur soit signalée soit quand votre première, ou votre deuxième entrée est vide. Vous avez déjà créé le type d'erreur, et le ZID qui a été attribué était Z30005. Votre type d'erreur a deux clés textuelles :

Input key : contient la clé de l'entrée erronnée
Input value : contient la valeur actuelle de l'entrée erronnée

Pour générer une erreur dans votre implémentation JavaScript, essayez ceci :

function Z30000( Z30000K1, Z30000K2 ) {
  if ( trim( Z30000K1 ) === '' ) {
    // si la première entrée est vide, générer une erreur Z30005
    // avec deux arguments de chaîne : [ première clé d'entrée, première valeur d'entrée ]
    Wikifunctions.Error( 'Z30005', [ "Z30000K1", Z30000K1 ] )
  }
  if ( trim( Z30000K2 ) === '' ) {
    // si la seconde entrée est vide, générer une erreur Z30005
    // avec deux arguments chaîne : [ seconde clé d'entrée, seconde valeur d'entrée ]
    Wikifunctions.Error( 'Z30005', [ "Z30000K2", Z30000K2 ] )
  }
  return Z30000K1 + " " + Z30000K2;
}

Pour créer une erreur dans votre implémentation Python, essayez ceci :

def Z30000(Z30000K1, Z30000K2):
    if Z30000K1.strip() == "":
        # si l'entrée est vide, générer une erreur Z30005
        # avec deux arguments chaîne : [ première clé d'entrée, première valeur d'entrée ]
        Wikifunctions.Error("Z30005", ["Z30000K1", Z30000K1])

    if Z30000K2.strip() == "":
        # si la deuxième entrée est vide, générer l'erreur Z30005
        # avec deux arguments chaîne : [ première clé d'entrée, première valeur d'entrée ]
        Wikifunctions.Error("Z30005", ["Z30000K2", Z30000K2])

    return Z30000K1 + " " + Z30000K2

Rappelez-vous que l'appel à Wikifunctions.Error() met fin à l'exécution !

Générer des erreurs à partir des compositions

Si vous créez l'implémentation d'une composition, vous pouvez générer une erreur en appelant la fonction spéciale Throw Error (Z851).

Fonction Throw Error (Z851)

La fonction Throw Error (Z851) est similaire à la méthode Wikifunctions.Error() et prend deux arguments :

Error type – référence du type d'erreur que vous voulez signaler
Error parameters – liste d'arguments pour créer votre erreur (doivent aussi être des String) .

Utiliser Throw Error

Supposons que vous souhaitez modifier votre composition pour qu'elle vérifie d'abord que les arguments ne sont pas vides, et qu'elle génère une erreur si un argument est vide. Si aucun d'entre-eux est vide, la composition originale est exécutée, soit :

join_with_separator( Z30000K1, Z30000K2, " " )

Pour cela, vous devez créer des pattes conditionnelles à l'aide la fonction If (Z802). Elle doit être comprise ainsi :

Si le premier argument est vide, générer une erreur pour le premier argument
Sinon procéder au contrôle du second argument
Si le deuxième argument est vide, générer une erreur pour ce deuxième argument
Sinon, procéder avec la patte de succès et renvoyer les chaînes jointes avec le séparateur espace

Ou sous forme de pseudo code fonctionnel :

if (
    is_empty_string( Z30000K1 ),
    throw_error( Z30005, [ "Z30000K1", Z30000K1 ] ),
    if(
        is_empty_string( Z30000K2 ),
        throw_error( Z30005, [ "Z30000K2", Z30000K2 ] ),
        join_with_separator( Z30000K1, Z30000K2, " " )
    )
)

Créons cela progressivement :

Commencez par ajouter une implémentation en cliquant sur le bouton + dans la table Implémentations de votre page Fonction.
Vérifier que l'option composition sous Implémentation est sélectionnée.
Cliquez sur l'icône › ou cliquez sur le lien Sélectionner une fonction pour développer les détails de la fonction.
Sous "fonction" chercher et sélectionner la fonction la plus extérieure que vous souhaitez utiliser, qui dans ce cas est if.
Vérifier la validité du premier argument :
1. À côté de condition, cliquer sur le bouton ... et sélectionner Appel de fonction.
2. Sous fonction, chercher et sélectionner la fonction is empty string
3. À côté de entrée, cliquer sur le bouton ... et sélectionnez Référence d'argument.
4. Sous key id, sélectionner la première entrée (par exemple first string)
5. Vous pouvez désormais refermer l'appel de la fonction condition si vous le souhaitez, en cliquant sur le chevron vers le bas à côté de condition. Vous devriez voir quelque chose comme f(x) est une chaîne vide (→ première chaîne)
Générer une erreur si la condition est vraie :
1. À côté de then, cliquer sur le bouton ... et sélectionner Appel de fonction.
2. Sous fonction, chercher et sélectionner la fonction Throw Error
3. Sous error type, chercher et sélectionner votre type d'erreur (vous pouvez entrer directement l'ID de l'erreur si vous le connaissez, par exemple Z30005)
4. Sous paramètres d'erreur, ajouter deux éléments en cliquant sur le bouton +
5. Pour Item 1 (cassant la clé de l'argument), définir son type à String et écrire l'identificateur d'arguments (par exemple first input ou Z30000K1)
6. Pour Item 2 (valeur d'argument offensant), cliquer sur … à côté de Item 2 et sélectionner argument reference
7. Sous key id, sélectionner la première entrée (par exemple first string)
8. Vous pouvez maintenant refermer l'appel de la fonction then si vous le souhaitez, en cliquant sur le chevron vers le bas à côté de then. Vous devriez voir quelque chose comme f(x) Throw Error( l'entrée avait le format incorrect, liste typée (Objet, "première entrée", → première chaîne) )
Continuer le contrôle du second argument si le premier est correct :
1. À côté de else, cliquer sur le bouton ... et sélectionner Appel de fonction
2. Sous fonction, chercher et sélectionner la fonction if
3. Configurer condition pour vérifier la validité du deuxième argument en suivant le même processus que celui décrit à l'étape 5.
4. Configurez "then" pour générer une erreur pour le deuxième argument en suivant le même processus que celui décrit à l'étape 6.
Enfin définir la patte de succès :
1. À côté du else imbriqué, cliquer sur le bouton ... et sélectionner Appel de fonction
2. Sous fonction, chercher et sélectionner la fonction réussie, qui dans ce cas peut être joindre des chaînes avec séparateur
3. À côté de première chaîne, cliquer sur le bouton ... et initialisez-le à Référence d'argument puis sélectionner première chaîne.
4. À côté de la seconde chaîne, cliquer sur le bouton ... et définissez-le à référence d'argument, puis sélectionner "seconde chaîne"
5. Sous separator ajouter un espace dans le champ de texte

L'appel résultant de la fonction doit être similaire à :

Composition Wikifunctions utilisant la fonction Throw Error — Composition Wikifunctions utilisant la fonction *Throw Error*

Composition Wikifunctions utilisant la fonction Throw Error, dans sa vue repliée — Composition Wikifunctions utilisant la fonction *Throw Error*, dans sa vue repliée

Gestion des erreurs dans les compostions

Bien qu'il soit utile de permettre aux fonctions de générer les erreurs attendues, il est crucial de pouvoir gérer les erreurs dans vos compositions afin d'utiliser ces fonctions en toute sécurité.

Supposons que vous souhaitiez créer une nouvelle fonction nom complet d'une personne – nous nous référerons à elle avec le ZID Z30010. Cette fonction doit renvoyer le nom complet de la personne avec un prénom et un nom de famille, mais si l'un des deux champs est vide, elle doit renvoyer le texte Unknown à la place.

Vous pouvez créer une composition en utilisant notre fonction d'exemple Join two strings with a space ou Z30000 pour générer le nom. Si l'une des entrées est vide, vous savez que Z30000 va générer une erreur de type Z30005. En utilisant la fonction Try-Catch Function (Z850) comme enveloppe, vous pouvez essayer l'opération de jointure et intercepter une erreur possible pour simplement renvoyer Unknown chaque fois qu'elle se produit.

Fonction Try-Catch (Z850)

La fonction Try-Catch Function (Z850) est intégrée avec ZID Z850 et prend trois arguments :

Function call – appel de la fonction initiale à exécuter. Si tout se passe bien, la réponse est le résultat de cet appel.
Error type – type d'erreur à capturer dans le cas où il apparaît pendant l'exécution de l'appel à la première fonction.
Error handler – fonction à appeler dans le cas où l'erreur spécifiée ci-dessus est capturée pendant l'exécution de l'appel de la fonction initiale. Si la capture a lieu, la valeur renvoyée est le résultat du gestionnaire d'erreur.

Utiliser Try-Catch

Une fois toutes les fonctions de notre composition réunies, nous pouvons les assembler ainsi :

try_catch(
    join_with_space( Z30010K1, Z30010K2 ),
    Z30005,
    echo( "Unknown" )
)

Cela signifie que :

La fonction Join two strings with a space sera testée avec les deux entrées et, si tout va bien, la sortie de cette fonction sera renvoyée
Si l'une des entrées est vide, Join two strings with a space génère une erreur de type Z30005
Notre Try-Catch Function (Z850) détecte alors cette erreur et exécute la fonction Echo (Z801) et renvoie Unknown

Créons cela progressivement :

Commencez par ajouter une implémentation en cliquant sur le bouton + dans la table Implémentations de votre page Fonction.
Vérifier que l'option composition sous Implémentation est sélectionnée.
Cliquer sur l'icône › ou cliquer sur le lien Sélectionner une fonction pour développer les détails de la fonction.
Sous "fonction" chercher et sélectionner la fonction la plus extérieure à utiliser, qui dans ce cas est Try-Catch.
Définir l'appel à la fonction principale :
1. Dans le champ où la fonction Try-Catch est sélectionnée, à côté de la touche appel à la fonction, cliquer sur le bouton ... et sélectionner appel de fonction
2. Sous fonction, chercher et sélectionner la fonction join two strings with space
3. À côté de première chaîne, cliquer sur le bouton ... et sélectionner argument reference puis sélectionner l'argument de premier nom dans le menu déroulant.
4. À côté de la seconde chaîne, cliquer sur le bouton ... et sélectionner argument reference, puis sélectionner l'argument de second nom à partir du menu déroulant.
Sélectionner l'erreur à récupérer :
1. Sous error type, chercher et sélectionner bad string input – vous pouvez chercher directement à l'aide de son ZID Z30005
Déclarer l'appel de fonction du gestionnaire d'erreur :
1. À côté de error handler, cliquer sur le bouton ... et sélectionner Appel de fonction.
2. Sous fonction, chercher et sélectionner la fonction écho
3. Sous input et type, chercher et sélectionner le type String
4. Maintenant, sous entrée, saisir Inconnu dans le champ de texte

La fonction résultante doit être similaire à ceci :

Composition Wikifunctions utilisant la fonction Try-catch, en mode développé — Composition Wikifunctions utilisant la fonction *Try-catch*, en mode développé

Composition Wikifunctions utilisant la fonction Try-catch, en mode replié — Composition Wikifunctions utilisant la fonction *Try-catch*, en mode replié

Tester vos cas d'utilisation en échec

Comme annoncé dans la section ci-dessus à propos de la pratique du TDD, il est important de tester non seulement les pattes les plus habituelles, mais également les cas aux limites possibles. De manière équivalente, il est aussi important de tester le comportement en cas d'échec. Dans cette section nous allons vous donner les outils nécessaires pour vérifier que votre fonction échoue avec un ensemble donné de valeurs d'entrées, et que l'erreur générée est bien celle qui est attendue.

Pour faire cela, deux fonctions système supplémentaires vous sont nécessaires :

Tester le type d'erreur (Z852)

La fonction Is error type (Z852) est intégrée avec ZID Z852 et prend deux arguments :

Error – objet Error (Z5), qui peut être émis par un appel en échec. Une instance d'erreur possède un type et une valeur.
Error type – référence à un Error type (Z50) qui sera comparé au type de l'erreur passé dans le premier argument. S'ils correspondent, la fonction renvoie true.

Récupérer l'erreur générée par l'appel de fonction (Z853)

La fonction Get error thrown by function call (Z853) est intégrée avec ZID Z853 et prend un argument :

Function call – appel d'une fonction qui peut renvoyer soit une valeur de succès de n'importe quel type, soit générer une erreur.

Cette fonction renvoie un Typed pair (Z882) avec un Boolean (Z40) en première position et un Object (Z1) en seconde position :

Si l'appel de fonction s'exécute avec succès et donc ne produit donc aucune erreur, la paire retournée contiendra False en première position void dans la seconde.
Si l'appel de fonction génère une erreur, la paire retournée contiendra True en première position et l'erreur détectée, en seconde position.

Pour utiliser cette fonction dans vos compositions, il est possible que vous deviez utiliser les fonctions supplémentaires :

Tester les erreurs

Disons que notre fonction cible, Joindre deux chaînes avec un espace ou Z30000, génère une erreur de type Z30005 et nous voulons tester ce comportement. Pour ce faire, nous devons :

Génèrer un appel à une fonction en échec
Récupérer l'erreur en utilisant la fonction Get error thrown by function call (Z853)
Vérifier que l'erreur est du bon type avec Is error type (Z852)

Les tests ont deux champs :

Call – appel de fonction générant une sortie d'après les valeurs des entrées à tester. Cet appel renvoie une valeur.
Result validation – appel de fonction qui valide que la valeur renvoyée par l'appel ci-dessus est bien celle qui était attendue. Le premier argument ce cet appel de fonction sera automatiquement attribué comme étant la valeur renvoyée par le premier appel.

Pour les instructions pas à pas sur la manière de créer des tests, voir Wikifunctions:Introduction#Create_tests.

Dans notre exemple, nous pouvons le structurer de la manière suivante — mais elle n'est pas la seule !

L'appel qui va renvoyer un objet Error (Z5) :

error = get_second_element_of_typed_list(
    get_error_thrown_by(
        join_strings_by_whitespace( "", "not empty" )
    )
)

Et la validation du résultat, qui prend l'objet Error (Z5) comme son premier argument :

is_error_type( error, Z30005 )

Faisons cela progressivement :

Commencez par ajouter un test en cliquant sur le bouton + dans la table Tests de votre page Fonction. Les champs call et result validation ont déjà certaines fonctions prédéfinies, mais pour tester les erreurs, nous devons les modifier.
D'abord, définissons l'appel :
1. Sous call, cliquer sur le bouton du chevron › pour développer l'appel de fonction.
2. Sous function, modifier le champ et chercher puis sélectionner la fonction Get second element of a typed pair
3. Une fois sélectionné, à côté de Typed pair cliquer sur le bouton ... et sélectionner Appel de fonction.
4. Sous fonction, chercher et sélectionner la fonction Get error thrown by function call
5. À côté de Appel de fonction, cliquer sur le bouton ... et sélectionner Appel de fonction.
6. Sous fonction, chercher et sélectionner la fonction "Join two strings with a space" (ou par ZID Z30000)
7. Maintenant définir les entrées de sorte à provoquer une faute : au moins l'une d'entre-elles doit être vide.
8. Vous pouvez maintenant, si vous le souhaitez, replier votre appel en cliquant à nouveau sur le bouton avec le chevron vers le bas !
Puis, définir la validation du résultat :
1. Sous validation des résultats, cliquer sur le bouton › pour développer l'appel de fonction.
2. Sous fonction, modifier le champ et recherchez et sélectionnez la fonction Is error type
3. Maintenant on vous demandera de ne configurer que le deuxième argument. Sous error type chercher et sélectionner le type de votre erreur Z30005 .
Voila, c'est terminé ! Vous pouvez maintenant cliquer sur la flèche circulaire dans la boîte Implémentations et vous verrez les cases vertes cochées.

Si tout c'est bien passé vous pouvez maintenant sauvegarder votre test. Il doit ressembler à :

Tester un échec en utilisant les fonctions Get error et Is error type, en mode développé — Tester un échec en utilisant les fonctions *Get error* et *Is error type*, en mode développé

Tester un échec en utilisant les fonctions Get error et Is error type, en mode replié — Tester un échec en utilisant les fonctions *Get error* et *Is error type* en mode replié

Deboguer vos implémentations

Parfois, les choses peuvent mal se passer. Une fonction peut se comporter différemment de ce à quoi on s'attendait ou une valeur peut ne pas ressembler parfaitement. Parfois, les implémentations sont vraiment complexes et, parce qu'elles sont exécutées dans un environnement de type bac à sable, il peut sembler très difficile de les déboguer. Pour comprendre ce qui se passe à l'intérieur d'un appel de fonction, Wikifunctions fournit un petit ensemble d'outils de débogage.

Ces outils ne changent pas le résultat d'une fonction, mais ajoutent des informations supplémentaires aux métadonnées renvoyées, que vous pouvez observer après avoir exécuté la fonction. Vous pouvez utiliser Wikifunctions.Debug() dans vos implémentations de code ou la fonction Add debug log to function call (Z854) pour vos compositions.

Dans cette section, vous apprendrez :

Comment ajouter des messages de débogage à la fois à partir de l'implémentation du code et des compositions,
comment inspecter les métadonnées manuellement ou via l'interface utilisateur pour explorer ces journaux.

Deboguer vos implémentations de code

Lorsque vous écrivez du code, à la fois en JavaScript ou en Python3, vous pouvez utiliser Wikifunctions.Debug() pour ajouter un message à votre journal de debogue et continuer l'exécution.

Wikifunctions.Debug() a un paramètre, qui est généralement censé être une chaîne de caractères. Cependant, tout autre objet passé en tant que paramètre sera directement converti en chaîne.

Si nous voulons ajouter des journaux de débogue à nos implémentations de code pour notre fonction d'exemple Join two strings with a space, nous pouvons le faire, en JavaScript :

function Z30000( Z30000K1, Z30000K2 ) {
  if ( trim( Z30000K1 ) === '' ) {
    Wikifunctions.Debug( `first input is empty "${ Z30000K1 }"` );
    Wikifunctions.Error( 'Z30005', [ "Z30000K1", Z30000K1 ] )
  }
  if ( trim( Z30000K2 ) === '' ) {
    Wikifunctions.Debug( `second input is empty "${ Z30000K2 }"` );
    Wikifunctions.Error( 'Z30005', [ "Z30000K2", Z30000K2 ] )
  }

  Wikifunctions.Debug( "both inputs are fine" );
  return Z30000K1 + " " + Z30000K2;
}

Et la même chose dans votre implémentation en Python3 sera :

def Z30000(Z30000K1, Z30000K2):
    if Z30000K1.strip() == "":
        Wikifunctions.Debug( 'first input is empty "'+Z30000K1+'"' )
        Wikifunctions.Error("Z30005", ["Z30000K1", Z30000K1])

    if Z30000K2.strip() == "":
        Wikifunctions.Debug( 'second input is empty "'+Z30000K2+'"' )
        Wikifunctions.Error("Z30005", ["Z30000K2", Z30000K2])

    Wikifunctions.Debug( 'both inputs are fine' )
    return Z30000K1 + " " + Z30000K2

De cette façon, peu importe ce qui se passe, nous allons ajouter un message dans vos journaux de débogue :

Si l'appel à la fonction échoue lors de la vérification de la première ou de la deuxième entrée, le résultat de l'exécution sera un échec et il contiendra un journal informatif avec la branche qui n'a pas réussi.
Si l'appel de la fonction réussit — parce que les deux entrées sont valides — l'appel de la fonction renvoie la chaîne jointe, mais les métadonnées renvoyées contiendront aussi un journal de débogue.

Deboguer vos compositions

Pour soutenir les compositions de débogue, Wikifunctions fournit la fonction intégrée Add debug log to function call (Z854). Cette fonction vous permet d'attacher des messages de débogue à l'exécution de tout appel de fonction qui génère la sortie finale. Les journaux de débogue recueillis pendant l'évaluation sont renvoyés dans le cadre des métadonnées d'exécution, sous la clé executorDebugLogs.

Ajouter les journaux de débogue à l'appel de fonction (Z854)

La fonction Add debug log to function call (Z854) est intégrée avec ZID Z854 et prend deux arguments :

Function call – toute composition que vous voulez exécuter.
Debug log – un message textuel qui sera sauvegardé si l'appel de la fonction est évalué.

Lorsque l'appel de fonction enveloppe est exécuté, le message fourni est ajouté aux journaux d'exécution. Si cette appel de fonction n'est pas exécuté ou si son exécution ne fait pas partie de la sortie finale, son journal de débogage n'apparaîtra pas dans les métadonnées du résultat final.

Vous bénéficiez de cette intégration si vous voulez observer :

Branche exécutée d'une condition, ou
ordre d'évaluation d'une composition.

Utiliser l'ajout de journaux de débogue à l'appel de fonction

Supposons que vous souhaitez jouter des journaux de débogage à notre fonction d'exemple Join two strings with a space ou Z30000, de sorte que différents messages soient ajoutés aux différents résultats possibles. Vous pourriez utiliser notre débogage intégré comme ceci :

if (
    is_empty_string( Z30000K1 ),
    add_debug_log( throw_error( Z30005, ... ), 'failed on first input' )
    if(
        is_empty_string( Z30000K2 ),
        add_debug_log( throw_error( Z30005, ... ), 'failed on second input' ),
        add_debug_log(
            join_with_separator( Z30000K1, Z30000K2, " " ),
            'both inputs are ok!'
        )
    )
)

Ainsi,

lorsqu'elle est appelée avec une première entrée vide, la fonction renvoie une réponse d'échec, et les métadonnées contiennent une entrée executorDebugLogs avec une trace failed on first input.
Si l'appel est fait avec une seconde entrée qui est vide, il va échouer aussi mais le message journalisé sera failed on second input
Lorsque l'appel est effectué avec des entrées valides, la fonction renvoie une réponse de succès avec des métadonnées contenant both inputs are ok dans sa clé executorDebugLogs.

Voici à quoi ressemblerait cette composition :

Implémentation de composition en utilisant Add debug logs pour enregistrer toutes les pattes d'exécution possibles — Implémentation de composition en utilisant *Add debug logs* pour enregistrer toutes les pattes d'exécution possibles

Accès aux journaux de débogue de l'exécution

Que vos journaux d'exécution soient ajoutés via Wikifunctions.Debug() ou via la fonction intégrée Add debug log to function call (Z854) , ils sont renvoyés dans le cadre des métadonnées de réponse. Pour voir les journaux, une fois que vous avez exécuté votre fonction, cliquer sur le bouton Details qui apparaît en bas de la section Résultat.

L'erreur et les informations de debug apparaissent en haut de la boîte de dialogue des Détails.

Voici ce que vous obtenez lorsque vous exécutez la composition de notre exemple précédent avec des entrées valides et d'autres invalides :


Dialogue des métadonnées de la fonction pour une exécution avec succès : pas d'erreur affichée, mais affiche le journal d'exécution avec succès : "both inputs are ok!"	Dialogue des métadonnées de la fonction pour une exécution en échec : affichage des informations d'erreur, et du journal d'exécution supplémentaire pour la première branche en échec : "failed on first input"