SARE
Simple API for Regular Expressions: event-based matching, where each capture group gets an action. Begun beside FIRE/J in 2006, rebuilt for JDK 21 in 2026.
Java's regular expression API hands you a Matcher and leaves you to walk it — loop, ask which group you are in, pull the text out, branch. SARE inverts that the way SAX inverts XML parsing: you assign an action to a group, and the parser calls it for every match that group takes part in.
It began in 2006 as a byproduct of FIRE/J, as a post from that March says; the code in the repository is from 2012 and 2013. In October 2026 it was rebuilt for JDK 21 and published as release 3.0.0.
Using it
An action only has to implement match, so it can be a lambda, and a group can be named:
RegexParser sare = new RegexParser("(?<key>\\w+)=(?<value>\\w+)");
sare.assignAction("key", (group, full, text) -> System.out.println("key " + text));
sare.assignAction(2, (group, full, text) -> System.out.println("value " + text));
sare.process("host=example, port=8080"); // returns 2key host value example key port value 8080
An action that has to open something before the parse, or close it afterwards, implements IGroupAction whole, with start() and end(). Each runs once per process call, however many groups the action is assigned to, and end() runs even when reading the input failed. Within a match, actions are called in group order. A group that took no part in a match, like (b) in (a)|(b) against a, is not reported. Building it is mvn on JDK 21 or later; there are no dependencies.
Input
| Method | Reads |
|---|---|
process(CharSequence) | the text as it is |
process(BufferedReader) | one line at a time, so memory holds a line rather than the input, and a match never crosses a line break |
process(InputStream) | the whole stream, decoded as UTF-8 or in a charset you pass, then matched as one text |
Each returns the number of matches. Read errors go to an error handler you can replace. An exception thrown by an action is not a read error, and it leaves process as it is.
Where it stops
- For one action over a short text, the JDK is enough. Since Java 9,
pattern.matcher(text).results()is a stream of matches. SARE is worth it when several actions share one parse, or when they have something to set up and tear down around it. - Only line-by-line input is streamed. A string or a byte stream is held in memory whole.
- The matcher is the JDK's.
java.util.regexfinds the leftmost-first match, with backtracking.
What changed in 2026
The 2013 build targeted Java 1.6, which no JDK since 12 compiles. The package, the class names and the two calls above are as they were. Underneath, three defects had been there all along. Reading from a BufferedReader never worked: at the end of the input the loop matched the null that marks it, failed, and returned 0 whatever had matched. start() and end() ran once per group rather than once per parse, so the 2013 README's own example, one action on five groups, printed "Starting" and "End" five times each. And an invalid expression was printed and left a parser with no pattern, which failed later with a NullPointerException; it is now refused when the parser is built. Actions can be lambdas now, groups can be named, and the example became a test suite. The repository keeps a changelog (external link, opens in a new tab) with the rest.
Source
- bkarak/sare (external link, opens in a new tab)
- Changelog — what changed in each release (external link, opens in a new tab)
BSD 3-Clause, copyright Vassilios Karakoidas.