Skip to main content

decl_lang/
yaml.rs

1//! YAML for documents (docs/tooling/05_render.md §2, §4): a reader of
2//! YAML 1.2 with the core schema into the JSON data model — the values
3//! `read_json` produces, so that a document written in YAML is
4//! indistinguishable from the same document written in JSON from the
5//! reader on — and a writer of the block-style form that every YAML 1.2
6//! reader (and no YAML 1.1 reader) reads back as the canonical JSON
7//! document. Beside them, the JSON layouts of §4.1. The reader accepts
8//! exactly what the document says and refuses the rest with the reason
9//! and the line, so that the three implementations refuse the same texts
10//! with the same words. A port of the reference's yaml.ts.
11use crate::engine::fmt_f;
12use crate::semantics::{json_str, Num, Value};
13use num_bigint::BigInt;
14use regex::Regex;
15use std::collections::{HashMap, HashSet};
16use std::rc::Rc;
17use std::sync::LazyLock;
18
19/// a document the reader refuses: `<reason> at line L`
20#[derive(Debug, Clone, PartialEq)]
21pub struct YamlError {
22    /// what was refused
23    pub reason: String,
24    /// the line it was found on (from 1)
25    pub line: usize,
26}
27impl YamlError {
28    /// `<reason> at line L`
29    pub fn message(&self) -> String {
30        format!("{} at line {}", self.reason, self.line)
31    }
32}
33impl std::fmt::Display for YamlError {
34    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
35        write!(f, "{}", self.message())
36    }
37}
38type YR<T> = Result<T, YamlError>;
39
40/// a document path names YAML by its extension (§2); anything else is JSON
41pub fn is_yaml_path(p: &str) -> bool {
42    let lower = p.to_ascii_lowercase();
43    lower.ends_with(".yaml") || lower.ends_with(".yml")
44}
45
46// ---------------- the core schema (§2): what a plain scalar means ----------------
47// null, bool, int (decimal, octal, hexadecimal), float — everything else
48// is a string. YAML 1.1's spellings (yes/no/on/off, sexagesimals,
49// timestamps, `1_000`) are strings.
50static RE_INT: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"^[-+]?[0-9]+$").unwrap());
51static RE_OCT: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"^0o[0-7]+$").unwrap());
52static RE_HEX: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"^0x[0-9a-fA-F]+$").unwrap());
53static RE_FLOAT: LazyLock<Regex> =
54    LazyLock::new(|| Regex::new(r"^[-+]?(\.[0-9]+|[0-9]+(\.[0-9]*)?)([eE][-+]?[0-9]+)?$").unwrap());
55static RE_NONFINITE: LazyLock<Regex> =
56    LazyLock::new(|| Regex::new(r"^([-+]?\.(inf|Inf|INF)|\.(nan|NaN|NAN))$").unwrap());
57
58/// what a plain scalar resolves to under the core schema
59#[derive(Debug, Clone, PartialEq)]
60pub enum Plain {
61    /// `null`, `~`, empty
62    Null,
63    /// a bool
64    Bool(bool),
65    /// an integer
66    Int(BigInt),
67    /// a float
68    Float(f64),
69    /// `.inf` / `.nan`: refused
70    NonFinite,
71    /// everything else
72    Str(String),
73}
74/// the core schema's reading of a plain scalar
75pub fn resolve_plain(s: &str) -> Plain {
76    if s.is_empty() || s == "~" || s == "null" || s == "Null" || s == "NULL" {
77        return Plain::Null;
78    }
79    if s == "true" || s == "True" || s == "TRUE" {
80        return Plain::Bool(true);
81    }
82    if s == "false" || s == "False" || s == "FALSE" {
83        return Plain::Bool(false);
84    }
85    if RE_INT.is_match(s) {
86        let digits = s.strip_prefix('+').unwrap_or(s);
87        return Plain::Int(digits.parse::<BigInt>().expect("an integer"));
88    }
89    if RE_OCT.is_match(s) {
90        return Plain::Int(BigInt::parse_bytes(&s.as_bytes()[2..], 8).expect("octal"));
91    }
92    if RE_HEX.is_match(s) {
93        return Plain::Int(BigInt::parse_bytes(&s.as_bytes()[2..], 16).expect("hex"));
94    }
95    if RE_FLOAT.is_match(s) {
96        return Plain::Float(parse_float(s));
97    }
98    if RE_NONFINITE.is_match(s) {
99        return Plain::NonFinite;
100    }
101    Plain::Str(s.to_string())
102}
103// the core schema's float forms (`1.`, `.5`, `+1e3`) are all Rust's
104fn parse_float(s: &str) -> f64 {
105    s.parse::<f64>().expect("a float")
106}
107fn plain_value(p: Plain) -> Value {
108    match p {
109        Plain::Null => Value::Null,
110        Plain::Bool(b) => Value::Bool(b),
111        Plain::Int(i) => Value::Int(Num::from(i)),
112        Plain::Float(f) => Value::Float(f),
113        Plain::Str(s) => Value::Str(s.into()),
114        Plain::NonFinite => Value::Null,
115    }
116}
117
118// ---------------- the reader ----------------
119const fn is_space(c: Option<char>) -> bool {
120    matches!(c, Some(' ') | Some('\t'))
121}
122const fn is_break_or_end(c: Option<char>) -> bool {
123    matches!(c, None | Some('\n'))
124}
125fn is_flow_end(c: Option<char>) -> bool {
126    matches!(c, Some(',') | Some('[') | Some(']') | Some('{') | Some('}'))
127}
128#[derive(Clone, Copy, PartialEq)]
129enum Where {
130    Seq,
131    Map,
132    None,
133}
134
135struct Reader {
136    s: Vec<char>,
137    i: usize,
138    anchors: HashMap<String, Value>,
139}
140
141impl Reader {
142    fn new(src: &str) -> Reader {
143        let text = src.strip_prefix('\u{feff}').unwrap_or(src);
144        let text = text.replace("\r\n", "\n").replace('\r', "\n");
145        Reader {
146            s: text.chars().collect(),
147            i: 0,
148            anchors: HashMap::new(),
149        }
150    }
151    // ---- positions ----
152    fn line(&self, at: usize) -> usize {
153        1 + self.s[..at.min(self.s.len())]
154            .iter()
155            .filter(|&&c| c == '\n')
156            .count()
157    }
158    fn err(&self, reason: &str, at: usize) -> YamlError {
159        YamlError {
160            reason: reason.to_string(),
161            line: self.line(at),
162        }
163    }
164    fn fail<T>(&self, reason: &str) -> YR<T> {
165        Err(self.err(reason, self.i))
166    }
167    fn fail_at<T>(&self, reason: &str, at: usize) -> YR<T> {
168        Err(self.err(reason, at))
169    }
170    fn at(&self, k: usize) -> Option<char> {
171        self.s.get(k).copied()
172    }
173    fn peek(&self) -> Option<char> {
174        self.at(self.i)
175    }
176    fn peek1(&self) -> Option<char> {
177        self.at(self.i + 1)
178    }
179    fn at_end_of(&self, k: usize) -> bool {
180        is_break_or_end(self.at(k))
181    }
182    fn at_end(&self) -> bool {
183        self.at_end_of(self.i)
184    }
185    fn line_start(&self, mut k: usize) -> usize {
186        while k > 0 && self.s[k - 1] != '\n' {
187            k -= 1;
188        }
189        k
190    }
191    fn col(&self) -> usize {
192        self.i - self.line_start(self.i)
193    }
194    /// the indentation of the line holding k: its leading spaces (a tab there is refused)
195    fn indent_of(&self, k: usize) -> YR<usize> {
196        let mut j = self.line_start(k);
197        let mut n = 0;
198        while self.at(j) == Some(' ') {
199            j += 1;
200            n += 1;
201        }
202        if self.at(j) == Some('\t') {
203            return self.fail_at("tab in indentation", j);
204        }
205        Ok(n)
206    }
207    /// skip spaces and a comment on the current line; stays before its break
208    fn skip_inline(&mut self) {
209        while is_space(self.peek()) {
210            self.i += 1;
211        }
212        if self.peek() == Some('#') {
213            while !self.at_end() {
214                self.i += 1;
215            }
216        }
217    }
218    /// the rest of the current line must be empty (a comment allowed)
219    fn end_line(&mut self, what: &str) -> YR<()> {
220        self.skip_inline();
221        if !self.at_end() {
222            return self.fail(&format!("unexpected content after {what}"));
223        }
224        Ok(())
225    }
226    /// advance over line breaks, blank lines, and comment lines to the next
227    /// content character, and return its column; None at the end. Idempotent:
228    /// at a content character with only indentation before it, stays.
229    fn next_content(&mut self) -> YR<Option<usize>> {
230        loop {
231            match self.peek() {
232                None => return Ok(None),
233                Some('\n') => {
234                    self.i += 1;
235                    continue;
236                }
237                _ => {}
238            }
239            let start = self.line_start(self.i);
240            let mut j = start;
241            while self.at(j) == Some(' ') {
242                j += 1;
243            }
244            if j < self.i {
245                // mid-line: the caller left content behind — it belongs to no node
246                return self.fail("unexpected content");
247            }
248            if self.at(j) == Some('\t') {
249                return self.fail_at("tab in indentation", j);
250            }
251            self.i = j;
252            match self.peek() {
253                None => return Ok(None),
254                Some('\n') => continue,
255                Some('#') => {
256                    while !self.at_end() {
257                        self.i += 1;
258                    }
259                    continue;
260                }
261                _ => return Ok(Some(j - start)),
262            }
263        }
264    }
265    /// is a `-`, `?`, or `:` at k an indicator (followed by a space or the line's end)?
266    fn indicator_at(&self, k: usize) -> bool {
267        is_space(self.at(k + 1)) || is_break_or_end(self.at(k + 1))
268    }
269    /// a document marker (`---` or `...`) at column 0 ends every node
270    fn at_marker(&self) -> bool {
271        self.line_is("---") || self.line_is("...")
272    }
273    fn line_is(&self, text: &str) -> bool {
274        let n = text.chars().count();
275        self.col() == 0
276            && self.i + n <= self.s.len()
277            && self.s[self.i..self.i + n].iter().collect::<String>() == text
278            && self.indicator_at(self.i + n - 1)
279    }
280    fn dash_here(&self) -> bool {
281        self.peek() == Some('-') && self.indicator_at(self.i)
282    }
283
284    // ---- the stream ----
285    fn document(&mut self) -> YR<Value> {
286        // directives and the start marker
287        loop {
288            if self.peek() == Some('%') && self.col() == 0 {
289                let mut end = self.i;
290                while !self.at_end_of(end) {
291                    end += 1;
292                }
293                let text: String = self.s[self.i..end].iter().collect();
294                static RE_YAML12: LazyLock<Regex> =
295                    LazyLock::new(|| Regex::new(r"^%YAML[ \t]+1\.2[ \t]*(#.*)?$").unwrap());
296                if RE_YAML12.is_match(&text) {
297                    self.i = end;
298                    continue;
299                }
300                if text.starts_with("%TAG") {
301                    return self.fail("uses a tag");
302                }
303                if text.starts_with("%YAML") {
304                    return self.fail("unsupported YAML version");
305                }
306                let word = text.split([' ', '\t']).next().unwrap_or("");
307                return self.fail(&format!("unsupported directive {word}"));
308            }
309            let Some(n) = self.next_content()? else {
310                return Ok(Value::Null);
311            };
312            if self.peek() == Some('%') && n == 0 {
313                continue;
314            }
315            break;
316        }
317        let mut value = None;
318        if self.line_is("---") {
319            self.i += 3;
320            self.skip_inline();
321            if !self.at_end() {
322                value = Some(self.node(-1, Where::Seq, -1)?);
323            }
324        } else if self.line_is("...") {
325            return self.fail("unexpected end marker");
326        }
327        let value = match value {
328            Some(v) => v,
329            None => self.node(-1, Where::None, -1)?,
330        };
331        // the tail: blank lines and comments, an end marker, nothing else
332        let mut ended = false;
333        loop {
334            if self.next_content()?.is_none() {
335                return Ok(value);
336            }
337            if self.line_is("...") {
338                self.i += 3;
339                self.end_line("the end marker")?;
340                ended = true;
341                continue;
342            }
343            if self.line_is("---") {
344                return self.fail("stream holds more than one document");
345            }
346            return self.fail(if ended {
347                "unexpected content after the end marker"
348            } else {
349                "unexpected content"
350            });
351        }
352    }
353
354    // ---- block nodes ----
355    /// the node whose text starts at the cursor (inline: on the line of the
356    /// `- ` or `key: ` it follows) or on the following lines (indented more
357    /// than `parent`; a sequence may sit at `seq_at` = the parent mapping's
358    /// own indentation). `where_` says what the inline position follows.
359    /// Null for an empty node, leaving the cursor where it was.
360    fn node(&mut self, parent: i64, where_: Where, seq_at: i64) -> YR<Value> {
361        self.skip_inline();
362        if !self.at_end() {
363            let c = self.col() as i64;
364            return self.node_at(c, where_, parent);
365        }
366        let save = self.i;
367        let Some(n) = self.next_content()? else {
368            return Ok(Value::Null);
369        };
370        let n = n as i64;
371        let dash = self.dash_here();
372        if (n <= parent && !(dash && seq_at == n)) || self.at_marker() {
373            self.i = save;
374            return Ok(Value::Null);
375        }
376        self.node_at(n, Where::None, parent)
377    }
378    fn node_at(&mut self, ind: i64, where_: Where, parent: i64) -> YR<Value> {
379        let c = self.peek();
380        match c {
381            Some('&') => {
382                let name = self.anchor_name()?;
383                self.skip_inline();
384                let v = if self.at_end() {
385                    self.node(parent, where_, -1)?
386                } else {
387                    let col = self.col() as i64;
388                    self.node_at(col, where_, parent)?
389                };
390                self.anchors.insert(name, v.clone());
391                Ok(v)
392            }
393            Some('*') => {
394                let at = self.i;
395                let name = self.anchor_name()?;
396                let Some(v) = self.anchors.get(&name).cloned() else {
397                    return self.fail_at(&format!("unknown alias *{name}"), at);
398                };
399                self.end_line("an alias")?;
400                Ok(copy_of(&v))
401            }
402            Some('!') => self.fail("uses a tag"),
403            Some('@') | Some('`') => self.fail(&format!("reserved indicator {}", c.unwrap())),
404            Some('%') => self.fail("unexpected directive"),
405            Some('[') | Some('{') => {
406                let v = self.flow_node()?;
407                self.end_line("a flow collection")?;
408                Ok(v)
409            }
410            Some('|') | Some('>') => self.block_scalar(parent),
411            Some('"') | Some('\'') => {
412                let start = self.i;
413                let text = self.quoted()?;
414                while is_space(self.peek()) {
415                    self.i += 1;
416                }
417                if self.peek() == Some(':') && self.indicator_at(self.i) {
418                    if where_ == Where::Map {
419                        return self.fail("unexpected mapping value");
420                    }
421                    self.i = start;
422                    return self.mapping(ind);
423                }
424                self.end_line("a scalar")?;
425                Ok(Value::Str(text.into()))
426            }
427            Some('-') if self.indicator_at(self.i) => {
428                if where_ == Where::Map {
429                    return self.fail("unexpected sequence");
430                }
431                self.sequence(ind)
432            }
433            Some('?') if self.indicator_at(self.i) => self.fail("mapping key is not a string"),
434            Some(':') if self.indicator_at(self.i) => self.fail("unexpected ':'"),
435            _ => {
436                // a plain scalar — a mapping when `: ` follows it on the line
437                if self.plain_is_key() {
438                    if where_ == Where::Map {
439                        return self.fail("unexpected mapping value");
440                    }
441                    return self.mapping(ind);
442                }
443                self.plain_scalar(parent)
444            }
445        }
446    }
447    fn anchor_name(&mut self) -> YR<String> {
448        self.i += 1; // & or *
449        let start = self.i;
450        while !self.at_end() && !is_space(self.peek()) && !is_flow_end(self.peek()) {
451            self.i += 1;
452        }
453        if self.i == start {
454            return self.fail_at("missing anchor name", start - 1);
455        }
456        Ok(self.s[start..self.i].iter().collect())
457    }
458    /// does the plain text at the cursor end in a `: ` on this line (before any comment)?
459    fn plain_is_key(&self) -> bool {
460        let mut k = self.i;
461        loop {
462            let c = self.at(k);
463            if is_break_or_end(c) {
464                return false;
465            }
466            if c == Some('#') && k > self.i && is_space(self.at(k - 1)) {
467                return false;
468            }
469            if c == Some(':') && self.indicator_at(k) {
470                return true;
471            }
472            k += 1;
473        }
474    }
475    /// the plain text on the current line up to a comment or the line's end (not a key)
476    fn plain_line(&mut self) -> YR<String> {
477        let start = self.i;
478        let mut end = self.i;
479        loop {
480            let c = self.at(end);
481            if is_break_or_end(c) {
482                break;
483            }
484            if c == Some('#') && end > start && is_space(self.at(end - 1)) {
485                break;
486            }
487            if c == Some(':') && self.indicator_at(end) {
488                return self.fail_at("unexpected ':'", end);
489            }
490            end += 1;
491        }
492        self.i = end;
493        let text: String = self.s[start..end].iter().collect();
494        let text = text.trim_end_matches([' ', '\t']).to_string();
495        self.skip_inline();
496        Ok(text)
497    }
498    fn plain_scalar(&mut self, parent: i64) -> YR<Value> {
499        let at = self.i;
500        let mut text = self.plain_line()?;
501        // continuation lines: indented more than the parent, folded with a
502        // space; blank lines between fold to line breaks
503        loop {
504            let save = self.i;
505            let mut blanks = 0;
506            let mut k = self.i;
507            if self.at(k) != Some('\n') {
508                break;
509            }
510            let mut found: Option<usize> = None;
511            while self.at(k) == Some('\n') {
512                k += 1;
513                let mut j = k;
514                while matches!(self.at(j), Some(' ') | Some('\t')) {
515                    j += 1;
516                }
517                if self.at(j) == Some('\n') {
518                    blanks += 1;
519                    k = j;
520                    continue;
521                }
522                if self.at(j).is_none() {
523                    break;
524                }
525                found = Some(j);
526                break;
527            }
528            let Some(found) = found else { break };
529            let ind = self.indent_of(found)? as i64;
530            let c = self.at(found);
531            if ind <= parent || c == Some('#') {
532                break;
533            }
534            if matches!(c, Some('-') | Some('?') | Some(':')) && self.indicator_at(found) {
535                break;
536            }
537            self.i = found;
538            if self.at_marker() || self.plain_is_key() {
539                self.i = save;
540                break;
541            }
542            let more = self.plain_line()?;
543            if blanks > 0 {
544                text.push_str(&"\n".repeat(blanks));
545            } else {
546                text.push(' ');
547            }
548            text.push_str(&more);
549            if self.i == save {
550                break;
551            }
552        }
553        let r = resolve_plain(&text);
554        if r == Plain::NonFinite {
555            return self.fail_at("non-finite float", at);
556        }
557        Ok(plain_value(r))
558    }
559    fn mapping(&mut self, ind: i64) -> YR<Value> {
560        let mut entries: Vec<(String, Value)> = vec![];
561        let mut seen: HashSet<String> = HashSet::new();
562        loop {
563            let at = self.i;
564            let key = self.key()?;
565            if seen.contains(&key) {
566                return self.fail_at(&format!("mapping repeats the key {}", json_str(&key)), at);
567            }
568            seen.insert(key.clone());
569            let value = self.node(ind, Where::Map, ind)?;
570            entries.push((key, value));
571            let Some(n) = self.next_content()? else { break };
572            let n = n as i64;
573            if n < ind || self.at_marker() {
574                break;
575            }
576            if n > ind {
577                return self.fail("bad indentation");
578            }
579            if self.dash_here() {
580                return self.fail("unexpected sequence");
581            }
582        }
583        Ok(Value::JObj(Rc::new(entries)))
584    }
585    /// a mapping key at the cursor, and the `:` after it
586    fn key(&mut self) -> YR<String> {
587        let c = self.peek();
588        let key: String = match c {
589            Some('"') | Some('\'') => self.quoted()?,
590            Some('?') if self.indicator_at(self.i) => {
591                return self.fail("mapping key is not a string")
592            }
593            Some('&') | Some('*') => return self.fail("mapping key is not a string"),
594            Some('!') => return self.fail("uses a tag"),
595            Some('[') | Some('{') => return self.fail("mapping key is not a string"),
596            _ => {
597                let start = self.i;
598                let mut end = self.i;
599                loop {
600                    let ch = self.at(end);
601                    if is_break_or_end(ch) {
602                        return self.fail_at("missing ':' after a mapping key", start);
603                    }
604                    if ch == Some('#') && end > start && is_space(self.at(end - 1)) {
605                        return self.fail_at("missing ':' after a mapping key", start);
606                    }
607                    if ch == Some(':') && self.indicator_at(end) {
608                        break;
609                    }
610                    end += 1;
611                }
612                let text: String = self.s[start..end].iter().collect();
613                let text = text.trim_end_matches([' ', '\t']).to_string();
614                if !matches!(resolve_plain(&text), Plain::Str(_)) {
615                    return self.fail_at("mapping key is not a string", start);
616                }
617                self.i = end;
618                text
619            }
620        };
621        while is_space(self.peek()) {
622            self.i += 1;
623        }
624        if !(self.peek() == Some(':') && self.indicator_at(self.i)) {
625            return self.fail("missing ':' after a mapping key");
626        }
627        self.i += 1;
628        Ok(key)
629    }
630    fn sequence(&mut self, ind: i64) -> YR<Value> {
631        let mut items = vec![];
632        loop {
633            self.i += 1; // the dash
634            items.push(self.node(ind, Where::Seq, -1)?);
635            let Some(n) = self.next_content()? else { break };
636            let n = n as i64;
637            if n < ind || self.at_marker() {
638                break;
639            }
640            if n > ind {
641                return self.fail("bad indentation");
642            }
643            if !self.dash_here() {
644                break;
645            }
646        }
647        Ok(Value::JArr(Rc::new(items)))
648    }
649
650    // ---- scalars ----
651    /// a single- or double-quoted scalar at the cursor, folded over lines
652    fn quoted(&mut self) -> YR<String> {
653        let q = self.peek().unwrap();
654        let at = self.i;
655        self.i += 1;
656        let mut out = String::new();
657        loop {
658            let Some(c) = self.peek() else {
659                return self.fail_at("unterminated quoted scalar", at);
660            };
661            if c == q {
662                if q == '\'' && self.peek1() == Some('\'') {
663                    out.push('\'');
664                    self.i += 2;
665                    continue;
666                }
667                self.i += 1;
668                return Ok(out);
669            }
670            if c == '\n' {
671                // folding: one break is a space, further breaks are kept
672                let mut breaks = 0;
673                while self.peek() == Some('\n') || is_space(self.peek()) {
674                    if self.peek() == Some('\n') {
675                        breaks += 1;
676                    }
677                    self.i += 1;
678                }
679                let trimmed = out.trim_end_matches([' ', '\t']).len();
680                out.truncate(trimmed);
681                if breaks > 1 {
682                    out.push_str(&"\n".repeat(breaks - 1));
683                } else {
684                    out.push(' ');
685                }
686                continue;
687            }
688            if q == '"' && c == '\\' {
689                self.i += 1;
690                let e = self.escape()?;
691                out.push_str(&e);
692                continue;
693            }
694            out.push(c);
695            self.i += 1;
696        }
697    }
698    fn escape(&mut self) -> YR<String> {
699        let c = self.peek();
700        let at = self.i - 1;
701        self.i += 1;
702        Ok(match c {
703            Some('0') => "\0".into(),
704            Some('a') => "\x07".into(),
705            Some('b') => "\x08".into(),
706            Some('t') | Some('\t') => "\t".into(),
707            Some('n') => "\n".into(),
708            Some('v') => "\x0b".into(),
709            Some('f') => "\x0c".into(),
710            Some('r') => "\r".into(),
711            Some('e') => "\x1b".into(),
712            Some(' ') => " ".into(),
713            Some('"') => "\"".into(),
714            Some('/') => "/".into(),
715            Some('\\') => "\\".into(),
716            Some('N') => "\u{85}".into(),
717            Some('_') => "\u{a0}".into(),
718            Some('L') => "\u{2028}".into(),
719            Some('P') => "\u{2029}".into(),
720            Some('x') | Some('u') | Some('U') => {
721                let len = match c {
722                    Some('x') => 2,
723                    Some('u') => 4,
724                    _ => 8,
725                };
726                let hex: String = self.s[self.i..(self.i + len).min(self.s.len())]
727                    .iter()
728                    .collect();
729                if hex.chars().count() != len || !hex.chars().all(|h| h.is_ascii_hexdigit()) {
730                    return self.fail_at("bad escape", at);
731                }
732                self.i += len;
733                let cp = u32::from_str_radix(&hex, 16).unwrap();
734                match char::from_u32(cp) {
735                    Some(ch) => ch.to_string(),
736                    // a lone surrogate: the reference keeps it as a code unit; no
737                    // document of the corpus carries one
738                    None => return self.fail_at("bad escape", at),
739                }
740            }
741            Some('\n') => {
742                // an escaped line break joins the lines; leading white space is dropped
743                while is_space(self.peek()) {
744                    self.i += 1;
745                }
746                String::new()
747            }
748            _ => return self.fail_at("bad escape", at),
749        })
750    }
751    /// a block scalar (`|` or `>`) with its indicators; `parent` is the enclosing indentation
752    fn block_scalar(&mut self, parent: i64) -> YR<Value> {
753        let at = self.i;
754        let folded = self.peek() == Some('>');
755        self.i += 1;
756        let mut chomp = 0i8; // 0 clip, -1 strip, 1 keep
757        let mut chomp_set = false;
758        let mut explicit = 0usize;
759        for _ in 0..2 {
760            match self.peek() {
761                Some('-') | Some('+') => {
762                    if chomp_set {
763                        return self.fail_at("bad block scalar header", at);
764                    }
765                    chomp = if self.peek() == Some('-') { -1 } else { 1 };
766                    chomp_set = true;
767                    self.i += 1;
768                }
769                Some(d) if ('1'..='9').contains(&d) => {
770                    if explicit != 0 {
771                        return self.fail_at("bad block scalar header", at);
772                    }
773                    explicit = d as usize - '0' as usize;
774                    self.i += 1;
775                }
776                _ => {}
777            }
778        }
779        self.end_line("a block scalar header")?;
780        // the content lines: those indented at least the content indentation
781        // (explicit, or the first non-blank line's), until a lesser one
782        let mut lines: Vec<(String, bool)> = vec![];
783        let mut indent: i64 = if explicit > 0 {
784            parent.max(0) + explicit as i64
785        } else {
786            -1
787        };
788        let mut k = self.i;
789        let mut end_at = self.i;
790        while self.at(k) == Some('\n') {
791            let start = k + 1;
792            let mut j = start;
793            while self.at(j) == Some(' ') {
794                j += 1;
795            }
796            let blank = matches!(self.at(j), Some('\n') | None);
797            let line_indent = (j - start) as i64;
798            if blank {
799                let mut e = j;
800                while !matches!(self.at(e), Some('\n') | None) {
801                    e += 1;
802                }
803                let text = if indent >= 0 && line_indent > indent {
804                    " ".repeat((line_indent - indent) as usize)
805                } else {
806                    String::new()
807                };
808                lines.push((text, true));
809                k = e;
810                end_at = e;
811                if self.at(e).is_none() {
812                    break;
813                }
814                continue;
815            }
816            if indent < 0 {
817                if line_indent <= parent {
818                    break;
819                }
820                indent = line_indent;
821                // blank lines before the first content line carry no spaces
822                for l in lines.iter_mut() {
823                    l.0.clear();
824                }
825            }
826            if line_indent < indent {
827                break;
828            }
829            if self.at(j) == Some('\t') && line_indent == indent {
830                return self.fail_at("tab in indentation", j);
831            }
832            let mut e = j;
833            while !matches!(self.at(e), Some('\n') | None) {
834                e += 1;
835            }
836            let text: String = self.s[start + indent as usize..e].iter().collect();
837            lines.push((text, false));
838            k = e;
839            end_at = e;
840            if self.at(e).is_none() {
841                break;
842            }
843        }
844        self.i = end_at;
845        // trailing blank lines are the chomping's business
846        let mut last = lines.len();
847        while last > 0 && lines[last - 1].1 {
848            last -= 1;
849        }
850        let body = &lines[..last];
851        let trailing = lines.len() - last;
852        let mut text = String::new();
853        if !folded {
854            text = body
855                .iter()
856                .map(|l| l.0.as_str())
857                .collect::<Vec<_>>()
858                .join("\n");
859        } else {
860            // folding: a break between two normal lines is a space, blank lines
861            // are kept as breaks, more-indented lines are kept as written
862            let more_indented =
863                |x: &(String, bool)| !x.1 && (x.0.starts_with(' ') || x.0.starts_with('\t'));
864            for (n, l) in body.iter().enumerate() {
865                if n == 0 {
866                    text = l.0.clone();
867                    continue;
868                }
869                let prev = &body[n - 1];
870                if l.1 || prev.1 || more_indented(prev) || more_indented(l) {
871                    text.push('\n');
872                } else {
873                    text.push(' ');
874                }
875                text.push_str(&l.0);
876            }
877        }
878        if body.is_empty() {
879            return Ok(Value::Str(
880                (if chomp > 0 {
881                    "\n".repeat(trailing)
882                } else {
883                    String::new()
884                })
885                .into(),
886            ));
887        }
888        Ok(Value::Str(
889            (match chomp {
890                -1 => text,
891                0 => text + "\n",
892                _ => text + &"\n".repeat(trailing + 1),
893            })
894            .into(),
895        ))
896    }
897
898    // ---- flow nodes ----
899    fn flow_ws(&mut self) {
900        loop {
901            match self.peek() {
902                Some(' ') | Some('\t') | Some('\n') => self.i += 1,
903                Some('#')
904                    if self.i == 0
905                        || is_space(self.at(self.i - 1))
906                        || self.at(self.i - 1) == Some('\n') =>
907                {
908                    while !self.at_end() {
909                        self.i += 1;
910                    }
911                }
912                _ => return,
913            }
914        }
915    }
916    fn flow_node(&mut self) -> YR<Value> {
917        self.flow_ws();
918        let Some(c) = self.peek() else {
919            return self.fail("unterminated flow collection");
920        };
921        match c {
922            '&' => {
923                let name = self.anchor_name()?;
924                let v = self.flow_node()?;
925                self.anchors.insert(name, v.clone());
926                Ok(v)
927            }
928            '*' => {
929                let at = self.i;
930                let name = self.anchor_name()?;
931                match self.anchors.get(&name).cloned() {
932                    Some(v) => Ok(copy_of(&v)),
933                    None => self.fail_at(&format!("unknown alias *{name}"), at),
934                }
935            }
936            '!' => self.fail("uses a tag"),
937            '[' => {
938                let at = self.i;
939                self.i += 1;
940                let mut items = vec![];
941                loop {
942                    self.flow_ws();
943                    match self.peek() {
944                        Some(']') => {
945                            self.i += 1;
946                            return Ok(Value::JArr(Rc::new(items)));
947                        }
948                        None => return self.fail_at("unterminated flow collection", at),
949                        Some(',') => return self.fail("unexpected ','"),
950                        _ => {}
951                    }
952                    items.push(self.flow_node()?);
953                    self.flow_ws();
954                    match self.peek() {
955                        Some(':') => return self.fail("unexpected ':'"),
956                        Some(',') => {
957                            self.i += 1;
958                            continue;
959                        }
960                        Some(']') => continue,
961                        _ => return self.fail("expected ',' or ']'"),
962                    }
963                }
964            }
965            '{' => {
966                let at = self.i;
967                self.i += 1;
968                let mut entries: Vec<(String, Value)> = vec![];
969                let mut seen: HashSet<String> = HashSet::new();
970                loop {
971                    self.flow_ws();
972                    match self.peek() {
973                        Some('}') => {
974                            self.i += 1;
975                            return Ok(Value::JObj(Rc::new(entries)));
976                        }
977                        None => return self.fail_at("unterminated flow collection", at),
978                        Some(',') => return self.fail("unexpected ','"),
979                        _ => {}
980                    }
981                    let key_at = self.i;
982                    let Value::Str(key) = self.flow_node()? else {
983                        return self.fail_at("mapping key is not a string", key_at);
984                    };
985                    if seen.contains(&*key) {
986                        return self.fail_at(
987                            &format!("mapping repeats the key {}", json_str(&key)),
988                            key_at,
989                        );
990                    }
991                    seen.insert(key.to_string());
992                    self.flow_ws();
993                    let mut value = Value::Null;
994                    if self.peek() == Some(':') {
995                        self.i += 1;
996                        self.flow_ws();
997                        if !matches!(self.peek(), Some(',') | Some('}')) {
998                            value = self.flow_node()?;
999                        }
1000                        self.flow_ws();
1001                    }
1002                    entries.push((key.to_string(), value));
1003                    match self.peek() {
1004                        Some(',') => {
1005                            self.i += 1;
1006                            continue;
1007                        }
1008                        Some('}') => continue,
1009                        _ => return self.fail("expected ',' or '}'"),
1010                    }
1011                }
1012            }
1013            '"' | '\'' => Ok(Value::Str(self.quoted()?.into())),
1014            ']' | '}' => self.fail(&format!("unexpected '{c}'")),
1015            _ => {
1016                // a plain scalar in flow context: ends at an indicator, folded over lines
1017                let at = self.i;
1018                let mut text = String::new();
1019                loop {
1020                    let start = self.i;
1021                    let mut end = self.i;
1022                    loop {
1023                        let ch = self.at(end);
1024                        if is_break_or_end(ch) || is_flow_end(ch) {
1025                            break;
1026                        }
1027                        if ch == Some('#') && end > start && is_space(self.at(end - 1)) {
1028                            break;
1029                        }
1030                        if ch == Some(':')
1031                            && (is_space(self.at(end + 1))
1032                                || is_break_or_end(self.at(end + 1))
1033                                || is_flow_end(self.at(end + 1)))
1034                        {
1035                            break;
1036                        }
1037                        end += 1;
1038                    }
1039                    let piece: String = self.s[start..end].iter().collect();
1040                    text.push_str(piece.trim_end_matches([' ', '\t']));
1041                    self.i = end;
1042                    // a line break inside the scalar folds to a space
1043                    let mut k = end;
1044                    while is_space(self.at(k)) {
1045                        k += 1;
1046                    }
1047                    if self.at(k) == Some('#') {
1048                        break;
1049                    }
1050                    if self.at(k) != Some('\n') {
1051                        break;
1052                    }
1053                    let mut blanks = 0;
1054                    while self.at(k) == Some('\n') || is_space(self.at(k)) {
1055                        if self.at(k) == Some('\n') {
1056                            blanks += 1;
1057                        }
1058                        k += 1;
1059                    }
1060                    let ch = self.at(k);
1061                    if ch.is_none()
1062                        || is_flow_end(ch)
1063                        || ch == Some('#')
1064                        || (ch == Some(':') && self.indicator_at(k))
1065                    {
1066                        self.i = k;
1067                        break;
1068                    }
1069                    if blanks > 1 {
1070                        text.push_str(&"\n".repeat(blanks - 1));
1071                    } else {
1072                        text.push(' ');
1073                    }
1074                    self.i = k;
1075                }
1076                if text.is_empty() {
1077                    return self.fail_at("unexpected content", at);
1078                }
1079                let r = resolve_plain(&text);
1080                if r == Plain::NonFinite {
1081                    return self.fail_at("non-finite float", at);
1082                }
1083                Ok(plain_value(r))
1084            }
1085        }
1086    }
1087}
1088
1089// an alias is a copy of the anchored value
1090fn copy_of(v: &Value) -> Value {
1091    match v {
1092        Value::JArr(items) => Value::JArr(Rc::new(items.iter().map(copy_of).collect())),
1093        Value::JObj(entries) => Value::JObj(Rc::new(
1094            entries
1095                .iter()
1096                .map(|(k, x)| (k.clone(), copy_of(x)))
1097                .collect(),
1098        )),
1099        other => other.clone(),
1100    }
1101}
1102
1103/// read one YAML document (§2) into the JSON data model
1104pub fn read_yaml(src: &str) -> Result<Value, YamlError> {
1105    Reader::new(src).document()
1106}
1107
1108// ---------------- the writer (§4.2) ----------------
1109// the YAML 1.1 spellings a 1.1 reader would take for a bool or a null
1110const YAML11_WORDS: [&str; 16] = [
1111    "y", "Y", "yes", "Yes", "YES", "n", "N", "no", "No", "NO", "on", "On", "ON", "off", "Off",
1112    "OFF",
1113];
1114/// plain only when a YAML 1.2 reader reads it back as exactly this string
1115/// and a YAML 1.1 reader has nothing to reinterpret: it starts with a
1116/// letter or `_`, holds no indicator that could open a collection, an
1117/// anchor, a tag, or a comment, no `: `, no `#`, no break, tab, or
1118/// unprintable character, does not end in `:` or a space, and is not a
1119/// word either schema reads as a bool or a null
1120pub fn plain_safe(s: &str) -> bool {
1121    let Some(first) = s.chars().next() else {
1122        return false;
1123    };
1124    if !(first.is_ascii_alphabetic() || first == '_') {
1125        return false;
1126    }
1127    if YAML11_WORDS.contains(&s) || !matches!(resolve_plain(s), Plain::Str(_)) {
1128        return false;
1129    }
1130    if s.ends_with(':') || s.ends_with(' ') {
1131        return false;
1132    }
1133    if s.contains(": ") || s.contains(" #") {
1134        return false;
1135    }
1136    for ch in s.chars() {
1137        let cp = ch as u32;
1138        if "[]{},&*!|>'\"%@`#".contains(ch) {
1139            return false;
1140        }
1141        if cp < 0x20 || cp == 0x7f || (0x80..=0x9f).contains(&cp) {
1142            return false;
1143        }
1144        if cp == 0xfeff || cp == 0xfffe || cp == 0xffff {
1145            return false;
1146        }
1147    }
1148    true
1149}
1150fn yaml_str(s: &str) -> String {
1151    if plain_safe(s) {
1152        s.to_string()
1153    } else {
1154        json_str(s)
1155    }
1156}
1157fn is_empty_coll(v: &Value) -> bool {
1158    match v {
1159        Value::JArr(items) => items.is_empty(),
1160        Value::JObj(entries) => entries.is_empty(),
1161        _ => false,
1162    }
1163}
1164fn is_block(v: &Value) -> bool {
1165    matches!(v, Value::JArr(_) | Value::JObj(_)) && !is_empty_coll(v)
1166}
1167fn scalar_text(v: &Value) -> String {
1168    match v {
1169        Value::Null => "null".into(),
1170        Value::Bool(b) => b.to_string(),
1171        Value::Int(i) => i.to_string(),
1172        Value::Float(f) => fmt_f(*f),
1173        Value::Str(s) => yaml_str(s),
1174        Value::JArr(_) => "[]".into(),
1175        Value::JObj(_) => "{}".into(),
1176        _ => panic!("to_yaml: unexpected value"),
1177    }
1178}
1179// the lines of a block node: the first without its indentation (the
1180// caller places it after `- ` or on a line of its own), the rest with
1181// `ind` in front of them
1182fn block_lines(v: &Value, ind: &str, step: &str) -> Vec<String> {
1183    let mut out: Vec<String> = vec![];
1184    match v {
1185        Value::JArr(items) => {
1186            for item in items.iter() {
1187                let sub = if is_block(item) {
1188                    block_lines(item, &format!("{ind}  "), step)
1189                } else {
1190                    vec![scalar_text(item)]
1191                };
1192                let lead = if out.is_empty() { "" } else { ind };
1193                out.push(format!("{lead}- {}", sub[0]));
1194                out.extend(sub[1..].iter().cloned());
1195            }
1196        }
1197        Value::JObj(entries) => {
1198            for (k, x) in entries.iter() {
1199                let key = yaml_str(k);
1200                let lead = if out.is_empty() { "" } else { ind };
1201                if !is_block(x) {
1202                    out.push(format!("{lead}{key}: {}", scalar_text(x)));
1203                    continue;
1204                }
1205                out.push(format!("{lead}{key}:"));
1206                let sub = block_lines(x, &format!("{ind}{step}"), step);
1207                out.push(format!("{ind}{step}{}", sub[0]));
1208                out.extend(sub[1..].iter().cloned());
1209            }
1210        }
1211        _ => unreachable!(),
1212    }
1213    out
1214}
1215/// the YAML text of a JSON value (read_json's shape), block style, no trailing newline
1216pub fn to_yaml(v: &Value, indent: usize) -> String {
1217    let step = " ".repeat(indent);
1218    if is_block(v) {
1219        block_lines(v, "", &step).join("\n")
1220    } else {
1221        scalar_text(v)
1222    }
1223}
1224
1225// ---------------- the JSON layouts (§4.1) ----------------
1226/// the JSON text of a value (read_json's shape): canonical for indent 0, laid out with `indent` spaces per level otherwise
1227pub fn to_json(v: &Value, indent: usize) -> String {
1228    fn go(x: &Value, ind: &str, indent: usize) -> String {
1229        match x {
1230            Value::Null => "null".into(),
1231            Value::Bool(b) => b.to_string(),
1232            Value::Int(i) => i.to_string(),
1233            Value::Float(f) => fmt_f(*f),
1234            Value::Str(s) => json_str(s),
1235            Value::JArr(items) => {
1236                if items.is_empty() {
1237                    return "[]".into();
1238                }
1239                let inner = format!("{ind}{}", " ".repeat(indent));
1240                if indent == 0 {
1241                    return format!(
1242                        "[{}]",
1243                        items
1244                            .iter()
1245                            .map(|e| go(e, ind, indent))
1246                            .collect::<Vec<_>>()
1247                            .join(",")
1248                    );
1249                }
1250                format!(
1251                    "[\n{}\n{ind}]",
1252                    items
1253                        .iter()
1254                        .map(|e| format!("{inner}{}", go(e, &inner, indent)))
1255                        .collect::<Vec<_>>()
1256                        .join(",\n")
1257                )
1258            }
1259            Value::JObj(entries) => {
1260                if entries.is_empty() {
1261                    return "{}".into();
1262                }
1263                let inner = format!("{ind}{}", " ".repeat(indent));
1264                if indent == 0 {
1265                    return format!(
1266                        "{{{}}}",
1267                        entries
1268                            .iter()
1269                            .map(|(k, e)| format!("{}:{}", json_str(k), go(e, ind, indent)))
1270                            .collect::<Vec<_>>()
1271                            .join(",")
1272                    );
1273                }
1274                format!(
1275                    "{{\n{}\n{ind}}}",
1276                    entries
1277                        .iter()
1278                        .map(|(k, e)| format!("{inner}{}: {}", json_str(k), go(e, &inner, indent)))
1279                        .collect::<Vec<_>>()
1280                        .join(",\n")
1281                )
1282            }
1283            _ => panic!("to_json: unexpected value"),
1284        }
1285    }
1286    go(v, "", indent)
1287}