API — ICoreEssentials/Diagnostics

The public contract of 3 header(s) under src/ICoreEssentials/Diagnostics — 3 class/struct definition(s), 38 declaration(s). Each section shows the header's banner and its public (and protected-virtual) surface exactly as the file writes it.

ICoreIODevice.h#

src/ICoreEssentials/Diagnostics/ICoreIODevice.h

ICoreIODevice#

ICoreIODevice.h:44 · class · nested OpenMode · 9 declaration(s)

ICoreIODevice -- something bytes can be read from and written to.

class ICoreIODevice {
public:
    enum OpenModeFlag {
        NotOpen   = 0x0000,
        ReadOnly  = 0x0001,
        WriteOnly = 0x0002,
        ReadWrite = ReadOnly | WriteOnly,
        Append    = 0x0004,
        Truncate  = 0x0008,
        Text      = 0x0010,
    };

    class OpenMode {
    public:
        constexpr OpenMode() : m_v(0) {}
        constexpr OpenMode(OpenModeFlag f) : m_v(static_cast<int>(f)) {}
        constexpr OpenMode operator|(OpenMode o) const { return OpenMode(m_v | o.m_v); }
        constexpr OpenMode& operator|=(OpenMode o) { m_v |= o.m_v; return *this; }
        constexpr bool testFlag(OpenModeFlag f) const {
            return (m_v & static_cast<int>(f)) == static_cast<int>(f);
        }
        constexpr int toInt() const { return m_v; }

    private:
        constexpr explicit OpenMode(int v) : m_v(v) {}
        int m_v;
    };

    virtual ~ICoreIODevice() = default;

    virtual bool         open(OpenMode mode) = 0;
    virtual void         close() = 0;
    virtual bool         isOpen() const = 0;
    virtual std::int64_t write(const ICoreByteArray& data) = 0;
    virtual std::int64_t write(const char* data, std::int64_t length) = 0;
    virtual ICoreByteArray readAll() = 0;
    virtual bool         flush() = 0;
    virtual ICoreString  errorString() const = 0;
};
};

ICoreLog.h#

src/ICoreEssentials/Diagnostics/ICoreLog.h

ICoreLog#

ICoreLog.h:63 · class · nested Stream, Sink · 5 declaration(s)

ICoreLog -- a line of developer diagnostics.

class ICoreLog {
public:
    class Stream {
    public:
        ~Stream();

        Stream(const Stream&) = delete;
        Stream& operator=(const Stream&) = delete;

        // Quoting off for the rest of the line, as QDebug::noquote() is.
        Stream& noquote();

        Stream& operator<<(const ICoreString& value);
        Stream& operator<<(const ICoreLatin1String& value);
        Stream& operator<<(ICoreLatin1Char value);

        // NOT quoted, matching QDebug -- see the header note.
        Stream& operator<<(const char* value);
        Stream& operator<<(const std::string& value);

        Stream& operator<<(char value);
        Stream& operator<<(bool value);
        Stream& operator<<(int value);
        Stream& operator<<(long value);
        Stream& operator<<(long long value);
        Stream& operator<<(unsigned value);
        Stream& operator<<(unsigned long value);
        Stream& operator<<(unsigned long long value);

        // Six significant digits, as QDebug's default is.
        Stream& operator<<(double value);
        Stream& operator<<(float value);

        Stream& operator<<(const ICorePoint& value);

        // Any other pointer, as an address. A TEMPLATE so that an exact
        // pointer match beats the bool overload -- `<< somePointer` would
        // otherwise be ambiguous between pointer-to-bool and pointer-to-void*,
        // both of which are the same conversion rank.
        template <typename T>
        Stream& operator<<(T* value) {
            char buffer[32];
            std::snprintf(buffer, sizeof(buffer), "0x%llx",
                          static_cast<unsigned long long>(reinterpret_cast<std::uintptr_t>(value)));
            // The public `const char*` overload, NOT this template again --
            // see the header note on the cast.
            return *this << static_cast<const char*>(buffer);
        }

    private:
        friend class ICoreLog;

        Stream();

        class Impl;
        std::unique_ptr<Impl> impl;
    };

    static Stream debug();
    static Stream warning();

    // ------------------------------------------------------------------
    // Error reporting with an installable destination (ESSENTIALS_INDEPENDENCE
    // D1). Essentials code reports errors here and knows nothing about where
    // they go. The application installs the real destination at startup
    // (Initialization.cpp forwards to ICoreLogger and the notification
    // center); with no sink installed both calls print to stderr, which is
    // the correct standalone-SDK behavior.
    //
    // error()            -- a developer-facing diagnostic line.
    // userVisibleError() -- an error the end user should also see surfaced
    //                       (the sink decides how; the app raises a
    //                       notification).
    //
    // installSink() is startup wiring, before any UI exists -- it is not
    // synchronized against concurrent logging.
    // ------------------------------------------------------------------
    struct Sink {
        std::function<void(const std::string& text)> error;
        std::function<void(const std::string& title, const std::string& message)> userVisibleError;
    };

    static void error(const std::string& text);
    static void userVisibleError(const std::string& title, const std::string& message);
    static void installSink(Sink sink);
};
};

ICoreTextStream.h#

src/ICoreEssentials/Diagnostics/ICoreTextStream.h

ICoreTextStream#

ICoreTextStream.h:59 · class · pImpl · 24 declaration(s)

ICoreTextStream -- text out of, or into, a device or a console.

class ICoreTextStream {
public:
    enum StandardStream { StdOut, StdErr };

    explicit ICoreTextStream(ICoreIODevice* device);
    explicit ICoreTextStream(ICoreIODevice& device);
    explicit ICoreTextStream(StandardStream which);

    ICoreTextStream(const ICoreTextStream&) = delete;
    ICoreTextStream& operator=(const ICoreTextStream&) = delete;

    ~ICoreTextStream();

    // --- writing ------------------------------------------------------------

    ICoreTextStream& operator<<(const ICoreString& value);
    ICoreTextStream& operator<<(const ICoreLatin1String& value);
    ICoreTextStream& operator<<(ICoreLatin1Char value);
    ICoreTextStream& operator<<(const char* value);
    ICoreTextStream& operator<<(char value);
    ICoreTextStream& operator<<(int value);
    ICoreTextStream& operator<<(long value);
    ICoreTextStream& operator<<(long long value);
    ICoreTextStream& operator<<(unsigned value);
    ICoreTextStream& operator<<(unsigned long long value);

    // Six significant digits, matching QTextStream's default precision.
    ICoreTextStream& operator<<(double value);
    ICoreTextStream& operator<<(float value);

    // The manipulator seam. See the Qt::endl note above.
    ICoreTextStream& operator<<(ICoreTextStream& (*manipulator)(ICoreTextStream&));

    static ICoreTextStream& endl(ICoreTextStream& stream);

    // --- reading ------------------------------------------------------------

    ICoreString readAll();

    // Without the newline, as QTextStream::readLine is.
    ICoreString readLine();

    [[nodiscard]] bool atEnd() const;

    void flush();

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};