path: root/doc/invoke-getdefs.texi

@node getdefs Invocation
@section Invoking getdefs
@pindex getdefs
@cindex AutoGen Definition Extraction Tool
@ignore
#  -*- buffer-read-only: t -*- vi: set ro:
# 
# DO NOT EDIT THIS FILE   (invoke-getdefs.texi)
# 
# It has been AutoGen-ed  August 11, 2012 at 09:42:23 AM by AutoGen 5.16.2
# From the definitions    ./opts.def
# and the template file   agtexi-cmd
@end ignore

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

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

@enumerate
@item
The ellipsis @code{...} 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.

@item
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.

@item
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:

@example
 * mumble:
 * "  this is some\n"
 * "  indented text."
@end example

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

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

Will produce the following:

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

@item
If you use of the @code{subblock} option, you can specify a nested
value, @xref{getdefs subblock}.  That is, this text:

@example
 * arg:  int, this, what-it-is
@end example

with the @code{--subblock=arg=type,name,doc} option would yield:

@example
arg = @{ type = int; name = this; doc = what-it-is; @};
@end example
@end enumerate

This section was generated by @strong{AutoGen},
using the @code{agtexi-cmd} template and the option descriptions for the @code{getdefs} program.
This software is released under the GNU General Public License, version 3 or later.

@menu
* getdefs usage::                  getdefs help/usage (@option{help})
* getdefs def-selection::          def-selection options
* getdefs enumerating::            enumerating options
* getdefs doc-insert::             doc-insert options
* getdefs input-files::            input-files options
* getdefs doc-output::             doc-output options
* getdefs config::                 presetting/configuring getdefs
* getdefs exit status::            exit status
* getdefs See Also::               See Also
@end menu

@node getdefs usage
@subsection getdefs help/usage (@option{help})
@cindex getdefs help

This is the automatically generated usage text for getdefs.

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

@exampleindent 0
@example
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 these options:
                                output
                                - may appear multiple times
   Str base-name      Base name for output file(s)
                                - prohibits these options:
                                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 (2012-08-11)
Report getdefs bugs to bkorb@@gnu.org
@end example
@exampleindent 4

@node getdefs def-selection
@subsection def-selection options
Specify which definitions are of interest and what to say about them.
@subsubheading defs-to-get option.
@anchor{getdefs defs-to-get}
@cindex getdefs-defs-to-get

This is the ``regexp to look for after the "/*="'' option.
This option takes an argument string @file{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 @code{/*=}.
@subsubheading subblock option.
@anchor{getdefs subblock}
@cindex getdefs-subblock

This is the ``subblock definition names'' option.
This option takes an argument string @file{sub-def}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
may appear an unlimited number of times.
@end itemize

This option is used to create shorthand entries for nested definitions.
For example, with:
@table @r
@item using subblock thus
@code{--subblock=arg=argname,type,null}
@item and defining an @code{arg} thus
@code{arg: this, char *}
@item will then expand to:
@code{arg = @{ argname = this; type = "char *"; @};}
@end table
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:
@*
@code{arg = @{ argname = mumble; null = "yes"; @};}.
@subsubheading listattr option.
@anchor{getdefs listattr}
@cindex getdefs-listattr

This is the ``attribute with list of values'' option.
This option takes an argument string @file{def}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
may appear an unlimited number of times.
@end itemize

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:
@*
@code{listattr=foo} defined, the text:
@*
@code{foo: this, is, a, multi-list} will then expand to:
@*
@code{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.
@node getdefs enumerating
@subsection enumerating options
specify how to number the definitions.
@subsubheading ordering option.
@anchor{getdefs ordering}
@cindex getdefs-ordering

This is the ``alphabetize or use named file'' option.
This option takes an optional argument string @file{file-name}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
is enabled by default.
@end itemize

By default, ordering is alphabetical by the entry name.  Use,
@code{no-ordering} if order is unimportant.  Use @code{ordering}
with no argument to order without case sensitivity.  Use
@code{ordering=<file-name>} if chronological order is important.
getdefs will maintain the text content of @code{file-name}.
@code{file-name} need not exist.
@subsubheading first-index option.
@anchor{getdefs first-index}
@cindex getdefs-first-index

This is the ``the first index to apply to groups'' option.
This option takes an argument number @file{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.
@node getdefs doc-insert
@subsection doc-insert options
Definition insertion options.
@subsubheading filelist option.
@anchor{getdefs filelist}
@cindex getdefs-filelist

This is the ``insert source file names into defs'' option.
This option takes an optional argument string @file{file}.
Inserts the name of each input file into the output definitions.
If no argument is supplied, the format will be:
@example
infile = '%s';
@end example
If an argument is supplied, that string will be used for the entry
name instead of @var{infile}.
@subsubheading assign option.
@anchor{getdefs assign}
@cindex getdefs-assign

This is the ``global assignments'' option.
This option takes an argument string @file{ag-def}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
may appear an unlimited number of times.
@end itemize

The argument to each copy of this option will be inserted into
the output definitions, with only a semicolon attached.
@subsubheading common-assign option.
@anchor{getdefs common-assign}
@cindex getdefs-common-assign

This is the ``assignments common to all blocks'' option.
This option takes an argument string @file{ag-def}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
may appear an unlimited number of times.
@end itemize

The argument to each copy of this option will be inserted into
each output definition, with only a semicolon attached.
@subsubheading copy option.
@anchor{getdefs copy}
@cindex getdefs-copy

This is the ``file(s) to copy into definitions'' option.
This option takes an argument string @file{file}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
may appear an unlimited number of times.
@end itemize

The content of each file named by these options will be inserted into
the output definitions.
@subsubheading srcfile option.
@anchor{getdefs srcfile}
@cindex getdefs-srcfile

This is the ``insert source file name into each def'' option.
This option takes an optional argument string @file{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:
@example
srcfile = '%s';
@end example
If an argument is supplied, that string will be used for the entry
name instead of @var{srcfile}.
@subsubheading linenum option.
@anchor{getdefs linenum}
@cindex getdefs-linenum

This is the ``insert source line number into each def'' option.
This option takes an optional argument string @file{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:
@example
linenum = '%s';
@end example
If an argument is supplied, that string will be used for the entry
name instead of @var{linenum}.
@node getdefs input-files
@subsection input-files options
specify which files to search for markers.
@subsubheading input option.
@anchor{getdefs input}
@cindex getdefs-input

This is the ``input file to search for defs'' option.
This option takes an argument string @file{src-file}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
may appear an unlimited number of times.
@end itemize

All files that are to be searched for definitions must be named on
the command line or read from @code{stdin}.  If there is only one
@code{input} option and it is the string, "-", then the input file
list is read from @code{stdin}.  If a command line argument is not
an option name and does not contain an assignment operator
(@code{=}), then it defaults to being an input file name.
At least one input file must be specified.
@node getdefs doc-output
@subsection doc-output options
Definition output disposition options:.
@subsubheading output option.
@anchor{getdefs output}
@cindex getdefs-output

This is the ``output file to open'' option.
This option takes an argument string @file{file}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
is a member of the autogen class of options.
@end itemize

If you are not sending the output to an AutoGen process,
you may name an output file instead.
@subsubheading autogen option.
@anchor{getdefs autogen}
@cindex getdefs-autogen

This is the ``invoke autogen with defs'' option.
This option takes an optional argument string @file{ag-cmd}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
is enabled by default.
@item
is a member of the autogen class of options.
@end itemize

This is the default output mode.  Specifying @code{no-autogen} is
equivalent to @code{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.
@subsubheading template option.
@anchor{getdefs template}
@cindex getdefs-template

This is the ``template name'' option.
This option takes an argument string @file{file}.
Specifies the template name to be used for generating the final output.
@subsubheading agarg option.
@anchor{getdefs agarg}
@cindex getdefs-agarg

This is the ``autogen argument'' option.
This option takes an argument string @file{ag-opt}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
may appear an unlimited number of times.
@item
must not appear in combination with any of the following options:
output.
@end itemize

This is a pass-through argument.  It allows you to specify any
arbitrary argument to be passed to AutoGen.
@subsubheading base-name option.
@anchor{getdefs base-name}
@cindex getdefs-base-name

This is the ``base name for output file(s)'' option.
This option takes an argument string @file{name}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
must not appear in combination with any of the following options:
output.
@end itemize

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 @code{template} option.  If that is not provided either, then
it is set to the base name of the current directory.


@node getdefs config
@subsection presetting/configuring getdefs

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


@noindent
@code{libopts} will search in @file{/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 @file{.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:
@example
[GETDEFS]
@end example
@noindent
or by
@example
<?program getdefs>
@end example
@noindent
Do not mix these styles within one configuration file.

Compound values and carefully constructed string values may also be
specified using XML syntax:
@example
<option-name>
   <sub-opt>...&lt;...&gt;...</sub-opt>
</option-name>
@end example
@noindent
yielding an @code{option-name.sub-opt} string value of
@example
"...<...>..."
@end example
@code{AutoOpts} does not track suboptions.  You simply note that it is a
hierarchicly valued option.  @code{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:

@subsubheading 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:

@table @samp
@item version
Only print the version.  This is the default.
@item copyright
Name the copyright usage licensing terms.
@item verbose
Print the full copyright usage licensing terms.
@end table

@node getdefs exit status
@subsection getdefs exit status

One of the following exit values will be returned:
@table @samp
@item 0 (EXIT_SUCCESS)
Successful program execution.
@item 1 (EXIT_FAILURE)
The operation failed or the command syntax was not valid.
@item 66 (EX_NOINPUT)
A specified configuration file could not be loaded.
@item 70 (EX_SOFTWARE)
libopts had an internal operational error.  Please report
it to autogen-users@@lists.sourceforge.net.  Thank you.
@end table
@node getdefs See Also
@subsection getdefs See Also
This program is documented more fully in the Getdefs section
of the Add-On chapter in the @code{AutoGen} Info system documentation.