AutoGen - The Automated Program Generator: 2.5 Controlling What Gets Processed

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.5 Controlling What Gets Processed

Definition processing directives can only be processed if the '#' character is the first character on a line. Also, if you want a '#' as the first character of a line in one of your string assignments, you should either escape it by preceding it with a backslash ‘`\`’, or by embedding it in the string as in `"\n#"`.

All of the normal C preprocessing directives are recognized, though several are ignored. There is also an additional `#shell` - `#endshell` pair. Another minor difference is that AutoGen directives must have the hash character (`#`) in column 1.

The final tweak is that `#!` is treated as a comment line. Using this feature, you can use: ‘`#! /usr/local/bin/autogen`’ as the first line of a definitions file, set the mode to executable and "run" the definitions file as if it were a direct invocation of AutoGen. This was done for its hack value.

The ignored directives are: ‘`#ident`’, ‘`#let`’, ‘`#pragma`’, and ‘`#if`’. Note that when ignoring the `#if` directive, all intervening text through its matching `#endif` is also ignored, including the `#else` clause.

The AutoGen directives that affect the processing of definitions are:

`#assert `shell-script` | (scheme-expr) | <anything else>`

  If the `shell-script` or `scheme-expr` do not yield `true` valued results, autogen will be aborted. If `<anything else>` or nothing at all is provided, then this directive is ignored.

  When writing the shell script, remember this is on a preprocessing line. Multiple lines must be backslash continued and the result is a single long line. Separate multiple commands with semi-colons.

  The result is `false` (and fails) if the result is empty, the number zero, or a string that starts with the letters 'n' or 'f' ("no" or "false").

`#define name [ <text> ]`

  Will add the name to the define list as if it were a DEFINE program argument. Its value will be the first non-whitespace token following the name. Quotes are not processed.

  After the definitions file has been processed, any remaining entries in the define list will be added to the environment.

`#elif`

  This must follow an `#if` otherwise it will generate an error. It will be ignored.

`#else`

  This must follow an `#if`, `#ifdef` or `#ifndef`. If it follows the `#if`, then it will be ignored. Otherwise, it will change the processing state to the reverse of what it was.

`#endif`

  This must follow an `#if`, `#ifdef` or `#ifndef`. In all cases, this will resume normal processing of text.

`#endmac`

  This terminates a "macdef", but must not ever be encountered directly.

`#endshell`

  Ends the text processed by a command shell into autogen definitions.

`#error [ <descriptive text> ]`

  This directive will cause AutoGen to stop processing and exit with a status of EXIT_FAILURE.

`#if [ <ignored conditional expression> ]`

  `#if` expressions are not analyzed. Everything from here to the matching `#endif` is skipped.

`#ifdef name-to-test`

  The definitions that follow, up to the matching `#endif` will be processed only if there is a corresponding `-Dname` command line option or if a `#define` of that name has been previously encountered.

`#ifndef name-to-test`

  The definitions that follow, up to the matching `#endif` will be processed only if there is not a corresponding `-Dname` command line option or there was a canceling `-Uname` option.

`#include unadorned-file-name`

  This directive will insert definitions from another file into the current collection. If the file name is adorned with double quotes or angle brackets (as in a C program), then the include is ignored.

`#line`

  Alters the current line number and/or file name. You may wish to use this directive if you extract definition source from other files. `getdefs` uses this mechanism so AutoGen will report the correct file and approximate line number of any errors found in extracted definitions.

`#macdef`

  This is a new AT&T research preprocessing directive. Basically, it is a multi-line #define that may include other preprocessing directives.

`#option opt-name [ <text> ]`

  This directive will pass the option name and associated text to the AutoOpts optionLoadLine routine (see section optionLoadLine). The option text may span multiple lines by continuing them with a backslash. The backslash/newline pair will be replaced with two space characters. This directive may be used to set a search path for locating template files For example, this:

      #option templ-dirs $ENVVAR/dirname

  will direct autogen to use the `ENVVAR` environment variable to find a directory named `dirname` that (may) contain templates. Since these directories are searched in most recently supplied first order, search directories supplied in this way will be searched before any supplied on the command line.

`#shell`

  Invokes `$SHELL` or ‘`/bin/sh`’ on a script that should generate AutoGen definitions. It does this using the same server process that handles the back-quoted ``` text. CAUTION let not your `$SHELL` be `csh`.

`#undef name-to-undefine`

  Will remove any entries from the define list that match the undef name pattern.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by Bruce Korb on May, 24 2008 using texi2html 1.78.