Extend comment syntax in Khiops dictionaries

[marcboulle]

Description

Extension de la gestion des commentaires dans les dictionnaires Khiops

Contexte: gestion des commentaires dans la version actuelle (V10)

• les commentaires sont préfixés par '//'
• on peut mettre des commentaires a peu près partout
• pour chaque groupe de lignes de commentaire, on ne conserve que la première ligne de commentaire, les autres sont ignorées
• on garde les commentaires suivants, attachés aux entités du langage
  • dictionnaire: commentaire précédent le début de déclaration du dictionnaire
  • variable: commentaire de fin de déclaration d'une variable
• tous les autres commentaire sont tolérés, mais simplement ignorés
  • n'étant rattaché à aucune entité du langage, ils ne sont pas gérés
  • quand on ré-écrit un dictionnaire, ils ont disparus

Besoins d'extension:

• pour une ligne de déclaration de variable trop longue, on préfère parfois mettre un commentaire avant la déclaration d'une variable
• besoins potentiels de commentaires multi-lignes
• besoin de commenter tout ou partie d'un dictionnaire, sans perdre les spécifications après lecture/écriture d'un fichier dictionnaire

Analyse du besoin

Problèmes à résoudre

• on ne devrait pas prendre en compte le caractère fin de ligne '\n' comme un jeton du langage
• chaque commentaire doit être rattaché à une entité du langage (dictionnaire ou variable)
  • c'est le cas quand on programme un dictionnaire depuis pykhiops depuis python plutôt que depuis un éditeur de texte
• dans la partie textuelle, comment savoir si un commentaire est rattaché à la variable suivante ou à la variable suivante?
• faible intérêt si rapport coût/bénéfice peu favorable

Piste de solution

• un test rapide avec l'analyseur lexical (KWClex.lex) a montré que l'on pouvait facilement distinguer les commentaires lignes
  • ^[ \t\n\f\r\v]*\/\/ pour un commentaire ligne n'ayant que des espaces entre le début de ligne et le début de commentaire
  • \/\/ pour un commentaire précédé d'autres jetons lexicaux
• on peut donc distinguer deux type de commentaires, sans explicitement utiliser '\n' comme un jeton du langage

Spécification

A chaque entité d'un langage, on associe:

• un libellé court
  • label actuel dans pykhiops, pour les entités Dictionary, Variable et VariableBlock
  • dans un fichier kdic, en fin de déclaration, sur la même ligne
  • dans la GUI: champ Label dans la liste des caractéristique d'un dictionnaire, obtenus via "Inspect dictionary"
• un commentaire multi-lignes
  • comments à ajouter dans pykhiops, pour les entités ayant déjà un label
    • commentaire multi-lignes
  • dans un fichier kdic, liste des commentaire lignes précédent une déclaration d'entité
    • les commentaires parsés sont trimés (comme les labels)
    • on peut ainsi avoir plusieurs lignes devant une variable, ou devant un dictionnaire
    • mais les lignes blanches restent ignorées
    • quand on ré-écrit un dictionnaire, on écrit les commentaires lignes
      • en tout début de ligne pour les commentaires associés au Dictionary
      • au niveau de la déclaration de type pour les commentaire de Variable ou VariableBlock
  • dans la GUI, on ne voit pas les commentaires

Compatibilité ascendante

• le label d'un dictionnaire (actuellement avant la déclaration) devient un comments
• cela ne semble pas grave

Avantages

• extension significative avec des commentaires multi-lignes
• faible coût de développement
• on peut faire une documentation plus pédagogique, compatible avec le parser de kdic
• on garde l'essentiel des commentaires, auparavant ignorés
• on peut commenter plusieurs variables
  • effet de bord: leur commentaire sera associé à la variable suivante (pas grave)
  • seul problème: si on commente les dernières variables d'un dictionnaire, elles seront perdues, car il n'y pas de variable suivante
  • introduire un champ de type end_comments, internal_comments, private_comments associé au Dictionary, pour la fin des déclarations: préférence (pour pykhiops) pour la terminologie internal_comments

Context

• Khiops version: V11