AuroraRuntime/Include/Aurora/IO/FS/FS.hpp

/***
    Copyright (C) 2021 J Reece Wilson (a/k/a "Reece"). All rights reserved.

    File: FS.hpp
    Date: 2021-6-9
    Author: Reece
***/
#pragma once

namespace Aurora::IO::FS
{
    struct IReadDir;

    /**
        Lists files with respect to a given partial or full path of a directory
        @param files relative address of an entry
    */
    AUKN_SYM bool FilesInDirectory(const AuString &string, AuList<AuString> &files);

    /**
        Lists directories with respect to a given partial or full path of a directory
        @param files relative address of an entry
    */
    AUKN_SYM bool DirsInDirectory(const AuString &string, AuList<AuString> &dirs);

    /**
      @brief Opens a directory iterator given a directory path
     * @param directory An Aurora path as defined in the README
     * @return 
    */
    AUKN_SYM AuSPtr<IReadDir> ReadDir(const AuString &directory);

    /**
     * @brief 
     * @param string 
     * @return 
    */
    AUKN_SYM AuSPtr<IReadDir> ReadDirRecursive(const AuString &string);

    /**
     * @brief Recursively deletes any given path
     * @param string 
     * @return 
    */
    AUKN_SYM bool DirDeleter(const AuString &string);

    /**
     * @brief 
     * @param string 
     * @param failingPaths 
     * @return 
    */
    AUKN_SYM bool DirDeleterEx(const AuString &string, AuList<AuString> &failingPaths);

    /**
     * @brief Writes a blob into a file chunk-by-chunk.
     *        The directory structure may or may not exist for the write operation to succeed.
     * @param path An Aurora path as defined in the README
     * @param blob 
     * @return true on success
    */
    AUKN_SYM bool WriteFile(const AuString &path, const Memory::MemoryViewRead &blob);

    /**
     * @brief Writes a UTF-8 string onto disk with a BOM
     *        The directory structure may or may not exist for the write operation to succeed.
     * @param path An Aurora path as defined in the README
     * @param str UTF-8 bytecode (can be ASCII)
     * @return true on success
    */
    AUKN_SYM bool WriteString(const AuString &path, const AuString &str);

    /**
     * @brief Returns a bytebuffer (does not write into) of a binary files contents
     * @param path An Aurora path as defined in the README
     * @param buffer 
     * @return 
    */
    AUKN_SYM bool ReadFile(const AuString &path, Memory::ByteBuffer &buffer);

    /**
     * @brief Reads a UTF-8 string from the disk.
     *        An attempt will be made to interpret known BOMs and translate
     *        using supported decoders, if possible. 
     *        For example: a Japanese Shift JIS marked file, or a Chinese GBK
     *                     marked file, *might* be readable as UTF-8 on your 
     *                     platform.
     * @param path An Aurora path as defined in the README
     * @param buffer 
     * @return true on success
    */
    AUKN_SYM bool ReadString(const AuString &path, AuString &buffer);

    /**
     * @brief Returns a non-atomic non-promise that the requested file didn't exist.
     *        > Use appropriate file locks and check for open file related errors when relevant
     *          Do not solely rely on this return value.
     * @param path An Aurora path as defined in the README
    */
    AUKN_SYM bool FileExists(const AuString &path);

    /**
     * @brief Returns a non-atomic non-promise that the requested directory didn't exist.
     * @param path An Aurora path as defined in the README
    */
    AUKN_SYM bool DirExists(const AuString &path);
    
    /**
     * @brief 
     * @param path 
     * @return 
    */
    AUKN_SYM bool DirMk(const AuString &path);

    /**
     * @brief Deletes a file or an empty directory
     * @param path 
     * @return true on success
     * @warning Directory iteration is not supported. No FS API will do 
     *          iterative tasks for you.
    */
    AUKN_SYM bool Remove(const AuString &path);

    /**
     * @brief Attempts to move a directory or file from the source 
     *        to the destination path.
     *  
     * @param src The source Aurora path as defined in the README
     * @param dest The source Aurora path as defined in the README
     * @return true on success
    */
    AUKN_SYM bool Relink(const AuString &src, const AuString &dest);

    /**
     * @brief Performs a synchronous platform-optimized copy of
     *        a *FILE*.
     * 
     * @param src The source Aurora path as defined in the README
     * @param dest The source Aurora path as defined in the README
     * @warning Directories are not supported. No FS API will do 
     *          iterative tasks for you.
     * @return true on success
    */
    AUKN_SYM bool Copy(const AuString &src, const AuString &dest);

    /**
     * @brief Specifies download level of trust
     * @param path
     * @return
    */
    AUKN_SYM bool BlockFile(const AuString &path);

    /**
     * @brief Specifies generic local-system/trusted level of trust
     * @param path
     * @return
    */
    AUKN_SYM bool UnblockFile(const AuString &path);

    /**
     * @brief Specifies user/executable level trust of a file
     * @warning This routine is intended to enable execution of files
     *          on both UNIX and NT based systems. UnblockFile
     *          will be enough for resources and some powershell scripts;
     *          however, this is required for unblocking / `mode |= 0111`ing
     *          executable files.
     * @param path 
     * @return 
    */
    AUKN_SYM bool TrustFile(const AuString &path);
    
    /**
     * @brief Transfers the contents of the specified filepath through a
     *        zstandard compression pipe to an ending path + ".zst" file.
     * @warning This file API does not relate to file-system level compression
     * @param path = ur mother
    */
    AUKN_SYM bool Compress(const AuString &path, AuInt8 level = 17);

    AUKN_SYM bool Decompress(const AuString &path);

    /**
     * @brief Normalizes an arbitrary string of in
     * @param out 
     * @param in 
     * @return 
    */
    AUKN_SYM bool NormalizePath(AuString &out, const AuString &in);

    /**
     * @brief Strips the filename part out of an Aurora path
     * @param out 
     * @param path 
     * @return 
    */
    AUKN_SYM bool GetFileFromPath(AuString &out, const AuString &path);

    /**
     * @brief Strips the directory part out of an Aurora path
     * @param out
     * @param path
     * @return
    */
    AUKN_SYM bool GetDirectoryFromPath(AuString &out, const AuString &path);
    
    AUKN_SYM bool GoUpToSeparator(AuString &out, const AuString &path);

    // Further apis can be found in: Stat.hpp, FileStream.hpp, Async.hpp, and Resources.hpp
}

#include "EFileAdvisoryLockLevel.hpp"
#include "EFileOpenMode.hpp"
#include "IFileStream.hpp"
#include "FileStream.hpp"
#include "FileSeekableReader.hpp"
#include "FileReader.hpp"
#include "FileWriter.hpp"
#include "Resources.hpp"
#include "Stat.hpp"
#include "IAsyncFileStream.hpp"
#include "Async.hpp"
#include "Watcher.hpp"
#include "IReadDir.hpp"
#include "Overlapped.hpp"