satteri-plugin-api 0.1.1

Rust plugin trait, typed visitors, and runner for Sätteri
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

use crate::context::PluginContext;
use crate::typed_nodes::*;
use satteri_arena::Arena;
use satteri_ast::mdast::MdastNodeType;

/// Metadata about a plugin.
#[derive(Debug, Clone)]
pub struct PluginMeta {
    pub name: &'static str,
    pub version: Option<&'static str>,
    pub description: Option<&'static str>,
}

impl PluginMeta {
    pub fn new(name: &'static str) -> Self {
        Self {
            name,
            version: None,
            description: None,
        }
    }
}

/// The result of a visitor method: either no change, or a replacement.
pub enum VisitResult {
    /// No structural change (plugin may have written to data_map via ctx)
    NoChange,
    /// Replace this node with a new one
    Replace(crate::commands::NewNode),
    /// Remove this node
    Remove,
}

impl VisitResult {
    pub fn no_change() -> Self {
        Self::NoChange
    }
    pub fn replace(node: crate::commands::NewNode) -> Self {
        Self::Replace(node)
    }
    pub fn remove() -> Self {
        Self::Remove
    }
}

/// The Rust plugin trait.
///
/// Implement only the visitor methods you need. Default implementations
/// return NoChange (no-op) so unimplemented visitors have zero overhead.
pub trait Plugin: Send + Sync {
    fn meta(&self) -> PluginMeta;

    /// Called once before any files are processed.
    fn init(&mut self) {}

    /// Called before each file.
    fn before(&mut self, _arena: &Arena, _ctx: &mut PluginContext) {}

    /// Called after each file.
    fn after(&mut self, _arena: &Arena, _ctx: &mut PluginContext) {}

    fn visit_heading(&mut self, _node: &Heading, _ctx: &mut PluginContext) -> VisitResult {
        VisitResult::NoChange
    }
    fn visit_paragraph(&mut self, _node: &Paragraph, _ctx: &mut PluginContext) -> VisitResult {
        VisitResult::NoChange
    }
    fn visit_text(&mut self, _node: &Text, _ctx: &mut PluginContext) -> VisitResult {
        VisitResult::NoChange
    }
    fn visit_link(&mut self, _node: &Link, _ctx: &mut PluginContext) -> VisitResult {
        VisitResult::NoChange
    }
    fn visit_image(&mut self, _node: &Image, _ctx: &mut PluginContext) -> VisitResult {
        VisitResult::NoChange
    }
    fn visit_code(&mut self, _node: &Code, _ctx: &mut PluginContext) -> VisitResult {
        VisitResult::NoChange
    }
    fn visit_list(&mut self, _node: &NodeView, _ctx: &mut PluginContext) -> VisitResult {
        VisitResult::NoChange
    }
    fn visit_list_item(&mut self, _node: &NodeView, _ctx: &mut PluginContext) -> VisitResult {
        VisitResult::NoChange
    }
    fn visit_blockquote(&mut self, _node: &NodeView, _ctx: &mut PluginContext) -> VisitResult {
        VisitResult::NoChange
    }
    fn visit_emphasis(&mut self, _node: &NodeView, _ctx: &mut PluginContext) -> VisitResult {
        VisitResult::NoChange
    }
    fn visit_strong(&mut self, _node: &NodeView, _ctx: &mut PluginContext) -> VisitResult {
        VisitResult::NoChange
    }
    fn visit_inline_code(&mut self, _node: &Text, _ctx: &mut PluginContext) -> VisitResult {
        VisitResult::NoChange
    }
    fn visit_html(&mut self, _node: &Text, _ctx: &mut PluginContext) -> VisitResult {
        VisitResult::NoChange
    }
    fn visit_table(&mut self, _node: &NodeView, _ctx: &mut PluginContext) -> VisitResult {
        VisitResult::NoChange
    }

    /// Optional: full arena access for wholesale rewrites. Return None to leave unchanged.
    fn transform_root(&mut self, _arena: &Arena, _ctx: &mut PluginContext) -> Option<Arena> {
        None
    }
}

/// A generic node view for nodes that don't have type-specific fields.
pub struct NodeView<'a> {
    pub(crate) node_id: u32,
    pub(crate) arena: &'a Arena,
}

impl<'a> NodeView<'a> {
    pub fn id(&self) -> u32 {
        self.node_id
    }
    pub fn children(&self) -> &[u32] {
        self.arena.get_children(self.node_id)
    }
    pub fn position(&self) -> NodePosition {
        NodePosition::from_node(self.arena.get_node(self.node_id))
    }
    pub fn node_type(&self) -> MdastNodeType {
        let raw = self.arena.get_node(self.node_id).node_type;
        MdastNodeType::from_u8(raw).unwrap_or(MdastNodeType::Root)
    }
}