BmnIFileReader.h

Go to the documentation of this file.

#pragma once
#ifndef BmnIFileReader_h
#define BmnIFileReader_h
 
// headers from this target
#include "BmnFileProcessingFlags.h"
// std:: headers
#include <filesystem>
// FairLogger headers
#include <fairlogger/Logger.h>
 
// o o o o o o o o o o o o o o o o o o o o o o o o o o o o o
// ================== BmnIFileReader class ==================
// o o o o o o o o o o o o o o o o o o o o o o o o o o o o o
 
/*
 * An abstract interface class for reading files. The primary goal of this class is to provide some
 * basic-reading functionality while children classes will implement various ways of extracting data
 * from files (mostly from compressed files as this is the goal).
 */
class BmnIFileReader
{
  public:
    /*
     * A constructor that's called from one of derived classes.
     * @param fileType A type of files that the derived-caller class can process
     * @param fileName A name of the file that's expected to be in the currently-working director
     * @warning Be very carful with "the currently-working directory" as it may not be the same as the executable path!
     */
    explicit BmnIFileReader(const BmnFileType fileType, const std::string& fileName = "");
 
    /*
     * A constructor that's called from one of derived classes.
     * @param fileType A type of files that the derived-caller class can process
     * @param fileName A name of the file that's expected to be in the currently-working director
     * @warning Be very carful with "the currently-working directory" as it may not be the same as the executable path!
     */
    explicit BmnIFileReader(const BmnFileType fileType, std::string&& fileName) noexcept;
 
    /*
     * A constructor that's called from one of derived classes.
     * @param fileType A type of files that the derived-caller class can process
     * @param filePath A path to the file that's expected to be read
     * @warning If you provide a relative path, be very careful that it's read relative to the currently-working
     * directory!
     */
    explicit BmnIFileReader(const BmnFileType fileType, const std::filesystem::path& filePath);
 
    /*
     * A constructor that's called from one of derived classes.
     * @param fileType A type of files that the derived-caller class can process
     * @param filePath A path to the file that's expected to be read
     * @warning If you provide a relative path, be very careful that it's read relative to the currently-working
     * directory!
     */
    explicit BmnIFileReader(const BmnFileType fileType, std::filesystem::path&& filePath) noexcept;
 
    virtual ~BmnIFileReader() = default;
    BmnIFileReader(const BmnIFileReader&) = delete;
    BmnIFileReader& operator=(const BmnIFileReader&) = delete;
    BmnIFileReader(BmnIFileReader&&) noexcept = delete;
    BmnIFileReader& operator=(BmnIFileReader&&) noexcept = delete;
 
    /*
     * A method that opens a binary file for reading according to the previously provided file path
     * @param processingFlags Flags that should be used for reading the file. Currently, only `ReadBinary` is supported
     */
    virtual void Open(
        const BmnBinaryFileProcessingOptions processingFlags = BmnBinaryFileProcessingOptions::ReadBinary) = 0;
 
    /*
     * A method that opens a binary file for reading
     * @param fileName A name of the file that's expected to be in the currently-working director
     * @param processingFlags Flags that should be used for reading the file. Currently, only `ReadBinary` is supported
     * @warning Be very carful with "the currently-working directory" as it may not be the same as the executable path!
     */
    virtual void Open(
        const std::string& fileName,
        const BmnBinaryFileProcessingOptions processingFlags = BmnBinaryFileProcessingOptions::ReadBinary);
 
    /*
     * A method that opens a binary file for reading
     * @param fileName A name of the file that's expected to be in the currently-working director
     * @param processingFlags Flags that should be used for reading the file. Currently, only `ReadBinary` is supported
     * @warning Be very carful with "the currently-working directory" as it may not be the same as the executable path!
     */
    virtual void Open(
        std::string&& fileName,
        const BmnBinaryFileProcessingOptions processingFlags = BmnBinaryFileProcessingOptions::ReadBinary);
 
    /*
     * A method that opens a binary file for reading
     * @param filePath A path to the file that's expected to be read
     * @param processingFlags Flags that should be used for reading the file. Currently, only `ReadBinary` is supported
     * @warning If you provide a relative path, be very careful that it's read relative to the currently-working
     * directory!
     */
    virtual void Open(
        const std::filesystem::path& filePath,
        const BmnBinaryFileProcessingOptions processingFlags = BmnBinaryFileProcessingOptions::ReadBinary);
 
    /*
     * A method that opens a binary file for reading
     * @param filePath A path to the file that's expected to be read
     * @param processingFlags Flags that should be used for reading the file. Currently, only `ReadBinary` is supported
     * @warning If you provide a relative path, be very careful that it's read relative to the currently-working
     * directory!
     */
    virtual void Open(
        std::filesystem::path&& filePath,
        const BmnBinaryFileProcessingOptions processingFlags = BmnBinaryFileProcessingOptions::ReadBinary);
 
    /*
     * A method that closes an open file stream and clears/removes all buffers.
     * This method should be used before reopening a file.
     */
    virtual void Close() noexcept = 0;
 
    /*
     * A method that extracts a requested number of bytes and puts them into the provided array
     * @param dataPointer A buffer for inserting new data
     * @param numberOfBytesToRead A number of bytes that should be copied into the provided buffer
     * @return The number of bytes that have actually been copied. If less than `numberOfBytesToRead`, it means we've
     * hit EOF or an error
     */
    virtual int64_t Read(void* dataPointer, int64_t numberOfBytesToRead) = 0;
 
    /*
     * @return A next byte ID that's to be read
     */
    [[nodiscard]] virtual int64_t Tell() const noexcept = 0;
 
    /*
     * Move the file reading ID to another position
     * @param aNewReadingPosition A next position to read
     * @warning If compressed files are used, this might still read and uncomress the data. The method might not have
     * high performance
     */
    virtual void Seek(int64_t aNewReadingPosition) = 0;
 
    /*
     * @return 'true' if no error has been detected while processing an input stream, otherwise 'false'
     */
    [[nodiscard]] virtual bool IsGood() const noexcept = 0;
 
    /*
     * @return 'true' if we have reached EOF, otherwise 'false'
     */
    [[nodiscard]] virtual bool IsEOF() const noexcept = 0;
 
    /*
     * A method that clears bad flags after an error has occurred. Just calling this error will most likely
     * not solve the problem, and you will get an error again in the next read. That is, before calling `Read`,
     * remove the previous error source
     */
    virtual void ClearStateFlags() = 0;
    /*
     * @return 'true' if the input file is open, otherwise 'false'
     */
    [[nodiscard]] virtual bool IsOpen() const noexcept = 0;
 
  public:
    // inline methods
 
    // This will set the path only if the file is NOT already open!
    inline void SetFilePath(const std::string& fileName);
    // This will set the path only if the file is NOT already open!
    inline void SetFilePath(std::string&& fileName) noexcept;
    // This will set the path only if the file is NOT already open!
    inline void SetFilePath(const std::filesystem::path& filePath);
    // This will set the path only if the file is NOT already open!
    inline void SetFilePath(std::filesystem::path&& filePath) noexcept;
    [[nodiscard]] inline std::filesystem::path& GetFilePath() noexcept;
    [[nodiscard]] inline const std::filesystem::path& GetFilePath() const noexcept;
    // @warning This method may throw - e.g., permission denied
    [[nodiscard]] inline int64_t GetInputFileSize() const;
 
    // Setting flags, i.e., old flags are lost!
    inline void SetProcessingFlags(const BmnBinaryFileProcessingOptions) noexcept;
    // Adding new flags, i.e., old flags are preserved!
    inline void AddProcessingFlags(const BmnBinaryFileProcessingOptions) noexcept;
    // Remove specific flags if they are valid
    inline void RemoveProcessingFlags(const BmnBinaryFileProcessingOptions) noexcept;
    // Get current processing flags
    [[nodiscard]] inline BmnBinaryFileProcessingOptions GetProcessingFlags() const noexcept;
 
    [[nodiscard]] inline BmnFileType GetFileType() const noexcept;
 
  protected:
    /*
     * Check the path and input flags that are always necessary for opening a file.
     * @param processingFlags Flags that are passed into an open function
     * @return 'true' if all conditions are satisfied, 'false' otherwise
     */
    [[nodiscard]] bool PerformStandardChecksBeforeOpening(const BmnBinaryFileProcessingOptions processingFlags);
 
  protected:
    // after opening a file, we don't need this path at all, but still, keeping it here for sanity and debugging reasons
    std::filesystem::path fFilePath;
    // Flags are settable before the file is opened
    BmnBinaryFileProcessingOptions fProcessingFlags;
    // The underlying type that's managing reading - we don't need this one here, but we will have 4 padding bytes
    // anyway so....
    BmnFileType fFileType;
    // 3 padding bytes
};
 
// o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o
// ================== BmnIFileReader inline methods ==================
// o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o
 
void BmnIFileReader::SetFilePath(const std::string& fileName)
{
    if (IsOpen()) {
        LOG(error) << "You may not change file name of BmnIFileReader when it's already open!\n";
        return;
    }
    fFilePath = fileName;
}
 
void BmnIFileReader::SetFilePath(std::string&& fileName) noexcept
{
    if (IsOpen()) {
        LOG(error) << "You may not change file name of BmnIFileReader when it's already open!\n";
        return;
    }
    fFilePath = std::move(fileName);
}
 
void BmnIFileReader::SetFilePath(const std::filesystem::path& filePath)
{
    if (IsOpen()) {
        LOG(error) << "You may not change file path of BmnIFileReader when it's already open!\n";
        return;
    }
    fFilePath = filePath;
}
 
void BmnIFileReader::SetFilePath(std::filesystem::path&& filePath) noexcept
{
    if (IsOpen()) {
        LOG(error) << "You may not change file path of BmnIFileReader when it's already open!\n";
        return;
    }
    fFilePath = std::move(filePath);
}
 
std::filesystem::path& BmnIFileReader::GetFilePath() noexcept
{
    return fFilePath;
}
 
const std::filesystem::path& BmnIFileReader::GetFilePath() const noexcept
{
    return fFilePath;
}
 
int64_t BmnIFileReader::GetInputFileSize() const
{
    if (fFilePath.empty())
        return 0ll;
    return std::filesystem::file_size(fFilePath);
}
 
void BmnIFileReader::SetProcessingFlags(const BmnBinaryFileProcessingOptions newFlags) noexcept
{
    if (IsOpen()) {
        LOG(error) << "You may not modify flags of BmnIFileReader when a file is already open!\n";
        return;
    }
    fProcessingFlags = newFlags;
}
 
void BmnIFileReader::AddProcessingFlags(const BmnBinaryFileProcessingOptions newFlags) noexcept
{
    if (IsOpen()) {
        LOG(error) << "You may not modify flags of BmnIFileReader when a file is already open!\n";
        return;
    }
    fProcessingFlags |= newFlags;
}
 
void BmnIFileReader::RemoveProcessingFlags(const BmnBinaryFileProcessingOptions badFlags) noexcept
{
    if (IsOpen()) {
        LOG(error) << "You may not modify flags of BmnIFileReader when a file is already open!\n";
        return;
    }
    fProcessingFlags &= (~badFlags);
}
 
BmnBinaryFileProcessingOptions BmnIFileReader::GetProcessingFlags() const noexcept
{
    return fProcessingFlags;
}
 
BmnFileType BmnIFileReader::GetFileType() const noexcept
{
    return fFileType;
}
 
#endif   // BmnIFileReader_h