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
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<fpdoc-descriptions>
<!--
$Id: getopts.xml,v 1.2 2004/09/13 19:27:49 michael Exp $
This file is part of the FPC documentation.
Copyright (C) 1997, by Michael Van Canneyt
The FPC documentation is free text; you can redistribute it and/or
modify it under the terms of the GNU Library General Public License as
published by the Free Software Foundation; either version 2 of the
License, or (at your option) any later version.
The FPC Documentation is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.
You should have received a copy of the GNU Library General Public
License along with the FPC documentation; see the file COPYING.LIB. If not,
write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.
-->
<package name="rtl">
<module name="getopts">
<short>GNU compatible access to command-line options.</short>
<!-- \FPCexampledir{optex} -->
<descr>
<p>
This document describes the GETOPTS unit for Free Pascal. It was written for
linux by Michael Van Canneyt. It now also works for all supported platforms.
</p>
<p>
The getopts unit provides a mechanism to handle command-line options in
a structured way, much like the GNU getopts mechanism. It allows you to
define the valid options for you program, and the unit will then parse the
command-line options for you, and inform you of any errors.
</p>
</descr>
<element name="OptSpecifier">
<short>Character indicating an option on the command-line.</short>
</element>
<element name="Orderings">
<short>Command-line ordering options.</short>
</element>
<element name="Orderings.require_order">
<short>Don't touch the ordering of the command-line options</short>
</element>
<element name="Orderings.permute">
<short>Change command-line options.</short>
</element>
<element name="Orderings.return_in_order">
<short>Return options in the correct order.</short>
</element>
<element name="No_Argument">
<short>Specifies that a long option does not take an argument.</short>
</element>
<element name="Required_Argument">
<short>Specifies that a long option needs an argument.</short>
</element>
<element name="Optional_Argument">
<short>Specifies that a long option optionally takes an argument.</short>
</element>
<element name="EndOfOptions">
<short>Returned by <link id="getopt"/>,<link id="getlongopts"/> to indicate that
there are no more options.</short>
</element>
<element name="TOption">
<short>Long option description record</short>
<descr>
The <var>TOption</var> type is used to communicate the long options to
<link id="GetLongOpts"/>.
The <var>Name</var> field is the name of the option. <var>Has_arg</var>
specifies if the option
wants an argument, <var>Flag</var> is a pointer to a <var>char</var>, which
is set to
<var>Value</var>, if it is non-<var>nil</var>.
</descr>
</element>
<element name="TOption.Name">
<short>Long option name</short>
</element>
<element name="TOption.Has_arg">
<short>Does the option have arguments (values)</short>
</element>
<element name="TOption.Flag">
<short>Flag</short>
</element>
<element name="TOption.Value">
<short>Value to return when option is encountered</short>
</element>
<element name="POption">
<short>Pointer to <link id="TOption"/> record.</short>
</element>
<element name="OptArg">
<short>Set to the argument of an option, if the option needs one.</short>
</element>
<element name="Optind">
<short>Index of the current <var>paramstr()</var>.</short>
<descr>
when all options have been processed, <var>optind</var> is the index of the first
non-option parameter. This is a read-only variable. Note that it can become
equal to <var>paramcount+1</var>.
</descr>
</element>
<element name="OptErr">
<short>Indicates whether <var>getopt()</var> prints error messages.</short>
</element>
<element name="OptOpt">
<short>In case of an error, contains the character causing the error.</short>
</element>
<element name="GetLongOpts">
<short>Return next long option.</short>
<descr>
<p>
Returns the next option found on the command-line, taking into account long
options as well. If no more options are
found, returns <var>EndOfOptions</var>. If the option requires an argument, it is
returned in the <var>OptArg</var> variable.
</p>
<p>
<var>ShortOptions</var> is a string containing all possible one-letter options.
(see <link id="Getopt"/> for its description and use)
<var>LongOpts</var> is a pointer to the first element of an array of <var>Option</var>
records, the last of which needs a name of zero length.
</p>
<p>
The function tries to match the names even partially (i.e. <var>--app</var>
will match e.g. the <var>append</var> option), but will report an error in case of
ambiguity.
If the option needs an argument, set <var>Has_arg</var> to
<var>Required_argument</var>, if the option optionally has an argument, set
<var>Has_arg</var> to <var>Optional_argument</var>. If the option needs no argument,
set <var>Has_arg</var> to zero.
</p>
<p>
Required arguments can be specified in two ways :
</p>
<ol>
<li>Pasted to the option : <var>--option=value</var></li>
<li>As a separate argument : <var>--option value</var></li>
</ol>
<p>
Optional arguments can only be specified through the first method.
</p>
</descr>
<errors>
see <link id="Getopt"/>.
</errors>
<seealso>
<link id="Getopt"/>
</seealso>
</element>
<element name="Getopt">
<short>Get next short option.</short>
<descr>
<p>
Returns the next option found on the command-line. If no more options are
found, returns <var>EndOfOptions</var>. If the option requires an argument, it is
returned in the <var>OptArg</var> variable.
</p>
<p>
<var>ShortOptions</var> is a string containing all possible one-letter options.
If a letter is followed by a colon (:), then that option needs an argument.
If a letter is followed by 2 colons, the option has an optional argument.
If the first character of <var>shortoptions</var> is a <var>'+'</var> then options following a non-option are
regarded as non-options (standard Unix behavior). If it is a <var>'-'</var>,
then all non-options are treated as arguments of a option with character
<var>#0</var>. This is useful for applications that require their options in
the exact order as they appear on the command-line.
If the first character of <var>shortoptions</var> is none of the above, options
and non-options are permuted, so all non-options are behind all options.
This allows options and non-options to be in random order on the command
line.
</p>
</descr>
<errors>
Errors are reported through giving back a <var>'?'</var> character. <var>OptOpt</var>
then gives the character which caused the error. If <var>OptErr</var> is
<var>True</var> then getopt prints an error-message to <var>stdout</var>.
</errors>
<seealso>
<link id="GetLongOpts"/>
</seealso>
<example file="optex/optex"/>
</element>
</module>
</package>
</fpdoc-descriptions>
|
