8. Add-on packages for AutoGen

This chapter includes several programs that either work closely with AutoGen (extracting definitions or providing special formatting functions), or leverage off of AutoGen technology. There is also a formatting library that helps make AutoGen possible.

AutoOpts ought to appear in this list as well, but since it is the primary reason why many people would even look into AutoGen at all, I decided to leave it in the list of chapters.

8.1 Automated Finite State Machine

The templates to generate a finite state machine in C or C++ is included with AutoGen. The documentation is not. The documentation is in HTML format for viewing, or you can download FSM.

8.2 Combined RPC Marshalling

The templates and NFSv4 definitions are not included with AutoGen in any way. The folks that designed NFSv4 noticed that much time and bandwidth was wasted sending queries and responses when many of them could be bundled. The protocol bundles the data, but there is no support for it in rpcgen. That means you have to write your own code to do that. Until now. Download this and you will have a large, complex example of how to use AutoXDR for generating the marshaling and unmarshaling of combined RPC calls. There is a brief example on the web, but you should download AutoXDR.

8.3 Automated Event Management

Large software development projects invariably have a need to manage the distribution and display of state information and state changes. In other words, they need to manage their software events. Generally, each such project invents its own way of accomplishing this and then struggles to get all of its components to play the same way. It is a difficult process and not always completely successful. This project helps with that.

AutoEvents completely separates the tasks of supplying the data needed for a particular event from the methods used to manage the distribution and display of that event. Consequently, the programmer writing the code no longer has to worry about that part of the problem. Likewise the persons responsible for designing the event management and distribution no longer have to worry about getting programmers to write conforming code.

This is a work in progress. See my web page on the subject, if you are interested. I have some useful things put together, but it is not ready to call a product.

8.4 Invoking columns

This program has no explanation.

This program was designed for the purpose of generating compact, columnized tables. It will read a list of text items from standard in or a specified input file and produce a columnized listing of all the non-blank lines. Leading white space on each line is preserved, but trailing white space is stripped. Methods of applying per-entry and per-line embellishments are provided. See the formatting and separation arguments below.

This program is used by AutoGen to help clean up and organize its output.

See `autogen/agen5/fsm.tpl' and the generated output `pseudo-fsm.h'.

This function was not implemented as an expression function because either it would have to be many expression functions, or a provision would have to be added to provide options to expression functions. Maybe not a bad idea, but it is not being implemented at the moment.

A side benefit is that you can use it outside of AutoGen to columnize input, a la the ls command.

This section was generated by AutoGen, the aginfo template and the option descriptions for the columns program. It documents the columns usage text and option meanings.

This software is released under the GNU General Public License.

8.4.1 columns usage help (-?)

This is the automatically generated usage text for columns:

columns (GNU AutoGen) - Columnize Input Text - Ver. 1.1
USAGE:  columns [ -<flag> [<val>] | --<name>[{=| }<val>] ]...
  Flg Arg Option-Name    Description
   -W Num width          Maximum Line Width
   -c Num columns        Desired number of columns
   -w Num col-width      Set width of each column
      Num spread         maximum spread added to column width
   -I Str indent         Line prefix or indentation
      Str first-indent   First line prefix
                                - requires these options:
                                indent
      Num tab-width      tab width
   -s opt sort           Sort input text
   -f Str format         Formatting string for each input
   -S Str separation     Separation string - follows all but last
      Str line-separation string at end of all lines but last
      no  by-columns     Print entries in column order
   -i Str input          Input file (if not stdin)
   -v opt version        Output version information and exit
   -? no  help           Display usage information and exit
   -! no  more-help      Extended usage information passed thru pager

Options are specified by doubled hyphens and their name
or by a single hyphen and the flag character.

This program was designed for the purpose of generating compact,
columnized tables.  It will read a list of text items from standard
in or a specified input file and produce a columnized listing of
all the non-blank lines.  Leading white space on each line is
preserved, but trailing white space is stripped.  Methods of
applying per-entry and per-line embellishments are provided.
See the formatting and separation arguments below.

This program is used by AutoGen to help clean up and organize
its output.

please send bug reports to:  autogen-users@lists.sourceforge.net

8.4.2 width option (-W)

This is the "maximum line width" option. This option specifies the full width of the output line, including any start-of-line indentation. The output will fill each line as completely as possible, unless the column width has been explicitly specified. If the maximum width is less than the length of the widest input, you will get a single column of output.

8.4.3 columns option (-c)

This is the "desired number of columns" option. Use this option to specify exactly how many columns to produce. If that many columns will not fit within line_width, then the count will be reduced to the number that fit.

8.4.4 col-width option (-w)

This is the "set width of each column" option. Use this option to specify exactly how many characters are to be allocated for each column. If it is narrower than the widest entry, it will be over-ridden with the required width.

8.4.5 spread option

This is the "maximum spread added to column width" option. Use this option to specify exactly how many characters may be added to each column. It allows you to prevent columns from becoming too far apart.

8.4.6 indent option (-I)

This is the "line prefix or indentation" option. If a number, then this many spaces will be inserted at the start of every line. Otherwise, it is a line prefix that will be inserted at the start of every line.

8.4.7 first-indent option

This is the "first line prefix" option.

This option has some usage constraints. It:

must appear in combination with the following options: indent.

If a number, then this many spaces will be inserted at the start of the first line. Otherwise, it is a line prefix that will be inserted at the start of that line.

8.4.8 tab-width option

This is the "tab width" option. If an indentation string contains tabs, then this value is used to compute the ending column of the prefix string.

8.4.9 sort option (-s)

This is the "sort input text" option. Causes the input text to be sorted. If an argument is supplied, it is presumed to be a pattern and the sort is based upon the matched text. If the pattern starts with or consists of an asterisk (*), then the sort is case insensitive.

8.4.10 format option (-f)

This is the "formatting string for each input" option. If you need to reformat each input text, the argument to this option is interpreted as an sprintf(3) format that is used to produce each output entry.

8.4.11 separation option (-S)

This is the "separation string - follows all but last" option. Use this option if, for example, you wish a comma to appear after each entry except the last.

8.4.12 line-separation option

This is the "string at end of all lines but last" option. Use this option if, for example, you wish a backslash to appear at the end of every line, except the last.

8.4.13 by-columns option

This is the "print entries in column order" option. Normally, the entries are printed out in order by rows and then columns. This option will cause the entries to be ordered within columns. The final column, instead of the final row, may be shorter than the others.

8.4.14 input option (-i)

This is the "input file (if not stdin)" option. This program normally runs as a filter, reading from standard input, columnizing and writing to standard out. This option redirects input to a file.

8.5 Invoking getdefs

If no input argument is provided or is set to simply "-", and if stdin is not a tty, then the list of input files will be read from stdin. This program extracts AutoGen definitions from a list of source files. Definitions are delimited by `/*=<entry-type> <entry-name>\n' and `=*/\n'. From that, this program creates a definition of the following form:

    #line nnn "source-file-name"
    entry_type = {
        name = entry_name;
        ...
    };

The ellipsis "..." is filled in by text found between the two delimiters, using the following rules:

Each entry is located by the pattern "\n[^*\n]*\\*[ \t]*([a-z][a-z0-9_]*):". Fundamentally, it finds a line that, after the first asterisk on the line, contains whitespace then a name and is immediately followed by a colon. The name becomes the name of the attribute and what follows, up to the next attribute, is its value.
If the first character of the value is either a single or double quote, then you are responsible for quoting the text as it gets inserted into the output definitions.
All the leading text on a line is stripped from the value. The leading text is everything before the first asterisk, the asterisk and all the whitespace characters that immediately follow it. If you want whitespace at the beginnings of the lines of text, you must do something like this:
* mumble: * " this is some\n" * " indented text."
If the `<entry-name>' is followed by a comma, the word `ifdef' (or 'ifndef') and a name `if_name', then the above entry will appear as:
#ifdef if_name #line nnn "source-file-name" entry_type = { name = entry_name; ... }; #endif
If you use of the subblock option, you can specify a nested value, See section subblock option. That is, this text:
* arg: int, this, what-it-is
with the `-subblock=arg=type,name,doc' option would yield:
arg = { type = int; name = this; doc = what-it-is; };

This section was generated by AutoGen, the aginfo template and the option descriptions for the getdefs program. It documents the getdefs usage text and option meanings.

This software is released under the GNU General Public License.

8.4.8 tab-width option

This is the "tab width" option. If an indentation string contains tabs, then this value is used to compute the ending column of the prefix string.

8.4.9 sort option (-s)

This is the "sort input text" option. Causes the input text to be sorted. If an argument is supplied, it is presumed to be a pattern and the sort is based upon the matched text. If the pattern starts with or consists of an asterisk (*), then the sort is case insensitive.

8.4.10 format option (-f)

This is the "formatting string for each input" option. If you need to reformat each input text, the argument to this option is interpreted as an sprintf(3) format that is used to produce each output entry.

8.4.11 separation option (-S)

This is the "separation string - follows all but last" option. Use this option if, for example, you wish a comma to appear after each entry except the last.

8.4.12 line-separation option

This is the "string at end of all lines but last" option. Use this option if, for example, you wish a backslash to appear at the end of every line, except the last.

8.4.13 by-columns option

This is the "print entries in column order" option. Normally, the entries are printed out in order by rows and then columns. This option will cause the entries to be ordered within columns. The final column, instead of the final row, may be shorter than the others.

8.4.14 input option (-i)

This is the "input file (if not stdin)" option. This program normally runs as a filter, reading from standard input, columnizing and writing to standard out. This option redirects input to a file.

8.5 Invoking getdefs

If no input argument is provided or is set to simply "-", and if stdin is not a tty, then the list of input files will be read from stdin. This program extracts AutoGen definitions from a list of source files. Definitions are delimited by `/*=<entry-type> <entry-name>\n' and `=*/\n'. From that, this program creates a definition of the following form:

    #line nnn "source-file-name"
    entry_type = {
        name = entry_name;
        ...
    };

The ellipsis "..." is filled in by text found between the two delimiters, using the following rules:

Each entry is located by the pattern "\n[^*\n]*\\*[ \t]*([a-z][a-z0-9_]*):". Fundamentally, it finds a line that, after the first asterisk on the line, contains whitespace then a name and is immediately followed by a colon. The name becomes the name of the attribute and what follows, up to the next attribute, is its value.
If the first character of the value is either a single or double quote, then you are responsible for quoting the text as it gets inserted into the output definitions.
All the leading text on a line is stripped from the value. The leading text is everything before the first asterisk, the asterisk and all the whitespace characters that immediately follow it. If you want whitespace at the beginnings of the lines of text, you must do something like this:
* mumble: * " this is some\n" * " indented text."
If the `<entry-name>' is followed by a comma, the word `ifdef' (or 'ifndef') and a name `if_name', then the above entry will appear as:
#ifdef if_name #line nnn "source-file-name" entry_type = { name = entry_name; ... }; #endif
If you use of the subblock option, you can specify a nested value, See section subblock option. That is, this text:
* arg: int, this, what-it-is
with the `-subblock=arg=type,name,doc' option would yield:
arg = { type = int; name = this; doc = what-it-is; };

This section was generated by AutoGen, the aginfo template and the option descriptions for the getdefs program. It documents the getdefs usage text and option meanings.

This software is released under the GNU General Public License.

8.4.8 tab-width option

This is the "tab width" option. If an indentation string contains tabs, then this value is used to compute the ending column of the prefix string.

8.4.9 sort option (-s)

This is the "sort input text" option. Causes the input text to be sorted. If an argument is supplied, it is presumed to be a pattern and the sort is based upon the matched text. If the pattern starts with or consists of an asterisk (*), then the sort is case insensitive.

8.4.10 format option (-f)

This is the "formatting string for each input" option. If you need to reformat each input text, the argument to this option is interpreted as an sprintf(3) format that is used to produce each output entry.

8.4.11 separation option (-S)

This is the "separation string - follows all but last" option. Use this option if, for example, you wish a comma to appear after each entry except the last.

8.4.12 line-separation option

This is the "string at end of all lines but last" option. Use this option if, for example, you wish a backslash to appear at the end of every line, except the last.

8.4.13 by-columns option

This is the "print entries in column order" option. Normally, the entries are printed out in order by rows and then columns. This option will cause the entries to be ordered within columns. The final column, instead of the final row, may be shorter than the others.

8.4.14 input option (-i)

This is the "input file (if not stdin)" option. This program normally runs as a filter, reading from standard input, columnizing and writing to standard out. This option redirects input to a file.

8.5 Invoking getdefs

If no input argument is provided or is set to simply "-", and if stdin is not a tty, then the list of input files will be read from stdin. This program extracts AutoGen definitions from a list of source files. Definitions are delimited by `/*=<entry-type> <entry-name>\n' and `=*/\n'. From that, this program creates a definition of the following form:

    #line nnn "source-file-name"
    entry_type = {
        name = entry_name;
        ...
    };

The ellipsis "..." is filled in by text found between the two delimiters, using the following rules:

Each entry is located by the pattern "\n[^*\n]*\\*[ \t]*([a-z][a-z0-9_]*):". Fundamentally, it finds a line that, after the first asterisk on the line, contains whitespace then a name and is immediately followed by a colon. The name becomes the name of the attribute and what follows, up to the next attribute, is its value.
If the first character of the value is either a single or double quote, then you are responsible for quoting the text as it gets inserted into the output definitions.
All the leading text on a line is stripped from the value. The leading text is everything before the first asterisk, the asterisk and all the whitespace characters that immediately follow it. If you want whitespace at the beginnings of the lines of text, you must do something like this:
* mumble: * " this is some\n" * " indented text."
If the `<entry-name>' is followed by a comma, the word `ifdef' (or 'ifndef') and a name `if_name', then the above entry will appear as:
#ifdef if_name #line nnn "source-file-name" entry_type = { name = entry_name; ... }; #endif
If you use of the subblock option, you can specify a nested value, See section subblock option. That is, this text:
* arg: int, this, what-it-is
with the `-subblock=arg=type,name,doc' option would yield:
arg = { type = int; name = this; doc = what-it-is; };

This section was generated by AutoGen, the aginfo template and the option descriptions for the getdefs program. It documents the getdefs usage text and option meanings.

This software is released under the GNU General Public License.

8.4.8 tab-width option

This is the "tab width" option. If an indentation string contains tabs, then this value is used to compute the ending column of the prefix string.

8.4.9 sort option (-s)

This is the "sort input text" option. Causes the input text to be sorted. If an argument is supplied, it is presumed to be a pattern and the sort is based upon the matched text. If the pattern starts with or consists of an asterisk (*), then the sort is case insensitive.

8.4.10 format option (-f)

This is the "formatting string for each input" option. If you need to reformat each input text, the argument to this option is interpreted as an sprintf(3) format that is used to produce each output entry.

8.4.11 separation option (-S)

This is the "separation string - follows all but last" option. Use this option if, for example, you wish a comma to appear after each entry except the last.

8.4.12 line-separation option

This is the "string at end of all lines but last" option. Use this option if, for example, you wish a backslash to appear at the end of every line, except the last.

8.4.13 by-columns option

This is the "print entries in column order" option. Normally, the entries are printed out in order by rows and then columns. This option will cause the entries to be ordered within columns. The final column, instead of the final row, may be shorter than the others.

8.4.14 input option (-i)

This is the "input file (if not stdin)" option. This program normally runs as a filter, reading from standard input, columnizing and writing to standard out. This option redirects input to a file.

8.5 Invoking getdefs

If no input argument is provided or is set to simply "-", and if stdin is not a tty, then the list of input files will be read from stdin. This program extracts AutoGen definitions from a list of source files. Definitions are delimited by `/*=<entry-type> <entry-name>\n' and `=*/\n'. From that, this program creates a definition of the following form:

    #line nnn "source-file-name"
    entry_type = {
        name = entry_name;
        ...
    };

The ellipsis "..." is filled in by text found between the two delimiters, using the following rules:

Each entry is located by the pattern "\n[^*\n]*\\*[ \t]*([a-z][a-z0-9_]*):". Fundamentally, it finds a line that, after the first asterisk on the line, contains whitespace then a name and is immediately followed by a colon. The name becomes the name of the attribute and what follows, up to the next attribute, is its value.
If the first character of the value is either a single or double quote, then you are responsible for quoting the text as it gets inserted into the output definitions.
All the leading text on a line is stripped from the value. The leading text is everything before the first asterisk, the asterisk and all the whitespace characters that immediately follow it. If you want whitespace at the beginnings of the lines of text, you must do something like this:
* mumble: * " this is some\n" * " indented text."
If the `<entry-name>' is followed by a comma, the word `ifdef' (or 'ifndef') and a name `if_name', then the above entry will appear as:
#ifdef if_name #line nnn "source-file-name" entry_type = { name = entry_name; ... }; #endif
If you use of the subblock option, you can specify a nested value, See section subblock option. That is, this text:
* arg: int, this, what-it-is
with the `-subblock=arg=type,name,doc' option would yield:
arg = { type = int; name = this; doc = what-it-is; };

This section was generated by AutoGen, the aginfo template and the option descriptions for the getdefs program. It documents the getdefs usage text and option meanings.

This software is released under the GNU General Public License.

8.4.8 tab-width option

This is the "tab width" option. If an indentation string contains tabs, then this value is used to compute the ending column of the prefix string.

8.4.9 sort option (-s)

This is the "sort input text" option. Causes the input text to be sorted. If an argument is supplied, it is presumed to be a pattern and the sort is based upon the matched text. If the pattern starts with or consists of an asterisk (*), then the sort is case insensitive.

8.4.10 format option (-f)

This is the "formatting string for each input" option. If you need to reformat each input text, the argument to this option is interpreted as an sprintf(3) format that is used to produce each output entry.

8.4.11 separation option (-S)

This is the "separation string - follows all but last" option. Use this option if, for example, you wish a comma to appear after each entry except the last.

8.4.12 line-separation option

This is the "string at end of all lines but last" option. Use this option if, for example, you wish a backslash to appear at the end of every line, except the last.

8.4.13 by-columns option

This is the "print entries in column order" option. Normally, the entries are printed out in order by rows and then columns. This option will cause the entries to be ordered within columns. The final column, instead of the final row, may be shorter than the others.

8.4.14 input option (-i)

This is the "input file (if not stdin)" option. This program normally runs as a filter, reading from standard input, columnizing and writing to standard out. This option redirects input to a file.

8.5 Invoking getdefs

If no input argument is provided or is set to simply "-", and if stdin is not a tty, then the list of input files will be read from stdin. This program extracts AutoGen definitions from a list of source files. Definitions are delimited by `/*=<entry-type> <entry-name>\n' and `=*/\n'. From that, this program creates a definition of the following form:

    #line nnn "source-file-name"
    entry_type = {
        name = entry_name;
        ...
    };

The ellipsis "..." is filled in by text found between the two delimiters, using the following rules:

Each entry is located by the pattern "\n[^*\n]*\\*[ \t]*([a-z][a-z0-9_]*):". Fundamentally, it finds a line that, after the first asterisk on the line, contains whitespace then a name and is immediately followed by a colon. The name becomes the name of the attribute and what follows, up to the next attribute, is its value.
If the first character of the value is either a single or double quote, then you are responsible for quoting the text as it gets inserted into the output definitions.
All the leading text on a line is stripped from the value. The leading text is everything before the first asterisk, the asterisk and all the whitespace characters that immediately follow it. If you want whitespace at the beginnings of the lines of text, you must do something like this:
* mumble: * " this is some\n" * " indented text."
If the `<entry-name>' is followed by a comma, the word `ifdef' (or 'ifndef') and a name `if_name', then the above entry will appear as:
#ifdef if_name #line nnn "source-file-name" entry_type = { name = entry_name; ... }; #endif
If you use of the subblock option, you can specify a nested value, See section subblock option. That is, this text:
* arg: int, this, what-it-is
with the `-subblock=arg=type,name,doc' option would yield:
arg = { type = int; name = this; doc = what-it-is; };

This section was generated by AutoGen, the aginfo template and the option descriptions for the getdefs program. It documents the getdefs usage text and option meanings.

This software is released under the GNU General Public License.

8.4.8 tab-width option

This is the "tab width" option. If an indentation string contains tabs, then this value is used to compute the ending column of the prefix string.

8.4.9 sort option (-s)

This is the "sort input text" option. Causes the input text to be sorted. If an argument is supplied, it is presumed to be a pattern and the sort is based upon the matched text. If the pattern starts with or consists of an asterisk (*), then the sort is case insensitive.

8.4.10 format option (-f)

This is the "formatting string for each input" option. If you need to reformat each input text, the argument to this option is interpreted as an sprintf(3) format that is used to produce each output entry.

8.4.11 separation option (-S)

This is the "separation string - follows all but last" option. Use this option if, for example, you wish a comma to appear after each entry except the last.

8.4.12 line-separation option

This is the "string at end of all lines but last" option. Use this option if, for example, you wish a backslash to appear at the end of every line, except the last.

8.4.13 by-columns option

This is the "print entries in column order" option. Normally, the entries are printed out in order by rows and then columns. This option will cause the entries to be ordered within columns. The final column, instead of the final row, may be shorter than the others.

8.4.14 input option (-i)

This is the "input file (if not stdin)" option. This program normally runs as a filter, reading from standard input, columnizing and writing to standard out. This option redirects input to a file.

8.5 Invoking getdefs

If no input argument is provided or is set to simply "-", and if stdin is not a tty, then the list of input files will be read from stdin. This program extracts AutoGen definitions from a list of source files. Definitions are delimited by `/*=<entry-type> <entry-name>\n' and `=*/\n'. From that, this program creates a definition of the following form:

    #line nnn "source-file-name"
    entry_type = {
        name = entry_name;
        ...
    };

The ellipsis "..." is filled in by text found between the two delimiters, using the following rules:

Each entry is located by the pattern "\n[^*\n]*\\*[ \t]*([a-z][a-z0-9_]*):". Fundamentally, it finds a line that, after the first asterisk on the line, contains whitespace then a name and is immediately followed by a colon. The name becomes the name of the attribute and what follows, up to the next attribute, is its value.
If the first character of the value is either a single or double quote, then you are responsible for quoting the text as it gets inserted into the output definitions.
All the leading text on a line is stripped from the value. The leading text is everything before the first asterisk, the asterisk and all the whitespace characters that immediately follow it. If you want whitespace at the beginnings of the lines of text, you must do something like this:
* mumble: * " this is some\n" * " indented text."
If the `<entry-name>' is followed by a comma, the word `ifdef' (or 'ifndef') and a name `if_name', then the above entry will appear as:
#ifdef if_name #line nnn "source-file-name" entry_type = { name = entry_name; ... }; #endif
If you use of the subblock option, you can specify a nested value, See section subblock option. That is, this text:
* arg: int, this, what-it-is
with the `-subblock=arg=type,name,doc' option would yield:
arg = { type = int; name = this; doc = what-it-is; };

This section was generated by AutoGen, the aginfo template and the option descriptions for the getdefs program. It documents the getdefs usage text and option meanings.

This software is released under the GNU General Public License.

8.4.8 tab-width option

This is the "tab width" option. If an indentation string contains tabs, then this value is used to compute the ending column of the prefix string.

8.4.9 sort option (-s)

This is the "sort input text" option. Causes the input text to be sorted. If an argument is supplied, it is presumed to be a pattern and the sort is based upon the matched text. If the pattern starts with or consists of an asterisk (*), then the sort is case insensitive.

8.4.10 format option (-f)

This is the "formatting string for each input" option. If you need to reformat each input text, the argument to this option is interpreted as an sprintf(3) format that is used to produce each output entry.

[