MRDOCS_PLUGIN_MAIN

Define the entry point of a plugin.

Synopsis

Declared in <mrdocs/Plugin.hpp>

#define MRDOCS_PLUGIN_MAIN(plugin)

Description

Use it once per plugin library, in exactly one translation unit, at namespace scope. It is the only thing a plugin has to define. A plugin may instead define the three extern "C" functions itself, in C++, with the signatures mrdocs::PluginBuildIdFn, mrdocs::PluginStdlibTagFn and mrdocs::PluginMainFn, each exported with MRDOCS_PLUGIN_EXPORT.

The macro defines mrdocs_plugin_build_id and mrdocs_plugin_stdlib_tag, which return MRDOCS_PLUGIN_BUILD_ID and MRDOCS_PLUGIN_STDLIB_TAG as the plugin's compiler saw them, and mrdocs_plugin_main, which calls the body that follows the macro. The body has the signature static mrdocs::Expected<void> installMrdocsPlugin(mrdocs::PluginContext& plugin), with plugin named by the macro argument.

The parameter is a mrdocs::PluginContext. Through it the body reads config() and calls registerGenerator and registerTransform. The reference is valid during the call only.

The body returns {} on success. To refuse, it returns mrdocs::Unexpected(mrdocs::formatError(...)), which stops the run with the plugin "<name>" failed: <message>. MRDOCS_TRY works in the body, because the error of a failed registration is returned the same way. The entry point runs once per mrdocs::ExtensionRegistry::LibraryRegistry, before the corpus is built. The tool has one per process, and a program that runs more than once shares one among its sessions. Work that depends on the run belongs in mrdocs::Transform::apply or mrdocs::Generator::build.

The body must not keep the context reference or a pointer to the configuration. It must not throw either: the macro does not catch exceptions, and the Expected the body returns is the only channel, so turn failures into an mrdocs::Error.

MRDOCS_PLUGIN_MAIN(plugin)
{
    return plugin.registerGenerator(std::make_unique<MyGenerator>());
}

Register a transform and a generator. A registration that fails, such as an id that is already taken, refuses the plugin with its message:

MRDOCS_PLUGIN_MAIN(plugin)
{
    mrdocs::Expected<void> added = plugin.registerTransform(
        std::make_unique<MyTransform>());
    if (!added)
    {
        return added;
    }
    added = plugin.registerGenerator(std::make_unique<MyGenerator>());
    if (!added)
    {
        return added;
    }
    return {};
}

Parameters

Name

Description

plugin

The name the body uses for the context it receives.

Created with MrDocs