/usr/share/doc/autogen-doc/autogen.html/Option-Argument-Handling.html is in autogen-doc 1:5.18.7-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This manual is for GNU AutoGen version 5.18, updated December 2015.
Copyright (C) 1992-2015 by Bruce Korb.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- Created by GNU Texinfo 6.0, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GNU AutoGen - The Automated Program Generator: Option Argument Handling</title>
<meta name="description" content="GNU AutoGen - The Automated Program Generator: Option Argument Handling">
<meta name="keywords" content="GNU AutoGen - The Automated Program Generator: Option Argument Handling">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="AutoOpts.html#AutoOpts" rel="index" title="AutoOpts">
<link href="Function-Index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Option-Definitions.html#Option-Definitions" rel="up" title="Option Definitions">
<link href="Internationalizing-Options.html#Internationalizing-Options" rel="next" title="Internationalizing Options">
<link href="arg_002ddefault.html#arg_002ddefault" rel="prev" title="arg-default">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space: nowrap}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: serif; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
</head>
<body lang="en">
<a name="Option-Argument-Handling"></a>
<div class="header">
<p>
Next: <a href="Internationalizing-Options.html#Internationalizing-Options" accesskey="n" rel="next">Internationalizing Options</a>, Previous: <a href="Option-Arguments.html#Option-Arguments" accesskey="p" rel="prev">Option Arguments</a>, Up: <a href="Option-Definitions.html#Option-Definitions" accesskey="u" rel="up">Option Definitions</a> [<a href="Function-Index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="AutoOpts.html#AutoOpts" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Option-Argument-Handling-1"></a>
<h4 class="subsection">7.5.7 Option Argument Handling</h4>
<a name="index-Option-Argument-Handling"></a>
<p>AutoOpts will either specify or automatically generate callback procedures
for options that take specialized arguments. The only option argument types
that are not specialized are plain string arguments and no argument at all.
For options that fall into one of those two categories, you may specify your
own callback function, as specified below. If you do this and if you
specify that options are resettable (see <a href="automatic-options.html#automatic-options">automatic options</a>), then your
option handling code <strong>must</strong> look for the ‘<samp>OPTST_RESET</samp>’ bit in
the <code>fOptState</code> field of the option descriptor.
</p>
<p>If the option takes a string argument, then the <code>stack-arg</code> attribute can
be used to specify that the option is to be handled by the <code>libopts</code>
<code>stackOptArg()</code> and <code>unstackOptArg()</code> library procedures (see
below). In this case, you may not provide option handling code.
</p>
<p>Finally, ‘<samp>documentation</samp>’ options (see <a href="opt_002dattr-documentation.html#opt_002dattr-documentation">opt-attr documentation</a>) may
also be marked as <samp>settable</samp> (see <a href="opt_002dattr-settable.html#opt_002dattr-settable">opt-attr settable</a>) and have
special callback functions (either ‘<samp>flag-code</samp>’, ‘<samp>extract-code</samp>’,
or ‘<samp>call-proc</samp>’).
</p>
<dl compact="compact">
<dt>‘<samp>flag-code</samp>’</dt>
<dd><a name="index-flag_002dcode"></a>
<p>statements to execute when the option is encountered. This may be used in
conjunction with option argument types that cause AutoOpts to emit handler
code. If you do this, the ‘<samp>flag-code</samp>’ with index zero (0) is emitted
into the handler code <em>before</em> the argument is handled, and the entry
with index one (1) is handled afterward.
</p>
<p>The generated procedure will be laid out something like this:
</p>
<div class="example">
<pre class="example">static void
doOpt<name>(tOptions* pOptions, tOptDesc* pOptDesc)
{
<flag-code[0]>
<AutoOpts defined handler code>
<flag-code[1]>
}
</pre></div>
<p>Only certain fields within the <code>tOptions</code> and <code>tOptDesc</code>
structures may be accessed. See <a href="Option-Processing-Data.html#Option-Processing-Data">Option Processing Data</a>. When writing
this code, you must be very careful with the <code>pOptions</code> pointer. The
handler code is called with this pointer set to special values for handling
special situations. Your code must handle them. As an example,
look at <code>optionEnumerationVal</code> in <samp>enum.c</samp>.
</p>
</dd>
<dt>‘<samp>extract-code</samp>’</dt>
<dd><a name="index-extract_002dcode"></a>
<p>This is effectively identical to <code>flag-code</code>, except that the
source is kept in the output file instead of the definitions file
and you cannot use this in conjunction with options with arguments,
other than string arguments.
</p>
<p>A long comment is used to demarcate the code. You must not modify
that marker. <i>Before</i> regenerating the option code file,
the old file is renamed from MUMBLE.c to MUMBLE.c.save. The template
will be looking there for the text to copy into the new output file.
</p>
</dd>
<dt>‘<samp>call-proc</samp>’</dt>
<dd><a name="index-call_002dproc"></a>
<p>external procedure to call when option is encountered. The calling
sequence must conform to the sequence defined above for the generated
procedure, <code>doOpt<name></code>. It has the same restrictions
regarding the fields within the structures passed in as arguments.
See <a href="Option-Processing-Data.html#Option-Processing-Data">Option Processing Data</a>.
</p>
</dd>
<dt>‘<samp>flag-proc</samp>’</dt>
<dd><a name="index-flag_002dproc"></a>
<p>Name of another option whose <code>flag-code</code> can be executed
when this option is encountered.
</p>
</dd>
<dt>‘<samp>stack-arg</samp>’</dt>
<dd><a name="index-stack_002darg"></a>
<p>Call a special library routine to stack the option’s arguments. Special
macros in the interface file are provided for determining how many of the
options were found (<code>STACKCT_OPT(NAME)</code>) and to obtain a pointer to a
list of pointers to the argument values (<code>STACKLST_OPT(NAME)</code>).
Obviously, for a stackable argument, the <code>max</code> attribute
(see <a href="Common-Attributes.html#Common-Attributes">Common Attributes</a>) needs to be set higher than <code>1</code>.
</p>
<p>If this stacked argument option has a disablement prefix, then the entire
stack of arguments will be cleared by specifying the option with that
disablement prefix.
</p>
</dd>
<dt>‘<samp>unstack-arg</samp>’</dt>
<dd><a name="index-unstack_002darg"></a>
<p>Call a special library routine to remove (<code>unstack</code>) strings
from a <code>stack-arg</code> option stack. This attribute must name
the option that is to be <code>unstacked</code>. Neither this option nor
the stacked argument option it references may be equivalenced to
another option.
</p></dd>
</dl>
<hr>
<div class="header">
<p>
Next: <a href="Internationalizing-Options.html#Internationalizing-Options" accesskey="n" rel="next">Internationalizing Options</a>, Previous: <a href="Option-Arguments.html#Option-Arguments" accesskey="p" rel="prev">Option Arguments</a>, Up: <a href="Option-Definitions.html#Option-Definitions" accesskey="u" rel="up">Option Definitions</a> [<a href="Function-Index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="AutoOpts.html#AutoOpts" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|