description des modifications

TODO.md

@@ -1,3 +1,84 @@
 # TODO
 
+Faire des fonctions pour faciliter la gestion de configuration par défaut
+
+La configuration est décrite dans un tableau nommé CONFIG par défaut
+~~~
+CONFIG=(
+    "-*- coding: utf-8 mode: sh -*-"
+    "# description de la variable NAME"
+    NAME=default_value
+    "# description de la variable LONG"
+    "# sur plusieurs lignes"
+    LONG="very long value"
+)
+~~~
+
+* si le premier élément commence par `-*-` alors il contient les informations
+  pour générer la ligne de mode pour le fichier de config s'il faut le créer de
+  toutes pièces.
+* chaque élément qui commence par `#` est une description de la variable qui
+  suit. plusieurs éléments sont fusionnés le cas échéant.
+* les éléments de la forme NAME=DEFAULT_VALUE définissent une variable et sa
+  valeur par défaut.
+
+A partir de ce tableau, la fonction upgrade_config() permet de créer un fichier
+de config s'il n'existe pas, ou de la mettre à jour avec de nouvelles variables
+s'il existe. Soit la commande suivante
+~~~
+upgrade_config path/to/config.conf CONFIG
+~~~
+
+Si le fichier config.conf n'existe pas, il est créé ainsi:
+~~~
+# -*- coding: utf-8 mode: sh -*- vim:sw=4:sts=4:et:ai:si:sta:fenc=utf-8
+
+# description de la variable NAME
+#NAME=default_value
+
+# description de la variable LONG
+# sur plusieurs lignes
+#LONG="very long value"
+~~~
+
+Si le fichier config contenait ceci:
+~~~
+# -*- coding: utf-8 mode: conf -*- vim:sw=4:sts=4:et:ai:si:sta:fenc=utf-8
+
+# description de la variable LONG
+LONG="my value"
+~~~
+il est transformé en ceci, c'est à dire que la définition manquante de NAME est
+rajoutée:
+~~~
+# -*- coding: utf-8 mode: conf -*- vim:sw=4:sts=4:et:ai:si:sta:fenc=utf-8
+
+# description de la variable LONG
+LONG="my value"
+
+# description de la variable NAME
+#NAME=default_value
+~~~
+
+A partir du tableau, la fonction load_config() permet de charger le fichier de
+config en ne sélectionnant que les variables qui sont mentionnées dans le
+tableau. Soit le fichier de configuration suivant
+~~~
+NAME=value
+LONG=something
+ROGUE=data
+~~~
+et les commandes suivantes
+~~~
+NAME=x
+LONG=y
+ROGUE=inchangée
+load_config path/to/config.conf CONFIG
+echo "NAME=$NAME, LONG=$LONG, ROGUE=$ROGUE"
+~~~
+le résultat est le suivant
+~~~
+NAME=value, LONG=something, ROGUE=inchangée
+~~~
+
 -*- coding: utf-8 mode: markdown -*- vim:sw=4:sts=4:et:ai:si:sta:fenc=utf-8:noeol:binary