Struct Engine 

pub struct Engine { /* private fields */ }

Headless Mermaid parser engine.

An engine owns detector/parser registries and a site-level Mermaid configuration. It is cheap to clone when callers need per-request option variants.

Implementations

impl Engine

pub fn new() -> Self

Creates an engine using the pinned Mermaid baseline registries and default site config.

pub fn try_native() -> Result<Self, RuntimePolicyError>

Creates an engine backed by all native system adapters.

pub fn with_fixed_today(self, today: Option<CivilDate>) -> Self

Overrides the “today” value used by diagrams that depend on local time (e.g. Gantt).

This exists primarily to make fixture snapshots deterministic. The default runtime policy uses the Unix epoch; native callers must explicitly select Engine::try_native.

pub fn try_with_fixed_local_offset_minutes( self, offset_minutes: i32, ) -> Result<Self, RuntimePolicyError>

Selects a fixed local UTC offset for diagrams with local-time semantics.

pub fn with_local_time_zone(self, time_zone: LocalTimeZone) -> Self

Installs an already-resolved local timezone without consulting ambient process state.

pub fn with_runtime_policy(self, policy: RuntimePolicy) -> Self

Replaces the complete runtime policy used to begin future operations.

pub fn with_operation_context(self, context: OperationContext) -> Self

Replays a previously frozen runtime context without consulting system state.

pub fn runtime_policy(&self) -> &RuntimePolicy

pub fn begin_operation(&self) -> Result<OperationContext, RuntimePolicyError>

pub fn fixed_local_offset_minutes(&self) -> Option<i32>

Returns the fixed local timezone offset configured for this engine.

pub fn local_time_zone(&self) -> &LocalTimeZone

pub fn with_site_config(self, site_config: MermaidConfig) -> Self

Applies site-level Mermaid config defaults.

pub fn with_exact_site_config(self, site_config: Option<MermaidConfig>) -> Self

Replaces the complete site-config environment while preserving custom registries.

None restores the pinned Mermaid defaults. An explicit config is merged onto those defaults without inheriting values from the engine’s previous site config.

pub fn registry(&self) -> &DetectorRegistry

Returns the detector registry used for automatic diagram type detection.

pub fn registry_mut(&mut self) -> &mut DetectorRegistry

Returns a mutable detector registry for custom diagram detection.

pub fn diagram_registry(&self) -> &DiagramRegistry

Returns the semantic JSON parser registry.

pub fn diagram_registry_mut(&mut self) -> &mut DiagramRegistry

Returns a mutable semantic JSON parser registry for custom diagram adapters.

pub fn render_diagram_registry(&self) -> &RenderDiagramRegistry

Returns the typed render-model parser registry.

pub fn render_diagram_registry_mut(&mut self) -> &mut RenderDiagramRegistry

Returns a mutable typed render-model parser registry.

pub fn parse_metadata_sync(&self, text: &str) -> Result<ParseMetadata>

Synchronous variant of Engine::parse_metadata.

This is useful for UI render pipelines that are synchronous (e.g. immediate-mode UI), where introducing an async executor would be awkward. The parsing work is CPU-bound and does not perform I/O.

pub fn parse_metadata_with_type_sync( &self, diagram_type: &str, text: &str, ) -> Result<ParseMetadata>

Parses metadata for an already-known diagram type (skips type detection).

This is intended for integrations that already know the diagram type, e.g. Markdown fences like ````mermaid/ flowchart` / ` sequenceDiagram`.

Example (Markdown fence)

use merman_core::Engine;

let engine = Engine::new();

// Your markdown parser provides the fence info string (e.g. "flowchart", "sequenceDiagram").
let fence = "sequenceDiagram";
let diagram = r#"sequenceDiagram
  Alice->>Bob: Hello
"#;

// Map fence info strings to merman's internal diagram ids.
let diagram_type = match fence {
    "sequenceDiagram" => "sequence",
    "flowchart" | "graph" => "flowchart-v2",
    "stateDiagram" | "stateDiagram-v2" => "stateDiagram",
    other => other,
};

let meta = engine
    .parse_metadata_with_type_sync(diagram_type, diagram)?;

pub fn parse_editor_semantic_facts_with_type_sync( &self, diagram_type: &str, text: &str, ) -> Result<Option<EditorSemanticFacts>>

Parses editor-facing semantic facts when a family has a parser-backed implementation.

Returned spans are byte offsets in the text supplied to this method.

pub async fn parse_metadata(&self, text: &str) -> Result<ParseMetadata>

Async facade for Engine::parse_metadata_sync.

The work is CPU-bound and executes synchronously; this method exists for callers that prefer an async-shaped API.

pub async fn parse_metadata_with_type( &self, diagram_type: &str, text: &str, ) -> Result<ParseMetadata>

Async facade for Engine::parse_metadata_with_type_sync.

The work is CPU-bound and executes synchronously.

pub fn parse_diagram_sync( &self, text: &str, options: ParseOptions, ) -> Result<Option<ParsedDiagram>>

Synchronous variant of Engine::parse_diagram.

Note: callers that want “always returns a diagram” behavior can set ParseOptions::suppress_errors to true to get an error diagram on parse failures.

pub fn parse_diagram_snapshot_sync( &self, text: &str, ) -> Result<Option<DiagramParseSnapshot>>

Captures semantic JSON or its original error, parser-owned typed warning facts, and parser-backed editor facts in one operation.

This is intended for editor integrations that need both diagnostics/facts and the Mermaid-compatible model. Once preprocessing and detection succeed, family parse errors and panics are retained inside the snapshot alongside metadata and recovery facts. Successful snapshots expose warnings through the warning_facts field of DiagramParseOutcome::Parsed; consumers should not decode the compatibility model’s warningFacts field. Consumers must project a retained failure state directly rather than parsing the source again. Error suppression is deliberately absent from this API; suppression remains limited to model-producing JSON and render facades.

pub fn parse_diagram_snapshot_controlled_sync( &self, text: &str, control: &OperationControl, ) -> OperationControlResult<Result<Option<DiagramParseSnapshot>>>

Captures an editor-facing parse operation with cooperative cancellation.

Cancellation is returned through the outer OperationControlResult and is never converted into a Mermaid parse error, failed snapshot, or recovery diagnostic.

pub fn capture_diagram_snapshot_controlled_sync( &self, text: &str, control: &OperationControl, ) -> OperationControlResult<DiagramSnapshotCapture>

Captures an editor parse operation while retaining preprocessing source-configuration evidence on non-cancellation failures and on panics after preprocessing completes. Cooperative cancellation remains the outer error channel and never yields a partial capture.

pub fn parse_diagram_snapshot_with_type_sync( &self, diagram_type: &str, text: &str, ) -> Result<Option<DiagramParseSnapshot>>

Captures one editor-facing parse operation when the diagram type is already known.

This has the same closed snapshot contract, including parser-owned typed warning facts, as Engine::parse_diagram_snapshot_sync, but skips automatic detection. Family parse failures and panics remain inside the returned snapshot.

pub async fn parse_diagram( &self, text: &str, options: ParseOptions, ) -> Result<Option<ParsedDiagram>>

Async facade for Engine::parse_diagram_sync.

The work is CPU-bound and executes synchronously.

pub fn parse_diagram_for_render_model_sync( &self, text: &str, options: ParseOptions, ) -> Result<Option<ParsedDiagramRender>>

Parses a diagram into a typed semantic model optimized for headless layout + SVG rendering.

Unlike Engine::parse_diagram_sync, this avoids constructing large serde_json::Value object trees for high-impact typed-first diagrams and instead returns typed semantic structs that the renderer can consume directly.

Callers that need the semantic JSON model should continue using Engine::parse_diagram_sync.

pub fn parse_diagram_for_render_model_controlled_sync( &self, text: &str, options: ParseOptions, operation: &OperationControl, ) -> OperationControlResult<Result<Option<ParsedDiagramRender>>>

Controlled variant of Self::parse_diagram_for_render_model_sync.

The caller owns the cloneable operation control and may cancel it from another thread or task. Cancellation is returned through the outer result and is never folded into a parse error or a partial render model.

pub async fn parse_diagram_for_render_model( &self, text: &str, options: ParseOptions, ) -> Result<Option<ParsedDiagramRender>>

Async facade for Engine::parse_diagram_for_render_model_sync.

The work is CPU-bound and executes synchronously.

pub fn parse_diagram_for_render_model_with_type_sync( &self, diagram_type: &str, text: &str, options: ParseOptions, ) -> Result<Option<ParsedDiagramRender>>

Parses a diagram into a typed semantic render model when the diagram type is already known (skips type detection).

This is the preferred entrypoint for Markdown renderers and editors that already know the diagram type from the code fence info string. It avoids the detection pass and can reduce a small fixed overhead in tight render loops.

pub fn parse_diagram_for_render_model_with_type_controlled_sync( &self, diagram_type: &str, text: &str, options: ParseOptions, operation: &OperationControl, ) -> OperationControlResult<Result<Option<ParsedDiagramRender>>>

Controlled known-type variant of Self::parse_diagram_for_render_model_with_type_sync.

pub async fn parse_diagram_for_render_model_with_type( &self, diagram_type: &str, text: &str, options: ParseOptions, ) -> Result<Option<ParsedDiagramRender>>

Async facade for Engine::parse_diagram_for_render_model_with_type_sync.

The work is CPU-bound and executes synchronously.

pub fn parse_diagram_with_type_sync( &self, diagram_type: &str, text: &str, options: ParseOptions, ) -> Result<Option<ParsedDiagram>>

Parses a diagram when the diagram type is already known (skips type detection).

This is the preferred entrypoint for Markdown renderers and editors that already know the diagram type from the code fence info string. It avoids the detection pass and can reduce a small fixed overhead in tight render loops.

Example

use merman_core::{Engine, ParseOptions};

let engine = Engine::new();
let input = "flowchart TD; A-->B;";

let parsed = engine
    .parse_diagram_with_type_sync("flowchart-v2", input, ParseOptions::strict())?
    .expect("diagram detected");

assert_eq!(parsed.meta.diagram_type, "flowchart-v2");

pub async fn parse_diagram_with_type( &self, diagram_type: &str, text: &str, options: ParseOptions, ) -> Result<Option<ParsedDiagram>>

Async facade for Engine::parse_diagram_with_type_sync.

The work is CPU-bound and executes synchronously.

Trait Implementations

impl Clone for Engine

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Engine

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Engine

fn default() -> Self

Returns the “default value” for a type.