API — ICoreEssentials/System

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

ICoreCommandLine.h#

src/ICoreEssentials/System/ICoreCommandLine.h

ICoreCommandLineOption#

ICoreCommandLine.h:57 · class · pImpl · 6 declaration(s)

ICoreCommandLineOption / ICoreCommandLine -- switches off the command line.

class ICoreCommandLineOption {
public:
    // `valueName` empty means this is a FLAG -- it takes no value and isSet()
    // is the only thing worth asking about it. That is how Qt distinguishes the
    // two as well, and how --tools is declared at the one call site.
    //
    // The defaults stay on the DECLARATION and are not repeated in the .cpp --
    // repeating them is an error, and the diagnostic points at the .cpp.
    ICoreCommandLineOption(const ICoreString& name,
                           const ICoreString& description,
                           const ICoreString& valueName    = ICoreString(),
                           const ICoreString& defaultValue = ICoreString());

    ~ICoreCommandLineOption();

    // An option is a small value and WAS implicitly copyable; a unique_ptr
    // member deletes that, so the four are written out in the .cpp rather than
    // silently narrowing the contract (H2.11, recipe trap 2). Nothing in the
    // tree copies one today -- this keeps it so that nothing has to stop.
    ICoreCommandLineOption(const ICoreCommandLineOption& other);
    ICoreCommandLineOption& operator=(const ICoreCommandLineOption& other);
    ICoreCommandLineOption(ICoreCommandLineOption&& other) noexcept;
    ICoreCommandLineOption& operator=(ICoreCommandLineOption&& other) noexcept;

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

ICoreCommandLine#

ICoreCommandLine.h:93 · class · pImpl · 12 declaration(s)

class ICoreCommandLine {
public:
    ICoreCommandLine();
    ~ICoreCommandLine();

    // Was implicitly copyable, and stays so -- see the option's note.
    ICoreCommandLine(const ICoreCommandLine& other);
    ICoreCommandLine& operator=(const ICoreCommandLine& other);
    ICoreCommandLine(ICoreCommandLine&& other) noexcept;
    ICoreCommandLine& operator=(ICoreCommandLine&& other) noexcept;

    void setApplicationDescription(const ICoreString& description);

    void addHelpOption();

    // Adding a nameless or duplicate option is a programming error at startup,
    // not a user error, so it is loud and fatal rather than a return value
    // nobody checks -- as B12's assert was.
    void addOption(const ICoreCommandLineOption& option);

    // Parses, and may end the program -- see the header note. argc/argv come
    // straight from main(); argv[0] is the program name and is skipped.
    void process(int argc, char** argv);

    [[nodiscard]] ICoreString value(const ICoreCommandLineOption& option) const;

    [[nodiscard]] bool isSet(const ICoreCommandLineOption& option) const;

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

ICoreLibrary.h#

src/ICoreEssentials/System/ICoreLibrary.h

ICoreLibrary -- a dynamically loaded shared library and the symbols in it.

QT-FREE (phase 3). dlopen/dlsym/dlclose, and LoadLibrary/GetProcAddress on Windows; <QLibrary> is gone from this header and from the umbrella.

⚠ THIS IS THE FIRST .cpp IN ICoreEssentials, AND THAT WAS THE WHOLE BLOCKER.

This wrapper looked trivial for months and was not. dlopen is twenty lines, but Windows needs <windows.h>, and this layer was HEADER-ONLY with its umbrella force-included into ~2,600 translation units. Putting <windows.h> there would have dragged the Win32 API -- and its macros, min/max and friends -- into every file in the project. So the row was blocked on an architectural decision rather than on difficulty, and it stayed blocked.

ICoreLibrary#

ICoreLibrary.h:68 · class · pImpl · 10 declaration(s)

class ICoreLibrary {
public:
    using FunctionPointer = void (*)();

    ICoreLibrary();
    ~ICoreLibrary();

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

    // Names the image to load. Does not touch the filesystem -- load() does.
    // Setting a new name while loaded unloads the old image first, per QLibrary.
    void setFileName(const ICoreString& fileName);

    // Map the image. False if it is missing, unreadable, or built for another
    // architecture -- errorString() says which.
    bool load();

    // Drop this handle. The OS keeps the image mapped while another handle on
    // it is still open, which is dlclose's own reference counting.
    bool unload();

    [[nodiscard]] bool isLoaded() const;

    // Address of an exported symbol, or nullptr if the image does not export it.
    // Loads the image on demand if it is not already, as QLibrary::resolve does.
    [[nodiscard]] FunctionPointer resolve(const char* symbol);

    // Why the last load/unload/resolve failed. Only meaningful after one of
    // them has returned a failure.
    [[nodiscard]] ICoreString errorString() const;

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