dot.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: MIT
#ifndef FSM_DOT_HPP
#define FSM_DOT_HPP
 
#include "fsm/fsm.hpp"
 
static_assert(FSM_ENABLE_INTROSPECTION,
              "fsm: dot export requires FSM_ENABLE_INTROSPECTION");
 
namespace fsm {
 
template <class Traits, class W>
void write_dot(W&& write) {
    using M = machine<Traits>;
    using State = typename Traits::State;
    detail::line_buf lb;
 
    write("digraph fsm {");
    write("  rankdir=LR;");
    write("  compound=true;");
    write("  node [shape=box, style=rounded];");
    write("  any [shape=point, xlabel=\"any\"];");
    write("  refused [shape=octagon, style=solid];");
 
    // States: composites as clusters containing their (transitive) children's
    // leaf nodes; leaves as plain nodes. One nesting level of cluster per
    // composite, emitted depth-first.
    constexpr auto& specs = Traits::states;
    // Emit clusters for roots first; nested composites are emitted within.
    struct Emitter {
        W& w;
        detail::line_buf& lb;
        void emit_state(State s, int indent) {
            if (detail::is_composite(Traits::states, s)) {
                line(indent);
                lb.str("subgraph cluster_");
                M::put_state_name(lb, s);
                lb.str(" {");
                w(lb.b);
                line(indent + 1);
                lb.str("label=\"");
                M::put_state_name(lb, s);
                lb.str("\";");
                w(lb.b);
                for (size_t i = 0; i < M::state_count; ++i) {
                    const auto& sp = Traits::states[i];
                    if (sp.parent.k == parent_kind::child && sp.parent.s == s)
                        emit_state(sp.state.s, indent + 1);
                }
                line(indent);
                lb.str("}");
                w(lb.b);
            } else {
                line(indent);
                M::put_state_name(lb, s);
                lb.str(";");
                w(lb.b);
            }
        }
        void line(int indent) {
            lb.reset();
            for (int i = 0; i < indent; ++i) lb.str("  ");
        }
    } em{write, lb};
 
    for (size_t i = 0; i < M::state_count; ++i) {
        const auto& sp = specs[i];
        if (sp.parent.k != parent_kind::child) em.emit_state(sp.state.s, 1);
    }
 
    // Edge endpoints: Graphviz cannot attach an edge to a cluster by name (an
    // unknown name would silently create a phantom node), so edges touching a
    // composite anchor at its initial-descent leaf and clip at the cluster
    // border via ltail/lhead (hence compound=true above).
    auto endpoint = [&lb](State s) {
        M::put_state_name(lb, detail::leaf_of(Traits::states, s));
    };
    auto cluster_attr = [&lb](const char* attr, State s) {
        lb.str(", ");
        lb.str(attr);
        lb.str("=cluster_");
        M::put_state_name(lb, s);
    };
 
    // Transition rows.
    for (size_t i = 0; i < M::row_count; ++i) {
        const auto& r = Traits::rows[i];
        const bool from_comp =
            r.from.k == from_kind::state && detail::is_composite(specs, r.from.s);
        bool to_comp = false;
        lb.reset();
        lb.str("  ");
        if (r.from.k == from_kind::any) lb.str("any");
        else endpoint(r.from.s);
        lb.str(" -> ");
        switch (r.to.k) {
            case target_kind::to:
                to_comp = detail::is_composite(specs, r.to.s);
                endpoint(r.to.s);
                break;
            case target_kind::internal_:
                to_comp = from_comp;  // self-annotation mirrors the source
                if (r.from.k == from_kind::any) lb.str("any");
                else endpoint(r.from.s);
                break;
            case target_kind::refuse_:
            default:
                lb.str("refused");
                break;
        }
        lb.str(" [label=\"");
        M::put_event_name(lb, r.on.e);
        if (r.when != nullptr) lb.str(" [guard]");
        if (r.then != nullptr) lb.str(" /action");
        if (r.to.k == target_kind::refuse_) {
            lb.str(" refuse(");
            M::put_reason_name(lb, r.to.r);
            lb.str(")");
        }
        if (r.label != nullptr) {
            lb.str("\\n");  // graphviz newline inside the edge label
            lb.str(r.label);
        }
        lb.str("\"");
        if (r.to.k == target_kind::internal_) lb.str(", style=dotted");
        if (from_comp) cluster_attr("ltail", r.from.s);
        if (to_comp)
            cluster_attr("lhead", r.to.k == target_kind::to ? r.to.s : r.from.s);
        lb.str("]");
        lb.str(";");
        write(lb.b);
    }
 
    // Timeout annotations: dashed self-edges labelled with duration + event.
    for (size_t i = 0; i < M::state_count; ++i) {
        const auto& sp = specs[i];
        if (sp.deadline.k != timeout_kind::after_ &&
            sp.deadline.k != timeout_kind::after_dyn_)
            continue;
        const bool comp = detail::is_composite(specs, sp.state.s);
        lb.reset();
        lb.str("  ");
        endpoint(sp.state.s);
        lb.str(" -> ");
        endpoint(sp.state.s);
        lb.str(" [style=dashed, label=\"after ");
        if (sp.deadline.k == timeout_kind::after_dyn_) {
            lb.str("dyn: ");
        } else {
            lb.u64(sp.deadline.ms);
            lb.str("ms: ");
        }
        M::put_event_name(lb, sp.deadline.event);
        lb.str("\"");
        if (comp) {
            cluster_attr("ltail", sp.state.s);
            cluster_attr("lhead", sp.state.s);
        }
        lb.str("];");
        write(lb.b);
    }
 
    write("}");
}
 
}  // namespace fsm
 
#endif  // FSM_DOT_HPP