mermaid.hpp

Go to the documentation of this file.

// sbl/dsp/diagram/mermaid.hpp — Render a Graph as a Mermaid flowchart (AP-037)
//
// Host-only: uses snprintf. Depth::Full draws every node the components
// described — the paper's figure. Depth::Components folds each nested group
// into one box and keeps the edges between boxes, one per pair.
//
// Usage:
//   char text[8192];
//   sbl::dsp::diagram::render_mermaid(graph, text, sizeof(text), Depth::Full);
 
#ifndef SBL_DSP_DIAGRAM_MERMAID_HPP_
#define SBL_DSP_DIAGRAM_MERMAID_HPP_
 
#include <cstddef>
#include <cstdint>
#include <cstdio>
 
#include <sbl/dsp/diagram/graph.hpp>
 
namespace sbl::dsp::diagram {
 
enum class Depth : uint8_t {
    Full,         ///< every node, as the components described them
    Components,   ///< nested groups folded to one box each
};
 
namespace detail {
 
struct Out {
    char* buf;
    size_t cap;
    size_t pos = 0;
 
    // The format string is a literal at every call site but arrives through
    // a template parameter pack, which -Wformat-security cannot see through.
    template<typename... Args>
    void line(const char* fmt, Args... args) {
        if (pos >= cap) return;
#if defined(__GNUC__)
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wformat-security"
#endif
        const int n = snprintf(buf + pos, cap - pos, fmt, args...);
#if defined(__GNUC__)
#pragma GCC diagnostic pop
#endif
        if (n < 0) return;
        pos += static_cast<size_t>(n) < cap - pos ? static_cast<size_t>(n) : cap - pos - 1;
        if (pos < cap - 1) buf[pos++] = '\n';
        buf[pos] = '\0';
    }
};
 
/// Label with the paper symbol and the cheap live parameter.
inline void node_label(const Node& n, char* out, size_t cap) {
    switch (n.kind) {
        case Kind::DelayLine:  snprintf(out, cap, "%s<br/>z^-%.1f", n.name, static_cast<double>(n.value)); break;
        case Kind::Loss:       snprintf(out, cap, "%s<br/>LP %.0f Hz", n.name, static_cast<double>(n.value)); break;
        case Kind::Allpass:    snprintf(out, cap, "%s<br/>AP %.2f", n.name, static_cast<double>(n.value)); break;
        case Kind::DcBlock:    snprintf(out, cap, "%s<br/>HP %.0f Hz", n.name, static_cast<double>(n.value)); break;
        case Kind::Reflection: snprintf(out, cap, "%s<br/>r = %+.2g", n.name, static_cast<double>(n.value)); break;
        case Kind::Load:
        case Kind::Resonator:  snprintf(out, cap, "%s<br/>%.0f Hz, Q %.1f", n.name, static_cast<double>(n.value), static_cast<double>(n.value2)); break;
        case Kind::Bandpass:   snprintf(out, cap, "%s<br/>BP %.0f Hz, Q %.1f", n.name, static_cast<double>(n.value), static_cast<double>(n.value2)); break;
        case Kind::Gain:       snprintf(out, cap, "%s<br/>× %.2f", n.name, static_cast<double>(n.value)); break;
        default:               snprintf(out, cap, "%s", n.name); break;
    }
}
 
/// Shape by kind: the reader should tell a delay from a filter at a glance.
inline void node_decl(const Node& n, uint8_t id, char* out, size_t cap) {
    char label[96];
    node_label(n, label, sizeof(label));
    switch (n.kind) {
        case Kind::DelayLine:  snprintf(out, cap, "n%u[\"%s\"]", id, label); break;
        case Kind::Loss:
        case Kind::Allpass:
        case Kind::DcBlock:    snprintf(out, cap, "n%u(\"%s\")", id, label); break;
        case Kind::Reflection: snprintf(out, cap, "n%u{{\"%s\"}}", id, label); break;
        case Kind::Junction:   snprintf(out, cap, "n%u((\"%s\"))", id, label); break;
        case Kind::Source:     snprintf(out, cap, "n%u>\"%s\"]", id, label); break;
        case Kind::Load:
        case Kind::Resonator:  snprintf(out, cap, "n%u[(\"%s\")]", id, label); break;
        case Kind::Bandpass:
        case Kind::Gain:       snprintf(out, cap, "n%u(\"%s\")", id, label); break;
        case Kind::Sum:        snprintf(out, cap, "n%u((\"%s\"))", id, label); break;
        case Kind::Tap:        snprintf(out, cap, "n%u[/\"%s\"/]", id, label); break;
        case Kind::Component:  snprintf(out, cap, "n%u[[\"%s\"]]", id, label); break;
    }
}
 
inline const char* wave_name(Wave w) {
    switch (w) {
        case Wave::Velocity: return "v";
        case Wave::Force:    return "F";
        case Wave::Signal:   return "";
    }
    return "";
}
 
inline void edge_decl(uint8_t from, uint8_t to, Wave w, char* out, size_t cap) {
    const char* label = wave_name(w);
    if (label[0]) snprintf(out, cap, "n%u -->|%s| n%u", from, label, to);
    else          snprintf(out, cap, "n%u --> n%u", from, to);
}
 
/// The group a node renders in at Components depth: nested groups fold to their id.
inline uint8_t fold_target(const Graph& g, uint8_t group) {
    // A group with a parent folds; a top-level group stays a subgraph.
    return (group != NO_GROUP && g.group(group).parent != NO_GROUP) ? group : NO_GROUP;
}
 
inline void emit_group(const Graph& g, uint8_t gid, Depth depth, Out& o, int indent) {
    const char* pad = indent ? "    " : "";
    o.line("%ssubgraph g%u[\"%s\"]", pad, gid, g.group(gid).name);
    // Child groups
    for (uint8_t c = 0; c < g.group_count(); ++c) {
        if (g.group(c).parent != gid) continue;
        if (depth == Depth::Components) {
            o.line("%s    n%u[[\"%s\"]]", pad, 200 + c, g.group(c).name);
        } else {
            emit_group(g, c, depth, o, indent + 1);
        }
    }
    // Own nodes
    for (uint8_t i = 0; i < g.node_count(); ++i) {
        if (g.node(i).group != gid) continue;
        char decl[160];
        node_decl(g.node(i), i, decl, sizeof(decl));
        o.line("%s    %s", pad, decl);
    }
    o.line("%send", pad);
}
 
} // namespace detail
 
/**
 * @brief Render the graph as a Mermaid flowchart into a buffer
 * @return characters written (excluding the terminator)
 */
inline size_t render_mermaid(const Graph& g, char* buf, size_t cap, Depth depth = Depth::Full) {
    if (cap == 0) return 0;
    detail::Out o{buf, cap};
    buf[0] = '\0';
    o.line("flowchart LR");
 
    for (uint8_t gid = 0; gid < g.group_count(); ++gid) {
        if (g.group(gid).parent == NO_GROUP) detail::emit_group(g, gid, depth, o, 0);
    }
    // Ungrouped nodes
    for (uint8_t i = 0; i < g.node_count(); ++i) {
        if (g.node(i).group != NO_GROUP) continue;
        char decl[160];
        detail::node_decl(g.node(i), i, decl, sizeof(decl));
        o.line("    %s", decl);
    }
 
    // Edges. At Components depth an edge whose end sits in a folded group is
    // redirected to that group's box, and duplicates between boxes dropped.
    uint8_t seen_from[Graph::MAX_EDGES];
    uint8_t seen_to[Graph::MAX_EDGES];
    uint8_t seen = 0;
    for (uint8_t i = 0; i < g.edge_count(); ++i) {
        const Edge& e = g.edge(i);
        uint8_t from = e.from, to = e.to;
        if (depth == Depth::Components) {
            const uint8_t gf = detail::fold_target(g, g.node(e.from).group);
            const uint8_t gt = detail::fold_target(g, g.node(e.to).group);
            if (gf != NO_GROUP) from = static_cast<uint8_t>(200 + gf);
            if (gt != NO_GROUP) to = static_cast<uint8_t>(200 + gt);
            if (from == to) continue;   // internal to a folded box
            bool dup = false;
            for (uint8_t k = 0; k < seen; ++k) {
                if (seen_from[k] == from && seen_to[k] == to) { dup = true; break; }
            }
            if (dup) continue;
            if (seen < Graph::MAX_EDGES) { seen_from[seen] = from; seen_to[seen] = to; ++seen; }
        }
        char decl[64];
        detail::edge_decl(from, to, e.wave, decl, sizeof(decl));
        o.line("    %s", decl);
    }
    return o.pos;
}
 
} // namespace sbl::dsp::diagram
 
#endif // SBL_DSP_DIAGRAM_MERMAID_HPP_