Skip to main content

instruction_md/
lines.rs

1//! What each source line of a document is, for editors that colour or fold Markdown source, and for the formatter.
2//! Every class comes from the reader's own tree — its metadata ranges, its directives' opening and closing lines, its
3//! rules, reasons and alerts, its comments — so an editor cannot show a line as a rule that the reader reads as prose.
4//! Only inside a Markdown node does a line's own text decide (a heading, a code fence).
5
6use std::sync::LazyLock;
7
8use crate::js::js_trim;
9use crate::pattern::Pattern;
10use crate::read::{RX, ReadOptions, Reading, read};
11use crate::text::literal;
12use crate::types::{Form, Node};
13
14/// A line's class: front-matter, backmatter, code, comment, heading, directive, alert, keyword, reason, data (a
15/// structured body), literal (a body quoted as written) or prose.
16#[derive(Clone, Debug, Default, PartialEq, Eq)]
17pub struct LineInfo {
18    pub class: &'static str,
19    /// On keyword and reason lines: the byte offset where the label (`- **MUST[id] (if …):**`, `BECAUSE:`) ends.
20    pub label_end: usize,
21    /// On keyword and alert lines: the keyword as written (MUST NOT, AVOID, TIP).
22    pub keyword: String,
23    /// On directive lines: the kind they open, close or are.
24    pub kind: String,
25}
26
27impl LineInfo {
28    fn class(class: &'static str) -> LineInfo {
29        LineInfo { class, ..LineInfo::default() }
30    }
31}
32
33struct Rx {
34    label_lead: Pattern,
35    label: Pattern,
36    reason: Pattern,
37    fence_start: Pattern,
38}
39
40static LRX: LazyLock<Rx> = LazyLock::new(|| {
41    let kw = crate::registry::keyword_names();
42    let sp = crate::js::JS_SPACES;
43    Rx {
44        label_lead: Pattern::must(r"^(?:[ \t]*>[ \t]?)*[ \t]*(?:(?:[-*+]|[0-9]{1,9}[.)])[ \t]+)?"),
45        label: Pattern::must(&format!(r"^(?:\*\*)?(?:{kw})(?:\[[^\]{sp}]*\])?(?: \(if [^()\r\n]*\))?:(?:\*\*)?")),
46        reason: Pattern::must(r"^(?:\*\*)?BECAUSE:(?:\*\*)?"),
47        fence_start: Pattern::must(r"^(?:[ \t]*>)*[ \t]*(`{3,}|~{3,})"),
48    }
49});
50
51/// One entry per line of the document read (as [`read`] splits it).
52pub fn classify_lines(r: &Reading) -> Vec<LineInfo> {
53    let mut out = vec![LineInfo::class("prose"); r.lines.len()];
54    for &n in &r.comments {
55        set(&mut out, n, LineInfo::class("comment"));
56    }
57    if let Some(fr) = r.front_range {
58        span(&mut out, fr.start, fr.end, "front-matter");
59    }
60    if let Some(br) = r.back_range {
61        span(&mut out, br.start, br.end, "backmatter");
62    }
63    walk(r, &r.document.body, &mut out);
64    out
65}
66
67fn set(out: &mut [LineInfo], n: u32, info: LineInfo) {
68    if n >= 1 && (n as usize) <= out.len() {
69        out[n as usize - 1] = info;
70    }
71}
72
73fn span(out: &mut [LineInfo], from: u32, to: u32, class: &'static str) {
74    for n in from..=to {
75        set(out, n, LineInfo::class(class));
76    }
77}
78
79fn line_at(r: &Reading, n: u32) -> &str {
80    if n >= 1 && (n as usize) <= r.lines.len() { &r.lines[n as usize - 1] } else { "" }
81}
82
83fn reason(r: &Reading, node: &Node, out: &mut [LineInfo]) {
84    let Some(at) = node.reason else { return };
85    set(out, at.start, LineInfo { label_end: label_end(line_at(r, at.start), &LRX.reason), ..LineInfo::class("reason") });
86    if at.end > at.start {
87        span(out, at.start + 1, at.end, "prose");
88    }
89}
90
91fn walk(r: &Reading, nodes: &[Node], out: &mut [LineInfo]) {
92    for node in nodes {
93        let Some(rg) = node.range else { continue };
94        if node.is_markdown() {
95            classify_markdown(r, rg.start, rg.end, out);
96            continue;
97        }
98        if matches!(node.form, Some(Form::Keyword | Form::Alert)) {
99            walk(r, node.children(), out);
100            let keyword = node.keyword.clone().unwrap_or_default();
101            if node.form == Some(Form::Alert) {
102                set(out, rg.start, LineInfo { keyword, ..LineInfo::class("alert") });
103            } else {
104                set(
105                    out,
106                    rg.start,
107                    LineInfo { label_end: label_end(line_at(r, rg.start), &LRX.label), keyword, ..LineInfo::class("keyword") },
108                );
109            }
110            reason(r, node, out);
111            continue;
112        }
113        // a container or a leaf: its fences, then what lies between them
114        let mut last = rg.start;
115        if node.form == Some(Form::Container) && rg.end > rg.start && RX.close.is_match(line_at(r, rg.end)) {
116            last = rg.end;
117        }
118        if node.form == Some(Form::Container) {
119            if node.value.is_some() {
120                if last > rg.start + 1 {
121                    span(out, rg.start + 1, last - 1, "data");
122                }
123            } else if literal(node) {
124                if last > rg.start + 1 {
125                    span(out, rg.start + 1, last - 1, "literal");
126                }
127            } else {
128                walk(r, node.children(), out);
129            }
130            reason(r, node, out);
131        }
132        set(out, rg.start, LineInfo { kind: node.kind.clone(), ..LineInfo::class("directive") });
133        if last != rg.start {
134            set(out, last, LineInfo { kind: node.kind.clone(), ..LineInfo::class("directive") });
135        }
136    }
137}
138
139/// Classes a Markdown node's lines: code fences and what they hold, ATX headings, the rest prose (comments kept).
140fn classify_markdown(r: &Reading, from: u32, to: u32, out: &mut [LineInfo]) {
141    let mut open = String::new();
142    let mut n = from;
143    while n <= to && (n as usize) <= out.len() {
144        let line = &r.lines[n as usize - 1];
145        let f = LRX.fence_start.captures(line);
146        let i = n as usize - 1;
147        n += 1;
148        if !open.is_empty() {
149            out[i] = LineInfo::class("code");
150            if let Some(f) = &f {
151                let run = f.get(line, 1).unwrap_or("");
152                let whole = f.get(line, 0).unwrap_or("");
153                if run.as_bytes()[0] == open.as_bytes()[0] && run.len() >= open.len() && js_trim(line) == js_trim(whole) {
154                    open.clear();
155                }
156            }
157            continue;
158        }
159        if let Some(f) = &f {
160            open = f.get(line, 1).unwrap_or("```").to_string();
161            out[i] = LineInfo::class("code");
162            continue;
163        }
164        if out[i].class == "comment" {
165            continue;
166        }
167        if RX.heading.is_match(line) {
168            out[i] = LineInfo::class("heading");
169        }
170    }
171}
172
173fn label_end(line: &str, label: &Pattern) -> usize {
174    let lead = LRX.label_lead.find_str(line).unwrap_or("");
175    lead.len() + label.find_str(&line[lead.len()..]).map_or(0, str::len)
176}
177
178/// The conservative formatter: what an editor may change without changing what a reader or an agent receives — LF
179/// line endings, one final newline, and no trailing whitespace on a directive's own lines (an opener, a closer, a
180/// leaf), which the text profile regenerates rather than copies. Prose, code, structured bodies and metadata are left
181/// as written: a trailing space in Markdown can be a line break, and a YAML edit can change a value.
182pub fn format(text: &str) -> String {
183    let bom = if text.starts_with('\u{feff}') { "\u{feff}" } else { "" };
184    let r = read(text, &ReadOptions::default());
185    let classes = classify_lines(&r);
186    let lines: Vec<&str> = r
187        .lines
188        .iter()
189        .enumerate()
190        .map(|(i, l)| if classes[i].class == "directive" { l.trim_end_matches([' ', '\t']) } else { l.as_str() })
191        .collect();
192    let joined = lines.join("\n");
193    let body = joined.trim_end_matches('\n');
194    if body.is_empty() {
195        return bom.to_string();
196    }
197    format!("{bom}{body}\n")
198}