freepascal.compiler/docs/getopts.tex

%
%   $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. 
%
\chapter{The GETOPTS unit.}
\FPCexampledir{optex}

This document describes the GETOPTS unit for Free Pascal. It was written for
\linux\ by Micha\"el Van Canneyt. It now also works for all supported platforms.

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.

The chapter is divided in 2 sections:
\begin{itemize}
\item The first section lists types, constants and variables from the
interface part of the unit.
\item The second section describes the functions defined in the unit.
\end{itemize}
\section {Types, Constants and variables : }
\subsection{Constants}
\var{No\_Argument=0} : Specifies that a long option does not take an
argument. \\
\var{Required\_Argument=1} : Specifies that a long option needs an
argument. \\
\var{Optional\_Argument=2} : Specifies that a long option optionally takes an
argument. \\
\var{EndOfOptions=\#255}  : Returned by getopt, getlongopts to indicate that
there are no more options.
\subsection{Types}
\begin{verbatim}
TOption = record
  Name    : String;
  Has_arg : Integer;
  Flag    : PChar;
  Value   : Char;
  end;
POption = ^TOption;
\end{verbatim}
The \var{option} type is used to communicate the long options to \var{GetLongOpts}.
The \var{Name} field is the name of the option. \var{Has\_arg} specifies if the option
wants an argument, \var{Flag} is a pointer to a \var{char}, which is set to
\var{Value}, if it is non-\var{nil}. 
\var{POption} is a pointer to a
\var{Option} record. It is used as an argument to the \var{GetLongOpts}
function.
\subsection{Variables}
\var{OptArg:String} \ Is set to the argument of an option, if the option needs
one.\\
\var{Optind:Longint} \ Is the index of the current \var{paramstr()}. When
all options have been processed, \var{optind} 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{OptErr:Boolean} \ Indicates whether \var{getopt()} prints error
messages.\\
\var{OptOpt:Char} \  In case of an error, contains the character causing the 
error.
\section {Procedures and functions}
\begin{function}{GetLongOpts}
\Declaration
Function GetLongOpts (Shortopts : String, LongOpts : POption; var Longint
: Longint ) : Char;

\Description

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}. If the option requires an argument, it is
returned in the \var{OptArg} variable.
\var{ShortOptions} is a string containing all possible one-letter options.
(see \seef{Getopt} for its description and use)
\var{LongOpts} is a pointer to the first element of an array of \var{Option} 
records, the last of which needs a name of zero length.  
The function tries to match the names even partially (i.e. \var{--app} 
will match e.g. the \var{append} option), but will report an error in case of
ambiguity.
If the option needs an argument, set \var{Has\_arg} to
\var{Required\_argument}, if the option optionally has an argument, set
\var{Has\_arg} to \var{Optional\_argument}. If the option needs no argument,
set \var{Has\_arg} to zero.
Required arguments can be specified in two ways : 
\begin{enumerate}
\item \ Pasted to the option : \var{--option=value}
\item \ As a separate argument : \var {--option value}
\end{enumerate}
Optional arguments can only be specified through the first method.

\Errors
 see \seef{Getopt}, \seem{getopt}{3}
\SeeAlso
Getopt
\end{function}
\begin{function}{Getopt}
\Declaration
Function Getopt (Shortopts : String) : Char;

\Description

Returns the next option found on the command-line. If no more options are
found, returns \var{EndOfOptions}. If the option requires an argument, it is
returned in the \var{OptArg} variable.
\var{ShortOptions} 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} is a \var{'+'} then options following a non-option are
regarded as non-options (standard Unix behavior). If it is a \var{'-'},
then all non-options are treated as arguments of a option with character
\var{\#0}. 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} 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.

\Errors
 
Errors are reported through giving back a \var{'?'} character. \var{OptOpt}
then gives the character which caused the error. If \var{OptErr} is
\var{True} then getopt prints an error-message to \var{stdout}.

\SeeAlso
\seef{GetLongOpts}, \seem{getopt}{3}
\end{function}

\FPCexample{optex}