FLM Document: flm.flmdocument

FLM document classes for multi-fragment rendering.

A FLMDocument collects multiple FLM fragments and renders them together, enabling cross-references, consistent numbering, footnote collection, and other features that require a global document context.

The rendering pipeline works as follows:

1. The document creates a FLMDocumentRenderContext with the active features and fragment renderer.

2. The user-provided render callback is called, which renders fragments within the render context.

3. Feature render managers process the first-pass output.

4. Delayed-render nodes (e.g., \\ref) are resolved.

5. The final output is produced by replacing delayed markers or by performing a second rendering pass.

The FLMDocumentRenderContext class

class flm.flmdocument.FLMDocumentRenderContext(doc, fragment_renderer, feature_document_managers, **kwargs)

Bases: FLMRenderContext

A render context created for document-mode rendering. Extends FLMRenderContext with support for feature managers and delayed rendering.

supports_feature(feature_name)

Check whether a feature is active in this render context.

Parameters:

feature_name – The unique string identifier of the feature.

Returns:

True if a render manager (possibly None) was created for feature_name, False otherwise.

feature_render_manager(feature_name)

Return the render manager for the given feature.

Parameters:

feature_name – The unique string identifier of the feature.

Returns:

The FeatureRenderManagerBase instance for feature_name, or None if the feature has no render manager.

Raises:

KeyError – If feature_name is not a supported feature.

register_delayed_render(node, fragment_renderer)

Register a node for delayed rendering.

The node is stored by its internal node ID so that its content can be rendered after the first pass, once the full document structure is known (e.g., for resolving \ref targets).

Parameters:

• node – The parsed node to register. Must have a _flm_node_id attribute.

• fragment_renderer – The active fragment renderer (currently unused but kept for API consistency with the base class).

Returns:

The node’s ID key, used internally to store and later retrieve the rendered content.

get_delayed_render_content(node)

Retrieve the rendered content for a previously registered delayed-render node.

This should be called after the document’s render() method has completed the delayed rendering phase.

Parameters:

node – The node whose delayed content is requested.

Returns:

The rendered content string for the node.

Raises:

KeyError – If the node was not registered or its delayed content has not yet been rendered.

make_standalone_fragment(flm_text, **kwargs)

Create a standalone-mode fragment within the document context.

This is a convenience method that calls make_fragment() with standalone_mode=True on the document’s environment.

Parameters:

• flm_text – The FLM source text to parse.

• kwargs – Additional keyword arguments forwarded to make_fragment().

Returns:

A FLMFragment in standalone mode.

The FLMDocument class

class flm.flmdocument.FLMDocument(render_callback, environment, enable_features=None, feature_document_options=None, metadata=None)

An FLM document that collects fragments for rendering together.

Usually you should create documents via make_document() rather than constructing this class directly.

Parameters:

• render_callback – A callable render_callback(render_context) that composes the output by calling render() on each fragment. Must return the composed output (string, dict, or list).

• environment – The FLMEnvironment instance.

• enable_features – An optional list of feature names to enable (subset of the environment’s features). None means all.

• feature_document_options – A dictionary mapping feature names to dictionaries of options passed to each feature’s DocumentManager.initialize().

• metadata – Arbitrary user-defined metadata (e.g., document title).

initialize()

Initialize all feature document managers.

Calls initialize(**feature_options) on each feature’s FeatureDocumentManagerBase, passing the corresponding options from feature_document_options (supplied at construction time). Must be called before render().

supports_feature(feature_name)

Check whether a feature is enabled in this document.

Parameters:

feature_name – The unique string identifier of the feature.

Returns:

True if feature_name has a document manager entry (possibly None), False otherwise.

feature_document_manager(feature_name)

Return the document manager for the given feature.

Parameters:

feature_name – The unique string identifier of the feature.

Returns:

The FeatureDocumentManagerBase instance, or None if the feature has no document manager.

Raises:

KeyError – If feature_name is not enabled in this document.

make_render_context(fragment_renderer, feature_render_options=None)

Create and initialize a FLMDocumentRenderContext.

Instantiates the render context with all feature document managers, then initializes each feature’s render manager with its options.

Parameters:

• fragment_renderer – The FragmentRenderer to use.

• feature_render_options – Optional dictionary mapping feature names to dictionaries of options passed to each feature’s RenderManager.initialize().

Returns:

A fully initialized FLMDocumentRenderContext.

render(fragment_renderer, feature_render_options=None)

Render the document and return the result.

This method performs the full rendering pipeline:

1. Creates a render context with feature render managers.

2. Calls the render callback (first pass).

3. Lets feature render managers process the first-pass output.

4. Renders delayed-render nodes (e.g., \ref).

5. Produces the final output by replacing delayed markers (or by performing a second pass if the fragment renderer does not support delayed render markers).

6. Calls feature render managers’ postprocess() methods.

Parameters:

• fragment_renderer – A FragmentRenderer instance (e.g., HtmlFragmentRenderer).

• feature_render_options – An optional dictionary mapping feature names to dictionaries of options passed to each feature’s RenderManager.initialize().

Returns:

A tuple (result, render_context) where result is the rendered output (string, dict, or list) and render_context is the FLMDocumentRenderContext used for rendering.