8.6 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;
        ...
    };

1. The ellipsis ... is filled in by text found between the two delimiters. Each line of text is stripped of anything before the first asterisk, then leading asterisks, then any leading or trailing white space.
2. If what is left starts with what looks like a name followed by a colon, then it is interpreted as a name followed by a value.
3. 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. So, 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."

4. If the <entry-name> is followed by a comma, the word ifdef (or ifndef) and a name if_name, then the above entry will be under ifdef control.

   /*=group entry_name, ifdef FOO * attr: attribute value =*/

   Will produce the following:

   #ifdef FOO #line nnn "source-file-name" group = { name = entry_name; attr = 'attribute value'; }; #endif

5. If you use of the subblock option, you can specify a nested value, See getdefs subblock. 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, using the agtexi-cmd template and the option descriptions for the getdefs program. This software is released under the GNU General Public License, version 3 or later.

8.6.1 getdefs help/usage (‘help’)

This is the automatically generated usage text for getdefs.

The text printed is the same whether selected with the help option (‘help’) or the more-help option (‘more-help’). more-help will print the usage text by passing it through a pager program. more-help is disabled on platforms without a working fork(2) function. The PAGER environment variable is used to select the program, defaulting to ‘more’. Both will exit with a status code of 0.

getdefs (GNU AutoGen) - AutoGen Definition Extraction Tool - Ver. 1.5
Usage:  getdefs [ <option-name>[{=| }<val>] ]...

Specify which definitions are of interest and what to say about them:

   Arg Option-Name    Description
   Str defs-to-get    Regexp to look for after the "/*="
   Str subblock       subblock definition names
                                - may appear multiple times
   Str listattr       attribute with list of values
                                - may appear multiple times

specify how to number the definitions:

   Arg Option-Name    Description
   opt ordering       Alphabetize or use named file
                                - disabled as '--no-ordering'
                                - enabled by default
   Num first-index    The first index to apply to groups

Definition insertion options:

   Arg Option-Name    Description
   opt filelist       Insert source file names into defs
   Str assign         Global assignments
                                - may appear multiple times
   Str common-assign  Assignments common to all blocks
                                - may appear multiple times
   Str copy           File(s) to copy into definitions
                                - may appear multiple times
   opt srcfile        Insert source file name into each def
   opt linenum        Insert source line number into each def

specify which files to search for markers:

   Arg Option-Name    Description
   Str input          Input file to search for defs
                                - may appear multiple times
                                - default option for unnamed options

Definition output disposition options::

   Arg Option-Name    Description
   Str output         Output file to open
                                - an alternate for 'autogen'
   opt autogen        Invoke AutoGen with defs
                                - disabled as '--no-autogen'
                                - enabled by default
   Str template       Template Name
   Str agarg          AutoGen Argument
                                - prohibits the option 'output'
                                - may appear multiple times
   Str base-name      Base name for output file(s)
                                - prohibits the option 'output'

Version, usage and configuration options:

   Arg Option-Name    Description
   opt version        output version information and exit
   no  help           display extended usage information and exit
   no  more-help      extended usage information passed thru pager
   opt save-opts      save the option state to a config file
   Str load-opts      load options from a config file
                                - disabled as '--no-load-opts'
                                - may appear multiple times

All arguments are named options.
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'.

The following option preset mechanisms are supported:
 - reading file /dev/null
This program extracts AutoGen definitions from a list of source files.
Definitions are delimited by '/*=<entry-type> <entry-name>\n' and '=*/\n'.
Packaged by Bruce (2015-08-21)
Report getdefs bugs to bkorb@gnu.org

8.6.2 def-selection options

Specify which definitions are of interest and what to say about them.

defs-to-get option.

This is the “regexp to look for after the "/*="” option. This option takes a string argument ‘reg-ex’. If you want definitions only from a particular category, or even with names matching particular patterns, then specify this regular expression for the text that must follow the /*=.

subblock option.

This is the “subblock definition names” option. This option takes a string argument ‘sub-def’.

This option has some usage constraints. It:

• may appear an unlimited number of times.

This option is used to create shorthand entries for nested definitions. For example, with:

using subblock thus

--subblock=arg=argname,type,null

and defining an arg thus

arg: this, char *

will then expand to:

arg = { argname = this; type = "char *"; };

The "this, char *" string is separated at the commas, with the white space removed. You may use characters other than commas by starting the value string with a punctuation character other than a single or double quote character. You may also omit intermediate values by placing the commas next to each other with no intervening white space. For example, "+mumble++yes+" will expand to:
arg = { argname = mumble; null = "yes"; };.

listattr option.

This is the “attribute with list of values” option. This option takes a string argument ‘def’.

This option has some usage constraints. It:

• may appear an unlimited number of times.

This option is used to create shorthand entries for definitions that generally appear several times. That is, they tend to be a list of values. For example, with:
listattr=foo defined, the text:
foo: this, is, a, multi-list will then expand to:
foo = 'this', 'is', 'a', 'multi-list';
The texts are separated by the commas, with the white space removed. You may use characters other than commas by starting the value string with a punctuation character other than a single or double quote character.

8.6.3 enumerating options

specify how to number the definitions.

ordering option.

This is the “alphabetize or use named file” option. This option takes an optional string argument ‘file-name’.

This option has some usage constraints. It:

• can be disabled with –no-ordering.
• It is enabled by default.

By default, ordering is alphabetical by the entry name. Use, no-ordering if order is unimportant. Use ordering with no argument to order without case sensitivity. Use ordering=<file-name> if chronological order is important. getdefs will maintain the text content of file-name. file-name need not exist.

first-index option.

This is the “the first index to apply to groups” option. This option takes a number argument ‘first-index’. By default, the first occurrence of a named definition will have an index of zero. Sometimes, that needs to be a reserved value. Provide this option to specify a different starting point.

8.6.4 doc-insert options

Definition insertion options.

filelist option.

This is the “insert source file names into defs” option. This option takes an optional string argument ‘file’. Inserts the name of each input file into the output definitions. If no argument is supplied, the format will be:

infile = '%s';

If an argument is supplied, that string will be used for the entry name instead of infile.

assign option.

This is the “global assignments” option. This option takes a string argument ‘ag-def’.

This option has some usage constraints. It:

• may appear an unlimited number of times.

The argument to each copy of this option will be inserted into the output definitions, with only a semicolon attached.

common-assign option.

This is the “assignments common to all blocks” option. This option takes a string argument ‘ag-def’.

This option has some usage constraints. It:

• may appear an unlimited number of times.

The argument to each copy of this option will be inserted into each output definition, with only a semicolon attached.

copy option.

This is the “file(s) to copy into definitions” option. This option takes a string argument ‘file’.

This option has some usage constraints. It:

• may appear an unlimited number of times.

The content of each file named by these options will be inserted into the output definitions.

srcfile option.

This is the “insert source file name into each def” option. This option takes an optional string argument ‘file’. Inserts the name of the input file where a definition was found into the output definition. If no argument is supplied, the format will be:

srcfile = '%s';

If an argument is supplied, that string will be used for the entry name instead of srcfile.

linenum option.

This is the “insert source line number into each def” option. This option takes an optional string argument ‘def-name’. Inserts the line number in the input file where a definition was found into the output definition. If no argument is supplied, the format will be:

linenum = '%s';

If an argument is supplied, that string will be used for the entry name instead of linenum.

8.6.5 input-files options

specify which files to search for markers.

input option.

This is the “input file to search for defs” option. This option takes a string argument ‘src-file’.

This option has some usage constraints. It:

• may appear an unlimited number of times.

All files that are to be searched for definitions must be named on the command line or read from stdin. If there is only one input option and it is the string, "-", then the input file list is read from stdin. If a command line argument is not an option name and does not contain an assignment operator (=), then it defaults to being an input file name. At least one input file must be specified.

8.6.6 doc-output options

Definition output disposition options:.

output option.

This is the “output file to open” option. This option takes a string argument ‘file’.

This option has some usage constraints. It:

• is a member of the autogen class of options.

If you are not sending the output to an AutoGen process, you may name an output file instead.

autogen option.

This is the “invoke autogen with defs” option. This option takes an optional string argument ‘ag-cmd’.

This option has some usage constraints. It:

• can be disabled with –no-autogen.
• It is enabled by default.
• is a member of the autogen class of options.

This is the default output mode. Specifying no-autogen is equivalent to output=-. If you supply an argument to this option, that program will be started as if it were AutoGen and its standard in will be set to the output definitions of this program.

template option.

This is the “template name” option. This option takes a string argument ‘file’. Specifies the template name to be used for generating the final output.

agarg option.

This is the “autogen argument” option. This option takes a string argument ‘ag-opt’.

This option has some usage constraints. It:

• may appear an unlimited number of times.
• must not appear in combination with any of the following options: output.

This is a pass-through argument. It allows you to specify any arbitrary argument to be passed to AutoGen.

base-name option.

This is the “base name for output file(s)” option. This option takes a string argument ‘name’.

This option has some usage constraints. It:

• must not appear in combination with any of the following options: output.

When output is going to AutoGen, a base name must either be supplied or derived. If this option is not supplied, then it is taken from the template option. If that is not provided either, then it is set to the base name of the current directory.

8.6.7 presetting/configuring getdefs

Any option that is not marked as not presettable may be preset by loading values from configuration ("rc" or "ini") files.

libopts will search in ‘/dev/null’ for configuration (option) data. If this is a plain file, it is simply processed. If it is a directory, then a file named ‘.getdefsrc’ is searched for within that directory.

Configuration files may be in a wide variety of formats. The basic format is an option name followed by a value (argument) on the same line. Values may be separated from the option name with a colon, equal sign or simply white space. Values may be continued across multiple lines by escaping the newline with a backslash.

Multiple programs may also share the same initialization file. Common options are collected at the top, followed by program specific segments. The segments are separated by lines like:

[GETDEFS]

or by

<?program getdefs>

Do not mix these styles within one configuration file.

Compound values and carefully constructed string values may also be specified using XML syntax:

<option-name>
   <sub-opt>...&lt;...&gt;...</sub-opt>
</option-name>

yielding an option-name.sub-opt string value of

"...<...>..."

AutoOpts does not track suboptions. You simply note that it is a hierarchicly valued option. AutoOpts does provide a means for searching the associated name/value pair list (see: optionFindValue).

The command line options relating to configuration and/or usage help are:

version

Print the program version to standard out, optionally with licensing information, then exit 0. The optional argument specifies how much licensing detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument. Only the first letter of the argument is examined:

‘version’

Only print the version. This is the default.

‘copyright’

Name the copyright usage licensing terms.

‘verbose’

Print the full copyright usage licensing terms.

8.6.8 getdefs exit status

One of the following exit values will be returned:

‘0 (EXIT_SUCCESS)’

Successful program execution.

‘1 (EXIT_FAILURE)’

The operation failed or the command syntax was not valid.

‘66 (EX_NOINPUT)’

A specified configuration file could not be loaded.

‘70 (EX_SOFTWARE)’

libopts had an internal operational error. Please report it to autogen-users@lists.sourceforge.net. Thank you.

8.6.9 getdefs See Also

This program is documented more fully in the Getdefs section of the Add-On chapter in the AutoGen Info system documentation.

This document was generated by Bruce Korb on August 21, 2015 using texi2html 1.82.