Section 3.1.1 User's Manual Question on $code require

[slipbits]

I've included my understanding of a few sections in the Bison User's 
Manual. What I am confused about is whether the declarations in %code 
require { declarations } are included in both the header file, if 
%header is given, and the source file (basename.<ext>). The text in the 
User's Manual, pg. 50 says  “and the new YYLTYPE definition before the 
Bison-generated YYSTYPE and YYLTYPE definitions in both the parser 
implementation file and the parser header file", which seems to say that 
it is.

thanks
art


     3.1 Outline of a Bison Grammar

The input Bison file contains 3 sections, {Declarations, Grammar Rules, 
Epilog}. The Declarations must precede the Grammar Rules, which must precede 
the Epilog Section. As in:

Declarations
%%
Grammar Rules
%%
Epilog

All Sections are optional except the Grammar Rules Section.

The Declarations Section consists of intermixed Prologue Declarations and Bison 
Declarations. The Prologue Declarations contains language specific declarative 
statements. The Bison Declarations contains Bison specific declarations, 
declarative statements which generate language specific output and execution 
time environmental directives (such as the names of files). This section is 
only concerned with declaration directives which cause generation of language 
specific declarations.

There may be many Prologue and Bison Declarations given in any order. There can 
only be one Grammar Rules Section and Epilog Section. The Prologue and Bison 
Declarations terminate when the Grammar Rules sections starts. After Grammar 
Rules are initiated, no Prologue or Bison Declaration statements are allowed.

The Prologue and Declaration Sections act in concert. The Prologue Declaration data 
is moved verbatim to the generated parser file, and some Bison Declarations cause 
output of data to the generated parser file,/basename/.<ext>. The Bison 
statements themselves are not copied to the generated parser, only the generated code.

For purposes of this section,/basename/.y is the Bison input file, 
and/basename/.<ext> is the generated parser file, where <ext> is the language 
specific suffix.

3.1.1 Order Independent Declarations
The Prologue Declarations and Bison Declarations are put in the generated parser file, 
or/basename/.<ext>, or header file,/basename/.h, or imported file in the order seen. 
That is, if the order of appearance in/basename/.y is “B P P B P”, then the order of 
elements in the generated parser file is “B P P B P” where P stands for Prologue 
Declarations and B stands for Bison*Declerations*  in/basename/.y and Declaration 
expansions in/basename/.<ext>.

The Prologue Declarations determines the content of language specific 
statements to be copied to the generated parser code. Positioning  preserves 
the application specific dependency order of statements, that is, when there is 
a dependency order where one statement must precede another, positioning allows 
preservation of that order. Positioning is strictly a consequence of the 
placement of the Prologue Declaration in/basename/.y.

An example of a dependency in C/C++ is:
typedef YYSTYPE YYSTYPE;
func(YYSTYPE x);

whereYYSTYPE  must be known before the function prototype is declared. If the 
order were reversed:
void func(YYSTYPE x);
typedef YYSTYPE YYSTYPE;

the function prototype would be incorrect because YYSTYPE was unknown.

In Bison this ordering is guaranteed by using:
%{
    typedef YYSTYPE YYSTYPE;
    void func(YYSTYPE x);
%}

or
%{typedef YYSTYPE YYSTYPE; %}
%{ void func(YYSTYPE x); %}

where “%{ declarations %}” is defined as a/Prologue Definitinn Block //(PDB)/. 
“%{  %}” is legal.

This is more complicated when there are Bison Declarative dependencies. In this case, 
a Bison Declarative generates code copied to/basename/.<ext> in which either 
other Bison Declaratives have a dependency or in which there is source dependency. In 
this case, the order of Prologue Dependencies must be sensitive the the Bison 
Declaratives.

Let’s consider the example above. As it turns our, YYSTYPE is determined by 
using the Bison Declarative %union. Suppose we have the following statements:
typedef int X;          // C/C++
%union { X Y }          // Bison Declarative
void func(YYSTYPE x);   // C/C++

What we have is that %union is dependent on the typedef, and the 
functionprototype is dependent on %union. How should be arrange our Prologue 
Directive and Dison Directives to ensure that the dependencies are supported. 
(This is an easy case, mind you):
%{ typedef int X;       %}           // C/C++
%union { X Y }               // Bison Declarative
%{ void func(YYSTYPE x); %}  // C/C++

The first Prologue Directive gets copied verbatim to/basename/.<ext>, the code generated by 
the Bison Declarative gets put into/basename/.<ext> next, and finally the 2^nd    Prologue 
Directive gets copied verbatim to/basename/.<ext>.

This is a simple case. More complex cases cause indigestion amongst the unwary, but 
help is on the way in 3.1.2 Order Specific Declaration. Note that the Bison ordering 
of elements in/basename/.<ext> are not considered here.

One other point. It is possible to specify that a header file be constructed,/basename/.h using, for example, the Bison Declarative %*api.header.include **o**r %header or %header **/filename/**.**The header will contain the Prologue Directives and the Bison 
Directives consistent with the order used in **/basename/**.<ext>. **For purposes of this section, we will consider all header files as 
having the format **/basename/**.h. In Java, a header file is an importable class containing 
declarations, and in D it is an importable document containing D 
declarations.*
*In all languages, it is possible to rename **/basename/**, 
**/basename/**.<ext> and **/basename/**.h. For purposes of this discussion we 
will treat **/basename/**as the standard name.*

Since the Prologue Declarations are copied to/basename/.<ext> in the order seen.

If the parser is for C then the following additional rules apply:

1.

   C trigraphs are ignored.C digraphs for ‘{‘ and ‘}’ must be balanced.

2.

3.

   “%{“ and “%}” are allowed in comments in all languages.

Summary:
Standard Prologue declarations are delimited by “%{“ and “%}” as in

     %{ declaratives %}
Items contained in this section cause a verbatim transfer of data from the Bison input 
to/basename/.<ext>. This means that if there is a mixture of Prologue statements and 
Bison Declarative statements, they are each transferred to the/basename/.<ext> in the 
order seen, as in:

   /basename.y/

        


        

   /basename/.<ext>

   %{ declarative 1 %}

        


        

   declarative 1

   Bison Declaration 1

        


        

   Bison Declaration 1

   %{ declarative 2 %}

        

   --->

        

   declarative 2

   %{ declarative 3 %}

        


        

   declarative 3

   Bison Declaration 2

        


        

   Bison Declaration 2

where Bison Declarations cause the generation of source language declarations to be 
inserted into/basename/.<ext>

3.1.2 Order Specific Declarations
There are cases where it is difficult to use the standard order, or the standard 
order defeats other objectives. In these cases there is a mechanism to force the 
placement ofPrologue Definitinn Blocks  and Bison Declaratives into a defined order 
tnto/basename/.<ext>.

As an example, consider the dedicated Bison Declarative statement %union (for 
C/C++). This statement defines the possible token values returned from the 
lexer/scanner, and defines them as a type (YYSTYPE) which allows an object of 
this type to be returned for all of the various lexer values.

Let us use the ordering statements in this section to look at our previous 
example.
typedef int X;          // C/C++
%union { X Y }          // Bison Declarative
void func(YYSTYPE x);  // C/C++

We guarantee that the dependency is resolved by guaranteeing that each item above is 
put into its correct location in/basename/.<ext>. This is done by:

%code top { typedef int X; }   // C/C++
%union { X Y }                 // Bison Declarative
%code { void func(YYSTYPE x); }// C/C++

where %code top guarantees the the typedef is placed before the %union and 
%code guarantees the function prototype is placed after. Further,
%code { void func(YYSTYPE x); }// C/C++
%union { X Y }                 // Bison Declarative
%code top { typedef int X; }   // C/C++

Works just as well because the Order Specific Declarations state where the code 
is to go. In fact, any combination of the above statement would work just as 
well. The Order Specific Declarations are not sensitive the placement of the 
declarations within/basename/.y.

The generated parser, in all languages, is separated into allocation sections. 
The location of these sections is language dependent, but the basic content and 
organization is as specified below.

/basename/.<ext>

        

/basename/.h

Bison Preamble

        

Bison Preamble

Top Block

        

%Token definitions

Require Block

        

Require Block

YYSTYPE, |YYLTYPE|  

        

YYSTYPE, YYLTYPE

Bison Declaration Expansions

        

Bison Declaration Expansions

Provide Block

        

Provide Block

Bison Epilog

        

Bot Block

Bot Block

        

   The description of these different generated parser locations is below.

1.

   Bison Preamble: A pro forma set of generated statements output by Bison. 
This region is exclusive to Bison.

2.

   Top Block: Defined as “%code top { declarations }”. Placement immediately 
after the Bison Preamble declarations. The contents are the same as for aPDB  
block with the additional condition that placement in the generated file is 
made explicit.

3.

   Require Block: Defined as “%code require { declarations }”. Declarations are 
placed before the YYSTYPE and YYLTYPE declarations.

4.

   YYSTYPE, YYLTYPE  Declaration:

5.

   Bison Declaration Expansions. The code generated by Bison directive is 
placed immediately following Top. This can either be in the C/C++ header file, 
the D, Java import files, or in the generated parser depending on Bison 
directives used. Bison declaratives are placed in this region in the order 
seen. That is, if declaration1 occurs in the Bison input file,/basename/.y, 
before declaration2, the in the generated parser declaration1 precedes 
declaration2.

6.

   Provide Block: Defined as “%code require { declarations }”. Declarations are 
placed after the YYSTYPE and YYLTYPE declarations.

7.

   Bison Epilog. Bison code required to ensure proper function of the generated 
parser are placed here. This region is exclusive to Bison.

8.

   Bot: Application code placed immediately before yyparse().

The positioning regions are:

1.

   %code import {/declarations/  } [D, Java] defines an/import block/. Contains 
only language import directives. Placed before the Java Class declaration in a 
file. IN D, placed before any class definitions.

2.

   %code provides {/declarations/  } [C/C++] defines a/provide block/. Placed 
after the defintions for YYSTYPE and YYLTYPE.

3.

   %code requires {/declarations/} [C/C++] defines a/require block//

   Copies the/declarations/  to/basename/.h, if a header file is specified through a 
Bison declaration. In all cases, copies the declarations to/basename/.<ext> and 
treats the require block as a top block. The declarations are placed before the Bison 
generated declarations for YYSTYPE and YYLTYPE. YYSTYPE defines the location 
structure used to define the beginning and end of a token(s) received from the 
scanner/lexer, subject to changes done as a result of grammar rule reductions. 
YYSTYPE defines the values returned by the scanner/slexer.
   NOTE: See 3.1.2 Prologue Alternatives, pg. 50 “and the new YYLTYPE 
definition before the Bison-generated YYSTYPE
   and YYLTYPE definitions in both the parser implementation file and
   the parser header file”. This position causes, in this case, YYLTYPE to be 
doubly defined in the same scope and is probably a C/C++ error. What you 
probably mean is that in the absence of %header, the require block is treated 
as a top block. When a %header is present, the declarations in the require 
block are copied to/basename/.h.

4.

   %code top {/declarations/  } [C/C++] defines a top/block/. Placed after any Bison 
Preamble declarations. Figuratively, placed at the top of/basename/.h 
or/basename/.<ext> before any other declarations.

5.

   %code {/declarations/  } [C/C++, D, Java] defines a/bot block/. Places the 
declarations before the yyparse() prototype/definition. All declarations made in any 
%code <tag> blocks are available for use.

Codes are concatenated. If two code with the same tag appear in any order 
in/basename/.y, then they are
concatenated in the order found. For example:

%code provide { declaration1; }
%code         { declaration2; }
%code provide { declaration3; } // becomes

%code provide { declaration1;
                declaration3; }
%code         { declaration2; }


The organization (when things appear) in basename.y are ignored.
 
The %code blocks are sorted by tags and then concatenated as required.
The sort preserves the order of %code blocks seen, that is, if we have:

%code tag1 { declaration1; }
%code tag2 { declaration2; }
%code tag1 { declaration3; } // becomes

%code tag1 { declaration1; }
%code tag1 { declaration3; }
%code tag2 { declaration2; } // and  after concatenation

%code tag1 { declaration1; }
             declaration3; }
%code tag2 { declaration2; }

Here is an extended example in C/C++. Suppose we have:

%code         { declaration1 }
%code provide { declaration2 }
%code require { declaration3 }
%code         { declaration4 }
%code top     { declaration5 }
%code top     { declaration6 }
%code require { declaration7 }


This is copied to/basename/.h and/basename/.<ext> as:


        

%heading

/basename/.<ext>

        

/b//asename.h/

        

/basename.<ext>/

declaration5 declaration6

        

declaration5 declaration6

        

declaration3 declaration7

declaration3 declaration7

        

declaration3 declaration7

        

YYSTYPE, YYLTYPE

YYSTYPE, YYLTYPE

        

YYSTYPE, YYLTYPE

        


declaration2

        

declaration2

        


declaration1 declaration4

        

declaration1 declaration4

        



where %heading indicates that a heading (/basename/.h) file is required.

The example shows the rearrangement of declarations according to their tags and 
the concatenation of declarations with the same tag.

Summary:
The code blocks are sensitive to the language and can not be intermixed. %code blocks 
with the same tag are concatenated in the order seen before placement 
into/basename/.h,/basename/.<ext>. Tor order of %code definitions are 
independent of their placement in a header file, source file, or class.

%code tag

        

C/C++

        

D/Java

        

Description

%code

        

•

        


        

Placed after all declarations

%code import

        

•

        

•

        

Placed in an importable class

%code provides

        

•

        


        

Placed after YYSTAB, YYLTYPE declearation

%code requires

        

•

        


        

Placed before YYSTAB, YYLTYPE declearation

%code top

        

•

        


        

Placed after Bison prologue and before %code require