emitting non-strings

[bakkot]

For ecmarkup, I need to associate the generated HTML productions with their original Production objects. The obvious way to do that is to make an emitter which creates JSDom nodes directly and sticks them in a WeakMap pointing back to the original object. But the Emitter API is string-based. Would it be possible to allow more general emitters which support emitting other types?

My current workaround is to assume that the production and emu-rhs elements are in the same order as in the original and index each list, which seems to work. So there's no urgency in supporting this.

Sidebar: as a question of API design, why is the emitter a property of the grammar? I would expect it to be passed in to the emit method. (That would be helpful here because then the emit method could have a type parameter for the type produced by the emitter, which doesn't work when the emitter is state instead of being an argument.)

[bakkot]

It occurs to me that I could just write something which walks over the grammar's rootFiles and does the emitting manually, bypassing the Emitter infrastructure entirely. Maybe that's better than trying to support this use case in grammarkdown itself. I'll leave this open pending thoughts from others, though.

[rbuckton]

The easiest way to do this with a custom emitter would be to use emitString and ignore the string result while using a property to track the current node, i.e.:

class ObjectEmitter extends Emitter {
    document: HTMLDocument;
    currentNode: HTMLElement;

    ...

    protected emitProduction(node: Production) {
        const linkId = this.resolver.getProductionLinkId(node.name);
        this.emitLinkAnchor(linkId);

        const node = this.document.createElement("emu-production");
        node.setAttribute("name", node.name.text);

        // push the new node as the currentNode
        const container = this.currentNode;
        this.currentNode = node;

        // NOTE: parameterList is written to attributes on `this.currentNode`
        this.emitNode(node.parameterList);

        if (node.colonToken) {
            switch (node.colonToken.kind) {
                case SyntaxKind.ColonColonToken:
                    node.setAttribute("type", "lexical");
                    break;

                case SyntaxKind.ColonColonColonToken:
                    node.setAttribute("type", "regexp");
                    break;
            }
        }

        if (node.body) {
            if (node.body.kind === SyntaxKind.OneOfList) {
                node.setAttribute("oneof", "oneof");
            }
            else if (node.body.kind === SyntaxKind.RightHandSide) {
                node.setAttribute("collapsed", "collapsed");
            }
        }

        this.emitNode(node.body);

        container.appendChild(this.currentNode);

        // restore the previous node
        this.currentNode = container;
    }

    ...

    private emitLinkAnchor(linkId: string | undefined) {
        if (linkId && this.options.emitLinks) {
            const link = this.document.createElement("a");
            link.setAttribute("name", linkId);
            this.currentNode.appendChild(link);
        }
    }
}

and elsewhere:

const document = ...; // JSDom document
const rootElement = ...; // JSDom element or maybe a document fragment
const grammar = ...;
await grammar.check();
for (const rootFile of grammar.rootFiles) {
    const emitter = new CustomEmitter(document, rootElement);
    emitter.emitString(rootFile, grammer.resolver, grammar.diagnostics);
}

Sidebar: as a question of API design, why is the emitter a property of the grammar? I would expect it to be passed in to the emit method. (That would be helpful here because then the emit method could have a type parameter for the type produced by the emitter, which doesn't work when the emitter is state instead of being an argument.)

Mostly because Grammar is kind of a one-stop-shop for interacting with Grammarkdown, and I wanted it to be easy to just do

const grammar = new Grammar(files);
await grammar.emit();

Even so, its still designed to be fairly flexible. You can subclass Grammar to provide a custom binder, checker, resolver, emitter, etc., or just use a custom emitter standalone.