path.inl

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of module \alib_system of the \aliblong.
///
/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
/// Published under \ref mainpage_license "Boost Software License".
//==================================================================================================
ALIB_EXPORT namespace alib { namespace  system {
 
/// The character type that this \alibmod_nl uses for String representations.
/// This is taken from the C++ standard library.
using PathCharType  = std::filesystem::path::value_type;
 
#if !defined(ALIB_PATH_CHARACTERS_WIDE)
#   if defined(_WIN32)
       static_assert(std::same_as<PathCharType, characters::wchar>,
           "Compiler symbol ALIB_PATH_CHARACTERS_WIDE wrongly detected: 1 but std::filesystem::path::value_type does not equal characters::wchar.");
#   else
       static_assert(std::same_as<PathCharType, characters::nchar>,
           "Compiler symbol ALIB_PATH_CHARACTERS_WIDE wrongly detected: 0 but std::filesystem::path::value_type does not equal characters::nchar.");
#   endif
#else
#   if ALIB_PATH_CHARACTERS_WIDE
       static_assert(std::same_as<PathCharType, characters::wchar>,
       "Given compiler-symbol ALIB_PATH_CHARACTERS_WIDE mismatch: Given 1 but std::filesystem::path::value_type does not equal characters::wchar.");
#   else
       static_assert(std::same_as<PathCharType, characters::nchar>,
       "Given compiler-symbol ALIB_PATH_CHARACTERS_WIDE mismatch: Given 0 but std::filesystem::path::value_type does not equal characters::nchar.");
#   endif
#endif
 
/// The string-type used with this \alibmod_nl.
using PathString     = strings::TString<PathCharType>;
 
/// The string-type used with this \alibmod_nl.
using CPathString    = strings::TCString<PathCharType>;
 
/// The string-type used with this \alibmod_nl.
using PathSubstring  = strings::TSubstring<PathCharType>;
 
#if ALIB_MONOMEM
/// A mono-allocated string representing a path.
using PathStringMA   = strings::TAString<PathCharType, PoolAllocator >;
 
/// A pool-allocated string representing a path.
using PathStringPA   = strings::TAString<PathCharType, PoolAllocator >;
#endif
 
#if DOXYGEN
/// A nulled path string. 
inline constexpr PathString NULL_PATH;
 
/// An empty path string.
inline constexpr PathString EMPTY_PATH;
#else
inline constexpr PathString NULL_PATH(nullptr);
inline constexpr PathString EMPTY_PATH(A_PATH(""));
#endif
 
 
#if !defined( _WIN32 ) || DOXYGEN
     /// The standard path separator character. Defaults to '\\' on Windows OS, '/' else.
    inline constexpr PathCharType    DIRECTORY_SEPARATOR = '/';
#else
    inline constexpr PathCharType    DIRECTORY_SEPARATOR = '\\';
#endif
 
// #############################################################################################
// MacOS System call wrappers (implemented in Objective-C)
// #############################################################################################
#if defined(__APPLE__)
class Path;
namespace macos
{
    void ALIB_APPLE_OC_NSTemporaryDirectory( Path& target );
    void ALIB_APPLE_OC_NSHomeDirectory     ( Path& target );
}
#endif
 
//==================================================================================================
/// Enumerates special system folders like "home", "temp", "config", etc.
/// This enumeration is primarily used with class \alib{system;Path} and this documentation
/// refers to this type.
//==================================================================================================
enum class SystemFolders
{
    /// The root directory .
    Root,
 
    /// The current directory of the process.
    Current,
 
    /// The user's home directory
    Home,
 
    /// The user's configuration directory. This is evaluated as follows:
    /// - Using environment variable \e HOME (under WindowsOS a combination of \e HOMEDRIVE
    ///   and \e HOMEPATH), the home directory is determined.
    /// - If within this directory \e ".config" exists, it is used, otherwise
    /// - if within this the directories \e "AppData/Roaming" exist, this is used.
    HomeConfig,
 
    /// The directory of the executable of the process.
    Module,
 
    /// A directory to be used for creation of temporary files.
    ///
    /// - On GNU/Linux OS this defaults to <c>/tmp</c>.
    /// - On Windows OS, environment variables "TMP" and "TEMP" are evaluated.<br>
    ///
    /// If the directory does not exist, then (on all OS), a new directory named \c ".tmp"
    /// is created in the user's home directory and returned (if not existent already).
    /// If this fails, the home directory itself is returned.
    ///
    /// \note With the potential creation of the directory \c ".tmp" in the user's home
    ///       directory, a small \c readme.txt file is created containing  the name of
    ///       the running application and the reason of the creation.
    ///
    /// To overrule this behavior, public static variable
    /// \alib{system;Path::tempDirEvaluatedOnce} may be set arbitrarily before using this
    /// enum value.
    Temp,
 
    /// A directory to be used for creation of temporary files that survives reboots of the
    /// host machine.
    ///
    /// - On GNU/Linux OS this defaults to <c>/var/tmp</c>.
    /// - On Windows OS, environment variables "TMP" and "TEMP" are evaluated (same as
    ///   with \b %SystemFolders::Temp).<br>
    ///
    /// If the directory does not exist, then (on all OS), a new directory named \c ".var.tmp"
    /// is created in the user's home directory and returned (if not existent already).
    /// If this fails, the home directory itself is returned.
    ///
    /// \note With the potential creation of the directory \c ".var.tmp" in the user's home
    ///       directory, a small \c readme.txt file is created, containing the name of
    ///       the running application and the reason of the creation.
    ///
    /// To overrule this behavior, public static variable
    /// \alib{system;Path::varTempDirEvaluatedOnce} may be set arbitrarily before using this
    /// enum value.
    VarTemp,
};
 
 
//==================================================================================================
/// Represents a directory or file in a file system.
///
/// Inherits a local string buffer fixed to size 256. The flexible nature of \alib
/// \alib{strings;TLocalString;local strings} allows dynamic allocation if this should be exceeded
/// (which usually is not expected with paths).
///
/// The character type of this \b AString derivate is bound to type definition
/// \alib{system::PathCharType}, which in turn aliases <c>std::filesystem::path::value_type</c>.
//==================================================================================================
class Path : public  strings::TLocalString<PathCharType, 256>
{
    // #############################################################################################
    // Fields
    // #############################################################################################
    public:
        /// Singleton containing the path for the use of enum value
        /// \alib{system;SystemFolders;SystemFolders::Temp}.
        /// This is evaluated once with the first use of \b %SystemFolders::Temp.
        /// To change the default behavior of evaluation, this variable may be filled with a proper
        /// path before using enum \b %SystemFolders::Temp with this class.
        ///
        /// The one-time evaluated value is stored in the \alib{monomem;GLOBAL_ALLOCATOR} and
        /// access to this variable is consequently protected with \alib{monomem;GLOBAL_ALLOCATOR_LOCK}.
        static      PathString          tempDirEvaluatedOnce;
 
        /// Singleton containing the path for the use of enum value
        /// \alib{system;SystemFolders;SystemFolders::VarTemp}".
        /// This is evaluated once with the first use of \b %SystemFolders::VarTemp.
        /// To change the default behavior of evaluation, this variable may be filled with a proper
        /// path before using enum \b %SystemFolders::VarTemp with this class.
        ///
        /// The one-time evaluated value is stored in the \alib{monomem;GLOBAL_ALLOCATOR} and
        /// access to this variable is consequently protected with \alib{monomem;GLOBAL_ALLOCATOR_LOCK}.
        static      PathString          varTempDirEvaluatedOnce;
 
    // #############################################################################################
    // Constructors
    // #############################################################################################
    public:
    using strings::TLocalString<PathCharType, 256>::TLocalString;
 
        //==========================================================================================
        /// Constructs an object representing no directory.
        /// Field #Path remains empty.
        //==========================================================================================
                                Path()
        {}
 
        //==========================================================================================
        /// Constructs an object representing one of the known special directories.
        /// @param special  The special directory to initialize this instance to.
        //==========================================================================================
                                Path( SystemFolders special )
        {
            Change( special );
        }
 
        //==========================================================================================
        /// Constructs an object representing one of the known special directories.
        /// @param special  The special directory to initialize this instance to.
        /// @param fileName The filename in folder \p{special}.
        //==========================================================================================
                                Path( SystemFolders special, const PathString& fileName )
        {
            Change( special );
            Add(fileName);
        }
 
        //==========================================================================================
        /// Constructs an object representing the given path.
        /// @param path  The initial path.
        //==========================================================================================
                                Path( const PathString& path )
        : strings::TLocalString<PathCharType, 256>(path)                                         {}
 
 
    // #############################################################################################
    // Interface
    // #############################################################################################
    public:
        //==========================================================================================
        ///  Creates the directory of the given \p{path}. If a relative path is given, then
        ///  it is appended to the currently stored path, otherwise the current path is replaced.
        ///  @param path     Zero-terminated string defining the path to test.
        ///  @return A value of enum type \alib{system;SystemErrors}.
        //==========================================================================================
        ALIB_DLL
        SystemErrors     Create( const PathString& path );
 
        //==========================================================================================
        ///  Creates the directory represented by this object by invoking #Create(const PathString&)
        ///  passing an empty String.
        ///  @return A value of the enum type \alib{system;SystemErrors}.
        //==========================================================================================
        ALIB_DLL
        SystemErrors     Create()                             { return Create(EMPTY_PATH); }
 
        //==========================================================================================
        /// Changes the directory. If the given path is relative (e.g., a name of a subdirectory
        /// or ".."), such path is added to the current #Path. Otherwise, this objects' path
        /// string is replaced.
        /// If the resulting destination directory is not valid, \c false is returned and this
        /// object is not changed.
        /// @param    path  The relative or absolute path to change to.
        /// @returns \c true if the change was successful, \c false otherwise.
        //==========================================================================================
        ALIB_DLL   bool         Change( const PathString& path );
 
        //==========================================================================================
        /// Changes the directory to one of the known special directories.
        /// @param special  The special directory to change this instance to.
        /// @returns \c true if the change was successful, \c false otherwise.
        //==========================================================================================
        ALIB_DLL   bool         Change( SystemFolders special );
 
        //==========================================================================================
        /// Changes the directory to one of the known special directories and adds the given
        /// \p{fileName} to this path.
        /// @param special  The special directory to change this instance to.
        /// @param fileName The filename within \p{special}.
        //==========================================================================================
        inline    void         Change( SystemFolders special, const PathString& fileName )
        {
            Change( special );
            Add(fileName);
        }
 
 
        //==========================================================================================
        /// Adds a directory or filename to the internal string. If the current string does not
        /// end with a \alib{system;DIRECTORY_SEPARATOR}, one will be inserted first.
        ///
        /// @param dirOrFilename The path component to add.
        /// @return \c *this to allow concatenated operations.
        //==========================================================================================
        inline    Path&         Add( const PathString& dirOrFilename )
        {
            if( CharAtEnd() != DIRECTORY_SEPARATOR )
                _(DIRECTORY_SEPARATOR);
            _(dirOrFilename);
            return *this;
        }
 
        //==========================================================================================
        /// Adds this processes' module name to the currently stored folder path.
        ///
        /// @param extension  An additional extension string that is added to the evaluated file
        ///                   name, for example <c>".jpg"</c>.
        //==========================================================================================
        ALIB_DLL   void         AddModuleName( const PathString& extension );
 
        //==========================================================================================
        ///  Tests if this path represents an existing directory in the file system.
        ///  @return \c true if a directory was found, \c false if not found or the path represents
        ///             a file.
        //==========================================================================================
        ALIB_DLL
        bool                    IsDirectory();
 
        //==========================================================================================
        /// Calls invokes static overload of this method, passing this object.
        /// @returns The result of a call to #IsAbsolute(const PathString&).
        //==========================================================================================
        int                     IsAbsolute()                     const { return IsAbsolute(*this); }
 
        //==========================================================================================
        /// Gets the name portion of the path.
        /// @returns A string containing the characters after the last directory separator.
        //==========================================================================================
        PathString              Name()                                                         const
        {
            auto idx= LastIndexOf(DIRECTORY_SEPARATOR);
            if( idx < 0 )
                return *this;
            return Substring(idx + 1);
        }
 
        //==========================================================================================
        /// Resolves the path by removing all symbolic links and relative addressing.
        /// @return \alib{system;SystemErrors;SystemErrors::OK} on success, otherwise
        ///         an error code.
        //==========================================================================================
        ALIB_DLL
        SystemErrors            MakeReal();
 
        //==========================================================================================
        /// Determines if the given string contains a path/filename with absolute addressing or
        /// not.
        /// \attention This method must be invoked on "real path strings" only. Assembled paths
        ///            which contain redundant slashes return a false result.
        /// @param    path  The relative or absolute path to check.
        /// @returns \c 0 if \p{path} is relative. If absolute, the position of the first character
        ///          that does not belong to the root symbol. For example, with windows OS, if
        ///          <c>"C:\XYZ"</c> was given, \c 3 is returned.
        ///          With other OSes "//" is searched.
        //==========================================================================================
        static  int             IsAbsolute( const PathString& path )
        {
            #if defined(_WIN32)
               if( path.Length() >= 3 )
               {
                    if(    path.CharAt<NC>(1) == ':'
                        && path.CharAt<NC>(2)== DIRECTORY_SEPARATOR    )
                        return 3;
 
                    if (   path.CharAt<NC>(0) == DIRECTORY_SEPARATOR
                        && path.CharAt<NC>(1) == DIRECTORY_SEPARATOR)
                        return int(path.IndexOf<NC>( DIRECTORY_SEPARATOR, 2 ) + 1);
               }
               return 0;
            #else
                if( path.CharAtStart() == '/' )
                    return 1;
                auto slashSlashPos= path.IndexOf(A_PATH("//"));
                if( slashSlashPos > 0 )
                    return int(slashSlashPos + 2);
                return 0;
            #endif
        }
 
}; //class Path
 
// Note(25/01/17):
//   Clang strangely did not find the following templated operators when they resided in an
//   exported namespace.
//   The workaround was to not export the namespace but export each operator instead.
//   We think this is wrong behavior and not aligned with the language specification.
#if !DOXYGEN
}} namespace alib::system {
 
ALIB_EXPORT
inline bool operator== (const Path& lhs, const Path& rhs)
{ return  lhs. template Equals   <CHK, lang::Case::Sensitive>(rhs); }
 
ALIB_EXPORT
inline auto operator<=> (const Path& lhs, const Path& rhs)
{ return  lhs. template CompareTo<CHK, lang::Case::Sensitive>(rhs); }
 
 
} ALIB_EXPORT namespace alib { namespace system {
#endif // DOXYGEN
 
} // namespace alib[::system]
 
/// Type alias in namespace \b alib.
using     Path=             system::Path;
 
/// Type alias in namespace \b alib.
using     SystemFolders=    system::SystemFolders;
 
 
// #################################################################################################
// Specializations of ZTArrayTraits for  class Path
// #################################################################################################
#if !DOXYGEN
namespace characters {
template<>
struct  ZTArrayTraits<system::Path, system::PathCharType>
{
    static constexpr Policy                      Access                          = Policy::Implicit;
    static constexpr Policy                      Construction                    = Policy::NONE;
    static constexpr const system::PathCharType* Buffer(const system::Path& src) { return src.Terminate(); }
    static constexpr integer                     Length(const system::Path& src) { return src.Length(); }
};
}// namespace alib[::characters]
#endif //!DOXYGEN
 
}  // namespace [alib]
 
ALIB_ENUMS_ASSIGN_RECORD(   alib::system::SystemFolders, alib::enumrecords::ERSerializable )
ALIB_BOXING_VTABLE_DECLARE( alib::system::Path*        , vt_system_path              )