4.4 Les modèles Calculate¶

Introduction¶

Linux, comme on le sait, stocke les réglages des applications dans des fichiers texte, la plupart dans le répertoire /etc, d'autres encore dans /var. Ces fichiers dits de configuration ont des formats différents : il est vrai que certains suivent la très simple logique « variable=valeur », mais on trouve également des configurations assez complexes écrites en XML ou similaires à du C.

La conception des configurations ainsi localisées paraît simple, mais c'est ce qui assure la stabilité exceptionnelle des logiciels sous Linux, car le système de fichiers seul s'en trouve impliqué.

La gestion des configurations varie en fonction de la distribution, qui proposent chacune son outil. Séduisante qu'elle puisse paraître, cette approche présente plusieurs inconvénients :

L'utilisateur prend l'habitude d'utiliser un gestionnaire de configuration particulier (et donc une distribution exclusivement).
Les réglages modifiables sont souvent limités par l'interface du gestionnaire.
Il devient problématique d'éditer les fichiers de configuration à la main, car le gestionnaire les réécrit à chaque fois que l'on y touche.

Généralités¶

Les Utilitaires Calculate 2 et, maintenant, 3 adoptent une approche aux modèles de configuration assez différente de la première version.

Les modèles sont normalement intégrés avec les fichiers de configuration existants. Tous les formats communs sont supportés.
L'intégration d'un modèle se fait en le convertissant en format XML. Il est à noter que le format du modèle peut différer de celui du fichier de configuration.
Le fichier modèle peut contenir une en-tête qui décrit les méthodes d'intégration.
Dans les dernières versions, les variables internes ont été renommées en fonction de leur type.

Modèles d'installation¶

Calculate permet de créer des modèles pour les appliquer par la suite, au lieu de modifier les fichiers de configuration directement.

Formats acceptés¶

Conformément à la méthode de stockage de données applicable, les fichiers modèles peuvent avoir de nombreux formats, à savoir :

apache, kde, bind, postfix, proftpd, samba, procmail, ldap, dovecot, xml_xfce, xml_xfcepanel, xml_gconf, xml_gconf_tree, compiz, plasma, squid, dhcp, openrc, qui sont les formats correspondant aux applications communément utilisées ;
bin, qui est le format des binaires ;
raw, ou format texte brut ;
patch, qui permet d'appliquer les expressions rationnelles (utilisant le type d'intégration patch).

Pour le format kde, les paramètres « - », « + » des éléments dans le champ de visibilité ne sont pas traitées.

Pour le format openrc, les noms de paramètres ne sont pas sensibles à la casse.

Identificateurs¶

A part les réglages des services sauvegardés en format original du logiciel, les fichiers modèles contiennent des éléments qui assurent la gestion des données. Par convention, on en distingue plusieurs types, décrits ci-dessous.

Variable

La variable est un élément texte du modèle qui, intégré dans le fichier de configuration correspondant, renvoie à une valeur.

Toute variable a un nom, une valeur et une visibilité :

Le nom peut être composé de chiffres et/ou de lettres.
La valeur est le texte substitué (créé par le logiciel).
La visibilité indique si la variable est utilisée globalement ou pour un modèle spécifique.

Les variables se subdivisent en variables de modèles et variables de fonctions.

Les variables de modèles sont globales, ce qui revient à dire que toute variable de ce type peut être utilisée par n'importe quel modèle. Par contre, sa valeur ne peut pas être modifiée dans le modèle.

Les variables de fonctions sont créées au sein d'un modèle ; c'est là aussi qu'on peut modifier leur valeur. Leur visibilité se limite au modèle courant.

Pour transférer la valeur d'une variable de fonctions d'un modèle à un autre, une pile LIFO est utilisée : la fonction push() y met la valeur prise dans le modèle courant pour que la fonction pop() la récupère dans l'autre.

Pile

La pile LIFO (pour Last In, First Out, « dernier arrivé, premier sorti ») sert à stocker les valeurs des variables de fonctions. Elle est disponible globalement, pour tous les modèles. Les fonctions de modèles push() (écriture) et pop() (lecture) sont utilisées, qui sont opérationnelles dans un modèle donné comme à travers plusieurs modèles.

En-tête

L'en-tête, ou header, se trouve en tout début du fichier comme son nom l'indique ; elle définit les méthodes d'intégration du modèle. La syntaxe est comme suit :

# Calculate <paramètre1>=<valeur1> <paramètre2> [<paramètre3>=<valeur3> ...]

Vous pouvez étendre l'en-tête sur plusieurs lignes si trop longue. Pour ce faire, mettez une barre oblique inversée (« \ ») à la fin de chaque ligne excepté la dernière.

Si l'en-tête est absente, les paramètres du fichier modèle seront ceux par défaut.

Paramètres acceptés :
Format

format=[...] indique le format du fichier modèle (voir Formats acceptés). Par défaut, le format est défini comme « raw », ou « bin » pour les fichiers qui contiennent des données binaires.
comment=[.] indique le début d'un commentaire de ligne (par exemple, #).

Intégration

append=[join|before|after|replace|remove|skip|patch|clear] indique le type d'intégration. Par défaut, ce paramètre est défini conformément au format du fichier. Si append=skip, le modèle ne sera pas traité. Si append=clear, le fichier de configuration sera nettoyé et sa longueur ramenée à zéro s'il s'agit d'un modèle de fichier ; si c'est un modèle de répertoire qui est traité, tous les fichiers et les sous-répertoires trouvés dedans seront supprimés.
force indique la suppression des fichiers existants avant l'écriture de la configuration. La règle est appliquée par défaut avec le paramètre « symbolic ».
link=chemin indique le chemin vers le fichier de configuration aulequel le modèle sera intégré. Par défaut c'est le même.
Exemple : link=/etc/conf.d/net.example
path=chemin indique le chemin vers le répertoire qui contient le fichier de configuration pertinent.
name=nom indique le nom du fichier de configuration.
mirror signale que l'intégration ne sera faite que si le fichier de configuration existe. Si, par contre, celui-ci est défini par le paramètre « link » et donc n'existe pas, le fichier cible sera effacé.
proteсted (ajouté dans la version 3.1.1) dit de protéger le fichier lors de la suppression du paquet auquel il appartient.
symbolic dit de créer un lien symbolique vers le fichier indiqué par le paramètre « link ».
autoupdate indique que le script cl-update-config est lancé lors de l'installation de tout paquet pour y appliquer les modèles pertinents. Les fichiers de configuration du paquet installé sont protégés. En d'autres termes, si le fichier existe déjà et qu'il a été modifié, cette modification ne sera pas validée automatiquement, mais par le biais d'une autre commande, dispatch-conf, qui permet à l'utilisateur de décider quelle configuration il veut garder. Si l'en-tête contient le paramètre autoupdate, le fichier sera copié vers le système une fois le modèle appliqué. Vous utiliserez toujours dispatch-conf pour transférer le fichier de configuration modifié si ce paramètre est absent.
run (ajouté dans la version 3.1.1) est une surcouche pour le fichier de configuration obtenu à partir du modèle. Le script sera lancé dès que le modèle aura été traité.
Exemple : run=/bin/bash.
exec est également une surcouche pour le fichier de configuration obtenu à partir du modèle. Contrairement à « run », le script n'est pas exécuté immédiatement, mais empilé sur les modèles non exécutables.
Exemple : exec=/bin/bash (à partir de la version 3.1.1, le script n'est pas sauvegardé sur le disque dur).
merge dit de configurer le(s) paquet(s) spécifié(s) après installation.
Exemple : merge=sys-apps/openrc,sys-boot/grub (à partir de la version 3.1.1, vous devez obligatoirement respecter le format « catégorie/paquet »).
env (ajouté dans la version 3.1) dit d'utiliser les variables d'un module spécifique dans le modèle. Si le module en question est absent du système, le modèle sera ignoré.
Exemple : env=install

Droit d'accès

chmod=XXX indique les droits d'accès au fichier de destination (exemple : 644). Par défaut ce sont ceux du fichier original. S'il n'existe pas, les droits correspondront à ceux du fichier modèle.
chown=utilisateur:groupe indique le propriétaire et/ou le groupe du fichier de destination (exemple : root:root).

Conditions

variable[>|<|==|!=|>=|<=]valeur ... est la syntaxe qui définit les conditions d'application du fichier modèle. Ces éléments peuvent être connectés par les opérateurs logiques ET (&) (pour calculate-lib>=2.2, c'est ET (&&)) et OU (||), la fonction ET ayant la priorité. Plusieurs conditions séparées par une espace seront considérées comme reliées par l'opérateur ET.

Etiquettes

Les modèles vous permettent d'ajuster le système, en prenant en charge votre matériel, en configurant le réseau, etc. Pour vous faire aider, vous pouver attribuer des étiquettes aux variables dans le fichier modèle, au lieu d'introduire des constantes.

Un exemple de fichier /etc/conf.d/hostname :

HOSTNAME="#-os_net_hostname-#"

Pour utiliser les variables d'un autre module, vous devez mettre ce dernier avant la variable, séparé par un point (ajouté dans la version 3.1).

Exemple :

#-install.os_install_root_dev-#

Blocs conditionnels

Les modèles supportent les blocs conditionnels.

Un bloc conditionnel est un bloc texte contenu dans le fichier modèle qui sera ajouté au fichier de configuration si l'expression rationnelle correspond.

Les expressions rationnelles servent à vérifier les valeurs. Dans les modèles Calculate, elles acceptent les types de données suivants :

les variables, qui réfèrent aux variables Calculate internes ;
les nombres, qui peuvent être des entiers ou des fractions ; dans ce dernier cas, la partie décimale doit être séparée d'un point ;
les lignes, qui peuvent contenir chiffres, lettres, caractères spéciaux ;
les numéros de version, qui représentent ou un plusieurs nombres séparés par des points (par exemple, 8.5.1).

Les opérations arithmétiques >, <, ==, !=, >=, <= (plus, moins, égal, non égal, plus ou égal, moins ou égal) sont utilisées pour vérifier l'équivalence. Le type de données sera défini avant l'opération.

Ces opérations peuvent être connectées avec les fonctions ET (&) et OU (||) ; c'est ET qui aura la priorité.

Tout bloc conditionnel doit commencer avec #?_variable1_==_valeur1_(...)# et se terminer avec #_variable1_#. Les deux doivent être placés en début de ligne.

Voici un exemple de bloc conditionnel à mettre dans le fichier /etc/make.conf :

#?os_arch_march==i686&&os_linux_shortname==CLD#
   CFLAGS="-O2 -march=i686 -pipe" 
   CHOST="i686-pc-linux-gnu" 
#os_arch_march#

Dans cet exemple, les variables setup_march et setup_sys_shortname sont comparées aux valeurs de ligne « i686 » et « CLD », respectivement. Si et seulement si les deux variables correspondent chacune à sa valeur, le bloc conditionnel sera ajouté au fichier résultant.

Fonctions

Pour créer des fichiers plus complexes, nécessitant des calculs lors du traitement, vous devrez utiliser les fonctions. Pareillement aux variables, les fonctions sont insérées dans le modèle avec la syntaxe qui suit : "#-_fonction_()-#".

Les fonctions qui ont le chemin du fichier pour argument (notamment path) peuvent utiliser ~ comme répertoire de l'utilisateur.

Fonctions disponibles :

belong (absente depuis 3.1.1) : analogue à « merge », mais traitant le nom du paquet seul, sans prendre en compte sa catégorie.

merge([catégorie/nom_de_paquet]) : vérifie le nom du paquet lors de l'installation. Dans d'autres cas, la fonction retourne une valeur positive.

Dans une fonction qui n'a pas d'argument, le nom du modèle (ou, pour les répertoires, le nom du répertoire) devient le nom du paquet, et la catégorie est remplacée par le répertoire parent. Si la catégorie ou le nom du paquet contient la version et/ou un numéro de triage (comme dans 20-mc,40-xfce-4.6), ces éléments seront ignorés.

Exemples :

sys-apps/15-portage-2.2/.calculate_directory : catégorie= sys-apps, nom_de_paquet= portage
sys-fs/udev : categorie = sys-fs, nom_de_paquet= udev

Le résultat dépend de la valeur de la variable cl_merge_pkg (qui a remplacé cl_belong_pkg dans la version 3.1.1 des Utilitaires Calculate).

cl_merge_pkg a la valeur « » :
- Avec ou sans argument, la fonction retourne « 1 ».
cl_merge_pkg a la valeur « _nom_de_paquet_ » :
- Si cl_merge_pkg et l'argument de la fonction ont la même valeur, la fonction retourne « 1 », sinon « ».
- Si la fonction n'a pas d'argument, la valeur de cl_merge_pkg et le nom du répertoire qui stocke le modèle avec la fonction merge() sont confrontés ; s'ils coïncident, la fonction retourne « 1 », sinon « ».

Pour les modèles qui modifient le code source de paquets (ac_install_patch), la fonction retourne le numéro de la version et non pas « 1 » quand le résultat est positif.

Exemple.
en-tête de modèle1 :

# Calculate merge(sys-auth/nss_ldap)!=

en-tête de modèle2 :

# Calculate merge(kde-libs/kdm)!=

Appliquer un modèle à sys-auth/nss_ldap. Mettre la valeur de la variable cl_merge_pkg à sys-auth/nss_ldap. Seul le modèle1 sera appliqué.
Appliquer les deux modèles. La valeur de cl_merge_pkg est celle par défaut, « ». modèle1 comme modèle2 seront appliqués.

Si merge reçoit un paramètre (que ce soit explicitement ou sur le chemin du fichier) qui est un paquet non existant, la fonction retourne une valeur vide.

case(typo,variable) affiche la valeur d'une variable en changeant la casse.

Ici :

typo correspond à la typographie utilisée. Les typos disponibles sont upper pour les majuscules, lower pour les minuscules, capitalize pour la majuscule réservée à la première lettre du mot et le reste en minuscules.
variable est le nom de la variable.

Exemple. Admettons que nous voulons afficher le nom de l'hôte en majuscules :

#-case(upper,os_net_hostname)-#

disk(point_de_montage,nom) affiche la valeur du paramètre du disque dur lors de l'installation du système.
Cette valeur est fournie par la variable correspondante (os_install_disk_ + nom ; s'il n'existe pas, os_disk_ + nom). Pour rechercher la bonne valeur, utilisez la variable os_install_disk_mount (qui indique les points de montage à l'installation).
Ici :

point_de_montage est le point de montage utilisé pour l'installation.
nom est l'élément final des noms de variables commençant par os_install_disk_/os_disk (os_install_disk_'/'os_disk_ + nom).

valeurs des variables
os_install_disk_mount = ['swap', '/', '', '/var/calculate']
os_disk_grub = ['0,0','0,1','0,2','0,3','0,4']

fonction disk(/var/calculate,grub)

On recherche /var/calculate dans la variable os_install_disk_mount, pour obtenir l'indice 4 ;
Dans la variable os_disk_grub, « 4 » est positionné à l'indice 4.
Le résultat renvoyé par la fonction disk(/var/calculate,grub) est donc 0,4.

fonction disk(/boot,grub)

La variable os_install_disk_mount ne contient pas /boot, l'indice est absent.
Comme l'indice n'est pas disponible, on recherche / dans la variable os_disk_install. On obtient l'indice 1.
Dans la variable os_disk_grub, « 0,1 » est positionné à l'indice 1.
Le résultat renvoyé par la fonction disk(/boot,grub) est donc 0,1.

Exemple.
Supposons qu'il nous faut le numéro de la partition sollicitée par Grub :

#-disk(/boot,grub)-#

On obtient 0,1.

env(service.variable) lit la valeur sauvegardée d'une variable de modèle d'un service. Elle est récupérée en traitant les fichiers qui stockent les valeurs des variables de modèles.
Ici :

service est le nom du service.
variable est une variable utilisée par ce service.
Il est à noter que les deux arguments doivent être séparés par un point.

Exemples :

Lire le nom de domaine requis pour se connecter à Jabber.
```
#-info(jabber,sr_jabber_host)-#
```

La valeur renvoyée est jabber.calculate.org.

exists(chemin,option) vérifie si un fichier ou un répertoire existe.
Si effectivement le fichier (ou le répertoire) existe, la fonction renvoie 1, sinon une valeur vide.

Ici :

chemin est un chemin dans le système de fichiers.
option est une option facultative, dont par exemple :

root, qui indique que le chemin vers le fichier ne contiendra pas de partie chroot. (Le chemin spécifié sera utilisé tel quel, quelles que soient les valeurs attribuées à cl_chroot_path et cl_root_path)

Exemple. Vérifions si le répertoire /etc existe :

#-exists(/etc)-#

La fonction retourne 1.

groups(groupe1,groupe2,...groupeN) vérifie si l'utilisateur appartient aux groupes groupe1, groupe2, ... groupeN.

Si l'utilisateur est au moins dans un groupe indiqué, la fonction renvoie 1, sinon une valeur vide est retournée.

Exemple. Vérifions si l'utilisateur courant appartient au groupe wheel :

#-group(wheel)-#

Si c'est le cas, la fonction retournera 1.

ini(variable,valeur,option) assure l'écriture et la lecture d'une variable dans le fichier de configuration utilisateur (~/.calculate/ini.env).

Fonctionnalité ajoutée dans la version 2.2.20-r4 : si la fonction est utilisée à configurer le système, le fichier de configuration sera localisé dans /etc/calculate/ini.env.

Ici :

variable est le nom d'une variable de fonction. Il doit obligatoirement commencer avec une lettre, mais peut contenir aussi des chiffres et le point. Le point sert à séparer le nom de la variable dans le fichier de configuration.
valeur est une valeur de variable de fonction. Elle est affectée à la variable et insérée dans le fichier de configuration. Si ce deuxième argument est absent, la variable est lue dans le fichier ; si ce dernier n'en contient aucune mention, la variable se voit attribuer une valeur vide.
Fonctionnalité ajoutée dans la version 2.2.20-r4 : si l'argument est une ligne vide sans guillemets, la variable sera supprimée. Si l'argument est une ligne vide entre guillemets, la valeur de la variable dans le fichier ini sera effacée.
option est une option facultative qui transforme la valeur de la variable. Les valeurs admises sont url, purl, unicode. En utilisant cet argument, laissez le second argument vide.

Voici quelques exemples :

Créer la variable « test », lui affecter la valeur 5, la porter sur le fichier de configuration.
```
#-ini(test,15)-#
```

Lire la valeur de la variable test qu'on vient d'insérer dans le fichier de configuration, remplacer la fonction avec la valeur de la variable lue, 15 en l'occurence :
```
#-ini(test)-#
```

Utiliser la fonction ini avec trois arguments. Admettons que le fichier ~/.calculate/ini.env contient la section
```
[test]
param = <paramètre de test>
```

La fonction

#-ini(test.param,,unicode)-#

retournera donc

\u0422\u0435\u0441\u0442\u043e\u0432\u044b\u0439 \u043f\u0430\u0440\u0430\u043c\u0435\u0442\u0440

alors que la fonction

#-ini(test.param,,url)-#

retournera

%d0%a2%d0%b5%d1%81%d1%82%d0%be%d0%b2%d1%8b%d0%b9%20%d0%bf%d0%b0%d1%80%d0%b0%d0%bc%d0%b5%d1%82%d1%80

L'option purl a ceci de différent par rapport à url qu'elle convertit « / » en code « %2F ».

server(service.option,variable) lit la valeur d'un paramètre de service. Pour ce faire, le fichier /var/calculate/remote/server.env est traité.

Ici :

service est le nom du service.
option est l'option.
variable est une variable de fonction (argument facultatif).
service et option doivent être séparés par un point.
Si l'argument variable est utilisé, la valeur de l'option obtenue sera attribuée à la variable de fonction variable.
Si l'argument variable n'est pas utilisé, la valeur de l'option obtenue sera insérée dans le fichier de configuration.

Exemples :

Lire la valeur du port utilisé pour la connexion sur Jabber.
```
#-server(jabber,port)-#
```

La valeur obtenue sera 5223.

Lire la valeur du port utilisé pour la connexion sur Jabber et la mettre dans la variable de fonction jabber_port.
```
#-server(jabber,port,jabber_port)-#
```

La variable jabber_port a donc la valeur 5223.

list(variable,indice) affiche une valeur de variable après une recherche à l'indice.

Ici :

variable est une variable de fonction ou variable de modèle (sa valeur doit être une liste).
indice est l'indice de recherche (rappelons que le premier élément a l'indice 0, et ainsi de suite).

Exemple.
La valeur de la variable est comme suit :
os_disk_dev = ['/dev/sda1', '/dev/sda2', '/dev/sda3', '/dev/sda4', '/dev/sda5']

#-list(os_disk_dev,1)-#

L'étiquette de la fonction sera remplacée par /dev/sda2.

Si un argument absent sur la liste est appelé, l'application des modèles est arrêtée. Depuis la version 2.2.17 des Utilitaires, une ligne vide est retournée dans ce cas.

in(variable,valeur1,valeur2...) : parmi les valeurs passées comme arguments à la fonction, afficher celle qui égale la variable variable. Si la valeur pertinente n'a pas été trouvée parmi les valeurs, la fonction retournera un vide.

Ici :

variable est la variable.
valeurX est la liste de valeurs contre laquelle la vérification sera faite.

Exemple :

La variable a la valeur suivante :
os_install_linux_shortname = CLDX

#-in(os_install_linux_shortname,CLDX,CLD,CLDG)-#

CLDX sera substitué à l'étiquette courante de la fonction.

load(argument,_chemin,option) affiche les données contenues dans un fichier.

Ici :
argument est le type de contenu à traiter.
chemin est le chemin du fichier.
option est une option facultative, dont par exemple :

root, qui indique que le chemin vers le fichier ne contiendra pas de partie chroot. Le chemin spécifié sera utilisé tel quel, quelles que soient les valeurs attribuées à cl_chroot_path et cl_root_path.

arg accepte les valeurs suivantes :

version
nombre
ligne
vide est le résultat, le contenu du fichier sans lignes commentées (commentaires introduits par # ou ;) ou vides.

chemin est le chemin relatif ou absolu vers le fichier.

Exemple. Afficher le contenu du fichier /proc/cpuinfo sur la ligne de la déclaration de la fonction :

#-load(char,/proc/cpuinfo)-#

module(espace_de_noms) (supprimé dans la version 3.1) permet de recevoir les variables des modèles du paquet ou d'exécuter les méthodes du paquet en utilisant son module API, ou encore exécuter une méthode spécifique pour tous les paquets qui en ont.

Ici :

espace_de_noms est l'espace de noms du module API.

L'espace de noms de variables disponibles est constitué d'éléments séparés par un point.

Le premier élément est un nom de paquet, soit le nom d'un paquet installé qui dispose d'un module API (il est à noter que le tiret (-) doit être remplacé par le soulignement (_) dans le nom.)

Pour tous les paquets, le premier nom de l'espace sera all (nom réservé).
Exemple de premier élément pour le paquet calculate-ldap :

calculate_ldap

Le deuxième élément est le nom d'une méthode API, sinon var, qui est un nom réservé pour cet espace.

Exemple de premier et deuxième éléments pour le paquet calculate-ldap, pour avoir accès aux variables :

calculate_ldap.var

Exemple de premier et deuxième éléments pour le paquet calculate-ldap, pour obtenir le résultat de l'exécution de la méthode is_setup() du module API (il s'agit de vérifier si le paquet a bien été configuré).

calculate_ldap.is_setup

Le troisième élément d'un espace est, dans la plupart des cas, l'espace de noms de variables du modèle.

Voici un exemple d'espace de noms pour obtenir la valeur de la variable de modèles cl_name du paquet calculate-ldap :

calculate_ldap.var.cl_name

Exemples d'utilisation de la fonction :
Obtenir la valeur de la variable de modèles cl_name (utilisée pour les noms de paquet) qui appartient au paquet calculate-ldap.

#-module(calculate_ldap.var.cl_name)-#

La fonction retourne

calculate-ldap

Vérifier si le paquet calculate-ldap est bien configuré et opérationnel :

#-module(calculate_ldap.is_setup)-#

Si c'est le cas, la fonction retournera

Vérifier si tous les paquets installés et qui ont un module API sont bien configurés aussi :

#-module(all.is_setup)-#

Si c'est le cas, la fonction retournera

pkg (catégorie/paquet) affiche la version d'un paquet installé. S'il existe plusieurs versions installées de ce paquet, la version du slot le plus élevé sera affichée.

Ici :

catégorie est la catégorie du paquet.
paquet est le nom du paquet.
Depuis la version 3.1.0_beta2 des Utilitaires Calculate, il est possible d'indiquer le slot du paquet, en le séparant avec un double point, comme suit : pkg(kde-base/kdelibs:4)

Vous ne pouvez spécifier que le nom du paquet comme mode compatible. Dans ce cas, le traitement se fera plus lentement.

Par exemple, affichons la version d'un paquet installé (soit 4.2.4) :

#-pkg(kde-base/kdelibs)-#

On en déduit que le paquet kdelibs-4.2.4 est installé.

print (message) affiche un message d'information sur écran quand le modèle est appliqué.

warning (message) affiche un avertissement sur écran quand le modèle est appliqué.

error (message) affiche un message d'erreur sur écran quand le modèle est appliqué.

push(variable, valeur) met la valeur de la variable en haut de la pile des variables de fonction modèle.

Ici :

variable est le nom d'une variable de fonction. Ce nom doit commencer avec une lettre, mais peut contenir des chiffres aussi. La variable est créée pour le temps du traitement du fichier de configuration.
valeur est la valeur de la variable de fonction qui, après être attribuée à la variable, est mise dans la pile des variables de fonctions des modèles. Si ce second argument est absent, la valeur de la variable se retrouvera en haut de la pile.

Exemples :

Créer la variable text, lui attribuer la valeur 15, puis la mettre dans la pile :
```
#-push(test,15)-#
```

Mettre la valeur de la variable test préalablement créée en haut de la pile :
```
#-push(test)-#
```

pop(variable) récupère une valeur de la pile des variables de fonctions des modèles et l'attribue à une variable.

Ici :

variable est le nom d'une variable de fonction. Ce nom doit commencer avec une lettre, mais peut contenir des chiffres aussi. La variable est créée pour le temps du traitement du fichier de configuration.

Exemple :

Créer la variable text, lui attribuer la valeur 15, puis la mettre dans la pile :
```
#-push(test,15)-#
```

Récupérer la valeur dans la pile et l'assigner à la variable test2:
```
#-pop(test2)-#
```

Il est possible de récupérer une valeur de la pile dans le modèle courant comme dans tout autre modèle.
Dès que la fonction l'ait obtenue, la valeur est supprimée de la pile.

replace(ancien, nouveau, variable) substitue, dans la variable, un texte nouveau au texte_ancien_.

Ici :

ancien est le texte dont chaque entrée dans la valeur de la variable sera remplacée avec le texte nouveau.
nouveau est le texte qui sera substitué au texte ancien, dans la valeur de la variable.
variable est une variable de fonction ou de modèle.

Les deux textes, ancien et nouveau, doivent être mis entre guillemets, simples ou doubles.

Les caractères de contrôle (\', \", \n, \r, \t, \) qu'on retrouve entre guillemets doubles seront traités.
Le texte entre guillemets simples ne sera pas traité.

Exemple.
Soit la valeur de la variable de modèle ur_signature :

Calculate Ltd.\n4 Stachek pl., Saint-Petersburg\nRUSSIA\nhttp://www.calculate.ru\n+7 812 3363632\n+7 495 7727678

Quand la fonction est exécutée :

#-replace('\n',"\n",ur_signature)-#

le texte suivant sera inséré à l'endroit spécifié (une fin de ligne correspondant à « \n ») :

Calculate Ltd.
4 Stachek pl., Saint-Petersburg 
RUSSIA
http://www.calculate.ru
+7 812 3363632
+7 495 7727678

rnd(type,longueur) affiche une série de caractères aléatoires.
Ici :

type est le type des caractères utilisés. Les valeurs acceptées sont : num pour chiffres uniquement, pas pour chiffres et lettres, uuid pour chiffres et lettres de A à F (ajouté dans la version 2.2.17).
longueur est le nombre de caractères.

Exemple. Afficher trois nombres aléatoires (soit 372) :

#-rnd(num,3)-#

sum(variable,sum_print, sum_out) donne les valeurs d'offset calculables. A l'origine, nous avons développé cette fonction pour configurer le bureau Plasma.

Ici :

variable est le nom d'une variable de la fonction sum. Ce nom doit commencer avec une lettre, mais peut contenir des chiffres aussi. La variable est créée pour le temps du traitement du fichier de configuration.
sum_print est une expression arithmétique dont le résultat sera affiché sur la ligne de la déclaration de la fonction. Si l'argument est absent, il n'y aura aucune sortie. Les quatre opérations sont supportées, à savoir l'addition (+), la soustraction (-), la multiplication (*) et la division (/). L'expression peut appeler d'autres variables de fonction, aussi que des variables de modèles.
sum_out est une expression arithmétique dont le résultat sera attribué à la variable (au premier argument de la fonction donc). Si ce troisième argument est absent, la variable se verra assigner la valeur calculée du deuxième argument.

Exemples :

Créer la variable clock, lui attribuer la valeur 15, sans rien afficher toutefois :
```
#-sum(clock,,15)-#
```

Créer la variable bt, lui attribuer la valeur de la variable clock puis l'afficher :
```
#-sum(bt,clock)-#
```

Placer un bouton sur la barre de 35 pixels de largeur, avec une indentation de 4 pixels sur les bords :
```
#-sum(bt,bt+2,bt+35+2)-#
```

Modes d'intégration¶

Il existe plusieurs modes d'intégration du fichier modèle avec le fichier de configuration original :

join est le mode d'intégration principal : les deux fichiers sont fusionnés. Pour plus de détails, référez-vous à la section Principe d'intégration.
before : le modèle est transféré et son contenu, ajouté au début du fichier original.
after : le modèle est transféré et son contenu, ajouté à la fin du fichier original.
replace : le modèle est transféré et remplace le fichier original.
delete : l'intégration n'a pas lieu, le fichier original est supprimé.
remove : au lieu d'intégrer, le fichier original est supprimé.

Pour les modes « before », « after », « replace », le fichier modèle subit les modifications suivantes avant intégration :

si des éléments de contrôle existent, ils seront traités ;
si l'en-tête existe, elle sera traitée ;
si le paramètre format figure dans l'en-tête, les caractères de contrôle +, -, ! seront traités.

Règles par défaut

Normalement, les Utilitaires Calculate décident du mode d'intégration en fonction du format.

Ainsi pour les formats samba, bind, etc., propres aux applications communes, le mode par défaut est « join » ; pour les formats raw et bin, « replace » ; pour un fichier vide, « delete » : le fichier résultant sera donc effacé.

Les règles d'intégration sont modifiables via le paramètre append, à définir dans l'en-tête du fichier modèle.

Localisation¶

Règles de nommage des fichiers¶

Les noms de fichiers modèles peuvent contenir des opérateurs de condition, définissant les règles qui doivent être respectées pour que le fichier soit transféré dans le système. Tout comme un lien vers le site, les conditions sont séparées du nom par le signe d'interrogation (?), et suivies ou non pas des opérateurs de condition, comme décrit dans la section Blocs conditionnels (voir ci-dessus).

Les opérations peuvent être reliées par les fonctions ET (&) et OU (?), ET ayant la priorité.

Exemple :

grub.conf?os_linux_shortname==CDS?os_linux_shortname==CLD

Dans cet exemple, le modèle configurera le chargeur d'amorçage, qu'il s'agisse de Calculate Linux Desktop ou de Calculate Directory Server.

Si l'en-tête du modèle contient des blocs conditionnels, les deux conditions doivent être remplies pour que le fichier modèle soit transféré dans le système.

Règles de nommage des répertoires¶

Les règles de nommage des répertoires sont similaires à celles valables pour les fichiers. Si les conditions fixées par les opérateurs qui les relient sont remplies, le répertoire sera transféré dans le système, sinon le répertoire avec son contenu sera ignoré.

Droits d'accès¶

Après l'intégration des deux fichiers, les droits d'accès au fichier de configuration sont déterminés comme suit :

Si le fichier de configuration existe dans le système, ses droits d'accès resteront les mêmes.
Si le fichier de configuration n'existe pas, les droits seront mis à 644 pour les fichiers et à 755 pour les répertoires.
Si la variable chmod ou chown est définie dans l'en-tête, les droits du fichiers de configuration seront modifiés en fonction de sa valeur.

Liens symboliques¶

Pour créer un lien symbolique, utilisez les paramètres link et symbolic dans l'en-tête du modèle.

Si le fichier modèle contient le corps du modèle aussi bien que l'en-tête, le fichier original sera modifié conformément aux règles d'intégration.

Calculate ne transférera pas les liens dits « morts » qui ne pointent vers aucun fichier (ou répertoire), à moins que l'option force ne soit indiquée explicitement.

Principe d'intégration¶

On entend par intégration la modification du fichier de configuration original en fonction du fichier modèle.

Pour intégrer, les textes respectifs des deux fichiers sont divisés en éléments tels que portées, variables, listes, listes séparées, commentaires, éléments de contrôle (voir ci-dessous).

Le fichier modèle doit respecter la syntaxe du fichier de configuration. La disposition des éléments du fichier original sera conservée. Les commentaires du fichier modèle ne seront pas transférés dans le fichier résultant.

Règles d'intégration¶

Un élément peut être fusionné, substitué ou supprimé.

Fusion

Les éléments absents du fichier original seront ajoutés à la fin de la portée. S'il y a une fin de ligne avant l'élément inséré, elle sera mise après cet élément, sinon avant.
Si une liste séparée est fusionnée, les éléments absents seront ajoutés immédiatement après le dernier élément de la liste du fichier de configuration.

Substitution

La valeur de l'élément est remplacée par celle du modèle, et le formatage est transféré avec.

Suppression

L'élément est supprimé avec la fin de ligne qui le précède.

Règles de fusion par défaut¶

Les règles de fusion s'appliquent aux éléments de même nom appartenant à une même portée du modèle.

Si le modèle et le fichier de configuration divergent, les règles suivantes sont appliquées par défaut :

Pour les portées, le contenu de la portée du modèle est fusionné (+) avec la portée du fichier de configuration.
Pour les variables, les valeurs sont remplacées (-) avec celles du modèle.
Pour les listes, le contenu de la liste est remplacé (-) avec celui de la liste du modèle.
Pour les listes séparées, comme pour les variables, les valeurs courantes sont remplacées (-).

Modifier les règles de fusion¶

Pour modifier les règles de fusion par défaut, ajoutez un caractère de contrôle au début du nom de l'élément dans le fichier de configuration :

"+" dit de fusionner les éléments (pour les portées et les listes) ; seuls les éléments uniques resteront après cette fusion.
"-" dit de remplacer l'élément.
"!" dit de supprimer l'élément.
Le marqueur @<action> décrit ces règles en format @CXmlConf.

Format CXmlConf¶

CXmlConf est le format universel qui sert à obtenir des réglages personnalisés avec la plupart des types de fichiers de configuration utilisés sous Linux/Unix.

Le fichier XML décrit les réglages en délimitant des structures logiques dites éléments, ou balises, qu'on peut traiter séparément par la suite. Après intégration du modèle, le fichier peut toujours être ramené à sa forme initiale, à quelques exceptions près (voir Principe d'intégration).

Les éléments sont décrits comme suit :

<cxmlconf>
  <head>
    <ver><version du format></ver>
    <format><format du fichier de configuration></format>
  </head>
  <body>
    [<area>...</area>... <field>..</field>]
  </body>
</cxmlconf>

où :

la balise <ver> indique le numéro de version du balisage.
la balise <format> indique le format du fichier de configuration (en fonction des applications communes).

Tous ces éléments, décrits ci-dessous, sont placés à l'intérieur de la balise <body/>.

Portées¶

Les portées de fichiers de configuration délimitent l'espace de noms de variables disponibles. Les portées peuvent contenir des structures logiques, y compris d'autres portées (exemple : {{Filename|named.conf}}).

La syntaxe est comme suit :

<area>
  <caption>
    <name><nom de la portée></name>
    <action>join|replace|drop</action>
    <quote><début de la portée (en-tête)></quote>
    <quote><fin de la portée></quote>
  </caption>

  [<field></field>...]

</area>

Variables¶

Les variables sont décrites comme suit :

<field type="var">
  <name><nom_de_variable></name>
  <value><valeur></value>
  <action>join|replace|drop</action>
  <quote><description originale></quote>
</field>

Certains fichiers de configuration, dont par exemple /etc/openldap/slapd.conf, contiennent la construction suivante :

index   cn              pres,sub,eq
index   sn              pres,sub,eq
index   uid             pres,sub,eq

Dans ce cas, le nom de la variable est constitué par les deux premières parties, et sa valeur, par la troisième.

La ligne :

index   cn              pres,sub,eq

donne en XML :

<field type="var">
  <name>indexcn</name>
  <value>pres,sub,eq</value>
  <quote>index   cn              pres,sub,eq</quote>
</field>
<field type="br" \>

Listes¶

Tout comme le fichier named.conf, un bloc « listen-on » peut contenir juste des valeurs de bloc et aucune valeur de variable.

Les valeurs sont définies par la structure :

<field type="list">
  <name>hostsallow</name>
  <value>192.168.0.0/24</value>
  <value>127.</value>
  <action>join|replace|drop</action>
  <quote><liste originale></quote>
</field>

où le texte original de description de la valeur est mis entre les balises <quote>, sans fin de ligne.

Listes séparées¶

Le fichier de configuration du serveur Apache peut contenir l'instruction Include, qui permet de rendre le fichier source modulaire. Ces cas sont décrits dans CXmlConf.

Les listes séparées sont décrites par la structure suivante :

<field type="seplist">
  <name>Include</name>
  <value>/etc/apache2/modules.d/*.conf</value>
  <action>join|replace|drop</action>
  <quote><liste originale></quote>
</field>

Commentaires¶

Lors de l'intégration, les commentaires au fichier original restent intacts.

Quel que soit leur type, les commentaires sont placés dans la balise <quote/> . Les symboles de commentaire et les fins de ligne y sont mis.

<field type="comment">
  <quote><commentaire original></quote>
</field>

Les commentaires incorporés (définis dans d'autres structures de commentaires) ne sont pas admis.

Elements de contrôle¶

Pour désigner la fin de ligne, la syntaxe est comme suit :

<field type="br">
  <quote><éléments de formatage></quote>
</field>

où quote contient des éléments tels que espaces, tabulations ...

Format XML¶

Formats XML supportés¶

Les formats XML actuellement pris en charge sont xml_xfce (pour configurer le gestionnaire de fenêtres XFCE), xml_xfcepanel (pour configurer les barres XFCE), xml_gconf (pour configurer l'environnement GNOME)

Les différences par rapport à CXmlConf¶

Les fichiers XML sont stockés et traités sans qu'on ait besoin de les convertir.
Les règles, les fonctions ou les variables affectent un fichier modèle XML de façon similaire à tout autre modèle, sauf quand il s'agit d'intégrer les éléments XML.

Intégration des éléments XML¶

Les attributs action des éléments XML assurent leur intégration dans un modèle.

Les valeurs acceptées sont :

action="join" : les éléments seront fusionnés (comportement par défaut).
action="replace" : l'élément du modèle sera substitué à l'élément du fichier.
action="drop" : l'élément du fichier sera supprimé.

Format xml_xfce

Ce format est constitué par des éléments channel et property.

Les attributs de channel stockent le nom et la version du fichier.

La balise <channel/> contient des balises <property/>.

Un exemple de <channel> :

<channel name="xfwm4" version="1.0">
  <property name="general" type="empty">
  .....
  </property>
</channel>

Un exemple de <property> :

<property name="wrap_workspaces" type="bool" value="false"/>

Chaque élément property a un attibut type.

Si type="array", cet élément ainsi que les éléments qu'il contient seront remplacés par ceux du modèle, sinon les éléments fournis par le modèle seront intégrés.

Exemple d'utilisation de type="array" :

<property name="workspace_names" type="array">
  <value type="string" value="Bureau 1"/>
  <value type="string" value="Bureau 2"/>
  <value type="string" value="Bureau 3"/>
  <value type="string" value="Bureau 4"/>
</property>

Format xml_xfcepanel

Ce format est constitué par des éléments de plusieurs types : panels, panel, properties, property, items, item.

S'il s'agit d'une balise <items/>, elle sera remplacée, ainsi que les balises qu'elle contient, par celles du modèle, sinon les éléments fournis par le modèle seront intégrés.

Voici une syntaxe items d'exemple :

<items>
  <item name="xfce4-mixer-plugin" id="9"/>
  <item name="clock" id="10"/>
  <item name="separator" id="52"/>
  <item name="actions" id="12"/>
</items>

Format xml_gconf

Ce format est constitué par des éléments <entry>.

Si une balise <entry/> a l'attribut ltype ou type="string", elle sera remplacée, ainsi que les balises qu'elle contient, par celles du modèle, sinon les éléments fournis par le modèle seront intégrés.

L'attribut mtime de <entry> indique le temps en secondes où la balise a été modifiée.

Voici un exemple de modèle xml_gconf :

# Calculate format=xml_gconf
<?xml version="1.0"?>
<gconf>
        <entry name="rgba_order" mtime="1235158855" type="string">
              <stringvalue>rgb</stringvalue>
       </entry>
       <entry name="dpi" mtime="1235162438" type="float" value="86">
       </entry>
       <entry name="hinting" mtime="1235266915" type="string">
               <stringvalue>full</stringvalue>
       </entry>
       <entry name="antialiasing" mtime="1235266915" type="string">
               <stringvalue>rgba</stringvalue>
       </entry>
</gconf>

Format xml_gconf_tree

Ce format est constitué par des éléments <dir> et <entry> et leurs attributs.

En cas d'intégration de type join, les attributs seront intégrés.

Lors de l'intégration, les balises <entry/> du fichier de configuration seront remplacées par les éléments respectifs du modèle.

L'attribut mtime de <entry> indique le temps en secondes où la balise a été modifiée.

Voici un exemple de modèle xml_gconf :

# Calculate format=xml_gconf_tree
<?xml version="1.0"?>
<gconf>
    <dir name="desktop">
        <dir name="gnome">
            <dir name="volume_manager">
                <entry name="percent_used" mtime="1285580987" schema="/schemas/desktop/gnome/volume_manager/percent_used"/>
                        </dir>
                </dir>
        </dir>
<gconf>

Exemple d'utilisation

Voyons un fichier modèle pour illustrer :

# Calculate format=xml_xfce
<?xml version="1.0" encoding="UTF-8"?>
<channel name="xfce4-session" version="1.0">
  <property name="general" type="empty" action="drop">
    <property name="FailsafeSessionName" type="empty"/>
    <property name="SessionName" type="string" value="Default"/>
    <property name="SaveOnExit" type="bool" value="true"/>
  </property>   
</channel>

La ligne <property name="general" type="empty" action="drop"> indique que cet élément, ainsi que les balises qu'il contient, seront supprimés.

Le fichier résultant de l'opération ressemblera à ceci :

<?xml version="1.0" encoding="UTF-8"?>
<channel name="xfce4-session" version="1.0">
</channel>

Format patch¶

Le format patch est destiné à traiter les fichiers de configuration avec des expressions rationnelles en Python.

Particularités¶

Si vous utilisez le format patch, le fichier de configuration sera soumis au traitement par le modèle (intégration de type patch), sans que ce dernier soit intégré de fait au fichier.

Description¶

La syntaxe d'un modèle de format patch est comme suit :

# Calculate format=patch
<reg><expression rationnelle Python 1></reg>
<text><texte à remplacer l'expression rationnelle 1></text>
<reg><expression rationnelle Python 2></reg>
<text><texte à remplacer l'expression rationnelle 2></text>
...

Exemple :

# Calculate format=patch
<reg>TEXT</reg>
<text>TEXT_CONFIG</text>

Ce modèle substitue TEXT_CONFIG à TEXT, dans le fichier de configuration.

Format diff¶

Ajouté dans la version 3.1.4.

Le format diff est utilisé pour appliquer un patch diff sur le code d'un paquet. Le fichier lui-même ne sera pas créé, les données obtenues seront traitées contre le répertoire indiqué dans le paramètre path.

Exemple :

# Calculate format=diff
--- panel-plugin/xkb-cairo.c    2012-07-17 16:23:24.997030066 +0400
+++ panel-plugin/xkb-cairo.c    2012-07-17 16:47:34.107054590 +0400
@@ -27,7 +27,7 @@
 #include "xkb-util.h" 
 #include "xfce4-xkb-plugin.h" 

-#define XKB_PREFERRED_FONT "Courier New, Courier 10 Pitch, Monospace Bold %d" 
+#define XKB_PREFERRED_FONT "Droid Sans, Courier New, Courier 10 Pitch, Monospace Bold %d"