//Copyright 2020 Siemens Digital Industries Software
//==================================================
//Copyright $2010.
//Siemens Product Lifecycle Management Software Inc.
//All Rights Reserved.
//==================================================
//Copyright 2020 Siemens Digital Industries Software

/**
    @file

    Provides access to environment variables.
    <br>All environment variable names are translated using mapping (as accessible through this namespace) before their evaluation.
*/

#ifndef BASE_UTILS_OSENVIRONMENT_HXX
#define BASE_UTILS_OSENVIRONMENT_HXX

#include <string>
#include <map>
#include <base_utils/libbase_utils_exports.h>

namespace Teamcenter
{
namespace OSEnvironment
{
    /**
       Returns the value of the environment variable with the given name.
       <br>If name mapping is turned on, the value is retrieved using the mapped environment variable name. If
       no value is found, the value is retrieved using the originally given variable name.

       @returns
       <ul>
       <li>If the environment variable exists, it returns its value
       <li>Otherwise, if the parameter #throwStdExceptionIfNotFound is set to false, it returns an empty string
       <li>Otherwise, it throws an std::exception exception
       </ul>

       @see #getMappedName for more information on mapping definition

       @exception  <std::exception> if the parameter #throwStdExceptionIfNotFound is set to true
       and the environment variable was not found.
    */
    BASE_UTILS_API std::string get(
        const std::string & name,                        /**< (I) The name of the unmapped environment variable */
        bool applyOSEnvNameMapping = true,               /**< (I) Specifies if the name should be mapped using Teamcenter::OSEnvNameMapping. */
        bool throwStdExceptionIfNotFound = false         /**< (I) Specifies if an std::exception is to be thrown if the environment variable does not exist.
                                                            <br>If set to false, an empty string is returned if the environment variable does not exist. */
        );                                              //lint !e1761 This is a non-member function and can be used without ambiguity after resolving the namespace at caller location. 2015-06-19

    /**
       Returns true if an environment variable with the given name is defined.
       <br>If name mapping is turned on, the mapped name is used first. If no environment variable
       with the mapped name can be found, the originally provided name is used.

       @returns
       <ul>
       <li>true if an environment variable with the given (potentially mapped) name exists
       <li>false otherwise
       </ul>

       @see #getMappedName for more information on mapping definition
    */
    BASE_UTILS_API bool has(
        const std::string & name,                  /**< (I) The name of the unmapped environment variable */
        bool applyOSEnvNameMapping = true          /**< (I) Specifies if the name should be mapped using Teamcenter::OSEnvNameMapping. */
        );

    /**
       Sets the environment variable with the given name to the given value.
       <br>The environment variable names are mapped using Teamcenter::OSEnvNameMapping unless the parameter
       #applyOSEnvNameMapping is set to false.

       @see #getMappedName for more information on mapping definition
    */
    BASE_UTILS_API void set(
        const std::string & name,                   /**< (I) The name of the unmapped environment variable. */
        const std::string & value,                  /**< (I) The value to be given to the potentially mapped environment variable. */
        bool applyOSEnvNameMapping = true           /**< (I) Specifies if the name should be mapped using Teamcenter::OSEnvNameMapping. */
        );                                          //lint !e1761 This is a non-member function and can be used without ambiguity after resolving the namespace at caller location. 2015-06-19


    /**
       Adds a name prefix mapping, e.g. from "OLDPREFIX_" to "NEWPREFIX_".
       <br>Subsequent calls to #getMappedName with "OLDPREFIX_nametrailer" will return "NEWPREFIX_nametrailer"
    */
    BASE_UTILS_API void addPrefixMapping(
        const std::string & oldPrefix, /**< (I) The name prefix that should be mapped to a new_prefix */
        const std::string & newPrefix  /**< (I) The replacement prefix */
        );


    /**
        Removes the prefix mapping that has previously been associated through a call to #addPrefixMapping
        <br>Subsequent calls to #getMappedName with "OLDPREFIX_nametrailer" will return "OLDPREFIX_nametrailer"
    */
    BASE_UTILS_API void removePrefixMapping(
        const std::string &oldPrefix /**< (I) The name prefix that should no longer be mapped to a new prefix */
        );

    /**
        Returns the mapped name that applies to the provided name.
        <br>E.g. it returns "NEWPREFIX_nametrailer" for an input "OLDPREFIX_nametrailer" if the mappings "OLDPREFIX_"
        to "NEWPREFIX_" has been set through #addPrefixMapping.

        @returns The mapped name
    */
    BASE_UTILS_API std::string getMappedName(
        const std::string & originalName /**< (I) The name to be checked against mapping */
        );


    /**
       Retrieves the actual map of prefixes.
    */
    BASE_UTILS_API const std::map< std::string, std::string > & getNamePrefixMap();     //lint !e1929 This function returns a const reference. Further the const reference of a member variable of a singleton whose lifecycle is managed well. 2015-06-19
}
}
#include <base_utils/libbase_utils_undef.h>
#endif