html-antlr4

An HTML lexer & parser that provides both visitor and listener patterns to traverse the parse tree.

Overview

This is a continuous-delivery focused synthesis of the ANTLR4 HTML grammar and the Optimized ANLTR TypeScript target provided by antlr4ts.

• Releases: See the GitHub Releases page for release notes and links to the distribution.

• Feedback: Got a feature request to make, or a bug to complain about? Depending on the nature of your feedback, it probably needs to go to one of three places:

  • 📐 For the grammar (which includes the API "shape" of the generated lexer/parser), provide feedback at the ANTLR4 grammar's GitHub Issues.
  • 🔢 For the code generated based on the grammar (or the runtime it depends on), provide feedback at antlr4ts's GitHub Issues.
  • 🚀 For the deployment process (versioning, update cadence, documentation), provide feedback at our own GitHub Issues.

  If in doubt, talk to us first so we can try to point you in the right direction.

Getting started

1. Install html-antlr4 and antlr4ts as dependencies using your preferred package manager.

npm install html-antlr4 antlr4ts --save

yarn add html-antlr4 antlr4ts

2. Use your grammar in TypeScript (or JavaScript)

import { HTMLLexer, HTMLParser } from "html-antlr4";
import { ANTLRInputStream, CommonTokenStream } from "antlr4ts";

let inputStream = new ANTLRInputStream("<strong>Hello there, <i>world</i>!</strong>");

let lexer = new HTMLLexer(inputStream);
let tokenStream = new CommonTokenStream(lexer);
let parser = new HTMLParser(tokenStream);

let tree = parser.htmlDocument();

The two main ways to inspect the tree are by using a listener or a visitor, you can read about the differences between the two here.

Listener Approach

// ...
import { HTMLParserListener, HtmlElementContext } from "html-antlr4";
import { ParseTreeWalker } from "antlr4ts/tree";

class EnterHtmlElementListener implements HTMLParserListener {
  enterHtmlElement(context: HtmlElementContext) {
    console.log(`Element start line number ${context._start.line}`);
    // ...
  }

  // other enterX functions...
}

// Create the listener
const listener: HTMLParserListener = new EnterHtmlElementListener();
// Use the entry point for listeners
ParseTreeWalker.DEFAULT.walk(listener, tree);

Visitor Approach

// ...
import { HTMLParserVisitor, HtmlElementContext } from "html-antlr4";
import { AbstractParseTreeVisitor } from "antlr4ts/tree";

// Extend the AbstractParseTreeVisitor to get default visitor behaviour
class CountElementsVisitor
  extends AbstractParseTreeVisitor<number>
  implements HTMLParserVisitor<number> {

  defaultResult() {
    return 0;
  }

  aggregateResult(aggregate: number, nextResult: number) {
    return aggregate + nextResult;
  }

  visitHtmlElement(context: HtmlElementContext): number {
    return 1 + super.visitChildren(context);
  }
}

// Create the visitor
const countElementsVisitor = new CountElementsVisitor();
// Use the visitor entry point
const count = countElementsVisitor.visit(tree);
console.log(`There are ${count} elements`);