diff options
Diffstat (limited to 'doc/invoke-getdefs.texi')
| -rw-r--r-- | doc/invoke-getdefs.texi | 599 |
1 files changed, 599 insertions, 0 deletions
diff --git a/doc/invoke-getdefs.texi b/doc/invoke-getdefs.texi new file mode 100644 index 0000000..b07257c --- /dev/null +++ b/doc/invoke-getdefs.texi @@ -0,0 +1,599 @@ +@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>...<...>...</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. + |