The pipeline extensions of one run, and the generators and transforms they add.

Synopsis

Declared in <mrdocs/Extensions/ExtensionRegistry.hpp>

class ExtensionRegistry;

Description

A pipeline extension is an entry of an addon root's extensions/ directory: a .lua or .js script, or a native shared library, either as a file directly in extensions/ or as the entry file of a directory of its own. Running a script's top level (once, at loadExtensions) registers two kinds of things: corpus transforms (mrdocs.register_transform) and output generators (mrdocs.register_generator). A native extension installs the same two kinds of things through its entry point (see mrdocs/Plugin.hpp).

Extensions are optional and live entirely outside the Corpus a corpus is just extracted symbols. An application that has no extensions never needs to load any; it adds the generators and transforms it wants in its own code. An application that wants to honor a configuration's extensions loads them here and runs them as steps in its own workflow.

The registry owns a GeneratorRegistry, which it exposes as generators. The generators of the run are in that registry whatever defined them, and the extensions add theirs to it as they load; the registry itself does not look generators up for anyone. It owns one pipeline of Transform objects, whatever their origin. loadExtensions adds the transforms of every extension, the native ones through the interface of a plugin and the scripts through mrdocs.register_transform. applyTransforms runs the pipeline in the order the transforms were added. Extensions load in a stable order, and that order is not something a transform may rely on.

The registry also owns the scripting engines and the registered functions, so it must outlive both applyTransforms and any generator it hands out. Destroying the registry closes the engines, and a script may have kept the corpus it was handed, so a corpus given to applyTransforms must outlive the registry: declare the corpus before the registry.

The native libraries a process loads are recorded in a LibraryRegistry, which a registry holds through a shared_ptr. A registry constructed alone has one of its own. A program that runs more than once in a process, such as a test runner, constructs one LibraryRegistry and passes it to every registry, so that each library is loaded and its entry point run once.

Typical workflow, after a corpus is built:

// The corpus is declared before the registry, so it is destroyed after
Corpus corpus = ...;
ExtensionRegistry ext;
MRDOCS_TRY(ext.loadExtensions(config, reporter));
MRDOCS_TRY(ext.applyTransforms(corpus, config, reporter));
Generator const* generator = ext.generators().find(id);

An application that runs once can write ExtensionRegistry::load(config, reporter) instead of the ExtensionRegistry and loadExtensions lines. A program that wants the generators the addons define as data too, and the order the tool uses, constructs a Session instead.

Types

Name

Description

LibraryRegistry

The record of the native libraries a process has loaded.

Member Functions

Name

Description

ExtensionRegistry [constructor]

Constructors

~ExtensionRegistry [destructor]

Destructor.

operator=

Move assignment.

applyTransforms

Apply the pipeline of transforms to a corpus.

generators

Return the generators of this registry.

installTransform

Append a transform to the pipeline.

loadExtensions

Discover and load the extensions declared by a configuration.

Static Member Functions

Name

Description

load

Create a registry holding the extensions of a configuration.

Created with MrDocs