Fonctions

Une fonction est un bloc de code réutilisable qui accomplit une certaine tâche. Chaque fois que vous avez besoin de cette tâche, vous pouvez utiliser la fonction dans votre script. Cela vous évite de perdre du temps et de l’énergie à ajouter du code pour cette tâche dans votre script chaque fois que vous en avez besoin. Cela permet également de garder vos scripts plus « propres » et moins encombrés en réduisant la quantité de code dans le script.

Les fonctions peuvent :

Prendre des données dans le script, les manipuler d’une manière ou d’une autre, puis renvoyer les résultats au script.
Effectuer une action ou une série d’actions et transmettre les données résultantes au script.

Certaines fonctions sont intégrées à Studio pour être utilisées dans vos scripts. Il n’est pas nécessaire d’ajouter quoi que ce soit à votre script pour utiliser une fonction intégrée. Lorsque vous voulez en utiliser un, vous pouvez simplement l’appeler.

Vous pouvez également créer vos propres fonctions personnalisées à utiliser dans un script. Ceci est utile lorsque vous avez du code que vous utilisez fréquemment dans votre script. Plutôt que de l’ajouter à votre script chaque fois que vous en avez besoin, vous pouvez créer une fonction qui contient le code. Ensuite, lorsque vous avez besoin de ce code, vous pouvez appeler la fonction.

Vous pouvez télécharger et importer des exemples d’utilisation des fonctions dans Studio.

Syntaxe

Les noms de fonctions sont terminés par une parenthèse ouverte et une parenthèse fermée : functionName().

Tout texte entre parenthèses est un paramètre, qui définit les données transmises entre la fonction et le script : functionName(param1,param2).

Pour créer une fonction personnalisée, utilisez la syntaxe suivante :

FUNCTION <name><([parameter], [...])> <{ ... [RETURN [data]]}>

Dans cette syntaxe :

FUNCTION est le mot-clé obligatoire qui commence toutes les instructions de fonctions personnalisées.
<name> est le nom de la fonction.
([<parameter>] [...]) définit tous les paramètres nécessaires à la fonction.
{ ... } contient le code de la fonction.
[RETURN <data>] est l’instruction à inclure pour transmettre les données de la fonction au script principal.

Vous pouvez donner n’importe quel nom à vos fonctions personnalisées, à condition de respecter les règles suivantes :

Utiliser des caractères alphanumériques (a-z, A-Z, 0-9).
Le premier caractère du nom doit être une lettre.
Utilisez le caractère de soulignement ( _ ) et le signe du dollar ( $ ) partout dans le nom.
N’utilisez pas de mots réservés ou de noms de fonctions intégrées.

La syntaxe d’une instruction RETURN est la suivante :

RETURN ou RETURN <var>

Lorsque vous appelez une fonction, utilisez l’une des syntaxes suivantes :

<{<varName>.<functionName><([parameter], [parameter], [...])>}>

Paramètres et arguments

De nombreuses fonctions doivent utiliser des données provenant du script. Pour ce faire, vous pouvez utiliser des paramètres et des arguments.

Les paramètres sont définis lors de la création d’une fonction. Un paramètre est un nom de variable qui apparaît entre les parenthèses qui suivent le nom de la fonction. Une fonction peut avoir plus d’un paramètre. Chaque paramètre est séparé par une virgule. Vous pouvez inclure un espace si vous le souhaitez, mais ce n’est pas obligatoire. Par exemple, la fonction logn(value, base) a deux paramètres, value et base.

Les données spécifiques que le script transmet à la fonction via les paramètres sont appelées arguments. L’exemple suivant illustre l’utilisation de la fonction intégrée abs(value) dans un script. Dans cet exemple, -42 est l’argument qui est passé dans le paramètre value.

ASSIGN abVal = abs(-42)

Dans Studio, tous les paramètres sont requis. Si une fonction est définie avec un paramètre, vous devez passer (transmettre) une valeur lorsque vous appelez la fonction. Le nombre d’arguments transmis à la fonction doit correspondre au nombre de paramètres définis.

Le script ne vérifie pas que les arguments sont du bon type ou du bon format. Toutefois, si l’argument n’est pas du type ou du format attendu par la fonction, celle-ci peut ne pas s’exécuter correctement ou les résultats peuvent ne pas être exacts.

Si trop ou pas assez d’arguments sont transmis dans la fonction, cela provoque une erreur de compilation lors de l’exécution du script. Cela peut se produire pour les fonctions intégrées et les fonctions personnalisées.

Formatage des arguments

Lorsque vous appelez une fonction qui requiert des paramètres, vous devez inclure les arguments que vous transmettez à la fonction. Suivez les lignes directrices suivantes pour formater les arguments :

Si l’argument est numérique ou variable, il n’est pas nécessaire de l’entourer de guillemets simples ou doubles.
Si l’argument est une variable, il n’est pas nécessaire de l’entourer d’accolades.
Si l’argument est alphanumérique et n’est pas une variable, il doit être placé entre guillemets simples ou doubles.

Par exemple, la dateadd() fonction nécessite trois paramètres, unit, date et value.

Unit définit la partie de la date que la fonction doit modifier, telle que l’année ou le mois. Date est la date originale que vous souhaitez modifier. Et value est le nombre de fois que vous voulez que la fonction augmente l’unité spécifiée de la date d’origine. L’exemple suivant montre comment chaque partie est formatée :

ASSIGN NewDateYearNumeric = dateadd('year', MyDateTime, 1)

unit est une chaîne alphanumérique et est donc formaté avec des guillemets simples. date dans cet exemple est une variable, il n’y a donc pas de guillemets. Si vous transmettez une date sous forme de chaîne, des guillemets seront nécessaires. La value n’est pas formatée, car elle est numérique.

Instructions RETURN

Une instruction RETURN met fin à une fonction et redonne le contrôle au script. Elle peut également transmettre des données au script.

Les instructions RETURN ne peuvent transmettre des données au script que sous la forme d’une variable ou d’un tableau. Elles ne peuvent pas transmettre plusieurs valeurs, sauf si ces valeurs font partie d’un tableau ou d’un objet. Elles ne peuvent pas transmettre d’objets, à moins que les objets ne soient d’abord convertis en JSON. Si nécessaire, vous pouvez les reconvertir en objets dans le script.

La syntaxe d’une instruction RETURN est la suivante :

RETURN ou RETURN <var>

Toutes les fonctions intégrées qui renvoient une valeur au script contiennent une instruction RETURN. Dans les fonctions personnalisées que vous créez, les instructions RETURN sont facultatives. S’il n’y a pas d’instruction RETURN, la fonction ne peut pas transmettre de valeurs au script. La seule façon d’utiliser une fonction qui n’a pas d’instruction RETURN est de l’appeler comme une instruction.

Si vous incluez une instruction RETURN dans une fonction, elle doit être la dernière ligne de la fonction.

Visibilité variable

Par défaut, toutes les valeurs de la fonction sont disponibles et utilisables uniquement à l’intérieur de la fonction. Lorsque la fonction se termine, toutes les valeurs de la fonction sont perdues. Si la fonction contient une instruction RETURN qui transmet une valeur de variable au script, seules les valeurs transmises par l’instruction RETURN sont disponibles en dehors de la fonction.

Si vous incluez dans une fonction personnalisée des variables qui existent dans le script principal, ces variables ont une portée globale. Cela signifie que ces valeurs sont disponibles en dehors de la fonction sans utiliser une instruction RETURN. De même, si vous déclarez une variable au sein de la fonction comme étant globale, sa valeur est disponible dans le script principal. Ce comportement est similaire à celui observé pour les sous-scripts.

Lorsque vous utilisez une fonction dans une expression ou comme valeur d’une variable, elle suit le comportement par défaut. Toutefois, si vous appelez une fonction en tant qu’instruction, toutes les valeurs de la fonction ont une portée globale et peuvent être utilisées en dehors de la fonction. Pour les fonctions sans RETURN, c’est la seule façon de les utiliser.

Créer des fonctions personnalisées

Vous pouvez créer des fonctions personnalisées lorsque vous avez du code que vous souhaitez pouvoir utiliser à plusieurs endroits dans votre script. Une fonction personnalisée n’est disponible que dans le script où vous l’avez créée. Si vous souhaitez utiliser une fonction personnalisée dans un autre script, vous devez copier le code de définition de la fonction dans ce script.

Vous pouvez créer une fonction dans une action Snippet de votre script, puis l’appeler à partir d’autres actions Snippet du même script. Si vous déboguez l’extrait de code contenant la définition de la fonction, il est inclus dans le débogage. Cependant, la fonction ne sera pas incluse lorsque vous déboguerez les autres extraits.

La syntaxe pour déclarer une fonction personnalisée est la suivante :

FUNCTION <name><([parameter], [...])> <{ ... [RETURN [data]]}>

FUNCTION est un mot-clé qui indique au script que ce qui suit est une fonction personnalisée. Les noms des fonctions doivent respecter les mêmes règles de dénomination que les autres entités des scripts :

Utiliser des caractères alphanumériques (a-z, A-Z, 0-9).
Le premier caractère du nom doit être une lettre.
Utilisez le caractère de soulignement ( _ ) et le signe du dollar ( $ ) partout dans le nom.
N’utilisez pas de mots réservés ou de noms de fonctions intégrées.

Si la fonction nécessite des paramètres, ceux-ci doivent être placés entre les parenthèses à la fin du nom de la fonction. S’il n’y a pas de paramètres, les parenthèses peuvent être laissées vides. Séparez les paramètres multiples par des virgules.

Le code qui compose la fonction se trouve entre les accolades. L’emplacement des accolades est flexible. Elles peuvent être placées sur la même ligne que le mot-clé et le nom FUNCTION ou sur des lignes séparées. Par exemple, les deux définitions de fonction suivantes sont valables :

FUNCTION myFunction() { ASSIGN var = "value" }

FUNCTION myFunction() 
{ 
	ASSIGN var = "value"
}

Si la fonction comprend une instruction RETURN, celle-ci doit être la dernière instruction de la fonction avant l’accolade fermante.

Elle n’accepte pas de chaîne sans guillemets, mais suppose une variable s’il n’y a pas de guillemets et s’il ne s’agit pas d’un nombre ou d’un booléen.

Pour en savoir plus sur la création de fonctions, consultez la page Instructions.

Aide relative au remplissage automatique pour les fonctions personnalisées

Vous pouvez ajouter une aide relative au remplissage automatique pour vos fonctions personnalisées. Il s’agit du texte de l’infobulle qui apparaît lorsque vous commencez à taper le nom de la fonction dans la fenêtre Snippet editor. Cette aide n’apparaît que si vous appelez la fonction avec la notation par points.

Vous pouvez utiliser ces infobulles pour donner des informations utiles sur la fonction. Par exemple, vous pouvez l’utiliser pour définir les paramètres de la fonction.

Pour ajouter une aide relative au remplissage automatique, ajoutez un commentaire sur la même ligne que l’instruction de la fonction. Par exemple, pour créer l’infobulle illustrée dans l’image précédente, votre instruction de fonction ressemblerait à ceci :

FUNCTION MyAppend(a,b) // My function to append the text
{
   RETURN "{a}{b}"
}

Si vous ajoutez l’aide relative au remplissage automatique à une fonction, les accolades contenant le code de la fonction doivent être placées sur une ligne distincte de la définition de la fonction. Le script considère que tout le texte situé après les deux barres obliques fait partie du commentaire. Si les accolades sont sur la même ligne, le script les inclut dans le commentaire.

Appeler des fonctions dans un script

Lorsque vous souhaitez utiliser une fonction dans votre script, vous devez l’appeler. Il y a trois façons d’appeler une fonction. Toutes les options ne conviennent pas à toutes les fonctions. Les options disponibles pour une fonction donnée dépendent du fait que la fonction renvoie ou non une valeur. Vous pouvez appeler une fonction :

Seule comme une instruction. Cette option s’applique à toutes les fonctions.
À l’endroit où vous utilisez une variable ou une expression. Cette option ne fonctionne qu’avec les fonctions qui renvoient une valeur.
Avec une variable utilisant la notation par points. Cette option ne fonctionne qu’avec les fonctions qui renvoient une valeur.

Appeler une fonction en tant qu’instruction

Une instruction est une ligne de code contenant un mot-clé de commande qui indique au script ce qu’il doit faire. Vous pouvez utiliser une fonction comme une instruction. Dans ce cas, vous n’avez pas besoin d’un mot-clé de commande spécial, comme pour d’autres instructions dans un extrait. Le code de la fonction indique au script ce qu’il doit faire.

Vous pouvez appeler n’importe quelle fonction en tant qu’instruction. Si une fonction ne contient pas d’instruction RETURN, c’est la seule façon de l’appeler. En effet, une instruction RETURN transmet les données de la fonction au script. Lorsqu’il n’y a pas de RETURN, le fait d’être appelée en tant qu’instruction est le seul moyen pour le script d’accéder aux données de la fonction.

La syntaxe pour appeler des fonctions en tant qu’instruction est la suivante :

L’exemple suivant montre que la fonction append() est appelée en tant qu’instruction:

IF TEST = 1
{
  ASSIGN originalString = "My name"
  ASSIGN originalString2 = "Whose pajamas are these? "
  ASSIGN appendWithEscape = $"They're the cat's pajamas."			
}
originalString.append(" is Inigo Montoya.")
originalString2.append(AppendWithEscape)

Utiliser une fonction à la place d’une variable

Lorsqu’une fonction renvoie une valeur, vous pouvez l’utiliser partout où vous utiliseriez une variable ou une expression. Le script peut utiliser la valeur retournée par la fonction comme s’il s’agissait de la valeur de la variable ou du résultat de l’expression.

Les syntaxes permettant d’utiliser une fonction à la place d’une variable sont les suivantes :

<{<varName>.<functionName><([parameter], [parameter], [...])>}>

Si vous souhaitez que le résultat de la fonction soit affecté à une variable, vous pouvez appeler la fonction dans le cadre d’une instruction ASSIGN. Par exemple, ASSIGN var = otherVar.function(). Toutefois, il existe un cas où cela ne fonctionne pas, à savoir l’appel d’une fonction membre de la fonction GetRESTproxy().

L’exemple suivant montre comment utiliser une fonction qui renvoie une valeur. Voici l’exemple de fonction :

FUNCTION replaceCharacters(string)
{
	ASSIGN adjustedString = string.replace("&", "and")
	RETURN adjustedString
}

Cette fonction remplace le caractère esperluette (&) par le mot and. Dans l’exemple suivant, la fonction replaceCharacters() est utilisée à la place d’une variable dans la chaîne de valeur de la variable stringRes. Lorsque ce code est exécuté, la valeur de stringRes est mise à jour en My favorite animals are dogs and cats.

ASSIGN testString = "dogs & cats"
ASSIGN stringRes = "My favorite animals are {replaceCharacters(testString)}."

Utiliser une fonction avec la notation par points

Lorsque les fonctions renvoient une valeur, vous pouvez les utiliser avec des variables en utilisant la notation par points. Cela permet d’attacher la fonction à la variable, comme ceci : variable.function(). Lorsque vous appelez une fonction de cette manière, la valeur de la variable est transmise à la fonction. Cette option ne fonctionne qu’avec les fonctions qui renvoient une valeur.

Syntaxe d’utilisation d’une fonction avec la notation par points :

<{<varName>.<functionName><([parameter], [parameter], [...])>}>

L’exemple suivant illustre cette approche. Voici la fonction :

FUNCTION MyAppend(a,b)
{
   RETURN "{a}{b}"
}

Il s’agit d’une boucle FOR qui utilise la fonction MyAppend avec la variable ph :

FOR i=1 TO 9
{
   ph = "{ph.MyAppend(i)}"
}

Le résultat de la boucle FOR est : ph="123456789".

Lorsque vous appelez une fonction en utilisant la notation par points, la valeur de la variable à laquelle elle est attachée est transmise à la fonction en tant qu’argument du premier paramètre. Dans l’exemple précédent, la valeur initiale de ph est transmise à la fonction MyAppend() en tant qu’argument du paramètre a. C’est pourquoi l’appel de la fonction ne comporte qu’un seul argument lorsque la définition de la fonction a deux paramètres. La valeur initiale de i est transmise à la fonction en tant qu’argument du paramètre b.

L’avantage d’appeler les fonctions avec la notation par points est qu’elle vous permet d’ajouter une infobulle d’aide pour la fonction.