5. Pragma Statements

Pragma statements are used as 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 settings, 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, pragma statements do not follow the scope of Flavor code.

A pragma statement that is included in a class will affect not only the class where it is contained but all classes declared after it. 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
-g get
noget		 Controls if a get() method is generated.
-p put
noput		 Controls if a put() method is generated.
-x putxml
noputxml		 Controls if a putxml() method is generated.
-t trace
notrace		 Controls if tracing code is generated in the get() method.
-l line
noline		 Controls line number output information for verbatim code.
-a num array = num Sets maximum array size.
-s nullstrings
nonullstrings		 Stores the strings as arrrays with null
-i includes
noincludes		 Generates include directives when for C++ 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 Statements 
// Activate both put and get, generate tracing code, and set array size to 128
%pragma put, get, trace, array=128

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

    unsigned int(10) length;

    // Switch array size to 1024
    %pragma array=1024

    char(3) data[length];

    // Switch array size back to 128
    %pragma array=128

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

// The settings above are still active here!

Here we start off setting the generation of both get() and put() methods, enabling tracing and setting the maximum array size to 128 elements. 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 pragma settings remain in effect even after the end of the Example class.

 

Copyright Notice