#pragma region CPL License
/*
Nuclex Native Framework
Copyright (C) 2002-2021 Nuclex Development Labs

This library is free software; you can redistribute it and/or
modify it under the terms of the IBM Common Public License as
published by the IBM Corporation; either version 1.0 of the
License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
IBM Common Public License for more details.

You should have received a copy of the IBM Common Public
License along with this library
*/
#pragma endregion // CPL License

#ifndef NUCLEX_STORAGE_FILESYSTEM_PATH_H
#define NUCLEX_STORAGE_FILESYSTEM_PATH_H

#include "Nuclex/Storage/Config.h"

#include <string> // std::string

// Possible additions:
//
// - MakeRelative() -> Probably not, all my asset paths will be relative anyway
//
//   May be useful for content authoring tools (level editors) where asset paths
//   should be saved as relative paths
//
//   /// <summary>Makes a path relative to the specified base</summary>
//   /// <param name="base">Base to which the path will be made relative</param>
//   /// <param name="absolute">Absolute path that will be made relative</param>
//   /// <returns>The relative path as seen to from the specified base directory</param>
//   public: NUCLEX_STORAGE_API static Path MakeRelative(
//     const Path &base, const Path &absolute
//   );
//
// - MakeAbsolute() -> Nope, use Resolve()!
//
//   May be useful for command line tools that want to make sure inputs specified
//   on the command line are used under their absolute paths
//
//   Already covered by Resolve() and a bad idea because on some operating systems,
//   additional information ("what is the working directory on drive E:?") may be
//   needed, making this method untestable and dependent on process state.
//
//   /// <summary>Makes the specified path absolute</summary>
//   /// <param name="base">
//   ///   Base path starting at which the relative path will be evaluated
//   /// </param>
//   /// <param name="relative">Path relative to the current working directory</param>
//   /// <returns>The absolute path</returns>
//   public: NUCLEX_STORAGE_API static Path MakeAbsolute(const Path &base, const Path &relative);
//
// - GetParent() -> Maybe..
//
//   If a file browser is implemented, this could be used for the "go up" command
//
//   public: NUCLEX_STORAGE_API static std::string GetParent(const std::string &path);
//
// - GetDirectory() -> Probably not, I don't need to fiddle around with paths like this
//
//   public: NUCLEX_STORAGE_API static std::string GetDirectory(const std::string &path);
//
// - Multi-input Join() -> Yes! Makes many things simpler
//
//   private: template<typename TBasePath, typename... TCombinedPaths>
//   using are_same = std::conjunction<std::is_same<Head, Tail>...>;
//
//   template<
//     typename... TCombinedPaths,
//     typename = std::enable_if_t<
//       std::conjunction<std::is_same<Head, Tail>...>::value, void
//     >
//   >
//   void print_same_type(const Path &basePath, const TCombinedPaths... &combinedPaths) {}
//

namespace Nuclex { namespace Storage { namespace FileSystem {

  // ------------------------------------------------------------------------------------------- //

  /// <summary>Path to a file or directory</summary>
  /// <remarks>
  ///   This class provides common utility methods to combine and split paths.
  ///   All methods assume UTF-8 strings and are implemented inside this library
  ///   to ensure repeatable and reliable behavior independent of C runtime and
  ///   host OS character sets.
  /// </remarks>
  class Path {

    /// <summary>A path that references the current directory</summary>
    public: NUCLEX_STORAGE_API static const std::string CurrentDirectory;

    /// <summary>A path that references the parent directory</summary>
    public: NUCLEX_STORAGE_API static const std::string ParentDirectory;

    /// <summary>Character(s) that will be used to separate directory names in a path</summary>
    /// <remarks>
    ///   This is the character you find between a directory and a filename or a directory
    ///   and a subdirectory in a path. It is not the character you find in the PATH variable
    ///   or other list as a separator between absolute paths.
    /// </remarks>
    public: NUCLEX_STORAGE_API const static std::string DirectorySeparator;

    /// <summary>Checks if the specified path is an absolute path</summary>
    /// <param name="path">Path that will be checked</param>
    /// <returns>True if the path is absolute, false if it is relative</returns>
    public: NUCLEX_STORAGE_API static bool IsAbsolute(const std::string &path);

    /// <summary>Checks if the specified path is a relative path</summary>
    /// <param name="path">Path that will be checked</param>
    /// <returns>True if the path is relative, false if it is absolute</returns>
    public: NUCLEX_STORAGE_API static bool IsRelative(const std::string &path);

    /// <summary>Figures out the stem of a path</summary>
    /// <param name="path">Path of which the stem will be determined</param>
    /// <returns>The stem of the specified part</returns>
    /// <remarks>
    ///   <para>
    ///     The stem of the path is those characters that will be not change no matter
    ///     how many directory levels you go 'up'. For example, on Linux systems,
    ///     the parent of '~/test/file.txt' is '~/test', then '~' then '~/..'.
    ///     The '~' remains. Same with a drive letter on Windows or the URI scheme
    ///     in a URI-like path (i.e. 'http://' is typically the stem there).
    ///   </para>
    ///   <para>
    ///     This handles plain paths, URI-like paths and UNC paths or drive letters
    ///     on Windows. A server name in UNC paths or a host name in URI-like paths
    ///     is not seen as part of the stem.
    ///   </para>
    /// </remarks>
    public: NUCLEX_STORAGE_API static std::string GetStem(const std::string &path);

    /// <summary>Extracts the filename from a path</summary>
    /// <param name="path">Path the filename will be extracted from</param>
    /// <param name="withExtension"
    /// <returns>The filename contained in the path</returns>
    /// <remarks>
    ///   <para>
    ///     This method does exactly what you would expect it to do. For dot files
    ///     (files that start with a dot, used on Linux systems for hidden files),
    ///     the dot is seen as part of the filename.
    ///   </para>
    ///   <para>
    ///     If a file has chained extensions (such as 'archive.tar.gz' or 'config.xml.zip'),
    ///     the entire chain is seen as the extension, so the name of the example files
    ///     from before would be 'archive' and 'config'.
    ///   </para>
    /// </remarks>
    public: NUCLEX_STORAGE_API static std::string GetFilename(
      const std::string &path, bool withExtension = true
    );

    /// <summary>Extracts the file extension from a path</summary>
    /// <param name="path">Path from which the extension will be extracted</param>
    /// <returns>The extension of the filename in the specified path</returns>
    public: NUCLEX_STORAGE_API static std::string GetExtension(const std::string &path);

    /// <summary>Eliminates all removable parent directory references in a path</summary>
    /// <param name="path">Path that will be normalized</param>
    /// <returns>The path with all removable parent directory references eliminated</returns>
    /// <remarks>
    ///   <para>
    ///     This cleans any unneccessary parent directory references from a path, so
    ///     '/home/me/../../etc/cfg' will become '/etc/cfg'.
    ///   </para>
    ///   <para>
    ///     Use this method with care. Assume, for example, a directory contained a symlink
    ///     to a directory in an entirely different place. The path '~/symlink/..' would
    ///     be normalized to '~', but the original path was actually going up from whatever
    ///     directory the symlink pointed to.
    ///   </para>
    ///   <para>
    ///     If you want the ultimate path, followed through symlinks, shortcuts and everything
    ///     to its ultimate destination, use the <see cref="Resolve" /> method instead.
    ///     This method is faster and allows independent verification in unit tests for paths
    ///     you have control over (i.e. below the game's install directory - it doesn't matter
    ///     if the install directory or anything above it is a symlink as it will never be left)
    ///   </para>
    /// </remarks>
    public: NUCLEX_STORAGE_API static std::string Normalize(const std::string &path);

    /// <summary>Establishes the ultimate target a path is referencing</summary>
    /// <param name="path">Path that will be resolved</param>
    /// <returns>
    ///   <para>
    ///     The ultimate target of the specified path. If the input is a relative path,
    ///     it will be turned absolute using the current working directory (if applicable
    ///     on the current platform), all directory separators will change to the platform's
    ///     native format and any symlinks will be traveled.
    ///   </para>
    ///   <para>
    ///     Use this if you need to resolve paths that may become a goose chase through
    ///     the platform's file system through symlinks and parent directory references.
    ///   </para>
    /// </returns>
    public: NUCLEX_STORAGE_API static std::string Resolve(const std::string &path);

    /// <summary>Joins two paths</summary>
    /// <param name="base">Path to which the other path will be appended</param>
    /// <param name="other">Path that will be joined to the base path</param>
    /// <returns>The combined path</returns>
    /// <remarks>
    ///   <para>
    ///     This method blindly appends one path to the other. The trailing path separator
    ///     will be taken care of, but if the second path is an absolute one, an invalid
    ///     path will result.
    ///   </para>
    ///   <para>
    ///     Whether the resulting path ends in a directory separator is up to the joined
    ///     path (or the base path if the joined path is empty). This method only takes
    ///     care of inserting a directory separator between the two paths if it is needed.
    ///   </para>
    /// </remarks>
    public: NUCLEX_STORAGE_API static std::string Join(
      const std::string &base, const std::string &other
    );

    /// <summary>Combines two paths</summary>
    /// <param name="base">Path that will serve as a base for the combined path</param>
    /// <param name="other">Path that will be combined with the base path</param>
    /// <returns>The combined path</returns>
    /// <remarks>
    ///   This combines two paths by finding the target ultimately pointed to by
    ///   the joined paths (for example, joining 'a/b/c' and '../d' results in
    ///   'a/b/d' rather than 'a/b/c/../d' as it would with <see cref="Join" />).
    ///   It does not make relative paths absolute or vice versa.
    /// </remarks>
    public: NUCLEX_STORAGE_API static std::string Combine(
      const std::string &base, const std::string &other
    );

    /// <summary>Determines the length of the path's stem</summary>
    /// <param name="path">Path in which the stem length is determined</param>
    /// <returns>The index at which the path's directory chain begins</returns>
    /// <remarks>
    ///   This checks for the part of the path that can not be removed by going up,
    ///   i.e. you can't go up from 'D:\\' or from '/' or from 'file://' by removing
    ///   this part of the path. For some paths, the stem length will be 0 (i.e. you
    ///   can go up from 'hello/' to './' or even further to '../', so the stem length
    ///   here is zero).
    /// </remarks>
    private: static std::string::size_type getStemLength(const std::string &path);

    /// <summary>Figures out the character at which the filename begins</summary>
    /// <param name="path">Path in which the beginning of the filename will be found</param>
    /// <returns>The index of the first filename character</returns>
    private: static std::string::size_type getFilenameStartIndex(const std::string &path);

  };

  // ------------------------------------------------------------------------------------------- //

}}} // namespace Nuclex::Storage::FileSystem

#endif // NUCLEX_STORAGE_FILESYSTEM_PATH_H