Guide de référence des macros du langage de génération par template

Les macros peuvent être utilisées pour exprimer la logique, et pour boucler sur des collections d'objets. Chaque mot clé de macro doit être précédé d'un caractère "." (point) et doit être le premier caractère, autre qu'un espace, sur une ligne. Prenez soin de respecter la syntaxe des macros en termes de passage à la ligne.

Vous pouvez définir une macro dans un template, ou dans une commande.

Il existe trois types de macros :

Les macros simples sont les macros qui ne sont constituées que d'une seule ligne.
Les macros de bloc se composent d'un mot clé de début et d'un mot clé de fin délimitant un bloc auquel la macro est appliquée. Leur structure se présente comme suit :

.nom-macro [(paramètres)]
	bloc-entrée
.endnom-macro [(fin)]

Les macros de boucle sont utilisées pour l'itération. A chaque itération, une nouvelle portée est créée. Le template spécifié dans le bloc est converti simultanément conformément à la portée d'itération.

.foreach_nom-macro [(paramètres[,en-tête[,fin]])]
	complex-template
.next[(séparateur)]

Remarque :

Les paramètres de macro peuvent être délimités par des guillemets. Les délimiteurs sont requis lorsque la valeur du paramètre inclut des virgules, des accolades et des espaces de début ou de fin. La séquence d'échappement pour les guillemets au sein d'un paramètre est \".

Pour pouvez utiliser les macros suivantes :

Macros conditionnelles et macro de boucle/itératives :
- Macro .if
- Macro .foreach_item – permet l'itération sur les collections d'objets
- Macro .foreach_line – permet l'itération sur les lignes
- Macro .foreach_part – permet l'itération sur les parties
- Macro .break– interrompt la boucle
Macros d'affectation - définit une variable locale ou un type valeur ainsi que des attributs volatiles :
- Macros .set_object et .set_value
- Macro .unset
Macros de résultats et de signalisation d'erreurs :
- Macro .log
- Macros .error et .warning
Macros de commandes - uniquement disponibles dans le contexte de l'exécution d'une commande générique :
- Macro .vbscript - incorpore du code VB script dans un template
- Macro .execute_vbscript - lance l'exécutions de scripts VB
- Macro .execute_command - lance des exécutables
- Macro .abort_command - stoppe l'exécution de commandes
- Macro .change_dir - change de répertoire
- Macro .create_path - crée un chemin spécifié
Macros de mise en forme :
- Macros .lowercase et .uppercase
- Macros .convert_code et .convert_name – convertit des codes en noms
Macros de manipulation de chaînes :
- Macro .replace
- Macro .delete
- Macro .unique
- Macro .block - ajoute un en-tête et une fin pour un bloc de texte
Macros diverses :
- Macro .comment et macro .// - insère un commentaire dans un template
- Macro .collection - renvoie une collection d'objets en fonction de la portée et de la condition spécifiées
- Macro .object - renvoie un objet en fonction de la portée et de la condition spécifiées
- Macro .bool - évalue une condition
- Macro .set_interactive_mode – spécifie si l'exécution du langage de génération par template peut comporter des interactions avec l'utilisateur

Macro .abort_command
Cette macro stoppe l'exécution de la commande. Elle est disponible pour exécuter des commandes de génération uniquement, et peut être combinée aux macros standard du langage de génération par template lorsque vous définissez des commandes.
Macro .block
La macro .block est utilisée pour ajouter un en-tête et/ou une fin à son contenu lorsque ce dernier n'est pas vide.
Macro .bool
Cette macro renvoie 'true' or 'false' en fonction de la valeur de la condition spécifiée.
Macro .break
Cette macro peut être utilisé pour sortir des boucles .foreach.
Macro .change_dir
Cette macro change le répertoire courant. Elle est disponible pour exécuter des commandes de génération uniquement, et peut être combinée aux macros standard du langage de génération par template lorsque vous définissez des commandes.
Macro .collection
Cette macro renvoie une collection d'objets basée sur la portée et la conditions spécifiées. Les collections sont représentées comme concaténation de l'OID terminé par un point virgule.
Macro .comment et macro .//
La macro .comment et la macro .// sont utiles pour insérer des commentaires dans un template. Les lignes qui commencent par .// ou par .comment sont ignorées lors de la génération.
Macros .convert_code et .convert_name
Ces deux macros utilisent des tables de conversion pour convertir le code d'un objet en nom, et réciproquement. Lorsque la table ne contient aucune occurrence, c'est le code ou nom d'entrée qui est renvoyé.
Macro .create_path
Cette macro créé un chemin spécifié si ce dernier n'existe pas.
Macro .delete
Supprime toutes les instances de la chaîne chaîne-suppr dans bloc-entrée-suppr.
Macros .error et .warning
Ces macros sont utilisées pour émettre des messages d'erreur et des avertissements lors de la conversion. Les erreurs interrompent la génération, tandis que les avertissements sont émis à titre d'information uniquement et peuvent être déclenchés si une incohérence est détectée lorsque vous appliquez le template sur un objet particulier. Les messages sont affichés à la fois dans le volet Aperçu et dans la fenêtre Résultats.
Macro .execute_command
Cette macro est utilisée pour lancer des exécutables sous forme de processus séparés. Elle est disponible pour exécuter des commandes de génération uniquement, et peut être combinée aux macros standard du langage de génération par template lorsque vous définissez des commandes.
Macro .execute_vbscript
Cette macro est utilisée pour exécuter un script VB spécifié dans un fichier séparé.
Macro .foreach_item
Cette macro est utilisée pour l'itération dans les collections d'objet :
Macro .foreach_line
La macro foreach_line est une macro simple qui procède à l'itération sur les lignes du template de saisie spécifié comme premier argument pour la macro. Le template spécifié dans le bloc est converti pour chaque ligne de l'entrée. Cette macro crée une nouvelle portée avec la variable locale CurrentLine. Cette dernière est définie dans le bloc comme étant la i-ème ligne du template en entrée dans l'itération i.
Macro .foreach_part
Cette macro procède à l'itération sur la partie du template en entrée spécifiée comme premier argument de la macro. Le template spécifié dans le bloc est converti pour chaque partie de l'entrée.
Macro .if
La macro if est utilisée pour la génération conditionnelle, et a la syntaxe suivante :
Macro .log
Cette macro consigne un message dans l'onglet Génération de la fenêtre Résultats, située dans la partie inférieure de la fenêtre principale. Elle est disponible pour exécuter des commandes de génération uniquement, et peut être combinée aux macros standard du langage de génération par template lorsque vous définissez des commandes.
Macros .lowercase et .uppercase
La macro .lowercase transforme en minuscules toutes les lettres majuscules d'un bloc de texte.
Macro .object
Cette macro renvoie une collection d'objets en fonction de la portée et de la condition spécifiées. Les références d'objet sont représentées sous forme d'OID ; par exemple : E40D4254-DA4A-4FB6-AEF6-3E7B41A41AD1.
Macro .replace
La macro .replace remplace toutes les occurrences d'une chaîne par une autre chaîne dans un bloc de texte.
Macro .set_interactive_mode
Cette macro permet de décider si l'exécution du GTL doit s'effectuer avec des interactions de l'utilisateur ou non.
Macrod .set_object et .set_value
Ces macros sont utilisées pour définir une variable locale de type objet (objet local) ou un type de valeur.
Macro .unique
L'objet de la macro unique est de définir un bloc dans lequel l'unicité de chaque ligne du texte généré est garantie. Cette macro peut être utile pour calculer les importations, inclusions, typedefs ou de déclarations anticipées dans des langages tels que Java, C++ ou C#.
Macro .unset
Permet d'annuler la définition de variables locales et d'attributs volatiles définis à l'aide des macros .set_value et .set_object.
Macro .vbscript
La macro vbscript est utilisée pour incorporer du code VB script dans un template. Il s'agit d'une macro de bloc.

Sujet parent : Personnalisation de la génération à l'aide du langage de génération par template