Document the frontend's NLTK -> tableau conversion (#79)

Author: jgonggrijp

frontend/src/app/services/parse.service.ts

@@ -11,8 +11,10 @@ export type ParseResponse = any;
 export class ParseService {
     private http = inject(HttpClient);
 
+    // Sink for triggering parse-and-prove requests to the backend.
     public submit$ = new Subject<ParseInput>();
 
+    // Raw responses from the backend.
     public parse$ = this.submit$.pipe(
         switchMap((form) =>
             this.http.post<ParseResponse>("/api/problem/parse", form).pipe(
@@ -25,10 +27,19 @@ export class ParseService {
         share()
     );
 
+    // Proofs from the response in a format that is easier to handle than the
+    // stringly NLTK.Tree serialization.
     public proofs$ = this.parse$.pipe(map(extractProofs));
 }
 
+/**
+ * Given a `{data: {ccg_trees, proofs}}` response from the backend, tease out
+ * the `proofs` and apply the `nltk2tableau` transformation to each proof
+ * within.
+ */
 function extractProofs(response: ParseResponse) {
+    // This is basically just `_.mapObject(response.data.proofs, nltk2tableau)`,
+    // but we don't depend on Underscore yet.
     const {entailment, contradiction} = response.data.proofs;
     return {
         entailment: nltk2tableau(entailment),
@@ -40,21 +51,65 @@ const emptyTableau = (): any => ({nodes: []});
 const pairNodes = (other: any[]) =>
     (node: any, index: number) => [node, other[index]];
 
+/**
+ * Given a single proof in serialized NLTK.Tree format, return the same proof in
+ * a more convenient format where each node has explicitly labeled `id`, `rule`,
+ * `mod`, `head`, `args` and `sign`.
+ *
+ * This function can handle proof trees of arbitrary depth without causing a
+ * stack overflow.
+ */
 export function nltk2tableau(nltk: any) {
     const tree = emptyTableau();
+    // We will be using trampolining instead of recursion. A general but
+    // admittedly not very helpful description can be found in the first bullet
+    // of
+    // https://en.wikipedia.org/wiki/Trampoline_(computing)#High-level_programming.
+    // The gist is this: instead of recursing, functions return pieces of work
+    // ("thunks") that should be executed next. The trampoline, which in this
+    // case is the current function, takes care of executing the thunks.
+
+    // The list of thunks to execute. One will be added for each tree node, one
+    // will be taken off on each iteration. Since we are always calling
+    // `nltkNode2tableauNode`, we leave this implicit in the thunk
+    // representation. It consists only of the arguments that we are passing to
+    // the function.
     const todo = [[nltk, tree]];
+    // The core of the trampoline. Process one thunk at a time. We know we are
+    // done when the list is empty.
     while (todo.length) {
+        // The algorithm is written such that the order in which we process
+        // child nodes does not matter, so we can simply pop thunks off the back
+        // of the todo list. tsc is apparently unable to infer that `todo` is
+        // guaranteed to be nonempty on the next line, hence the silencing
+        // comment.
         // @ts-ignore
         let task: [any, any] = todo.pop();
+        // Processing a thunk might produce zero or more new thunks, depending
+        // on the number of children of the processed node.
         let newTasks = nltkNode2tableauNode(...task);
         todo.push(...newTasks);
     }
     return tree;
 }
 
+/**
+ * Internal function that maps a single serialized NLTK.Tree node to an
+ * explicitly structured node inside `tree`. This function relies on an external
+ * trampoline (in `nltk2tableau`) and returns thunks instead of recursing into
+ * child nodes.
+ */
 function nltkNode2tableauNode(nltk: any, tree: any) {
+    // `nltk` is in a strictly nested format: each node contains its children.
+    // Our own format does not follow this rule: chains of nodes with single
+    // children are stored as adjacent elements in an array. `tree` is the
+    // object that contains this array (`tree.nodes`). When there is a
+    // bifurcation, the subtrees are stored inside `tree` rather than in the
+    // bifurcating node.
     const node: any = {};
     tree.nodes.push(node);
+    // Tease out the different parts of the stringified node payload. The
+    // following lines will be rewritten using regular expressions.
     const lines = nltk.node.split('\n');
     if (lines[0] === 'Closed') {
         node.rule = lines[1];
@@ -82,13 +137,27 @@ function nltkNode2tableauNode(nltk: any, tree: any) {
     } else if (lines[0] !== 'Model') {
         node.head = nltk.node;
     }
+    // With the node itself having been decoded, now comes the part where a
+    // "normal" function would recurse and where we return follow-up thunks
+    // instead.
     if (!nltk.children || !nltk.children.length) {
         node.end = true;
+        // Leaf node. No recursion, no thunks.
         return [];
     }
     if (nltk.children.length === 1) {
+        // Node with one child, the most common case. The child will be appended
+        // to `tree.nodes` after the current node.
         return [[nltk.children[0], tree]];
     }
+    // Multiple children. Most likely two, but the code would transparently
+    // support larger numbers of children. We create empty subtrees so we can
+    // pass those in the thunks as containers for the child nodes. The fact that
+    // the subtrees have already been created, is what makes it possible to
+    // process the children in arbitrary order.
     tree.subtrees = nltk.children.map(emptyTableau);
+    // We essentially do a `_.zip(nltk.children, tree.subtrees)` in order to
+    // create the thunks. I could have fumbled with `Iterator.zip` instead, but
+    // that feels like more hassle and the polyfill would be huge.
     return nltk.children.map(pairNodes(tree.subtrees));
 }