3. 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++ or Java code. In the following we describe its options in detail, and explain how they affect the generated code. Options are grouped in terms of their functional behaviors. Note that command line options affect the entire Flavor source file (.fl). Applying certain options/settings to specific classes, not the whole .fl file, can be achieved using pragma statements.

3.1 Usage Message

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

    flavorc -t input.fl

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

3.2 Version Information

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

    FLAVORC Version 5.0 [Beta] 4/22/2002
    Copyright (C) 1996-2002, Columbia University.
    For the latest information, visit the Flavor Web site at:
        http://flavor.sourceforge.net

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

3.3 Language Selection

In the case where -gc option is used, the output from the translator is placed in a single pair of .h and .cpp files. The Flavor translator 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 the class scope. In addition, the code generator will produce a set of get() and put() methods, which will read and write data to and from a bistream; all class members are declared public. Starting with Version 5.0, the generated code also includes a putxml() method for converting bitstreams into corresponding XML documents.

When producing Java codes (with the -gj option), the translator generates a .java file per Flavor class defined in the .fl file.

Starting with Version 5.0, the translator (XFlavor) can produce an XML schema (a .xsd file) for a given Flavor description. For every class defined in Flavor, a corresponding complex type is defined. The -gx option is used to generate the schema.

3.4 Output Type Selection

The -n option is used to compile and check the validity of the Flavor code without generating corresponding C++/Java code or XML schema. This option is very useful when only the syntax of the Flavor code need to be checked.

The rest of the options affect the type of code that the translator produces. By default, the translator will produce both a put() and a get() method without any tracing code. The -p and -g options can be used to selectively switch off the generation of their respective methods.

Starting from Flavor Version 5.0, the translator also generates a putxml() method for converting Flavor described bitstreams into XML documents. Using the -x option, the generation of this method can be disabled.

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. In this case 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.

3.5 Output File Selection

When generating C++ code, the default output file names for the for the .h and .cpp files are the input file name with corresponding suffixes. For example, for the Flavor source file sample.fl, the default output files are sample.h and sample.cpp.

In the case of producing Java code, the translator produces one .java file per Flavor class and they are packaged using the input file name, by default. Using the -oj name option, the desired package name can be set. Also, if global constants are used in a Flavor file, a Global class is defined to contain them. The name of this class can be modified using the -og option. The generated Java code utilizes the Flavor library by importing the library package. By default, the package name is flavor; however, this can be modified by using the -op option.

Additionally, when generating an XML schema, the default output file name is the input file name with the suffix changed to .xsd.

3.6 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 the default value 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.

3.7 Null-Terminated Strings

The translator converts strings to arrays, with or without a trailing '\0' (null). This option causes to include the trailing null. This option can also be used by using the nullstrings/nonullstrings pragma statements.

3.8 Error Message Formatting

For users 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).

3.9 Include Directives

Some development environments, most notably Microsoft's MFC library, require that their header files are the first to be included. To allow control about header file inclusion, the -i option can be used to instruct the translator to not produce any #include directives in the C++ code (or import statements in the Java code). The programmer then must ensure that the proper includes are present in the .h and .cpp files using verbatim code. There is also corresponding pragma statments (includes/noincludes) for controlling this.

3.10 Optional Checks

The translator can perform a number of checks for source code structures that sometimes may be undesirable. Warnings for these conditions are not normally issued, since they are considered acceptable. Some also require additional processing that can slow down compilation. A list of the available checks can be obtained using the -w help option. The complete list of options is as follows:

 help            print the list of available options

 abstract      warn when pure abstract classes are used

 cyclic         warn when cyclic references are detected

 includes      warn when cyclic includes/imports are detected

The abstract test checks if there are abstract classes without any derived classes with IDs. In general, abstract classes act only as placeholders for one of their derived classes, and hence should not appear alone in a source file.

The cyclic test checks if there are cyclic data structures, i.e., classes which - either directly or indirectly - contain instances of themselves. Such structures can cause infinite loops of get() or put() calls, if not properly constrained by the bitstream syntax.

The includes test checks if there are cyclic includes, i.e., files which - either directly or indirectly through other included or imported files - include themselves. Due to the need for cross-connecting Flavor files to ensure that ID spaces and lengthof() or isidof() operators work correctly, such cyclic indludes are acceptable. The translator makes sure that a file is not processed more than once. If this is not the intended structure for a set of files, this option can be used to enable the translator to issue a warning message.

3.11 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.

3.12 Disallow Further Options

This options is used to disallow usage of further options. This allows to use a Flavor source file name that starts with a dash.

Copyright Notice