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.}
This document describes the GETOPTS unit for Free Pascal. It was written for
\linux\ by Micha\"el Van Canneyt. It also works under DOS.

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}
Option = record
  Name    : string;
  Has_arg : Integer;
  Flag    : ^Char;
  Value   : Char;
  end;
POption = ^Option;
\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:Integer} \ 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}
\function {Getopt}{(Shortopts : String)}{Char}
{
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 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}.
}
{\seef{GetLongOpts}, \seem{getopt}{3}}

\input{optex/optex.tex}

\function {GetLongOpts}{(Shortopts : String, LongOpts : POption; var Longint
: Integer )}{Char}
{
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.
}
{ see \seef{Getopt}, \seem{getopt}{3}}

For an example, see \seef{Getopt}