1using(3)                            ANTLR3C                           using(3)
2
3
4

NAME

6       using - Using the ANTLR3 C Target
7

Introduction

9       Using the ANTLR target involves gaining knowledge of a number of
10       elements:
11
12       1.  Writing ANTLR grammars (not covered in this manual);
13
14       2.  How ANTLR works (not covered in this manual);
15
16       3.  How to use the @sections with the C target
17
18       4.  Interoperation with the runtime within rule actions;
19
20       5.  Implementing custom versions of the standard library methods;
21
22       If you are as yet unfamiliar with how ANTLR works in general, then it
23       is suggested that you read the various wiki pages concerned with
24       getting started. However there are a few things that you should note:
25
26       • The lexer is independent of the parser. You cannot control the lexer
27         from within the parser;
28
29       • The tree parser is independent of the parser. You cannot control the
30         parser from within the tree parser(s);
31
32       • Each tree parser is independent of other tree parsers.
33
34       This means that your lexer runs first and consumes all the input stream
35       until you stop it programmatically, or it reaches the end of the input
36       stream. It produces a complete stream of tokens, which the parser then
37       consumes.
38

@sections in a C Targeted Grammar

40       Within a grammar file there are a number of special sections you can
41       add that cause the code within them to be placed at strategic points in
42       the generated code such as before or after the #include statements in
43       the .c file, within the generated header file or within the constructor
44       for the recognizer.
45
46       Many of the @sections used within a Java targeted grammar have some
47       equivalent function within a C targeted grammar, but their use may well
48       be subtly different. There are also additional sections that have
49       meaning only within a grammar targeted for the C runtime.
50
51       Detailed documentation of these sections is given here: Using Sections
52       Within Grammar Files
53

Interoperation Within Rule Actions

55       Rule actions have a limited number of elements they can access by name,
56       independently of the target language generated. These are elements such
57       as $line, $pos, $text and so on. Where the $xxx returns a basic type
58       such as int, then you can use these in C as you would in the Java
59       target, but where a reference returns a string, you will get a pointer
60       to the C runtime string implementation pANTLR3_STRING. This will give
61       you access to things like token text but also provides some convenience
62       methods such as pANTLR3_STRING->substring() and
63       pANTLR3_STRING->toUTF8().
64
65       The generated code provides a number of C MACROs, which make it easier
66       to access runtime components. Always use these macros when available,
67       to protect your action code from changes to the underlying
68       implementation.
69
70       Detailed documentation of macros and rule action interoperation is
71       given here: Interoperation Within Rule Actions
72

Implementing Customized Methods

74       Unless you wish to create your own tree structures using the built in
75       ANTLR AST rewriting notation, you will rarely need to override the
76       default implementation of runtime methods. The exception to this will
77       be the syntax err reporting method, which is essentially a stub
78       function that you will usually want to provide your own implementation
79       for. You should consider the built in function
80       displayRecognitionError() as an example of where to start as there can
81       be no really useful generic error message display.
82
83
84
85Version 3.3.1              Wed Jul 19 2023 00:00:00                   using(3)
Impressum