changes31(3)

🎀 NAME 🎀

changes31 — the glow-up notes: what changed in 3.1 vs 3.0, bestie edition, brought to you by the ANTLR3C girlies ✨

okay so listen. this whole page is the receipts on everything that shifted between 3.0 and 3.1. some of it might lowkey require tiny lil changes to your grammar files, or to the programs that call your grammar. so pls, actually read the whole list, because future you will be SO grateful and it might literally save you time later 🫶

---

🧸 Constructor Return Values

back in the day (previous releases), the return value from both the generated constructors and the built-in constructor functions would hand you back a value of -1 or -2 if something went sideways.

but here's the tea: the only problem that can really occur is lack of memory. so, to dodge that far-off possibility that some memory allocation scheme would return an address of -1 for a pointer, the return address is now NULL if there was no memory available. no cap.

and the old macros for this mechanism? removed. gone. which, yes, forces you to read this information 🙈. now you literally only need to check the return address for NULL — or you could just not bother and join with 95% of the world's C code 💀 iconic behavior honestly.

---

🌳 Tree Parser Rewrites

the 3.1 runtime now supports tree rewrites from tree parsers! slay. see the main ANTLR documentation for more details ✨

🚨 heads up: this beta version contains Known Issues regarding the release of memory allocated to tree nodes when they are rewritten in some combinations of re-writing tree parsers. these issues will be corrected before release. so like, it's giving "we're working on it" 💅

---

🐛 ANTLRWorks Debugger

the ANTLRWorks debugger is now fully supported by this version of the runtime, periodt 💖

• it supports remote debugging only — you cannot generate C, compile and debug it from the ANTLRWorks IDE. nope, not a vibe.
• however, both parser and tree parser debugging is supported, providing you're using a version of ANTLRWorks that supports tree parser debugging 🦋
• generate the C code with the -debug option of the ANTLR tool, as per any other target.

😭 real talk: when you invoke your debugging version of the parser, it will appear to hang but is in fact waiting on a local TCP socket connection from the ANTLRWorks debugger. and since the target environment is unknown, it is not prudent to generate notification status messages using something like printf, because the target environment may not have a console or implement printf. so like... don't do that.

---

💅 Macro Changes

prior to the 3.1 release, accessing the token source of a lexer required knowledge of where the token source pointer was located within the lexer. messy.

in 3.1, the token source got buried further in the innards of the C runtime, and that kind of knowledge is considered irrelevant and confusing. so when you're creating a token stream from a token source, it is now mandatory to use the new C macro TOKENSOURCE(lxr), which will expand to point at the token source interface. and this MACRO will be maintained across future versions 🫶 (promise).

you can see how to use it in the downloadable examples, available from the downloads page of the ANTLR web site. here's the relevant code for creating a token stream, extracted from those examples:

tstream = antlr3CommonTokenStreamSourceNew(ANTLR3_SIZE_HINT, TOKENSOURCE(lxr));

---

🌈 and that's the whole page, bestie! this was brought to you by Version 3.3.1, dated Tue Jul 29 2025 00:00:00 — go forth and debug responsibly 👑💜