Pragma Statements

4. Pragma Statements

Pragma statements is a mechanism for setting translator options from inside a Flavor source file. This allows modification of translation parameters without modifying the makefile that builds the user's program, but - more importantly - it allows very fine control on which translation options are applied to each class, or even variable. Almost all command-line options have pragma equivalents. The ones excluded were not considered useful for specification within a source file.

Pragma statements are introduced with the %pragma directive. It can appear wherever a statement or declaration can. It can contain one or more setting, separated by commas, and it cannot span more than one line. After a setting is provided, it will be used for the remainder of the Flavor file, unless overridden by a different pragma setting. In other words, pragmas do not follow the scope of Flavor code.

A pragma that is included in a class will affect not only the class where it is contained but all classes declared after it. It should be noted that for pragmas that affect an entire class, the currently available value at the end of the classes declaration is the one used. An example is provided below.

The following table summarizes the correspondence between command line options and pragma settings. The prefix 'no' in front of an option, when applicable, disables that option.

Command Line	Pragma	Notes
`-p`	`put noput`	Controls if a `put()` method is generated.
`-g`	`get noget`	Controls if a `get()` method is generated.
`-t`	`trace notrace`	Controls if tracing code is generated in the `get()` method.
`-a num`	`array = num`	Sets maximum array size.
`-l`	`line noline`	Controls line number output information for verbatim code.
`-B string`	`bitstream = "string"`	Sets the name for the bitstream I/O class.
`-F string`	`prefix = "string"`	Sets the prefix for Flavor-generated internal variables.
`-E string`	`efunc = "string"`	Sets the name for the bitstream syntax error reporting function.
`-T string`	`tfunc = "string"`	Sets the name for the tracing function.

The following shows an example of the use of pragma statements.

Example of Pragma Statementsl
`// activate both put and get, set array size to 128 % pragma put, get, trace class Example { // no put() method needed %pragma noput // the following array will have 128 elements unsigned int(10) length; // switch array to 1024 %pragma array = 1024 char(3) data[length]; // switch array back to 128 %pragma array=128 // use custom tracer %pragma trace="Tracer.trace" } // the setting above are still active here!`

// activate both put and get, set array size to 128
% pragma put, get, trace

class Example {
    // no put() method needed
    %pragma noput

    // the following array will have 128 elements
    unsigned int(10) length;

   // switch array to 1024
   %pragma array = 1024

   char(3) data[length];

   // switch array back to 128
   %pragma array=128

   // use custom tracer
   %pragma trace="Tracer.trace"
}

// the setting above are still active here!

Here we start off setting both get() and put() method output, and also enable tracing. Inside the Example class, we disable the put() method output. This class reads a chunk of data, which is preceded by its size (length, a 10-bit quantity). This means that the largest possible buffer size is 1024 elements. Hence for the data array that immediately follows, we set the array size to 1024, and then switch it back to the default of 64.

Finally, at the end of the class we select a different tracing function name; this function is really a method of a clas, but this is irrelevant for the translator. Since this directive is used when the get() method code is produced, it will affect the entire class despite the fact that it is declared at its end.

Note that these directives remain in effect even after the end of the Example class.