Luna/libos/include/os/File.h

/**
 * @file File.h
 * @author apio (cloudapio.eu)
 * @brief A C++-friendly API for file access.
 *
 * @copyright Copyright (c) 2023, the Luna authors.
 *
 */

#pragma once
#include <fcntl.h>
#include <luna/Attributes.h>
#include <luna/Buffer.h>
#include <luna/Result.h>
#include <luna/SharedPtr.h>
#include <luna/StringView.h>
#include <os/Path.h>
#include <stdio.h>
#include <sys/types.h>

namespace os
{
    /**
     * @brief An object-oriented file handle, which is closed when all references to it go out of scope.
     */
    class File : public Shareable
    {
      public:
        /**
         * @brief The supported file opening modes.
         */
        enum OpenMode
        {
            ReadOnly = O_RDONLY,            // Open the file read-only.
            WriteOnly = O_WRONLY | O_TRUNC, // Open the file write-only, truncating it.
            ReadWrite = O_RDWR | O_TRUNC,   // Open the file read-write, truncating it.
            Append = O_WRONLY | O_APPEND,   // Open the file write-only, and append to it.
            ReadAppend = O_RDWR | O_APPEND, // Open the file read-write, and append to it.
        };

        enum class SeekMode
        {
            Beginning = SEEK_SET, // Seek from the beginning of the file.
            Current = SEEK_CUR,   // Seek from the current file position.
            End = SEEK_END,       // Seek from the end of the file.
        };

        /**
         * @brief Create a new File object from a file path, opening the file.
         *
         * @param path The path to open.
         * @param flags The opening mode to pass to open(2).
         * @return Result<SharedPtr<File>> A new File object, or ENOENT if the file did not exist.
         */
        static Result<SharedPtr<File>> open(const Path& path, OpenMode flags);

        /**
         * @brief Create a new File object from a file path, opening the file or creating it if it does not exist.
         *
         * @param path The path to open.
         * @param flags The opening mode to pass to open(2).
         * @param mode If a new file is created, the file permissions to apply to it. (default: u=rw,g=r,o=r)
         * @return Result<SharedPtr<File>> A new File object.
         */
        static Result<SharedPtr<File>> open_or_create(const Path& path, OpenMode flags, mode_t mode = 0644);

        /**
         * @brief Create a new File object from a file path, creating the file but erroring out if the file already
         * exists.
         *
         * @param path The path to open.
         * @param flags The opening mode to pass to open(2).
         * @param mode The file permissions to apply to the created file. (default: u=rw,g=r,o=r)
         * @return Result<SharedPtr<File>> A new File object, or EEXIST if the file already existed.
         */
        static Result<SharedPtr<File>> create(const Path& path, OpenMode flags, mode_t mode = 0644);

        /**
         * @brief If path is "-", return standard input (as is common for many CLI apps). Otherwise, open path for
         * reading.
         *
         * @param path The path to open.
         * @return Result<SharedPtr<File>> A new File object if path was not "-", or the File
         * object for standard input if path was "-".
         */
        static Result<SharedPtr<File>> open_input_file(StringView path);

        /**
         * @brief Returns the File corresponding to standard input.
         *
         * @return SharedPtr<File> The File object for standard input.
         */
        static SharedPtr<File> standard_input();

        /**
         * @brief Returns the File corresponding to standard output.
         *
         * @return SharedPtr<File> The File object for standard output.
         */
        static SharedPtr<File> standard_output();

        /**
         * @brief Returns the File corresponding to standard error.
         *
         * @return SharedPtr<File> The File object for standard error.
         */
        static SharedPtr<File> standard_error();

        /**
         * @brief Make this File object automatically close on the next call to execve(2).
         */
        void set_close_on_exec();

        /**
         * @brief Write a string to this File.
         *
         * @param str The string to write (doesn't have to be null-terminated).
         * @return Result<void> Whether the operation succeeded.
         */
        Result<void> write(StringView str);

        /**
         * @brief Write a memory buffer to this File.
         *
         * @param buf The buffer to write.
         * @return Result<void> Whether the operation succeeded.
         */
        Result<void> write(const Buffer& buf);

        /**
         * @brief Write a formatted string to this File.
         *
         * @param format The format string.
         * @param ... The format arguments.
         * @return Result<void> Whether the operation succeeded.
         */
        Result<usize> write_formatted(const char* format, ...) _format(2, 3);

        /**
         * @brief Write a formatted string to this File.
         *
         * @param format The format string.
         * @param args The format arguments.
         * @return Result<void> Whether the operation succeeded.
         */
        Result<usize> write_vformatted(const char* format, va_list args);

        /**
         * @brief Read a line from this File.
         *
         * @return Result<String> The line as an owned String object, or an empty string if there is no more
         * data to read.
         */
        Result<String> read_line();

        /**
         * @brief Read the entire File's contents as a string.
         *
         * @return Result<String> The file's contents as an owned String object.
         */
        Result<String> read_all_as_string();

        /**
         * @brief Read data from this File.
         *
         * @param buf The output buffer to store the data in. Will be resized to fit the data.
         * @param size The maximum number of bytes to read.
         * @return Result<void> Whether the operation succeeded.
         */
        Result<void> read(Buffer& buf, usize size);

        /**
         * @brief Read an object from this File.
         *
         * @tparam T The type of the object to read.
         * @param object A reference to the object in question.
         * @return Result<void> Whether the operation succeeded.
         */
        template <typename T> Result<void> read_typed(T& object)
        {
            TRY(raw_read((u8*)&object, sizeof(T)));
            return {};
        }

        /**
         * @brief Read the entire File's contents.
         *
         * @return Result<Buffer> The file's contents as an owned Buffer object.
         */
        Result<Buffer> read_all();

        /**
         * @brief Read a single character from the File.
         *
         * @return Result<int> A character value above 0 (to be cast to an unsigned char), or EOF (typically -1)
         * if there is no more data to read.
         */
        Result<int> getchar();

        /**
         * @brief Returns the file descriptor associated with this File.
         *
         * @return int The file descriptor.
         */
        int fd() const
        {
            return fileno(m_file);
        }

        /**
         * @brief Flushes the stream's buffers.
         */
        void flush();

        /**
         * @brief Move this File's file pointer back to the beginning.
         */
        void rewind();

        /**
         * @brief Change the file pointer's position.
         *
         * @param offset The number of bytes to move the file pointer (can be negative, to move backwards).
         * @param mode Where to seek from.
         * @return Result<void> Whether the operation succeeded.
         */
        Result<void> seek(off_t offset, SeekMode mode);

        /**
         * @brief Read the file pointer's current position.
         *
         * @return Result<off_t> An error, or the file pointer's position.
         */
        Result<off_t> tell();

        /**
         * @brief Buffering modes for a File.
         */
        enum BufferingMode
        {
            NotBuffered = _IONBF,
            LineBuffered = _IOLBF,
            FullyBuffered = _IOFBF,
        };

        /**
         * @brief Change the buffering mode of this File.
         *
         * @param mode The buffering mode.
         */
        void set_buffer(BufferingMode mode);

        File(Badge<File>);
        ~File();

      private:
        static Result<SharedPtr<File>> construct(const Path& path, int flags, mode_t mode);
        static void initialize_standard_streams();

        Result<usize> raw_read(u8* buf, usize length);
        Result<usize> raw_write(const u8* buf, usize length);

        FILE* m_file { nullptr };
    };

    /**
     * @brief Print a formatted string to standard output.
     *
     * @param format The format string (in the same format as printf(3)).
     * @param ... The format arguments.
     * @return Result<void> Whether the operation succeeded.
     */
    Result<void> print(const char* format, ...) _format(1, 2);

    /**
     * @brief Print a newline-terminated formatted string to standard output.
     *
     * @param format The format string (in the same format as printf(3)).
     * @param ... The format arguments.
     * @return Result<void> Whether the operation succeeded.
     */
    Result<void> println(const char* format, ...) _format(1, 2);

    /**
     * @brief Print a formatted string to standard error.
     *
     * @param format The format string (in the same format as printf(3)).
     * @param ... The format arguments.
     * @return Result<void> Whether the operation succeeded.
     */
    Result<void> eprint(const char* format, ...) _format(1, 2);

    /**
     * @brief Print a newline-terminated formatted string to standard error.
     *
     * @param format The format string (in the same format as printf(3)).
     * @param ... The format arguments.
     * @return Result<void> Whether the operation succeeded.
     */
    Result<void> eprintln(const char* format, ...) _format(1, 2);
}