mirror of
https://gitlab.com/freepascal.org/fpc/source.git
synced 2025-04-20 18:29:28 +02:00
206 lines
6.9 KiB
XML
206 lines
6.9 KiB
XML
<?xml version="1.0" encoding="ISO8859-1"?>
|
|
<fpdoc-descriptions>
|
|
<!--
|
|
|
|
$Id$
|
|
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> |