2. Command Line Options

The Flavor translator accepts a number of command line options that affect its operation and the interface of the generated code with a programmer's C++ code. In the following we describe its option in detail, and explain how it affects the generated code. Options are grouped in terms of functional behavior. Note that command line options affect the entire Flavor source file; if you want to apply settings to specific classes, this can be done using pragma statements.

2.1 Usage Message

Prints a usage summary, including a list of the available command line options. The translator only works at one file at a time, which must  have an extension .fl. All options must be specified before the input file name. For example:

    flavorc input.fl

The exit value of the translator (the value returned to the operating system) is the number of error encountered during parsing and code generation. A value of 0 indicates successful operation.

2.2 Version Information

Prints a message detailing the current version number and date of release of the translator. For example:

    FLAVORC Version 2.0 [Exp] 1997/06/04
    Copyright (C) 1996-1997, Columbia University. All rights reserved.
    For the latest information, visit the Flavor Web site at:
        http://www.ee.columbia.edu/flavor

The bracketed expression, if present, after the version number indicates that the release is not final.

2.3 Language Selection

The translator is capable of producing both C++ and Java code. At this time, only the C++ code generator is included in the public release. Support for Java is expected for Version 2.2. If you are interested in obtaining a prerelease version, please contact us.

All output from the translator is placed in a single output file. The code generator produces one C++ class for each Flavor class defined. Each class contains as member variables all parsable variables defined in the Flavor code, as well as any variables defined in class scope. In addition, the code generator will produce a get() and a put() method, which will read and write data to and from a bistream. Global variables in Flavor source are also declared global in the generated C++ code as well. All class members are declared public, unless overidden using pragma statements in the Flavor code itself.

2.4 Output Type Selection

These options affect the type of code that the generator produces. By default, the translator will produce both a put() and a get() method without any tracing code. The -p and -g options can selectively switch off the generation of their respective methods, while -n is useful when only a syntax check of the Flavor source is needed.

The -t option triggers insertion of tracing code in the get() method. Note that if no get() method is produced, this option has no effect. No warning message will be produced by the translator, as pragma statements inside the Flavor code may selectively trigger the output of get() methods.

When verbatim code is used, the translator generates C++ preprocessor statements to indicate its position in the Flavor source code. This helps development environments that automatically position the programmer's editor to the source position where the error was detected. This information is also used by source code debuggers to position their source window to the right file and line. In the case where you want compiler error messages to refer to the flavorc-generated file, or your debugger to use the flavorc-generated C++ file, you can switch this line information off using the -l option.

2.5 Output File Selection

The default output file name for the generated code is the input file name with a suffic '.h' when C++ code is produced, or '.java' when Java code is produced.

2.6 Error Message Formatting

For user's developing code using Microsoft's Developer Studio IDE, this option triggers formatting of error messages in a format compatible with the IDE. This allows direct positioning to the file and line that caused the error message (using the 'F4' key).

2.7 Array Sizing

Although Flavor supports arrays of arbitrary sizes, the translator produces code that declares all arrays with a constant, statically defined size. This option sets the initial value for this size, with a default of 64. The translator will automatically increase it (and issue a warning message) when it detects that a larger value is needed. Note that this is not always possible, so that care should be taken by the programmer to ensure that a large-enough size is used. The array size can also be set selectively for individual variables or classes using pragma statements.

2.8 Run-Time Interface

The generated code relies on a small number of classes and functions to perform low-level bitstream I/O and error reporting. These are part of the run-time library which is included in this package. The design of the run-time library has been done in a way that facilitates its substitution by alernate implementations that may better suit a programmer's application needs. These options allow the customization of the code produced by the translator so that the programmer-supplied substitute classes or functions are called. Note that, although the names can be modified, the interface exposed by these classes must comply to the one expected by flavorc. More information on this interface can be found in the Run-Time Library section.

The -B option sets the name of the class implementing low-level I/O. The default class, provided in the run-time library, is Bitstream. The -E option is used to set the name for the function to be called when bitstream syntax errors occur. The default is flerror. Finally, the -T option is used to set the name of the functions that should be used to create trace reports. Note that at least two such functions are required (one handling integer-compatible values, and one handling double-compatible values). The default name is trace.

Flavor also uses a small number of internal variables. To avoid conflicts with variables defined in the user's code, all such variables are given a prefix. The default is _F_, but it can be changed using the -F option.