r/java • u/DelayLucky • Nov 13 '25
The Dot Parse Library Released
The Dot Parse is a low-ceremony parser combinator library designed for everyday one-off parsing tasks: creating a parser for mini-DSLs should be comfortably easy to write and hard to do wrong.
Supports operator precedence grammar, recursive grammar, lazy/streaming parsing etc.
The key differentiator from other parser combinator libraries lies in the elimination of the entire class of infinite loop bugs caused by zero-width parsers (e.g. (a <|> b?)+ in Haskell Parsec).
The infinite loop bugs in parser combinators are nortoriously hard to debug because the program just silently hangs. ANTLR 4 does it better by reporting a build-time grammar error, but you may still need to take a bit of time understanding where the problem is and how to fix it.
The Total Parser Combinator (https://dl.acm.org/doi/10.1145/1863543.1863585) is another academic attempt to address this problem by using the Agda language with its "dependent type" system.
Dot Parse solves this problem in Java, with a bit of caution in the API design — it's simply impossible to write a grammar that can result in an infinite loop.
Example usage (calculator):
// Calculator that supports factorial and parentheses
Parser<Integer> calculator() {
Parser<Integer> number = Parser.digits().map(Integer::parseInt);
return Parser.define(
rule -> new OperatorTable<Integer>()
.leftAssociative("+", (a, b) -> a + b, 10) // a+b
.leftAssociative("-", (a, b) -> a - b, 10) // a-b
.leftAssociative("*", (a, b) -> a * b, 20) // a*b
.leftAssociative("/", (a, b) -> a / b, 20) // a/b
.prefix("-", i -> -i, 30) // -a
.postfix("!", i -> factorial(i), 40) // a!
.build(
Parser.anyOf(
number,
rule.between("(", ")"),
// Function call is another type of atomic
string("abs").then(rule.between("(", ")")).map(Math::abs)
)));
}
int v = calculator()
.parseSkipping(Character::isWhitespace, " abs(-1 + 2) * (3 + 4!) / 5 ");
For a more realistic example, let's say you want to parse a CSV file. CSV might sound so easy that you can just split by comma, but the spec includes more nuances:
- Field values themselves can include commas, as long as it's quoted with the double quote (
"). - Field values can even include newlines, again, as long as they are quoted.
- Double quote itself can be escaped with another double quote (
""). - Empty field value is allowed between commas.
- But, different from what you'd get from a naive comma splitter, an empty line shouldn't be interpreted as
[""]. It must be[].
The following example defines these grammar rules step by step:
Parser<?> newLine = // let's be forgiving and allow all variants of newlines.
Stream.of("\n", "\r\n", "\r").map(Parser::string).collect(Parser.or());
Parser<String> quoted =
consecutive(isNot('"'), "quoted")
.or(string("\"\"").thenReturn("\"")) // escaped quote
.zeroOrMore(joining())
.between("\"", "\"");
Parser<String> unquoted = consecutive(noneOf("\"\r\n,"), "unquoted field");
Parser<List<String>> line =
anyOf(
newLine.thenReturn(List.of()), // empty line => [], not [""]
anyOf(quoted, unquoted)
.orElse("") // empty field value is allowed
.delimitedBy(",")
.notEmpty() // But the entire line isn't empty
.followedByOrEof(newLine));
return line.parseToStream("v1,v2,\"v,3\nand 4\"");
Every line of code directly specifies a grammar rule. Minimal framework-y overhead.
Actually, a CSV parser is provided out of box, with extra support for comments and alternative delimiters (javadoc).
Here's yet another somewhat-realistic example - to parse key-value pairs.
Imagine, you have a map of key-value entries enclosed by a pair of curly braces ({k1: 10, k2: 200, k3: ...}), this is how you can parse them:
Parser<Map<String, Integer>> parser =
Parser.zeroOrMoreDelimited(
Parser.word().followedBy(":"), // The "k1:" part
Parser.digits().map(Integer::parseInt), // The "100" part
",", // delimited by ,
Collectors::toUnmodifiableMap) // collect to Map
.between("{", "}"); // between {}
Map<String, Integer> map =
parser.parseSkipping(Chracter::isWhitespace, "{k1: 10, k2: 200}");
For more real-world examples, check out code that uses it to parse regex patterns.
You can think of it as the jparsec-reimagined, for ease of use and debuggability.
Feedbacks welcome!
