Cameleon2: Tdl

Tdl

Tdl est une petite bibliothèque pour représenter, écrire et lire des listes de choses à faire ("TODO lists") dans des fichiers XML. Une bibliothèque additionnelle, Tdl_gui, peut être utilisée pour afficher et éditer ces fichers dans des applications utilisant LablGtk2.

Une TODO list est une arboresence de groupes, chacun pouvant contenir des items (correspondants aux tâches) et d'autres groupes.

Le programme tdl.{x,byte} inclus dans Cameleon utilise cette bibliothèque pour permettre l'édition de tels fichiers par une interface graphique. tdl_export.{x,byte} est un programme en ligne de commande permettant de fusionner, filtrer des TODO lists ou encore d'en exporter au format RSS. tdl2html.{x,byte} permet quant à lui de générer du code HTML ou une page HTML d'après une TODO list. L'utilisation de ces outils est expliquée plus loin.

Enfin, une vue "tdl" utilisant cette bibliothèque est disponible dans Chamo.

Documentation de référence de la bibliothèque

La documentation générée par OCamldoc est accessible ici: Tdl, Tdl_gui.

L'outil tdl

Le programme tdl.{x,byte} permet d'éditer graphiquement des TODO lists. Le fichier à éditer est donné en argument sur la ligne de commande:

tdl.x file.tdl

L'outil tdl_export

L'outil tdl_export.{x,byte} permet de fusionner et/ou filtrer des TODO lists. Le résultat peut être une nouvelle TODO list ou bien un document XML au format RSS, construit en utilisant les dates des tâches de la TODO list finale.

Exemples d'utilisation

Fusionner les TODO list des fichiers f1.tdl, f2.tdl et f3.tdl. Le résultat (la TODO finale) est affiché sur la sortie standard.

tdl.x f1.tdl f2.tdl f3.tdl

Le même résulatt peut être obtenu par la commande suivante, car "-" comme nom de fichier indique de lire une TODO list sur l'entrée standard:

cat f2.tdl | tdl.x f1.tdl - f3.tdl

Un filtre peut être indiqué en paramètre. Ce filtre est appliqué à la lecture de chaque TODO list et permet de n'en sélectionner que les groupes et les items qui correspondent au filtre. La syntaxe des filtres est donnée plus loin. Dans la commande ci-dessous, nous ne conservons que les items en état "done" et les groupes non vides:

tdl.x f1.tdl f2.tdl f3.tdl --filter 'not empty and state: done'

Il est possible de générer un document XML au format RSS au lieu d'une nouvelle TODO list, par exemple pour indiquer les tâches réalisées (état "done"), comme dans la commande suivante:

tdl.x f1.tdl f2.tdl f3.tdl --filter "state: done" --rss > output.rss

Enfin, il est possible de découper la TODO list finale en plusieurs TODO lists, une par jour, en utilisant la date de fin de chaque item. Le préfixe des fichiers généré est donné en paramètre de l'option "--split-by-day". Les fichiers générés sont de la forme "préfixe-<année>-<mois>-<jour>.tdl":

tdl.x f1.tdl f2.tdl f3.tdl --filter "state: done" --split-by-day /tmp/things-done

Les filtres

Un petit langage permet de définir des filtres sur les TODO lists, c'est-à-dire des conditions sur les groupes et les items pour les sélectionner. Voici une description de ce langage dans le style BNF:

FILTER ::=
| group: REGEXP
| item: REGEXP
| empty
| state: STATE
| desc: REGEXP
| before DATETIME
| FILTER and FILTER
| FILTER or FILTER
| not FILTER
| ( FILTER )

STATE ::=
| done
| suspended
| high
| normal
| low

REGEXP ::=
| quoted_string
| [^'\n' '"' '(' ')' ' ' '\009' '\012' ':' '/' '<' '>']+

DATETIME ::=
| [0-9]+-[0-9]+-[0-9]+
| [0-9]+-[0-9]+-[0-9]+ [0-9]+:[0-9]+:[0-9]+

REGEXP est une expression régulière comme celles du module Str d'Objective-Caml.

DATETIME peut être par exemple "2007-08-08" ou "2007-08-08 23:12:07". Si aucune heure n'est indiquée, l'heure, la minute et la seconde sont considérées comme étant à 0.

Comme on peut le voir, les filtres sur les groupes et les items sont indiqués ensemble dans la même expression. C'est pour simplifier l'expression des filtres. En réalité, quand un filtre est appliqué à une TODO list, il est séparé en deux filtres: l'un pour les groupes, l'autre pour les items. En effet, certains filtres sont invalides pour les groupes (comme "state: done") tandis que d'autres sont invalides pour les items (comme "empty"). Par exemple le filtre "state: done and not empty" donnera deux filtres: "state: done" pour les items et "not empty" pour les groupes.

L'outil tdl2html

L'outil tdl2html.{x,byte} génère du code HTML ou une page HTML à partir d'une TODO list. La TODO list est lue sur l'entrée standard et le code HTML est affiché sur la sortie standard. La liste des options est accessible par la commande

tdl2html.x --help