Cameleon2: Tdl

Tdl

Tdl is a simple library to represent, store and read TODO lists in XML files. An additional library, Tdl_gui, can be used to display and edit such files in LablGtk2 applications.

A TODO list is a tree of groups; each group may contain items (corresponding to tasks) and other groups.

The tdl.{x,byte} program included in Cameleon uses this library to allow the edition of such files with a graphical interface. tdl_export.{x,byte} is a command-line tool to merge and filter TODO lists, or export such lists to RSS format. tdl2html.{x,byte} can be used to generate HTML code or a complete HTML page from a given TODO list. The use of these tools is explained further.

At last, a "tdl" view using this library is available in Chamo.

Library documentation reference

The documentation generated by OCamldoc can be browsed here: Tdl, Tdl_gui.

The tdl tool

The tdl.{x,byte} program allows the edition of TODO lists files in a graphical interface. The file to edit is given in parameter on the command line:

tdl.x file.tdl

The tdl_export tool

The tdl_export.{x,byte} tool can be used to merge of filter TODO lists. The result is a new TODO list, or a XML document in RSS format built using the dates of items of the final TODO list.

Examples

Merging the TODO lists of files f1.tdl, f2.tdl and f3.tdl. The result (the final TODO list) is printed on standard output.

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

The same result can be obtained with the following command, since "-" as filename indicates to read a TODO list on standard input:

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

A filter can be given in parameter. This filter is applied on each read TODO list and allows to select only some groups or items matching the filter. The syntax of filters in given further. In the command below, we only keep items in "done" state and non empty groups:

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

It is also possible to generate a XML document in RSS format instead of a new TODO list, for example to indicate the completed tasks (with "done" state), as in the following command:

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

At last, one can split the final TODO list in various TODO lists, one per day, by using the end date of each item. The prefix of generated files is given in parameter to the "--split-by-day" option. The generated files are named "prefix-<year>-<month>-<day>.tdl":

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

Filters

A small language allows to define filters on TODO lists, that is conditions on groups and items to select them. Here is a description of this language in BNF-style:

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]+

The REGEXP is a regular expression as the ones of the Str module of Objective-Caml.

DATETIME can be for example "2007-08-08" or "2007-08-08 23:12:07". If no time is give, then hour, minute and second are considered to be 0.

As you can see, filters on groups and items are indicated together in one expression. This is just to simplify the expression of filters. When a filer is applied on a TODO list, this filter is first splitted in two: one filter for groups and another filter for items, since some filters are invalid for items (like "empty") and some are invalid for groups (like "state:"). For example the filter "state: done and not empty" will give two filters: "state: done" for items and "not empty" for groups.

The tdl2html tool

The tdl2html.{x,byte} tool generates HTML code or a HTML page from a given TODO list. The TODO list is read on standard input and the HTML code is printed to the standard output. The available options can be obtained with the command

tdl2html.x --help