atsections(3)

✨ atsections — Using Sections Within Grammar Files ✨

okay bestie, welcome to the ANTLR3C corner of the manual where we talk about sticking @-annotations into your grammar files. it's giving "decorate your grammar, get code placed exactly where you want it" and honestly? iconic.

---

💖 Introduction 💖

so a C-targeted grammar can absolutely use special annotations inside the grammar file, and they all start with the @ character. these sections make the stuff you put in them land at defined spots in the generated code — like, say, inside the generated C header file. main character placement energy fr fr.

the general form of these annotations is literally this:

section
  : '@' (( 'parser' | 'lexer' ) '::')? SECTIONNAME '{' yourcode '}'
  ;

now here's the tea: if you leave out the parser or lexer keywords, the ANTLR tool just assumes stuff on your behalf — a lexer target for a lexer grammar, a parser target for a parser or tree parser grammar, and a parser target for a combined lexer/parser grammar. and like, the docs are politely begging you: as a matter of course, include the parser or lexer target keyword. don't make the tool guess, bestie. 🙈

documentation about the @sections available for a grammar targeted at C starts right now. let's go. 🦋

---

🎀 Sections @init and @declarations 🎀

Java targeted grammars let you drop the special section @init after a rule's declaration (that's lexer, parser and tree parser rules, for the record). this lets you both declare and initialize variables that are local to the code generated for that rule, and then you can reference them inside your rule action code. cute, right?

with the C target though, the generated code has to live under the restrictions of C semantics — which means you must declare any local variables first, then assign to them afterwards. so alongside the @init section (which C programmers should use to initialize their local variables), the C target also gives you the @declarations section, which is also a rule based section. that's where the C programmer should declare the local variables, so declaration and initialization stay separated like they're supposed to. separation slay. 💅

here's an example:

translation_unit
@declarations
{
    pANTLR3_BOOLEAN hasUsing;
}
@init
{

    // Assume no Using directives
    //
    hasUsing = ANTLR3_FALSE;

}
    : rulea ruleb ...

using the @declarations and @init sections guarantees your generated code will compile correctly on any standard C compiler — assuming, of course, that you typed in valid C code. no pressure or anything. 😭

---

👑 @header section. 👑

the @parser::header or @lexer::header annotations cause the code they encapsulate to be placed at the start of each generated file, regardless of whether it's a .c or a .h file. perfect for inserting copyright information and so on into all your generated files. chef's kiss.

NOTE: be careful not to confuse this concept with placing code in the generated .h header file!! the name choice is unfortunate, but it was already used in the Java target to allow placement of imports statements in generated java classes. so the intent of this section has been kept the same. it's not a bug, it's a legacy vibe. iykyk.

here is an example:

@lexer::header
{
  // Copyright (c) Jim Idle 2007 - All your grammar are belong to us.
}

@parser::header
{
  // Copyright (c) Jim Idle 2007 - All your grammar are belong to us.
}

---

🌸 @includes section 🌸

the @parser::includes or @lexer::includes annotations cause the code they encapsulate to be placed in the generated .h file, after the standard includes required by the ANTLR generated code.

here you could, for instance, place a #include statement so your grammar code pulls in some standard definitions. but listen — because you may use multiple parsers and lexers in your solution, you should probably not place #define statements here, but in the @postinclude section instead. that way you can create different #defines for different recognizers. organization? we love her. 💖

here is an example:

@lexer::includes
{
  #include "myprojectcommondefs.h"
}

@parser::includes
{
  #include "myprojectcommondefs.h"
}

---

🧚 @preincludes section 🧚

the @parser::preincludes or @lexer::preincludes annotations cause the code they encapsulate to be placed in the generated .h file, before the standard includes required by the ANTLR generated code.

use this section when you want to place #defines and other definitions in the code before the standard ANTLR runtime includes defined them. that lets you override any predefined symbols and options that the includes would otherwise take defaults for. for instance, if you've built a version of the runtime with a special version of malloc, you can #define #ANTLR3_MALLOC to match the definition you used for the ANTLR runtime library. get in before the defaults, bestie. 🔥

---

🌈 @postinclude section 🌈

the @parser::postinclude or @lexer::postinclude annotations cause the code they encapsulate to be placed in the generated .C file, after the generated include file (which includes the standard ANTLR3C library includes).

code you place here will then be subject to any macros defined by your own includes, by the generated include, and by the standard ANTLR3 includes. this is a great place to #undef anything whose default values you don't like, but can't override before the includes define them. take back control. 😤

this is also a great place to #define any macros you may wish to use in the generated .c file. and here's the thing — since you can include multiple parsers in your projects, you'll need to include the generated .h file of each of them, possibly globally, but almost certainly in a context where you're including more than one .h file simultaneously. so if you commonly use the same macro names for accessing structures and so on, and they change from grammar to grammar, you should define them here to avoid creating conflicting definitions in the header files. conflict-free queen behavior, periodt. 💅✨

---

and that's the whole page, bestie. this was Version 3.3.1, dated Tue Jul 29 2025 00:00:00 — go forth and annotate your grammars, you absolute icon. 🫶👑