Notes préliminaires :

Dans la notation de la syntaxe des instructions, les crochets [ ] indiquent une partie optionnelle et les triples points ... signalent une partie répétitive.

Le texte en italiques surlignées décrit des limitations actuelles du convertisseur, sujettes à une nécessaire évolution.

* L'étoile signale les dispositions qui sont réservées aux générateurs à gestion globale. Leur présence dans le code d'un générateur à gestion locale génère une erreur en post-traitement de l'analyse de son code source.

Pour faciliter la comparaison, le présent document a une structure similaire au document de référence de HAML.

1. Fonctionnalités

1.1. Fonctionnalités générales

• Sous-ensemble structuré du HAML → simplification de la syntaxe
• Limitation aux fonctions cloisonnées pour les concepteurs de site → sécurité
• Ouverture possible pour les concepteurs de composants et les super-administrateurs → souplesse

1.2. Présentation

Le langage GAL est globalement un sous-ensemble du langage HAML.

Les ajouts concernent soit des simplifications d'écriture des formes les plus fréquentes (render), soit la déclaration des attributs des générateurs.

Les restrictions opérées visent soit une simplification de la syntaxe pour simplifier l'apprentissage et pour réduire les risques d'interprétation, soit une sécurisation du code par la non implémentation des fonctions potentiellement dangereuses. Elles peuvent aussi résulter d'un développement encore limité du compilateur ; dans ce cas, elles disparaitront sans doute dans une version ultérieure du compilateur.

Pour des raisons de sécurité, les concepteurs d'un site ne sont autorisés à écrire que des générateurs à gestion locale, donc obligatoirement écrits en GAL ; ils peuvent bien sûr utiliser les composants globaux. Si leurs besoins dépassent les limites du langage, ils devront faire appel à un super-administrateur qui soit adaptera un composant existant ou en écrira un nouveau, soit développera le générateur souhaité en gestion globale.

Le compilateur GAL ne vérifie pas intégralement si le code source est conforme à la syntaxe Ruby. Il se limite à vérifier juste ce qu'il est nécessaire pour garantir le cloisonnement des sites et la sécurité de l'application. Il peut donc laisser passer des erreurs Ruby qui seront détectées lors de l'exécution du fichier HAML produit.

Le compilateur GAL n'est pas encore terminé, mais le noyau réalisé permet l'écriture de la quasi-totalité des générateurs de site, hormis les gabarits, et donc d'en laisser la responsabilité aux concepteurs de site sans risque pour la sécurité des autres sites et celle de l'application.

2. Utilisation du langage

2.1. Classe Gal

Le convertisseur est réalisé sous la forme de la classe Ruby de nom Gal, intégrée dans le module GalHelper.

Le constructeur de cette classe prend deux paramètres facultatifs :

Gal.new(generator = nil, options = {})

• generator = référence sur un générateur (de type Generator, Fixnum ou String)
• options = liste d'options sur le contrôle du flux

Il est possible de définir ou de redéfinir le générateur de base d'un objet Gal par la méthode generator=.

Si aucun générateur n'est défini, la méthode source= permet d'initialiser un code source (de type String) à traiter.

Si le générateur est défini, le code source traité sera celui enregistré dans le fichier d'extension .gal dans le dossier des fichiers source du site ou dans celui des composants si le générateur est commun.

Les méthodes suivantes restituent les paramètres d'état :

• generator = référence du générateur associé (de type Generator)
• options = liste des paramètres d'appel du convertisseur
• source = code source (de type String)

Le contexte est aussi défini par plusieurs attributs ou méthodes du générateur : filename('gal'), updatable (vrai en gestion locale, faux en gestion globale)...

La conversion est effectuée par l'application de la méthode haml sur un objet de type Gal.

Cette méthode retourne le code HAML produit. Plusieurs autres méthodes permettent de récupérer d'autres résultats ou indicateurs :

• attributes : liste des attributs du générateur à modifier, avec leurs valeurs
• rules : liste des paramètres d'appel du générateur, avec les valeurs par défaut
• errors_count : nombre d'erreurs détectées par la conversion
• require_global_management : vrai si le code contient une instruction protégée, faux sinon

Il est enfin possible d'appeler en pré- ou en post-traitement la méthode write_error(type, message) qui génère une ligne d'erreur au format d'un commentaire HAML (-#) et qui augmente le compteur d'erreurs.

2.2. Options

Les options suivantes peuvent être positionnées lors de l'appel du constructeur de la classe Gal. Elles sont toutes du type Boolean.

• :verbose = génère en commentaires toutes les informations du convertisseur
• :comment = génère les lignes de commentaires
• :blank_lines génère les lignes blanches
• :source_lines = génère en commentaires une copie des lignes source

L'effet de ces options est modifiables par des commandes dans le code source.

2.3. Codage

Les fichiers source GAL sont supposés avoir des caractères codés au format international UTF-8.

Les fichiers HAML sont produits dans ce même format. Ils commencent par la ligne de déclaration de ce format :

-# coding: utf-8

2.4. Indentation et structure du code

L'indentation des lignes représente l'inclusion des différents blocs HTML ou des blocs de code Ruby.

L'indentation doit être respectée suivant cette logique. La seule exception concerne les commandes GAL.

Le pas d'indentation est fixée à 2 espaces.

L'indentation en entrée n'est pas testée. Elle est restituée en sortie.

3. Pein texte

3.1. Texte simple

Le texte est une suite de caractères qui forment en général l'essentiel du contenu sémantique de la page HTML vers la quelle il est transféré sans modification.

texte

Une ligne de texte ne doit pas commencer par l'un des caractères - = ~ ! & : / # . %

Du texte peut figurer seul sur une ligne ou suivre une balise HTML, un identifiant ou une classe. Il ne doit toutefois pas comporter d'interpolation de code par une séquence #{ }.

3.2. Caractère d'échappement \

La barre de fraction inversée \ permet de lever la limitation sur le premier caractère d'une ligne de texte.

\texte

La caractère \ est copié vers la sortie HAML, mais il ne sera pas intégré dans la page HTML finale.

4. Éléments HTML

Les balises structurent le code des pages HTML qui seront finalement servies aux internautes.

4.1. Nom d'une balise HTML : %

%tag[#ident][.class1[.class2[...]]]{attr1: value1[, attr2: value2[, ...]]} [Text]

La code d'une balise est composé d'une ou de plusieurs lettres. Leur casse est indifférente.

Une balise peut être immédiatement suivie, dans cet ordre, d'un identifiant, d'une ou de plusieurs classes, d'une liste d'attributs, puis d'une espace et d'un texte HTML. La syntaxe HAML interdit que la présence d'un texte sur la même ligne soit suivi d'un bloc indenté sur les lignes suivantes (règle non testée par le compilateur GAL).

4.2. Attributs

Les attributs HTML précisent la balise qui précède, en début de ligne, ou implicitement la balise div si seuls un identifiant ou une ou plusieurs classes sont mentionnés.

La liste d'attributs est placée entre accolades :

%tag[#ident][.class1[.class2[...]]]{attr1: value1[, attr2: value2[, ...]]}  [Text]

La liste peut contenir un ou plusieurs couples nom: valeur.

Des espaces peuvent être insérés à volonté entre chaque élément de la liste, sauf entre un nom et le caractère deux-points : qui le suit.

NB : Si, au moment de la génération de la page HTML, une valeur a la valeur false ou nil, alors l'attribut correspondant ne sera pas généré.

{#.#. =4.3. :Identifiant et classes : # et .#}

Identifiant

Un identifiant sert à repérer un bloc du code HTML généré pour l'application des styles CSS ou du code Javascript. Un identifiant doit être unique sur une page HTML (non testé par le compilateur GAL qui n'en voit qu'une partie).

Un identifiant peut être placé soit après une balise HTML pour la qualifier, soit en début de ligne. Dans ce cas, une balise HTML div sera générée pour le rattachement de l'identifiant.

#ident[.class1[.class2[...]]]{attr1: value1[, attr2: value2[, ...]]} [Text]

Une balise ne peut avoir qu'un seul identifiant.

Un identifiant peut être suivi, dans cet ordre, d'une ou de plusieurs classes, d'une liste d'attributs, puis d'une espace et d'un texte HTML. La syntaxe HAML interdit que la présence d'un texte sur la même ligne soit suivi d'un bloc indenté sur les lignes suivantes (règle non testée par le compilateur GAL).

Classe

Une classe sert à repérer un bloc du code HTML généré pour l'application des styles CSS ou du code Javascript. Une classe peut être réutilisée sur une page HTML.

Une classe peut être placée soit après une balise HTML ou un identifiant, soit en début de ligne. Dans ce cas, une balise HTML div sera générée pour le rattachement de la classe.

.class1[.class2[...]]{attr1: value1[, attr2: value2[, ...]]} [Text]

Une ou plusieurs autres classes peuvent être définies sur la même ligne, pour le même bloc div généré.

Elles peuvent être suivies, dans cet ordre, d'une liste d'attributs, puis d'une espace et d'un texte HTML. La syntaxe HAML interdit que la présence d'un texte sur la même ligne soit suivi d'un bloc indenté sur les lignes suivantes (règle non testée par le compilateur GAL).

4.3. Suppression des espaces : > et <

%tag[#ident][.class1[.class2[...]]]< [Text]
%tag[#ident][.class1[.class2[...]]]> [Text]

Si le code d'une balise, d'un identifiant ou d'une classe est immédiatement suivi du caractère inférieur <, les données internes à cette balise sont placées immédiatement après son code HTML généré, sans saut de ligne. Ce signe est inutile si du texte figure sur la même ligne, car dans ce cas aucun saut de ligne n'est normalement généré.

Si le code d'une balise, d'un identifiant ou d'une classe est immédiatement suivi du caractère supérieur >, le code généré par cette balise est placé immédiatement après le code précédemment généré.

Il est possible de combiner les deux codes sous l'une des deux formes %tag<> ou %tag>< .

5. Doctype : !!!

La déclaration du type du document HTML se place comme première instruction utile.

!!! doctype

Seule la valeur 5 pour le doctype est utilisable en mode de gestion locale d'un générateur. Elle correspond à la syntaxe HTML 5.

!!! 5 produit <!DOCTYPE html> sur la page HTML finalement générée.

* Les autres valeurs du doctype ne sont possibles qu'en mode de gestion globale. La liste des valeurs possibles figure sur la documentation de référence HAML.

6. Commentaires

Les commentaires sont écrites par les programmeurs pour faciliter la compréhension et la maintenance du code.

Les lignes vides ou blanches peuvent être considérées comme des commentaires.

Cette instruction destinée au programmeur n'est pas restituée dans le fichier produit, sauf dans le cas des commentaires conditionnels.

6.1. Commantaires HTML

/ [comments]

Cette forme génère des commentaires HTML <!-- Comments --> dans la page finale générée.

Un bloc indenté sous cette ligne n'est valide que si aucun texte de commentaire ne figure sur la ligne. Tout le bloc est également considéré comme un commentaire.

Des commentaires conditionnels pour le navigateur Internet Explorer de Microsoft sont générés par la séquence /[ I E ], sans les espaces à l'intérieur qui ne sont placés là que pour que cette page se génère correctement... Les commentaires conditionnels sont à placer dans un bloc indenté sous cette ligne.

6.2. Commantaires HAML

-# [comments]

Le troisième caractère ne doit pas être un point d'exclamation '!' ou une barre de fraction '/', respectivement réservés aux commandes et aux méta-attributs GAL.

Un bloc indenté sous cette ligne est valide, même si un texte de commentaire figure sur la ligne. Tout le bloc est également considéré comme un commentaire.

7. Évaluation de code Ruby

7.1. Insertion Ruby : =

Rédaction ultérieure.

7.2. Exécution Ruby : -

Non encore réalisé

7.3. Interpolation Ruby

Rédaction ultérieure.

8. Filtres : :

Non encore réalisé

9. Extensions GAL

9.1. Appel d'un composant ou d'un partiel : =>

L'appel d'un composant commun permet de produire une partie de la page qui sera affichée aux internautes par un élément de la bibliothèque commune du projet. L'appel d'un partiel du site est similaire avec un partiel propre au site.

C'est une instruction tellement importante pour les générateurs de site qu'une syntaxe spéciale (non HAML) lui est réservée.

=> [component:] name[[[, param1: value1], :param2], ...]
=> partial: name[[[, param1: value1], :param2], ...]

Le nom du composant ou du partiel est donné par une valeur, en général une mot (ex. : p1007_text), mais ce peut être aussi un symbole (ex. : :p1007_text) ou une chaine de caractères (ex. : 'p1007_text').

Le nom du composant ou du partiel peut être suivi par un ou plusieurs couples (paramètre, valeur). Si la valeur est omise (syntaxe : :param2), la valeur est supposée à true, cas très fréquent pour les options d'un composant.

Le nom d'un paramètre doit être immédiatement suivi du caractère deux-points, sinon des espaces peuvent être intercalées entre chaque éléments de l'instruction.

Un changement de ligne est autorisé après une virgule à condition que l'indentation des lignes suites soit identique et supérieure à celle de la première ligne de l'instruction.

La valeur d'un paramètre est soit une constante numérique, booléenne ou chaine de caractères entre simples ou doubles apostrophes ( ' ou " ), soit une variable locale ou de classe (nom précédé d'une arobase @), en particulier l'un des paramètres d'appel définis par le méta-attribut rules.

{#.#. =9.2. :Commandes GAL : -#!#}

Les commandes contrôle le flux de la compilation ou celui de l'ajout de commentaires dans le fichier produit. Un commande a donc un effet pour les lignes source qui la suit.

Au début de l'analyse d'un fichier source, l'état du compilateur est en mode GAL et en affichage non verbeux (pas de recopie des commentaires).

-#! command [comment]

L'espace préalable au code de la commande est indifférent : il peut être absent, simple ou multiple.

La casse des lettres est indifférente.

L'ajout d'un commentaire après le code de la commande est autorisé.

Par exception aux règles régissant l'indentation des lignes, celle d'une ligne de commande est indifférente. Il est donc possible de l'écrire sans indentation pour la rendre plus visible.

Cette instruction destinée au compilateur GAL n'est pas restituée dans le fichier produit.

Liste des commandes

• Contrôle de la compilation
• -#! Ignore
  Les lignes suivantes sont à ignorer par le compilateur.
• -#! Continue
  La compilation reprend pour les lignes suivantes.
• -#! Stop
  La compilation est arrêtée.
• -#! HAML *
  Les lignes suivantes sont en HAML. Elles sont recopiées sans analyse.
• -#! GAL
  Les lignes suivantes sont en GAL. Elles sont normalement traitées par le compilateur.
• Contrôle d'affichage
• -#! Verbose
  Les lignes blanches et les commentaires sont recopiées ainsi que toutes les observations du compilateur.
• -#! Blank
  Les lignes blanches sont recopiées.
• -#! Comment
  Les commentaires sont recopiés.
• -#! Source
  Les lignes source sont recopiées en commentaires numérotés.
• -#! No [source]
  Les lignes source ne sont plus recopiées.

* : La commande HAML est réservée aux générateurs à gestion globale.

{#.#. =9.3. :Méta-attributs du générateur : -#/#}

Les méta-attributs permettent de contrôler ou de positionner les attributs du générateur.

Les méta-attributs doivent être placés en début du fichier source, avant la première instruction générée.

Cette instruction destinée au compilateur n'est pas restituée dans le fichier produit, à l'exception de l'attribut Rules (voir ci-dessous)

-#/ attribute: value

La casse des lettres du code d'un attribut est indifférente.

Un attribut à valeur unique ne peut être défini qu'une seule fois.

Un attribut à valeurs multiples peut être défini en plusieurs fois, les différentes valeurs sont alors regroupées. Le code de l'attribut peut être donné au singulier ou au pluriel.

Un attribut booléen est vrai si la valeur est true, yes ou oui dans la langue courante (casse des lettres indifférente). Il sera faux pour toute autre valeur.

Un attribut est indéfini (nil) si la valeur est absente.

Liste des méta-attributs

• Attributs à valeur texte unique
• -#/ name
  Le nom doit être celui du générateur.
• -#/ kind
  Type du générateur : space_view, work_view, layout, partial ou component.
• -#/ title
  Titre du générateur.
• -#/ layout
  Gabarit du générateur, parmi ceux du site ou les gabarits communs.
   
• Attributs à valeur booléenne unique
• -#/ updatable *
  Gestion locale (si true) par un concepteur du site ou globale (si false). Les valeurs local et global sont aussi acceptées.
  Le mode de gestion doit être celui du générateur.
• -#/ positionable
  Indicateur de positionnement graphique des œuvres sur un espace. Sauf pour les composants, sa valeur est calculée.
  Un avertissement est généré en commentaire si la valeur n'est pas celle celle du générateur de type autre que component.
• -#/ todo
  Indicateur de gestion À faire.
   
• Attributs à valeurs multiples
• -#/ tags
  Étiquettes de classement par catégories du générateur.
• -#/ rules *
  Paramètres d'appel du générateur, avec leurs valeurs par défaut et leurs descriptions. Uniquement pour les composants et pour les partiels.
• -#/ remarks
  Remarques de gestion.

* : Les attributs rules sont réservés aux générateurs à gestion globale, y compris pour les partiels.

Méta-attribut rules

Rédaction ultérieure.