Environment.h

Go to the documentation of this file.

////////////////////////////////////////////////////////////////////////////////
///
/// \file
/// \author Gerald Fahrnholz
/// 
/// \defgroup GrpEnvironment Using Environment
/// @{
/// \ingroup GrpTestUtils 
/// \brief
/// Class Environment allows easy access to path informations, system environment variables
/// and command line arguments.
///
/// \n This class allows to manage/access/change the informations as described in
///    the following section. It is the task of the application itself to make use of
///    this information in a suitable way corresponding to the application's purpose.
///    The class Environment itself simply provides the information and makes no use of it.
///
///    The following features are supported.
///    - <b>Path of Executable (Runtime):</b>\n
///      get the path of the currently running executable (full path or only drive)
///
///    - <b>Path of Sources (Compile time):</b>\n
///      get the path where the sources were compiled (you may need this path to access
///      data/config files stored within the source directories):
///        - full path or drive
///        - cut off part of the source dir
///        - explicitly set the complete directory path
///
///    - <b>Path for output and reference files:</b>\n
///        - get/set the directory to generate test output files (e.g. protocols)
///        - get/set directory to read some reference files from (e.g. valid data to
///          be compared during testing
///
///    - <b>Command Line Parameters</b>\n
///      Assumed syntax for command line params is "-optionName [optionValue]"\n
///      arguments not matching this rule are simply ignored, e.g. "--option"
///      (used by Boost.Test) is skipped when parsing the command line 
///        - get/set command line param as strings
///        - get/set command line param as arbitrary (streamable) numeric types
///
///    - <b>System Environment Variables</b>\n
///        - get/set environment variable as string
///        - get/set environment variable as arbitrary (streamable) numeric types
///
///    - <b>Name of user and computer</b>\n
///
///    - <b>General functions</b>\n
///        - get textual <b>description for a system error code</b>
///        - <b>start</b> an arbitrary <b>executable file</b>
///
/// <b>\n Examples of Usage:</b>\n
/// \code
///
/// #include "TestToolBox\EnvironmentImpl.h"
/// namespace TTB = TestToolBox;
///
/// // define input path somewhere within source directories
/// // Remark: at startup the source directory is the directory
/// // where file environmentImpl.h is stored
/// TTB::TheEnvironment()->CutSourceDirAfter("\\SW-Root\\");
/// std::string myInputFilePath = TTB::TheEnvironment()->GetSourceDir()
///     + "MyInputFiles\\TestCaseA.input"
///
/// // accessing command line
/// if (TTB::TheEnvironment()->IsExistingCommandLineOption("-trace"))
/// {
///     ...
/// }
/// long numOfExecutions = TTB::TheEnvironment()->GetCommandLineOptionVal<long>("-numExecutions")
///
/// // accessing environment variable
/// bool produceDetailedOutput = TTB::TheEnvironment()->GetSystemEnvVariableVal<bool>("DetailedOutput");
///
/// // Display a textual description of a system error code as received via
/// // return value or via GetLastError()
/// if (!SomeSystemFunctionCall())
/// {
///     DWORD errCode = ::GetLastError();
///     cout << "Function failed, reason: "
///         << TTB::Environment::GetErrorDescription(errCode).c_str() << std::endl;
///
/// // Start notepad to display some test results
/// TTB::Environment::StartExeFile("notepad.exe","c:\tmp\MyTestResults.txt");
/// 
/// \endcode
///
/// \sa Environment.h (File documentation)
/// \sa TestToolBox::Environment (class documentation)
/// \sa GrpTestEnvironment (unit test for class Environment)
/// 
////////////////////////////////////////////////////////////////////////////////

#pragma once

#include <string>
#include <map>
#include "TestToolBox\CommonSources\CommonDefinitions.h"

#ifdef USE_TEST_INSTANCE_DLL
#    include "TestToolBox\TestInstanceDll.h"
#endif

//************************************************************************

namespace TestToolBox
{


//************************************************************************
//************************************************************************


/// \brief Class allows easy access to path informations, system environment variables
/// and command line arguments.
/// For more info about usage see \ref GrpEnvironment.
///
/// \nosubgrouping 
/// \sa Environment.h (File documentation)
/// \sa GrpTestEnvironment (unit test for class Environment)
/// \sa GrpEnvironment (Usage documentation)
class Environment
{
public:

    /// Mode describing the behaviour of a called function in case of error
    enum CallMode
    {
        CM_DEFAULT, ///< return default value in case of error
        CM_THROW    ///< throw std::exception in case of error
    };
///\cond do not document

    // Constructor
    // All path variables will be initialized.
        Environment();

    // Destructor
        virtual ~Environment();

    // Get the only instance of TestEnv
    // Get the pointer to the only instance of this class
#ifdef USE_TEST_INSTANCE_DLL
    static Environment* Get (void)
    {return TTB_GetInstance_Environment();}
    static Environment* s_pEnvironment;
    static void Cleanup (void)
    {TTB_CleanupInstance_Environment();}
#else
    static Environment* Get (void)
    {if (!s_pEnvironment) s_pEnvironment = new Environment;
         return s_pEnvironment;}
    static Environment* s_pEnvironment;
    static void Cleanup (void)
    {delete s_pEnvironment; s_pEnvironment = 0;}
#endif

///\endcond

    //---------------------------------------------------------------
    /// \name Exe path
    /// \{

    /// Get complete path for exe file (e.g. "C:\MyTargetBin\MyAppname.exe")
    std::string GetExeFileFullPath (void)
    {return m_exeFileFullPath;}

    /// Get directory path (e.g. "C:\MyTargetBin")
    std::string GetExeDir (void)
    {return m_exeDir;}

    /// Get drive letter (e.g. "C:")
    std::string GetExeDrive (void)
    {return m_exeDrive;}

    /// Get application name, i.e. name of executable without extension (e.g. "MyAppname")
    std::string GetAppName (void)
    {return m_appName;}

    /// \}

    //---------------------------------------------------------------
    /// \name Source path
    /// \{


    /// \brief Get the directory where the sources are stored.
    /// The initial value is generated from the preprocessor expression __FILE__
    /// and relates to the directory where the sources have been compiled (usually
    /// within a version management system)
    /// An arbitrary string can be set using SetSourceDir(). To limit the path
    /// use function CutSourceDirAfter().    // 
    std::string GetSourceDir()
    {return m_sourceDir;}

    /// Get drive letter (e.g. "C:")
    std::string GetSourceDrive (void)
    {return m_sourceDrive;}

    /// \brief Find first occurance of the given string within source dir and
    /// cut off the rest of the source dir string
    void CutSourceDirAfter (std::string const & in_findStr);

    /// Explicitly replace the value of SourceDir with the given string
    void SetSourceDir (std::string const & in_sourceDir)
    {m_sourceDir = in_sourceDir; CalculateSourceDrive();}

    /// \}


    //---------------------------------------------------------------
    /// \name Out/Ref directories
    /// Get and set file paths used for unit testing. When starting up both path directories
    /// are initialized with the executable directory as available through GetExeDir().
    /// \{

        std::string GetOutputDir()
        {return m_outputDir;}

        void SetOutputDir (std::string in_outputDir)
    {m_outputDir = in_outputDir;}

        std::string GetReferenceDir()
    {return m_referenceDir;}

        void SetReferenceDir (std::string in_referenceDir)
        {m_referenceDir = in_referenceDir;}

    /// \}


    //---------------------------------------------------------------
    /// \name Name of user and computer
    /// \{

    /// Get name of computer
    static std::string GetNameOfComputer (void);

    /// Get name of user which has logged in
    static std::string GetNameOfUser (void);
    /// \}

    //---------------------------------------------------------------
    /// \name Access to command line
    /// When starting up all command line params of format "-option [value]"
    /// are read into an internal string map upon which all functions except
    /// GetCommandLineStr()/GetArgsStr() are working.
    /// \{

    /// Get the complete command line as a single string
    static std::string GetCommandLineStr (void);

    /// Get the complete command line args as a single string.
    /// The name of the executable (usually arg0) is not contained.
    static std::string GetArgsStr (void);

    /// Check whether the given option is given within the command line
    bool IsExistingCommandLineOption (
        std::string const & in_nameOption) const
    {return m_cmdLineOptions.find(in_nameOption)!=m_cmdLineOptions.end();}

    /// Get the given option in string format
    std::string GetCommandLineOption (
        std::string const & in_nameOption);

    /// Change/create the given option in string format
    void SetCommandLineOption (
        std::string const & in_nameOption,
        std::string const & in_optionValue)
    {m_cmdLineOptions[in_nameOption]=in_optionValue;}

    /// Get the given option in numeric/any streamable format
    template<class T>
    T GetCommandLineOptionVal(
        const std::string& in_nameOption,
        CallMode           in_callMode = CM_DEFAULT)
    {
        TRCF("Environment::GetCommandLineOptionVal");

        std::string optionValAsString = GetCommandLineOption(in_nameOption);
        std::istringstream iss(optionValAsString);
        T result = T();
        if ((iss >> result).fail())
        {
            result = T(); // reset to default value
            std::ostringstream oss;
            oss << "Could not convert command line option >" << in_nameOption 
                << "< with value >" << optionValAsString << "<"
                << " to type >" << typeid(T).name() << "<";
            TRC(TL_ERROR, "ERROR: %s", oss.str().c_str());
            if (in_callMode == CM_THROW)
            {
                TRC(TL_ERROR, "ERROR: throwing exception: %s", oss.str().c_str());
                throw std::exception(oss.str().c_str());
            }
        }
        return result;
    }

    /// Set the given option in numeric/any streamable format
    template<class T>
    void SetCommandLineOptionVal(
        const std::string& in_nameOption,
        T                  in_val)
    {
        TRCF("Environment::SetCommandLineOptionVal");

        TRC(TL_DEBUG,"called for type %s", typeid(T).name());

        std::ostringstream oss;
        oss << in_val;
        SetCommandLineOption (in_nameOption,oss.str());
    }
    /// \}


    //---------------------------------------------------------------
    /// \name Access to system environment variables
    /// \{

    /// Check whether the given environment variable is existing
    bool IsExistingSystemEnvVariable (
        std::string const & in_envVarName)
    {std::string dummy; return GetSystemEnvVariable(in_envVarName, dummy);}

    /// \brief Get the given environment variable in string format
    /// A return value of false signals that the environment variable
    /// is not set.
    bool GetSystemEnvVariable (
        std::string const & in_envVarName,
        std::string&        out_envVarValue);

    /// \brief Get the given environment variable as string. If variable is
    /// not existing an empty string is returned
    std::string GetSystemEnvVariable (std::string const & in_envVarName);

    /// Set the given environment variable in string format
    void SetSystemEnvVariable (
        std::string const & in_envVarName,
        std::string const & in_envVarValue);

    /// Get the given environment variable in numeric/any streamable format
    template<class T>
    T GetSystemEnvVariableVal(
        const std::string& in_envVarName,
        CallMode           in_callMode = CM_DEFAULT)
    {
        TRCF("Environment::GetSystemEnvVariableVal");

        std::string envVarValAsString = GetSystemEnvVariable(in_envVarName);
        std::istringstream iss(envVarValAsString);
        T result = T();
        if ((iss >> result).fail())
        {
            result = T(); // reset to default value
            std::ostringstream oss;
            oss << "Could not convert environment variable >" << in_envVarName 
                << "< with value >" << envVarValAsString << "<"
                << " to type >" << typeid(T).name() << "<";
            TRC(TL_ERROR, "ERROR: %s", oss.str().c_str());
            if (in_callMode == CM_THROW)
            {
                TRC(TL_ERROR, "ERROR: throwing exception: %s", oss.str().c_str());
                throw std::exception(oss.str().c_str());
            }
        }
        return result;
    }

    /// Set the given environment variable in numeric/any streamable format
    template<class T>
    void SetSystemEnvVariableVal(
        const std::string& in_envVarName,
        T                  in_val)
    {
        TRCF("Environment::SetSystemEnvVariableVal");

        TRC(TL_DEBUG,"called for type %s", typeid(T).name());

        std::ostringstream oss;
        oss << in_val;
        SetSystemEnvVariable (in_envVarName,oss.str());
    }
    /// \}

    //---------------------------------------------------------------
    /// \name General Helper Functions
    /// \{

    /// Get a textual description for a system error code
    static std::string GetErrorDescription (int in_systemError);

    /// Start an arbitrary executable file
    static bool StartExeFile (
        std::string const & in_executableToStart,
        std::string const & in_startArguments ="");
    /// \}

protected:
///\cond do not document

    // File/dir info about running executable
    std::string m_exeFileFullPath;
    std::string m_exeDir;
    std::string m_exeDrive;
    std::string m_appName;

    // Dir info about source directory
    std::string m_sourceDir;
    std::string m_sourceDrive;

        // Directory to generate output files (protocol files, reports, ...)
        std::string m_outputDir;

        // Directory to read reference files from
        std::string m_referenceDir;
///\endcond

    /// \brief Set of command options as read from command line\n
    /// each command option has the format -optionName [paramValue]
    typedef std::map<std::string,std::string> CmdLineOptions;

    /// Stored command line options
    CmdLineOptions m_cmdLineOptions;

private:
///\cond do not document
    void CalculateSourceDrive (void);
    void ParseCommandLine (void);
    bool GetNextOption (
        std::string&  inOut_rCmdLine,
        std::string&  out_rOpt,
        std::string&  out_rPar);
    bool GetNextToken (
        std::string&            inOut_rCmdLine,
        std::string&            out_token,
        std::string::size_type& out_tokenEndPos);
///\endcond

}; // class Environment

///\cond do not document
__declspec(selectany) Environment* Environment::s_pEnvironment = 0;
///\endcond

/// Access/create the singleton instance of Environment
inline Environment* TheEnvironment (void)
{return Environment::Get();}

//************************************************************************
//************************************************************************


} // namespace TestToolBox

///@} // end group GrpEnvironment

---