ofstd/include/dcmtk/ofstd/ofcmdln.h

/*
 *
 *  Copyright (C) 1998-2010, OFFIS e.V.
 *  All rights reserved.  See COPYRIGHT file for details.
 *
 *  This software and supporting documentation were developed by
 *
 *    OFFIS e.V.
 *    R&D Division Health
 *    Escherweg 2
 *    D-26121 Oldenburg, Germany
 *
 *
 *  Module:  ofstd
 *
 *  Author:  Joerg Riesmeier
 *
 *  Purpose: Handle command line arguments (Header)
 *
 *  Last Update:      $Author: joergr $
 *  Update Date:      $Date: 2010-10-14 13:15:50 $
 *  CVS/RCS Revision: $Revision: 1.43 $
 *  Status:           $State: Exp $
 *
 *  CVS/RCS Log at end of file
 *
 */


#ifndef OFCMDLN_H
#define OFCMDLN_H

#include "dcmtk/config/osconfig.h"
#include "dcmtk/ofstd/oftypes.h"
#include "dcmtk/ofstd/oflist.h"
#include "dcmtk/ofstd/ofstring.h"
#include "dcmtk/ofstd/ofconsol.h"

#define INCLUDE_CSTDIO
#include "dcmtk/ofstd/ofstdinc.h"


/*--------------------*
 *  type declaration  *
 *--------------------*/

typedef signed long OFCmdSignedInt;
typedef unsigned long OFCmdUnsignedInt;
typedef double OFCmdFloat;
typedef OFString OFCmdString;

// necessary for MSVC5 :-/
typedef OFListIterator(OFString) OFListIterator_OFString;


/*------------------------*
 *  forward declarations  *
 *------------------------*/

struct OFCmdOption;
struct OFCmdParamPos;


/*----------------------*
 *  struct declaration  *
 *----------------------*/

struct OFCmdParam
{

    enum E_ParamMode
    {
        PM_Mandatory,
        PM_Optional,
        PM_MultiMandatory,
        PM_MultiOptional
    };

    OFCmdParam(const char *param,
               const char *descr,
               const E_ParamMode mode)
      : ParamName(param),
        ParamDescription(descr),
        ParamMode(mode)
    {
    }

    const OFString ParamName;
    const OFString ParamDescription;
    const E_ParamMode ParamMode;

private:

    OFCmdParam& operator=(const OFCmdParam& arg);
};


/*---------------------*
 *  class declaration  *
 *---------------------*/

class OFCommandLine
{

 public:

 // --- enumerations

    enum E_ParseStatus
    {
        PS_Normal,
        PS_NoArguments,
        PS_ExclusiveOption,
        PS_UnknownOption,
        PS_MissingValue,
        PS_MissingParameter,
        PS_TooManyParameters,
        PS_CannotOpenCommandFile
    };


    enum E_ValueStatus
    {
        VS_Normal,
        VS_Invalid,
        VS_NoMore,
        VS_Empty,
        VS_Underflow,
        VS_Overflow
    };


    enum E_ParamValueStatus
    {
        PVS_Normal,
        PVS_Invalid,
        PVS_CantFind,
        PVS_Empty,
        PVS_Underflow,
        PVS_Overflow
    };

    enum E_FindOptionMode
    {
        FOM_Normal,
        FOM_First,
        FOM_Next,
        FOM_FirstFromLeft,
        FOM_NextFromLeft
    };


 // --- constructor and destructor

    OFCommandLine();

    virtual ~OFCommandLine();


 // --- initialization

    void setOptionChars(const char *chars);

    void setOptionColumns(const int longCols,
                          const int shortCols);

    void setParamColumn(const int column);

    OFBool addOption(const char *longOpt,
                     const char *shortOpt,
                     const int valueCount,
                     const char *valueDescr,
                     const char *optDescr,
                     const int flags = 0);

    OFBool addOption(const char *longOpt,
                     const char *shortOpt,
                     const char *optDescr,
                     const int flags = 0);

    OFBool addOption(const char *longOpt,
                     const int valueCount,
                     const char *valueDescr,
                     const char *optDescr,
                     const int flags = 0);

    OFBool addOption(const char *longOpt,
                     const char *optDescr,
                     const int flags = 0);

    void addGroup(const char *name,
                  const int longCols = 0,
                  const int shortCols = 0);

    void addSubGroup(const char *name,
                     const int longCols = 0,
                     const int shortCols = 0);

    OFBool addParam(const char *param,
                    const char *descr,
                    const OFCmdParam::E_ParamMode mode = OFCmdParam::PM_Mandatory);

    OFBool addParam(const char *param,
                    const OFCmdParam::E_ParamMode mode = OFCmdParam::PM_Mandatory);


 // --- get information

    const OFString &getProgramName() const
    {
        return ProgramName;
    }

    int getArgCount() const
    {
        return OFstatic_cast(int, ArgumentList.size());
    }

    OFBool gotoFirstArg();

    OFBool gotoNextArg();

    OFBool getCurrentArg(const char *&arg);

    OFBool getCurrentArg(OFCmdString &arg);

    int getParamCount() const
    {
        return OFstatic_cast(int, ParamPosList.size());
    }

    int getMinParamCount() const
    {
        return MinParamCount;
    }

    int getMaxParamCount() const
    {
        return MaxParamCount;
    }

    OFBool hasExclusiveOption() const
    {
        return ExclusiveOption;
    }


 // --- find/get parameter (parameter is an argument which is no option)

    OFBool findParam(const int pos);

    E_ParamValueStatus getParam(const int pos,
                                OFCmdSignedInt &value);

    E_ParamValueStatus getParamAndCheckMin(const int pos,
                                           OFCmdSignedInt &value,
                                           const OFCmdSignedInt low,
                                           const OFBool incl = OFTrue);

    E_ParamValueStatus getParamAndCheckMinMax(const int pos,
                                              OFCmdSignedInt &value,
                                              const OFCmdSignedInt low,
                                              const OFCmdSignedInt high);

    E_ParamValueStatus getParam(const int pos,
                                OFCmdUnsignedInt &value);

    E_ParamValueStatus getParamAndCheckMin(const int pos,
                                           OFCmdUnsignedInt &value,
                                           const OFCmdUnsignedInt low,
                                           const OFBool incl = OFTrue);

    E_ParamValueStatus getParamAndCheckMinMax(const int pos,
                                              OFCmdUnsignedInt &value,
                                              const OFCmdUnsignedInt low,
                                              const OFCmdUnsignedInt high);

    E_ParamValueStatus getParam(const int pos,
                                OFCmdFloat &value);

    E_ParamValueStatus getParamAndCheckMin(const int pos,
                                           OFCmdFloat &value,
                                           const OFCmdFloat low,
                                           const OFBool incl = OFTrue);

    E_ParamValueStatus getParamAndCheckMinMax(const int pos,
                                              OFCmdFloat &value,
                                              const OFCmdFloat low,
                                              const OFCmdFloat high);

    E_ParamValueStatus getParam(const int pos,
                                const char *&param);

    E_ParamValueStatus getParam(const int pos,
                                OFCmdString &param);


 // --- find/get option (option is an argument which starts with an option character, see above)

    OFBool findOption(const char *longOpt,
                      const signed int pos = 0,
                      const E_FindOptionMode mode = FOM_Normal);

    OFBool gotoFirstOption();

    OFBool gotoNextOption();

    OFBool getCurrentOption(const char *&opt);

    OFBool getCurrentOption(OFCmdString &opt);

    void beginOptionBlock();

    void endOptionBlock();


 // --- get value (used for option values)

    E_ValueStatus getValue(OFCmdSignedInt &value);

    E_ValueStatus getValueAndCheckMin(OFCmdSignedInt &value,
                                      const OFCmdSignedInt low,
                                      const OFBool incl = OFTrue);

    E_ValueStatus getValueAndCheckMinMax(OFCmdSignedInt &value,
                                         const OFCmdSignedInt low,
                                         const OFCmdSignedInt high);

    E_ValueStatus getValue(OFCmdUnsignedInt &value);

    E_ValueStatus getValueAndCheckMin(OFCmdUnsignedInt &value,
                                      const OFCmdUnsignedInt low,
                                      const OFBool incl = OFTrue);

    E_ValueStatus getValueAndCheckMinMax(OFCmdUnsignedInt &value,
                                         const OFCmdUnsignedInt low,
                                         const OFCmdUnsignedInt high);

    E_ValueStatus getValue(OFCmdFloat &value);

    E_ValueStatus getValueAndCheckMin(OFCmdFloat &value,
                                      const OFCmdFloat low,
                                      const OFBool incl = OFTrue);

    E_ValueStatus getValueAndCheckMinMax(OFCmdFloat &value,
                                         const OFCmdFloat low,
                                         const OFCmdFloat high);

    E_ValueStatus getValue(const char *&value);

    E_ValueStatus getValue(OFCmdString &value);


 // --- parsing command line

    E_ParseStatus parseLine(int argCount,
                            char *argValue[],
                            const int flags = 0,
                            const int startPos = 1);


 // --- get usage/status strings

    void getSyntaxString(OFString &syntaxStr) const;

    void getOptionString(OFString &optionStr) const;

    void getParamString(OFString &paramStr) const;

    void getStatusString(const E_ParseStatus status,
                         OFString &statusStr);

    void getStatusString(const E_ParamValueStatus status,
                         OFString &statusStr);

    void getStatusString(const E_ValueStatus status,
                         OFString &statusStr);


 // --- flags (used for method parseLine)

    static const int PF_ExpandWildcards;
    static const int PF_NoCommandFiles;

 // --- flags (used for method addOption)

    static const int AF_Exclusive;
    static const int AF_Internal;
    static const int AF_NoWarning;

 protected:

    OFBool checkOption(const OFString &option,
                       const OFBool mode = OFTrue) const;

    OFBool findParam(int pos,
                     OFListIterator(OFCmdParamPos *) &pos_iter);

    const OFCmdOption *findCmdOption(const OFString &option) const;

    void storeParameter(const OFString &param,
                        const int directOption = 0);

    E_ParseStatus parseCommandFile(const char *argValue,
                                   OFList<OFString> &argList);

    int packColumnValues(int longCols,
                         int shortCols) const;

    void unpackColumnValues(const int value,
                            unsigned int &longCols,
                            unsigned int &shortCols) const;

#ifdef HAVE_WINDOWS_H

    void expandWildcards(const OFString &param,
                         int directOption = 0);
#endif

    E_ParseStatus checkParamCount();

    OFBool getLastArg(OFString &arg);

    OFBool getMissingParam(OFString &param);


 private:

    OFString ProgramName;

    OFList<OFCmdOption *> ValidOptionList;
    OFList<OFCmdParam *> ValidParamList;

    OFList<OFString> ArgumentList;
    OFListIterator(OFString) ArgumentIterator;

    OFList<OFCmdParamPos *> ParamPosList;
    OFList<OFListIterator_OFString> OptionPosList;
    OFListIterator(OFListIterator_OFString) OptionPosIterator;
    OFListIterator(OFListIterator_OFString) OptionBlockIterator;

    OFBool OptionBlockMode;
    OFString OptionChars;

    OFBool ExclusiveOption;

    int LongColumn;
    int ShortColumn;
    int ParamColumn;

    int MinParamCount;
    int MaxParamCount;

    OFCmdParam::E_ParamMode LastParamMode;


 private:

    OFCommandLine &operator=(const OFCommandLine &obj);
};


#endif


/*
 *
 * CVS/RCS Log:
 * $Log: ofcmdln.h,v $
 * Revision 1.43  2010-10-14 13:15:50  joergr
 * Updated copyright header. Added reference to COPYRIGHT file.
 *
 * Revision 1.42  2010-04-28 13:23:18  joergr
 * Added type cast to integer variable in order to avoid compiler warnings
 * reported by VisualStudio 2005.
 *
 * Revision 1.41  2009-12-23 12:15:51  joergr
 * Added support for getting the name of the program, i.e. the value of argv[0].
 *
 * Revision 1.40  2009-06-04 09:53:00  joergr
 * Added new flag that can be used to avoid wrong warning messages (in debug
 * mode) that an option has possibly never been checked.
 *
 * Revision 1.39  2008-04-16 12:39:35  joergr
 * Added support for reverse search direction (left to right) to findOption().
 *
 * Revision 1.38  2006/07/27 13:16:11  joergr
 * Changed parameter "exclusive" of method addOption() from type OFBool into an
 * integer parameter "flags".
 * Added addOption() flag for internal options that are not shown in the syntax
 * usage output. Prepended prefix "PF_" to parseLine() flags.
 * Option "--help" is no longer an exclusive option by default.
 *
 * Revision 1.37  2005/12/08 16:05:48  meichel
 * Changed include path schema for all DCMTK header files
 *
 * Revision 1.36  2003/12/05 13:59:33  joergr
 * Fixed problem with retrieving option values using the new iteration feature.
 *
 * Revision 1.35  2003/12/05 10:36:03  joergr
 * Added support for iterating over command line arguments and options.
 * Removed leading underscore characters from preprocessor symbols (reserved
 * symbols). Updated copyright date where appropriate.
 *
 * Revision 1.34  2003/06/12 13:19:58  joergr
 * Added support for so-called command files ("@filename") which can be used to
 * summarize command line options and parameter
 *
 * Revision 1.33  2003/05/20 08:42:39  joergr
 * Renamed parameters/variables "string" to avoid name clash with STL class.
 *
 * Revision 1.32  2002/12/09 13:04:41  joergr
 * Replaced tab characters by spaces.
 *
 * Revision 1.31  2002/12/05 13:48:21  joergr
 * Make sure that no warning on "unchecked command line options" is reported in
 * debug mode when an exclusive option is used.
 *
 * Revision 1.30  2002/11/27 11:23:04  meichel
 * Adapted module ofstd to use of new header file ofstdinc.h
 *
 * Revision 1.29  2002/09/19 08:30:20  joergr
 * Added general support for "exclusive" command line options besides "--help",
 * e.g. "--version".
 *
 * Revision 1.28  2001/11/09 15:46:42  joergr
 * Renamed some of the getValue/getParam methods to avoid ambiguities reported
 * by certain compilers.
 *
 * Revision 1.27  2001/08/23 16:05:52  meichel
 * Added private undefined copy assignment operators to avoid gcc warnings
 *
 * Revision 1.26  2001/06/01 15:51:32  meichel
 * Updated copyright header
 *
 * Revision 1.25  2000/10/10 12:01:20  meichel
 * Created/updated doc++ comments
 *
 * Revision 1.24  2000/04/14 15:17:11  meichel
 * Adapted all ofstd library classes to consistently use ofConsole for output.
 *
 * Revision 1.23  2000/03/08 16:36:01  meichel
 * Updated copyright header.
 *
 * Revision 1.22  2000/03/07 15:38:49  joergr
 * Changed behaviour of class OFConsoleApplication to support automatic
 * evaluation of "--help" option for command line application with no
 * mandatory parameter.
 *
 * Revision 1.21  2000/03/03 14:02:46  meichel
 * Implemented library support for redirecting error messages into memory
 *   instead of printing them to stdout/stderr for GUI applications.
 *
 * Revision 1.20  2000/03/02 12:39:11  joergr
 * Fixed inconsistency: console applications with no or only optional
 * parameters could not be started without any command line argument
 * because this was always regarded identical with "--help" (print usage).
 *
 * Revision 1.19  1999/10/04 10:02:31  joergr
 * Fixed bug in wildcard expansion (concerning "direct option" feature).
 *
 * Revision 1.18  1999/09/13 16:36:54  joergr
 * Corrected bug in OFCommandLine::findOption() regarding the optional
 * parameter 'pos' specifying a reference command line parameter.
 *
 * Revision 1.17  1999/09/06 16:48:25  joergr
 * Added support to method 'findOption()' to detect options which are
 * 'direct' predecessors of an optionally specified reference parameter.
 *
 * Revision 1.16  1999/05/04 08:38:26  joergr
 * Added DOC++ comments to header file.
 *
 * Revision 1.15  1999/04/29 15:21:45  joergr
 * Removed debug code.
 *
 * Revision 1.13  1999/04/28 13:13:16  joergr
 * Removed some '#ifdef DEBUG' statements from header files to avoid
 * problems with inconsistent compilations.
 *
 * Revision 1.12  1999/04/27 17:46:05  joergr
 * Added some comments (DOC++ style).
 *
 * Revision 1.10  1999/04/26 16:32:47  joergr
 * Added support to define minimum width of short and long option columns.
 * Removed bug: empty parameters have always been interpreted as options.
 * Enhanced support of wildcard expansion under Windows (now very similar
 * to Unix shells).
 *
 * Revision 1.9  1999/03/24 16:59:38  joergr
 * Added optional parameters to define minimum width of columns for short and
 * long options in syntax output.
 * Changed optional integer parameter in method findOption to enum type.
 *
 * Revision 1.8  1999/02/08 11:51:38  joergr
 * Removed '#include <iostream.h>' from ofcmdln.h.
 *
 * Revision 1.7  1999/02/05 14:07:07  joergr
 * Added automatic wildcard expansion for Windows compilers.
 *
 * Revision 1.6  1998/12/02 18:44:25  joergr
 * Introduced test whether added options are correct (starting with defined
 * option character followed by a character which is no number). Changed
 * parse routine to distinguish between options (normally starting mit - or
 * +) and signed numbers which can be valid parameters.
 *
 * Revision 1.5  1998/12/02 17:38:53  joergr
 * Introduced new enum type used to indicate the status when converting
 * parameter values (similar to option values). Changed return value of
 * getParam() methods to this type. Added corresponding getStatusString()
 * method to convert status code to strings.
 *
 * Revision 1.4  1998/12/02 15:19:49  joergr
 * Added methods to convert parameters to signed/unsigned integers and
 * floats. Changed return value of existing getParam() methods.
 *
 * Revision 1.3  1998/11/30 12:30:18  joergr
 * Use lists of pointers (!) to internal data structures to avoid errors with
 * MSVC5 (operator '==' was not defined to compare structures).
 *
 * Revision 1.2  1998/11/30 12:27:02  joergr
 * Introduced additional type definition to avoid errors with MSVC5 when
 * using ListIterators of ListIterators (syntax problems?).
 *
 * Revision 1.1  1998/11/27 12:34:47  joergr
 * Added class to handle command line arguments.
 *
 *
 */

---

Generated on 6 Jan 2011 for OFFIS DCMTK Version 3.6.0 by Doxygen 1.5.1