mrdocs::Session

Everything one run of MrDocs owns.

Synopsis

Declared in <mrdocs/Session.hpp>

class Session;

Description

A session is made from the configuration of a run with create and destroyed when the run ends. It owns that configuration, returned by config. A session that exists has loaded its extensions. It owns the ExtensionRegistry, which in turn owns the GeneratorRegistry. The generators, the transform pipeline and the scripting engines of the run live and die together, and nothing refers to them from outside. The session owns and forwards. The documentation of each piece says what it does.

One run owns one session. The only piece that sessions may share is the ExtensionRegistry::LibraryRegistry. A shared library cannot be unloaded and the entry point of a plugin must not run twice, so a program that runs more than once in a process, such as a test runner, constructs one and passes it to each create. A session created alone has one of its own.

The session also owns the report::Reporter of the run, returned by log. It starts from log-level and warn-as-error. The transforms and generators the session runs report through it, and so does a corpus built with it, so two sessions never share a level or a total.

A corpus given to applyTransforms must outlive the session, because a script may keep the corpus it was handed. So the corpus is declared before the session and destroyed after it.

A session can be moved. The references that log, generators and extensions returned stay valid.


Config config = ...;
// The corpus is declared before the session, so it is destroyed after
std::optional<Corpus> corpus;
MRDOCS_TRY(Session session, Session::create(std::move(config)));
MRDOCS_TRY(Corpus built, Corpus::build(session.config(), session.log()));
corpus.emplace(std::move(built));
MRDOCS_TRY(session.applyTransforms(*corpus));
Generator const* generator = session.generators().find(id);
MRDOCS_TRY(session.build(*generator, *corpus));

Member Functions

NameDescription
Session [constructor]Move constructor.
~Session [destructor]Destructor.
operator= Move assignment.
applyTransforms Apply the pipeline of transforms to a corpus.
build Build the documentation of a corpus with a generator.
config Return the configuration of the run.
extensions Return the extension registry of the run.
generators Return the generators of the run.
log Return the reporter of the run.

Static Member Functions

NameDescription
create Make the session of a run.