Les fonctions

Une fonction est un bloc de code réutilisable qui accomplit une tâche précise. 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 dans Studio pour être utilisées dans vos scripts. Vous n'avez rien à ajouter dans 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 afin de les utiliser dans un script. Ceci est utile lorsque vous utilisez fréquemment du code 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.

Syntaxe

Les noms de fonctions sont terminés par un ensemble de parenthèses ouvertes et fermées  : 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 dont la fonction a besoin.
• { ... } 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 :

• Utilisez 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 dollar ($) n'importe où dans le nom.
• N'utilisez pas les mots réservés ou les noms des 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 :

<functionName><([parameter], [parameter], [...])>

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

Paramètres et arguments

De nombreuses fonctions doivent utiliser des données provenant du script. Vous pouvez faire ceci à l’aide de paramètres et d’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 posséder plusieurs paramètres. Chaque paramètre est séparé des autres par une virgule. Vous pouvez inclure un espace si vous le voulez, mais ce n'est pas obligatoire. Par exemple, la fonction logn(value, base) possède 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 transmis au paramètre value.

ASSIGN abVal = abs(-42)

Dans Studio, tous les paramètres sont obligatoires. Si une fonction est définie avec un paramètre, vous devez 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'achever correctement ou les résultats peuvent ne pas être exacts.

Si le nombre d'arguments transmis dans la fonction est trop élevé ou trop faible, 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 consignes suivantes pour formater les arguments :

• Si l'argument est numérique ou variable, il n'est pas nécessaire de le placer entre 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 fonction dateadd() exige trois paramètres, unit, date et value.

Unit définit la partie de la date que la fonction doit modifier, par exemple l'année ou le mois. Date est la date originale que vous voulez modifier. Et value indique de combien 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)

Comme unit est une chaîne alphanumérique, elle est formatée avec des guillemets simples. Dans cet exemple, date est une variable et n'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 parce qu'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 le reconvertir en objet 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 RETURNconsiste à 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 d’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 indices.

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éation de fonctions personnalisées

Vous pouvez créer des fonctions personnalisées lorsque vous avez du code que vous voulez 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 voulez 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 dans le même script. Si vous déboguez le snippet 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 snippets.

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 de fonctions doivent suivre les mêmes conventions de dénomination que les autres entités dans les scripts.

• Utilisez 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 dollar ($) n'importe où dans le nom.
• N'utilisez pas les mots réservés ou les noms des 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 par des virgules.

Le code qui compose la fonction se trouve entre les accolades. Le placement des accolades est flexible. Ils peuvent figurer sur la même ligne que le mot-clé et le nom de 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.

La fonction ne prend pas de chaînes, pas de 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 les fonctions, consultez la page Instructions de déclaration.

Aide au remplissage automatique pour les fonctions personnalisées

Vous pouvez ajouter une aide au remplissage automatique pour vos fonctions personnalisées. Il s'agit d’un texte qui s'affiche dans une infobulle lorsque vous commencez à taper le nom de la fonction dans la fenêtre Snippet editor. Cette aide n'apparaît qu’en cas d’appel de la fonction avec la notation par points.

Voir l'image

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

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

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

Si vous ajoutez l’aide 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.

Appel de fonctions dans un script

Lorsque vous voulez utiliser une fonction dans votre script, vous devez l'appeler. Il existe 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 utiliseriez 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.

Appel d’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 c'est le cas pour d'autres instructions dans un snippet. Le code dans la fonction indique au script ce qu'il doit faire.

Vous pouvez appeler n’importe quelle fonction comme une instruction. Si une fonction ne contient pas d’instruction RETURN, c'est la seule façon de l'appeler. En effet, l'instruction RETURN renvoie les données de la fonction dans le script. Lorsqu'il n'y a pas de RETURN, l'appel 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 :

<functionName><([parameter], [parameter], [...])>

L'exemple suivant montre que la fonction append() est appelée comme une 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)

Utilisation d’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 :

<functionName><([parameter], [parameter], [...])>

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

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

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

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

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