argumentParser.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies, Inc.
** All rights reserved.
*******************************************************************************/
/*******************************************************************************
** $RCSfile: argumentParser.h,v $ $Revision: 1.2 $ $State: Exp $
*******************************************************************************/
#ifndef argumentParser_H_
#define argumentParser_H_

//
// \file argumentParser.h
// \brief This file contains the declaration and description of the DtArgumentParser class.
//

#include "tdbutil/tdbUtilDefines.h"
#include <vlutil/vlConfig.h>
#include <matrix/vlVector.h>
#include "tdbutil/arguments.h"
#include "tdbutil/argumentException.h"
#include <sstream>


class DtFilename;

//
// DtArgumentParser is a base class for command-line-argument parsers.
// \note The class parses instances of DtArgument classes, so while primarily 
// intended for command-line argument parsing, it doesn't matter how the 
// DtArguments object was created as long as it is well-formed.
// 
// Derive additional argument parsing classes from this one for your specific 
// application.  Simply override the appropriate parse function for the arguments
// your application is concerned with.  
// \note This base class assumes that all arguments (not the options for those 
// arguments) are "switches", which means that they all begin with '-'.  If 
// your application does not enforce that condition, override the processNonSwitch()
// virtual function.
//
class DT_DLL_tdbutil DtArgumentParser
{

public:
   DtArgumentParser();

   virtual ~DtArgumentParser() = 0;

   // Begins the parsing process. Call this function when you are ready 
   // to handle the arguments.
   void processArguments(const DtArguments& arguments);

protected:

   // \return the current argument.
   std::string getArgument() const;

   // Returns the number of arguments remaining to be processed.  Does not 
   // differentiate between the types of arguments (switches, non-switches, etc).
   unsigned numArgumentsLeft() const;

   // \name Argument Reading Functions

   // \return the current argument as a string. No error-checking performed.
   void readString(std::string& stringRead);

   // \return the current argument as a string. No error-checking performed.
   // \note Does \b not increment the argument iterator.  Useful for checking that
   // the next argument is the desired type/value before incrementing the iterator
   void peekString(std::string& stringRead) const;

   // \return the current argument as a file name. If the current argument is not
   // a valid filename (validFilename()), it throws an exception.
   void readFilename(DtFilename& filenameRead);

   // \return the current argument as a double. If the current argument is not
   // a valid double (validDouble()), it throws an exception.
   void readDouble(double& doubleRead);

   // \return the current argument as a a vector of \b 3 doubles. If any number is 
   // not a valid double (validDouble()), it throws an exception.
   void readVector(DtVector& vectorRead);

   // \return the current argument as an int. If the current argument is not
   // a valid int (validInt()), it throws an exception.
   void readInt(int& intRead);

   // \return the current argument as an unsigned int. If the current argument 
   // is not a valid unsigned int (validUnsigned()), it throws an exception.
   void readUnsigned(unsigned& unsignedRead);

   // \return the current argument as a bool. 'y' or 'yes' result in true.
   // 'n' or 'no' result in false.
   // Anything else throws an exception.
   void readBool(bool& boolRead);


   // \name Argument Validation Functions
   //
   // \return true if a filename is valid. 
   // \note Currently doesn't check anything, but is there for future enhancement.
   bool validFilename(const std::string& argument) const;

   // \return true if the string is a valid integer.
   bool validInt(const std::string& argument) const;

   // \return true if the string is a valid unsigned integer.
   bool validUnsigned(const std::string& argument) const;

   // \return true if the string is a valid double precisions floating-point number.
   bool validDouble(const std::string& argument) const;


   // \name Error-Handling Functions 
   // Throws an exception.  Intended for use with the the 
   // "I-don't-know-what-this-argument-is" case. 
   void unknownArgument() const;

   // Throws an exception with the given error message
   void argumentError(const char* message) const;

   // \return The lower-case version of the input.
   std::string convertToLower(const std::string& inputString) const;

   // Defines the handling for arguments which are not directly supported by this
   // object. They may be handled by another parser or they may result
   // in an UnknownArgument() call.
   virtual void bounce();

   // Determines if the specified argument is a switch or not, and calls the 
   // appropriate function accordingly.
   // \see processSwitch
   // \see processNonSwitch
   virtual void process(const std::string& argument);

   // Process arguments which are actually switches. That is to say, they have
   // the '-' character first in their chars.  
   virtual void processSwitch(const std::string& argument);

   // Process arguments that are \b not switches. This includes all arguments 
   // that do not have the '-' character first.  
   // \see process
   virtual void processNonSwitch(const std::string& argument);

   // \name Individual Parsing Functions 
   // Makes it easy for derived classes to parse the arguments they are 
   // concerned with.  Override the specific ones you need to handle, and the
   // remaining will call bounce().  
   // \note The parse functions can throw DtArgumentExceptions or 
   // a derived type such as DtUnknownArgumentException.
   virtual void parseA();
   virtual void parseB();
   virtual void parseC();
   virtual void parseD();
   virtual void parseE();
   virtual void parseF();
   virtual void parseG();
   virtual void parseH();
   virtual void parseI();
   virtual void parseJ();
   virtual void parseK();
   virtual void parseL();
   virtual void parseM();
   virtual void parseN();
   virtual void parseO();
   virtual void parseP();
   virtual void parseQ();
   virtual void parseR();
   virtual void parseS();
   virtual void parseT();
   virtual void parseU();
   virtual void parseV();
   virtual void parseW();
   virtual void parseX();
   virtual void parseY();
   virtual void parseZ();
   virtual void parseDoubleDash();

private:
   // not implemented
   DtArgumentParser& operator=(const DtArgumentParser& other);
   DtArgumentParser(const DtArgumentParser& other);
   
   // If the first character of the string is '-', then it is a switch
   // \return A boolean indicating whether the argument is a switch or not.
   bool isSwitch(const std::string& argument) const;

   // Throws an exception when value is not of type expectedType
   void errorInRead(const std::string& value,  const std::string& expectedType) const;
   
   // This is intended as an easy way of giving useful feedback.
   // An example is best: if you call with (3, "A VECTOR") while reading the 
   // -foo argument, it will throw an exception with the message "An error was 
   // encountered in the -foo argument:\n Expected to find A VECTOR", if there 
   // are not at least three more arguments. Note the types/values of the 
   // arguments are not looked at - it merely examines the number of arguments.
   void validateExistence(unsigned numExpectedArguments, 
                          const std::string& expectedArgumentsDescription) const;

   DtArguments::DtArgumentConstIter myArgumentsIter;
   std::string myCurrentArgument;
   const DtArguments* myArguments;
};


// Identifies an invalid or unknown argument, such as -hhelp or just plain
// garbage like -asdf
class DtUnknownArgumentException : public DtArgumentException 
{
public:
   inline DtUnknownArgumentException(const char* errorMessage, 
      const DtException *previousException = 0) throw();
}; 

inline DtUnknownArgumentException::DtUnknownArgumentException(
   const char* errorMessage, const DtException *previousException) throw() :
   DtArgumentException(errorMessage)
{
}



// Attempts to convert a specified string input into an instance of the type 
// specified by the destination parameter. 
// 
// \return A boolean indicating success or failure at conversion.
//
template< class T >
bool DtConvert(const std::string& input, T& destination)
{
   std::istringstream convert(input);
   convert >> destination;

   return !convert.fail();
} 



#endif