OUI: Options, Usage and Initializations

Contents

    0.0: Invocation
    1.0: Introducation
    2.0: Packages
    3.0: Options
    4.0: Initializations
    5.0: Usage
    6.0: Handling Default Initializations
    7.0: See Also

0.0: Invocation

oui [options] file [file ...]
    -k Keep incomplete output file on error
    -o <filename> Specify Output Filename
    -q Print usage message
    -u Don't sort the "sort" strings
    -v Increasing level of verbosity
    -w Treat warnings as errors

1.0: Introducation

When invoking a program from a shell command line, "options" are characters which may be added to the program name, possibly with arguments, which request a change in the behaviour of the program. For example, the -l option to the command ls causes a long-format output.

"Usage" is text which describes the options available from the command line as well as other useful information about running the program. Under QNX, usage information can be read by invoking the use utility, (e.g. use ls.)

"Initializations" are C-language commands which must be executed before the features of a particular package can be used. This includes processing command-line options as well as any other startup operations such as clearing the screen or establishing a connection with a windowing system.

oui reads in definition files for one or more "packages" and produces C source code for a function called oui_init_options() and usage information compatible with the QNX usemsg utility. oui is particularly helpful as an adjunct to function libraries. Many library "packages" require initialization code to be run and may offer standard options to users from the command line.

2.0: Packages

        <package> sample

It is often the case that one package is only useful in combination with another package or packages. This can be indicated by way of the "include" statement:

        <include> msg

When combining multiple packages, it is often the case that the initializations for one package must come before or after the initializations for another package. This type of dependency can be expressed through the <preceed> and <follow> statements.

        <follow> msg msghdr dg

3.0: Options

If your package is going to support one or more command-line options, you must specify which option letters it will handle in an <opts> statement:

        <opts> "lt:q"

When packages are combined, the options required by each package are checked against the options for every other package to guarantee that there are no conflicts. In certain special cases, two related packages may wish to "share" an option letter. This can be accomplished by creating a third package which they both include. This is the case with the msg package and the client package which share the -h option. If they each specified h as an option, oui would complain that there was a conflict.

Specifying the option letters only means that the application will quietly accept those options at runtime. We have not as yet told oui what to do when those options are specified.

4.0: Initializations

        <init> printf("Starting Up...");

        <init>
          DG_init_options(argc, argv);

If your initialization references a function or data object, that object should most likely be defined prior to its invocation. This is usually done in C via the #include statement. In oui, this is replaced with the <include> statement:

        <include> "dg.h"
        <include> <stdlib.h>

You should include any header files required by your initializations without regard to whether other packages might also be including those headers. oui will guarantee that only one #include statement will be generated for each required header.

Sometimes you will need to make global or static definitions within the C file which is generated by oui. The <defs> keyword is used for this purpose. Each line following the <defs> command is copied into the output file outside of the initialization function:

        <defs>
          int file_count;
          #define MAX_FILES 5

Often you may find you want to add a single option to an existing program, for example passing a calibration constant to a data extraction program. Ordinarily, processing any options requires generation of a function which loops while calling getopt(). This is somewhat tedious when only a single option is required. The <switch> and <arg> commands will generate this loop for you automatically. Lines following the <switch> command are placed inside a switch statement in a position suitable for case statements. For example, the commands:

        <switch>
          case 'l':
          limit = atoi(optarg);
          break;

Warning: As currently implemented, the <switch> command does not respect the <follow> and <preceed> directives. A single loop is generated and is placed before all the other initializations. However it can still be useful in these cases: go ahead and use <switch>, then use the generated C code to create your own init_options() function. You can put the new init_options() function back into the .oui file under <defs>, remove the <switch> and replace it with an <init> referencing the new function.

The <args> command will place code in a loop which processes any arguments remaining on the command line after the options are handled. Again, the optarg variable is used to reference each argument in turn:

        <args>
          process(optarg);

Note that the same caveats apply to <args> as apply to <switch>. It is really only useful in very simple cases.

5.0: Usage

<synopsis> accepts exactly one line of text which becomes the first line of the programs usage message. There may be only one <synopsis> statement among all the packages referenced, since there can be only one synopsis. The default synopsis is:

        %C [options]

Usage for the options is provided with the <sort> command:

        <sort>
          -l <limit> Define a new upper limit
          -c Clear the server's error count

More general usage can be provided with the <unsort> command. This text will not be rearranged in the final output, so it is possible to provide paragraphs of information.

Oui always ignores blank lines and lines with only whitespace in the input, since whitespace often helps to make the input file readable. This can present a problem if you want a blank line to appear in the output. This is most likely only in the <unsort> text, but might arise elsewhere also. The <blank> command will introduce a blank line into the output of the appropriate section.

Finally, comments may be introduced to the input file by way of the <comment> command. All lines following this command up to the next keyword are treated as comments and ignored.

6.0: Handling Default Initializations

I have come up with a mechanism to provide this sort of flexibility. It works like this:

1) The package in question defines a local variable to hold the initialization parameter. In our example, the package is msghdr and the initialization parameter is the message header:

        <package> msghdr
        ...
        <var>
          char *msg_hdr;

        <package> msghdr_init
        <init>
          msg_hdr = "hdr";

        <follow> msghdr_init

4) An application (or another library package) wishing to override the initialization simply redefines the msghdr_init package, providing a different initialization. The first package by that name which is read by oui is the only one which is used, so controlling the order in which the packages is read controls which initialization takes effect.

This approach has proven effective in handling a wide range of message header defaults. The hooks have not been fully realized for other packages requiring additional parameters, such as the command control package, but I believe the same approach can be made to work there.

7.0: See Also

Return to Manuals Guide