1
<?xml version="1.0" encoding="ISO8859-1"?>
5
$Id: getopts.xml,v 1.2 2004/09/13 19:27:49 michael Exp $
6
This file is part of the FPC documentation.
7
Copyright (C) 1997, by Michael Van Canneyt
9
The FPC documentation is free text; you can redistribute it and/or
10
modify it under the terms of the GNU Library General Public License as
11
published by the Free Software Foundation; either version 2 of the
12
License, or (at your option) any later version.
14
The FPC Documentation is distributed in the hope that it will be useful,
15
but WITHOUT ANY WARRANTY; without even the implied warranty of
16
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17
Library General Public License for more details.
19
You should have received a copy of the GNU Library General Public
20
License along with the FPC documentation; see the file COPYING.LIB. If not,
21
write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
22
Boston, MA 02111-1307, USA.
25
<module name="getopts">
26
<short>GNU compatible access to command-line options.</short>
27
<!-- \FPCexampledir{optex} -->
30
This document describes the GETOPTS unit for Free Pascal. It was written for
31
linux by Michael Van Canneyt. It now also works for all supported platforms.
34
The getopts unit provides a mechanism to handle command-line options in
35
a structured way, much like the GNU getopts mechanism. It allows you to
36
define the valid options for you program, and the unit will then parse the
37
command-line options for you, and inform you of any errors.
41
<element name="OptSpecifier">
42
<short>Character indicating an option on the command-line.</short>
45
<element name="Orderings">
46
<short>Command-line ordering options.</short>
48
<element name="Orderings.require_order">
49
<short>Don't touch the ordering of the command-line options</short>
51
<element name="Orderings.permute">
52
<short>Change command-line options.</short>
54
<element name="Orderings.return_in_order">
55
<short>Return options in the correct order.</short>
59
<element name="No_Argument">
60
<short>Specifies that a long option does not take an argument.</short>
63
<element name="Required_Argument">
64
<short>Specifies that a long option needs an argument.</short>
67
<element name="Optional_Argument">
68
<short>Specifies that a long option optionally takes an argument.</short>
71
<element name="EndOfOptions">
72
<short>Returned by <link id="getopt"/>,<link id="getlongopts"/> to indicate that
73
there are no more options.</short>
76
<element name="TOption">
77
<short>Long option description record</short>
79
The <var>TOption</var> type is used to communicate the long options to
80
<link id="GetLongOpts"/>.
81
The <var>Name</var> field is the name of the option. <var>Has_arg</var>
82
specifies if the option
83
wants an argument, <var>Flag</var> is a pointer to a <var>char</var>, which
85
<var>Value</var>, if it is non-<var>nil</var>.
89
<element name="TOption.Name">
90
<short>Long option name</short>
92
<element name="TOption.Has_arg">
93
<short>Does the option have arguments (values)</short>
95
<element name="TOption.Flag">
98
<element name="TOption.Value">
99
<short>Value to return when option is encountered</short>
102
<element name="POption">
103
<short>Pointer to <link id="TOption"/> record.</short>
106
<element name="OptArg">
107
<short>Set to the argument of an option, if the option needs one.</short>
110
<element name="Optind">
111
<short>Index of the current <var>paramstr()</var>.</short>
113
when all options have been processed, <var>optind</var> is the index of the first
114
non-option parameter. This is a read-only variable. Note that it can become
115
equal to <var>paramcount+1</var>.
119
<element name="OptErr">
120
<short>Indicates whether <var>getopt()</var> prints error messages.</short>
123
<element name="OptOpt">
124
<short>In case of an error, contains the character causing the error.</short>
127
<element name="GetLongOpts">
128
<short>Return next long option.</short>
131
Returns the next option found on the command-line, taking into account long
132
options as well. If no more options are
133
found, returns <var>EndOfOptions</var>. If the option requires an argument, it is
134
returned in the <var>OptArg</var> variable.
137
<var>ShortOptions</var> is a string containing all possible one-letter options.
138
(see <link id="Getopt"/> for its description and use)
139
<var>LongOpts</var> is a pointer to the first element of an array of <var>Option</var>
140
records, the last of which needs a name of zero length.
143
The function tries to match the names even partially (i.e. <var>--app</var>
144
will match e.g. the <var>append</var> option), but will report an error in case of
146
If the option needs an argument, set <var>Has_arg</var> to
147
<var>Required_argument</var>, if the option optionally has an argument, set
148
<var>Has_arg</var> to <var>Optional_argument</var>. If the option needs no argument,
149
set <var>Has_arg</var> to zero.
152
Required arguments can be specified in two ways :
155
<li>Pasted to the option : <var>--option=value</var></li>
156
<li>As a separate argument : <var>--option value</var></li>
159
Optional arguments can only be specified through the first method.
163
see <link id="Getopt"/>.
170
<element name="Getopt">
171
<short>Get next short option.</short>
174
Returns the next option found on the command-line. If no more options are
175
found, returns <var>EndOfOptions</var>. If the option requires an argument, it is
176
returned in the <var>OptArg</var> variable.
179
<var>ShortOptions</var> is a string containing all possible one-letter options.
180
If a letter is followed by a colon (:), then that option needs an argument.
181
If a letter is followed by 2 colons, the option has an optional argument.
182
If the first character of <var>shortoptions</var> is a <var>'+'</var> then options following a non-option are
183
regarded as non-options (standard Unix behavior). If it is a <var>'-'</var>,
184
then all non-options are treated as arguments of a option with character
185
<var>#0</var>. This is useful for applications that require their options in
186
the exact order as they appear on the command-line.
187
If the first character of <var>shortoptions</var> is none of the above, options
188
and non-options are permuted, so all non-options are behind all options.
189
This allows options and non-options to be in random order on the command
194
Errors are reported through giving back a <var>'?'</var> character. <var>OptOpt</var>
195
then gives the character which caused the error. If <var>OptErr</var> is
196
<var>True</var> then getopt prints an error-message to <var>stdout</var>.
199
<link id="GetLongOpts"/>
201
<example file="optex/optex"/>
206
</fpdoc-descriptions>
b'\\ No newline at end of file'
added
removed
docs/getopts.xml
