`deploydb` est un moyen de décrire des informations de déploiement ou de
configuration à propos de certains objets (hôtes, modules, webapps, woapps,
etc.)

# Syntaxe

Le format du fichier de configuration est volontairement simple. Toute la
logique est implémentée dans les clients qui accèdent à l'information stockée

Le fichier contient deux sortes d'informations:
* définition d'objet
* définition de faits

Les lignes vides ou commençant par '#' sont ignorées.
Si une ligne commence par un espace, elle est fusionnée avec la ligne
précédente.

## Définition d'objet

Une définition d'objet a le format suivant:
~~~
otype oid[=values] [ATTRS...] [LINKS...]
~~~

`otype`
: type d'objet à créer ou à mettre à jour

`oid`
: identifiant de l'objet à créer ou à mettre à jour

`values`
: valeurs de l'objet, séparées par des virgules

`ATTR`
: attribut de l'objet

`LINK`
: définition d'objet lié

Une définition d'attribut a l'un des formats suivants:
~~~
name[=value]
name+[=value]
name-[=value]
name%[=value]
~~~

Les attributs sont multivalués, et par défaut, on rajoute la nouvelle valeur aux
valeurs existantes sauf si elle existe déjà dans l'attribut.

value vaut par défaut 'true', ce qui n'est pas la même chose qu'une valeur
vide. comparer les deux définitions suivantes:
~~~
first     # first vaut 'true'
second=   # second vaut ''
~~~

Les types de mise à jour valides sont:
* `=` ajout de la valeur si l'attribut ne la contient pas déjà
* `+=` ajout inconditionnel d'une valeur à l'attribut
* `-=` suppression d'une valeur de l'attribut
* `%=` remettre à zéro l'attribut d'abord

Ainsi, les définitions suivantes sont équivalentes deux à deux:
~~~
attr=value attr=value # le doublon est supprimé
attr=value            # c'est comme si on ne spécifie la valeur qu'une seule fois

attr=value attr%=first attr=second
attr=value attr-=value attr=first attr=second
~~~

Une définition de lien a le format suivant:
~~~
-otype oids... [ATTRS...]
~~~

`otype`
: type de l'objet lié

`oids`
: liste d'identifiants d'objets liés séparés par des virgules

`ATTR`
: attribut à rajouter à la définition du lien

Voici un exemple complet:
~~~
humain bob nom=Payet prenom=Robert
    age=42
    desc="un humain qui a un père, une mère et deux voitures"
    -humain eric type=pere
    -humain martine type=mere
    -vehicule titine,bumblebee
humain eric nom=Payet prenom=Eric
humain martine nom=Payet prenom="Martine Joséphine"
vehicule titine marque=Citroen immatriculation=BX-467-PM
vehicule bumblebee marque=Camaro type=autobot
~~~

## Définition de faits

Un fait est l'affirmation d'un lien d'action ou d'état entre deux objets,
décrit par un verbe. Par exemple, pour décrire le fait que bob mange une
tarte, on écrirait:
~~~
humain bob
aliment tarte

-humain bob
    mange -aliment tarte
~~~

Une définition de fait a le format suivant:
~~~
-sotype soids... [DEFATTRS...]
    verb -totype toids... [FACTATTRS...]
    ...
~~~

`sotype`
`totype`
: types d'objets source et cible

`soid`
`toid`
: identifiants des objets source et cible

`verb`
: identifiant du lien entre la source et la destination. en général, il s'agit
  d'un verbe d'action ou d'état conjugué à la 3ème personne du singulier.

  si le verbe commence par `~` alors la définition est inversée. par exemple,
  les deux faits suivants sont rigoureusement équivalents:
      ~~~
      -otype src verb -otype dest
      -otype dest ~verb -otype src
      ~~~
  cela permet de supporter les cas où la définition inverse est plus facile.

`DEFATTR`
: attribut pour tous les faits définis dans cette déclaration

`FACTATTR`
: attribut spécifique au fait défini

# deploydb

Le script `deploydb` permet d'interroger la base de données ou de lancer une
fonction pour traiter le contenu de la base de données

Dans ce document, `DEPLOYDBDIR` désigne le répertoire du script `deploydb`

Options
`-c, --config CONFIG`
: spécifier un fichier de configuration à charger. la valeur par défaut est
  `deploydb.conf`

  si le fichier de configuration n'est pas spécifié ou est spécifié sans chemin,
  `deploydb:path` est initialisé avec la valeur par défaut suivante:
  ~~~
  ~/etc/deploydb:/var/local/deploydb:DEPLOYDBDIR
  ~~~

  sinon, `deploydb:path` est initialisé avec le répertoire de CONFIG

`-m, --module MODULE`
: spécifier un module supplémentaire à charger. le module python effectivement
 cherché dans le path et chargé est `MODULE_module`. La liste par défaut des
 modules à charger contient un seul élément, `base`, ce qui signifie que le
 module `base_module` est chargé. Les modules permettent de définir de la
 logique pour les objets, ou l'outil à lancer.

`-r, --func FUNC`
: spécifier le nom de la fonction à lancer après le chargement des modules et
  des fichiers de configuration. La valeur par défaut est `base.query`, qui
  interroge la base de données et affiche son contenu.

  La fonction est appelée avec les arguments de la ligne de commande, sans les
  options, qui sont traitées en amont.

`--dump`
: afficher le contenu complet de la base de données, pour débugger. ignorer
  l'option `-r`

# Module base

Le module `base` chargé par défaut définit
* les objets de type `deploydb`, `host`
* la fonction `query()`

## deploydb

En créant des instances de cet objet avec des identifiants normalisés, il est
possible de modifier la configuration.

`deploydb path dir=CONFDIR`
: définir les répertoires de recherche pour les fichiers de configuration
  spécifiés sans chemin. dans ce document, cette valeur est appelée
  `deploydb:path`

`deploydb include file=CONFIG`
: définir des fichiers de configuration supplémentaire à charger. Si les
  fichiers sont spécifiés sans chemin, il sont cherchés dans `deploydb:path`

`deploydb loadcsv file=CSVFILE`
: charger des définitions d'objets depuis des fichiers CSV. Si les fichiers sont
  spécifiés sans chemin, ils sont cherchés dans `deploydb:path`

  L'attribut `otype_col` qui vaut par défaut `otype` permet de définir la
  colonne qui contient le type d'objet. L'attribut `otype` permet de spécifier
  le type d'objet si la colonne n'existe pas dans le fichier.

  L'attribut `oid_col` qui vaut par défaut `oid` permet de définir la colonne
  qui contient l'identifiant d'objet à créer.

  Toutes les autres colonnes du fichier sont utilisées pour définir les
  attributs des objets.

## host

Cet objet définit un hôte vers lequel on peut par exemple déployer un artifact.

`host * domain=DOMAIN.TLD`
: définir un domaine par défaut pour tous les hôtes spécifiés sans domaine

Les attributs suivants sont supportés:

`host`
: nom d'hôte. le domaine par défaut est ajouté le cas échéant. pour ne pas
  rajouter un domaine, spécifier le nom avec un point final e.g `localhost.`

`hostname`
: nom d'hôte sans le domaine

`domain`
: domaine sans le nom d'hôte

`ip`
: adresse IP de l'hôte

Si seul `host` est spécifié, `hostname` et `domain` sont calculés en fonction de
sa valeur.

Si seul `hostname` est spécifié, `host` est calculé en fonction de sa valeur et
de celle de `domain`

Si `ip` n'est pas spécifié, une résolution DNS est effectuée pour déterminer
l'adresse de `host`

Si l'objet est défini sans valeurs, alors la valeur finale est la liste des hôtes.

## base.query()

Interroger la base de données

XXX déterminer le format des requêtes

-*- coding: utf-8 mode: markdown -*- vim:sw=4:sts=4:et:ai:si:sta:fenc=utf-8:noeol:binary