Requirements

NOTE: this document describes the original requirements for prototyping
gentrex. It is generic, the actual implementation fills in some details
and has a more precise terminology especially around implementation details.


The lib supports queries on trees. This set of requirement does not
imply API details, only semantics on a high level. The caller is responsible
for presenting a tree and a query expression. The lib is responsible for
running the expression and return matches.

R1. Queries are evaluated on a tree. The tree consists of nodes.
    Nodes can be referenced (by unique IDs or pointers, it's up
    to the implementation; gentrex uses void * pointers at the moment).
    The tree has a root node, the query call to the library
    will specify this root node. The caller provides ways to hop
    from one node to another:
      - next: to the next sibling of the node to the right
      - child: to the first child of the node
      - parent: to the parent node
    Either of these can return NULL. (NULL means "no node referenced")

R2. A query gets a root node, an expression and a query state.

R3. There is a call for resetting a query state. It may be possible to
    preload query state with values in case the query may depend on such
    external values.

R4. A query updates the query state and returns the next match in the tree.
    Thus the query can be considered as an iterator. The tree is not to be
    changed during the iteration - this is the responsibility of the caller.

R5. The query call may use the state to communicate details of the match
    to the caller.

R6. The query call indicates if there was no (more) match. The caller
    should not issue subsequent calls with the same state after such
    an indication.