Skip to main content

oneyaml_core/
code.rs

1//! Stable `Y####` diagnostic codes and the single code registry.
2//!
3//! # Allocation rules
4//!
5//! | Range         | Area                                                        |
6//! |---------------|-------------------------------------------------------------|
7//! | `Y0001–Y0999` | syntax: decode, lex, parse, recovery                        |
8//! | `Y1000–Y1999` | schema & resolution: directives, tags, duplicate keys, settings conflicts |
9//! | `Y2000–Y2999` | limits                                                      |
10//! | `Y3000–Y3999` | serde                                                       |
11//! | `Y9000–Y9999` | reserved; `Y9000` = internal error                   |
12//!
13//! `Y0000` is never used. Codes are allocated **sequentially within their
14//! range**, only in this file: a new code is `max + 1` of its range, added as
15//! a constant plus a matching [`REGISTRY`] entry.
16//!
17//! **The registry is append-only.** A code is never removed, reused,
18//! renumbered, renamed, or given a new meaning. To retire a code, set
19//! [`CodeInfo::deprecated`]; the entry stays forever, so ranges stay
20//! contiguous. `crates/oneyaml-core/tests/codes.snapshot` freezes every
21//! entry (code, name, severity, status, summary) and a test compares the
22//! registry with it, so any change to an existing entry shows up as a snapshot
23//! diff in review.
24
25use crate::Severity;
26
27/// A stable diagnostic code, rendered as `Y####`.
28///
29/// ```
30/// use oneyaml_core::code::{self, CodeRange};
31/// use oneyaml_core::{Code, Severity};
32///
33/// let c = Code::parse("Y1014").unwrap();
34/// assert_eq!(c, code::DUPLICATE_KEY_LAST_WINS);
35/// assert_eq!((c.get(), c.to_string()), (1014, "Y1014".to_owned()));
36/// assert_eq!(c.range(), CodeRange::Schema);
37/// assert_eq!(CodeRange::Schema.bounds(), (1000, 1999));
38/// let info = c.info().unwrap(); // the registry entry
39/// assert_eq!(info.name, "DUPLICATE_KEY_LAST_WINS");
40/// assert_eq!(info.severity, Severity::Warning);
41/// assert!(Code::parse("Y0000").is_none()); // Y0000 is never used
42/// assert_eq!(format!("{c:?}"), "Y1014"); // `Debug` shows the same form
43/// ```
44#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
45pub struct Code(u16);
46
47/// The area a [`Code`] belongs to.
48#[non_exhaustive]
49#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
50pub enum CodeRange {
51    /// `Y0001–Y0999`: decode, lex, parse, recovery.
52    Syntax,
53    /// `Y1000–Y1999`: directives, tags, duplicate keys, settings conflicts.
54    Schema,
55    /// `Y2000–Y2999`: resource limits.
56    Limits,
57    /// `Y3000–Y3999`: serde.
58    Serde,
59    /// `Y9000–Y9999`: reserved. `Y9000` is the internal error.
60    Reserved,
61}
62
63impl CodeRange {
64    /// The inclusive numeric bounds of this range.
65    #[must_use]
66    pub const fn bounds(self) -> (u16, u16) {
67        match self {
68            Self::Syntax => (1, 999),
69            Self::Schema => (1000, 1999),
70            Self::Limits => (2000, 2999),
71            Self::Serde => (3000, 3999),
72            Self::Reserved => (9000, 9999),
73        }
74    }
75}
76
77impl Code {
78    /// Returns the code with number `n`, or `None` if `n` lies outside every
79    /// allocated range (including `0`).
80    ///
81    /// This validates the *range* only and exists for parsing, deserializing,
82    /// and tests. Library code never calls it: it emits only the registered
83    /// constants in this module, which a test enforces by scanning the
84    /// library crates' sources.
85    #[must_use]
86    pub const fn new(n: u16) -> Option<Self> {
87        match n {
88            1..=3999 | 9000..=9999 => Some(Self(n)),
89            _ => None,
90        }
91    }
92
93    /// The numeric value.
94    #[must_use]
95    pub const fn get(self) -> u16 {
96        self.0
97    }
98
99    /// The range this code belongs to.
100    #[must_use]
101    pub const fn range(self) -> CodeRange {
102        match self.0 {
103            0..=999 => CodeRange::Syntax,
104            1000..=1999 => CodeRange::Schema,
105            2000..=2999 => CodeRange::Limits,
106            3000..=3999 => CodeRange::Serde,
107            _ => CodeRange::Reserved,
108        }
109    }
110
111    /// Parses the `Y####` form (exactly four digits).
112    #[must_use]
113    pub fn parse(s: &str) -> Option<Self> {
114        let digits = s.strip_prefix('Y')?;
115        if digits.len() != 4 || !digits.bytes().all(|b| b.is_ascii_digit()) {
116            return None;
117        }
118        Self::new(digits.parse().ok()?)
119    }
120
121    /// The registry entry for this code, if it is allocated.
122    #[must_use]
123    pub fn info(self) -> Option<&'static CodeInfo> {
124        REGISTRY.iter().find(|info| info.code == self)
125    }
126}
127
128impl core::fmt::Display for Code {
129    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
130        write!(f, "Y{:04}", self.0)
131    }
132}
133
134// `Debug` prints the documented `Y####` form so a code inside a derived
135// `Debug` (a `Diagnostic`, an error kind) reads the same as everywhere else.
136impl core::fmt::Debug for Code {
137    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
138        core::fmt::Display::fmt(self, f)
139    }
140}
141
142/// One registry entry.
143#[non_exhaustive]
144#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
145pub struct CodeInfo {
146    /// The code.
147    pub code: Code,
148    /// The constant's name in this module.
149    pub name: &'static str,
150    /// The severity diagnostics with this code are emitted at by default.
151    pub severity: Severity,
152    /// One-line meaning. Never changes once published.
153    pub summary: &'static str,
154    /// Retired: never emitted any more, but never removed or reused.
155    pub deprecated: bool,
156}
157
158// ---------------------------------------------------------------------------
159// Y0001–Y0999: syntax.
160// ---------------------------------------------------------------------------
161
162/// Directives not followed by an explicit `---` (productions 210-211). Error.
163pub const DIRECTIVE_WITHOUT_DOCUMENT: Code = Code(1);
164/// A `%YAML`/`%TAG` directive with missing, extra, or malformed parameters,
165/// or a directive without a name (§6.8). Error.
166pub const MALFORMED_DIRECTIVE: Code = Code(2);
167/// A directive inside a document that was not ended with `...`
168/// (production 211). Error.
169pub const DIRECTIVE_IN_DOCUMENT: Code = Code(3);
170/// Content after a document's root node, or after a `...` marker on the same
171/// line (§9.1). Error.
172pub const CONTENT_AFTER_DOCUMENT: Code = Code(4);
173/// A line indented so that it belongs to no open block collection (§8.2).
174/// Error.
175pub const INVALID_INDENTATION: Code = Code(5);
176/// A block sequence or mapping starting on a line where only a scalar may
177/// start, e.g. after `---`, after an implicit key's `:`, or after properties
178/// (production 200). Error.
179pub const BLOCK_COLLECTION_NOT_ALLOWED: Code = Code(6);
180/// An implicit mapping key spanning more than one line (production 154).
181/// Error.
182pub const MULTILINE_IMPLICIT_KEY: Code = Code(7);
183/// A character that cannot start a node (§7.3.3, production 126). Error.
184pub const INVALID_NODE_START: Code = Code(8);
185/// A quoted scalar not closed before the end of input or a document marker
186/// (§7.3). Error.
187pub const UNTERMINATED_QUOTED_SCALAR: Code = Code(9);
188/// An invalid escape sequence in a double-quoted scalar (§5.7). Error.
189pub const INVALID_ESCAPE: Code = Code(10);
190/// A continuation line of a quoted scalar indented too little
191/// (production 69). Error.
192pub const QUOTED_SCALAR_INDENTATION: Code = Code(11);
193/// An empty or malformed anchor or alias name (production 102). Error.
194pub const INVALID_ANCHOR: Code = Code(12);
195/// A malformed tag property (§6.9.1). Error.
196pub const INVALID_TAG: Code = Code(13);
197/// An alias node with an anchor or tag (production 104). Error.
198pub const ALIAS_WITH_PROPERTIES: Code = Code(14);
199/// A node with two anchors or two tags (production 96). Error.
200pub const DUPLICATE_PROPERTY: Code = Code(15);
201/// A tab character used as block indentation (§6.1). Error.
202pub const TAB_INDENTATION: Code = Code(16);
203/// Unexpected content after a complete node on the same line. Error.
204pub const UNEXPECTED_CONTENT: Code = Code(17);
205/// A block mapping entry without its `:` value indicator (production 192).
206/// Error.
207pub const MISSING_MAPPING_COLON: Code = Code(18);
208/// Syntax this parser version does not implement yet. **Deprecated**: used
209/// only for flow collections and block scalars by pre-release parsers
210/// that did not implement them; never emitted any more. Error.
211pub const UNSUPPORTED_SYNTAX: Code = Code(19);
212/// A malformed block scalar header: an indentation indicator of `0`, a
213/// repeated indicator, or text after the header (production 162). Error.
214pub const INVALID_BLOCK_HEADER: Code = Code(20);
215/// A leading empty line of an auto-indented block scalar has more spaces
216/// than its first content line (§8.1.1.1). Error.
217pub const BLOCK_SCALAR_INDENTATION: Code = Code(21);
218/// A flow collection not closed before the end of input or a document
219/// marker (§7.4). Error.
220pub const UNTERMINATED_FLOW_COLLECTION: Code = Code(22);
221/// Two flow collection entries without a `,` between them (productions 138,
222/// 141). Error.
223pub const MISSING_FLOW_SEPARATOR: Code = Code(23);
224/// A `,`, `]`, or `}` where it cannot appear, e.g. a leading or doubled
225/// `,`, or a mismatched closing bracket (§7.4). Error.
226pub const UNEXPECTED_FLOW_INDICATOR: Code = Code(24);
227/// An implicit key (with its properties and trailing white space) longer
228/// than 1024 characters (productions 154-155, §8.2.2). Error.
229pub const IMPLICIT_KEY_TOO_LONG: Code = Code(25);
230/// A character outside `nb-json` (production 2), i.e. a C0 control other
231/// than tab, inside a quoted scalar (§7.3). Error.
232pub const INVALID_QUOTED_CHARACTER: Code = Code(26);
233/// A `: ` inside an unquoted (plain) scalar that is the value of a block
234/// mapping entry, on the entry's line, e.g. `title: The farm: a banana
235/// story`. The `: ` would start a nested mapping, which cannot begin on
236/// that line (production 200). A more specific diagnosis of the case that
237/// earlier parser versions reported as [`BLOCK_COLLECTION_NOT_ALLOWED`];
238/// carries a machine-applicable fix that quotes the value. Error.
239pub const INLINE_COLON_IN_PLAIN_VALUE: Code = Code(27);
240/// The input of [`INLINE_COLON_IN_PLAIN_VALUE`] was read as one string
241/// because the `lenient_inline_colons` setting is on. Warning.
242pub const LENIENT_INLINE_COLON: Code = Code(28);
243/// Bytes that are not valid UTF-8 in input decoded as UTF-8 (§5.2). Each
244/// maximal invalid run is replaced by U+FFFD. Error.
245pub const INVALID_UTF8: Code = Code(29);
246/// Input decoded as UTF-16 with an unpaired surrogate or a trailing odd byte
247/// (§5.2). Each maximal invalid run is replaced by U+FFFD. Error.
248pub const INVALID_UTF16: Code = Code(30);
249/// Input decoded as UTF-32 with a code unit that is not a Unicode scalar
250/// value, or trailing bytes that do not form a code unit (§5.2). Each
251/// maximal invalid run is replaced by U+FFFD. Error.
252pub const INVALID_UTF32: Code = Code(31);
253/// A byte order mark (U+FEFF) where YAML 1.2.2 does not allow one (§5.2,
254/// productions 27, 202, 211). A mark is allowed only at the very start of
255/// a line that starts a document prefix: the start of the stream, after a
256/// `...` line, or after a complete document (whose end it then marks; only
257/// a document starting with `---` may follow it). It is also allowed
258/// inside quoted scalars, whose `nb-json` characters include it.
259///
260/// Reported for a mark after white space or other text on a line, after
261/// directives, inside a document's structure, and inside comment text or
262/// block scalar content (`nb-char` excludes it). Recovery: a mark between
263/// tokens is skipped, and columns are counted as if it were absent; a
264/// mark inside a comment or a block scalar stays in that token (the
265/// diagnostic's span is the mark; the block scalar's value keeps it). A
266/// mark ends a plain scalar (it is no `ns-char`), so text right after it
267/// is read as new content (usually a further error). A mark between an
268/// implicit key and its `:` is skipped like any other.
269///
270/// When a mark makes another construct fail (a key without `:`, a block
271/// scalar header, a block scalar's offending line, a directive, or any
272/// other syntax error whose offending line holds a mark before any quote
273/// character), this code is reported too, right after that construct's
274/// error (whose label comes first on the line), so the construct's error
275/// is the one a strict parse fails with.
276/// Not covered: a mark after a quote character on such a line (it may be
277/// inside a quoted scalar, where it is allowed), which then shows only
278/// through the other error.
279///
280/// A mark at the start of a line after a complete document is valid and
281/// ends that document; if what follows is not a document starting with
282/// `---`, the error is `CONTENT_AFTER_DOCUMENT` (or
283/// `DIRECTIVE_IN_DOCUMENT`), with a label on that mark, and the content is
284/// read as the next document. Error.
285pub const MISPLACED_BYTE_ORDER_MARK: Code = Code(32);
286/// A second `%YAML` directive for one document (§6.8.1: it is an error to
287/// give more than one). Reported at the start of the second directive.
288/// Error. (A `%TAG` handle declared twice is still
289/// [`DUPLICATE_DIRECTIVE`]; before this code existed that code also
290/// covered a second `%YAML` directive.)
291pub const DUPLICATE_YAML_DIRECTIVE: Code = Code(33);
292/// A comment holding a character that is not printable (production 1): a
293/// C0 control other than tab, DEL, or a C1 control other than U+0085.
294/// Comment text is made of `nb-char`s (productions 75 and 27). Reported at
295/// the first such character. Error.
296pub const INVALID_COMMENT_CHARACTER: Code = Code(34);
297/// A named tag handle (`!e!`) not declared by a `%TAG` directive of its
298/// document (§6.8.2.1). The shorthand cannot be read, so this is a fault
299/// of the text, a syntax error. Error. (Reported where the parser earlier
300/// reported [`UNDEFINED_TAG_HANDLE`], which is no longer produced.)
301pub const UNDECLARED_TAG_HANDLE: Code = Code(35);
302
303// ---------------------------------------------------------------------------
304// Y1000–Y1999: schema & resolution.
305// ---------------------------------------------------------------------------
306
307/// A `%YAML 1.1` directive. By default the document is parsed as
308/// YAML 1.2; under `honor_version_directive` the YAML 1.1 preset applies.
309/// The message says which. Warning.
310pub const YAML_VERSION_1_1: Code = Code(1000);
311/// `%YAML 1.x` with `x > 2`: processed as YAML 1.2. Warning.
312pub const YAML_VERSION_NEWER_MINOR: Code = Code(1001);
313/// `%YAML` with a major version other than 1. Error.
314pub const YAML_VERSION_UNSUPPORTED_MAJOR: Code = Code(1002);
315/// A reserved directive (`%NAME` other than `YAML`/`TAG`) was ignored
316/// (YAML 1.2.2 §6.8). Warning.
317pub const RESERVED_DIRECTIVE_IGNORED: Code = Code(1003);
318/// A `%TAG` handle declared twice for one document (§6.8.2). A second
319/// `%YAML` directive is [`DUPLICATE_YAML_DIRECTIVE`]. Error.
320pub const DUPLICATE_DIRECTIVE: Code = Code(1004);
321/// A named tag handle (`!e!`) not declared by a `%TAG` directive of its
322/// document (§6.8.2.1). Error. Deprecated: the parser reports
323/// [`UNDECLARED_TAG_HANDLE`] (`Y0035`) instead, because the fault is in the
324/// text.
325pub const UNDEFINED_TAG_HANDLE: Code = Code(1005);
326/// A `%YAML 1.0` directive. By default the document is parsed as
327/// YAML 1.2; under `honor_version_directive` the YAML 1.1 preset applies,
328/// as for 1.1. The message says which. Warning.
329pub const YAML_VERSION_1_0: Code = Code(1006);
330/// An explicitly tagged scalar whose text is not a valid form of its core
331/// tag under the active schema, e.g. `!!int twelve` (§10). Error.
332pub const INVALID_SCALAR_FOR_TAG: Code = Code(1007);
333/// A collection tag (`!!seq`, `!!map`) on a scalar node (§10). Error.
334pub const COLLECTION_TAG_ON_SCALAR: Code = Code(1008);
335/// A core tag that does not match the collection it is on, e.g. `!!str [a]`
336/// or `!!map [a]` (§10). Error.
337pub const WRONG_TAG_ON_COLLECTION: Code = Code(1009);
338/// JSON schema: a plain scalar matching none of the JSON patterns
339/// (§10.2.2). Error.
340pub const JSON_UNMATCHED_SCALAR: Code = Code(1010);
341/// A combination of settings in which a setting has no effect.
342/// Warning.
343pub const MEANINGLESS_SETTINGS: Code = Code(1011);
344/// A combination of settings that would produce incorrect results.
345/// Error.
346pub const INCORRECT_SETTINGS: Code = Code(1012);
347/// A mapping key that is equal to an earlier key of the same mapping
348/// (§3.2.1.1). Error.
349pub const DUPLICATE_KEY: Code = Code(1013);
350/// A duplicate mapping key tolerated by `DuplicateKeys::LastWins`: the
351/// last value wins; a secondary label points at the first definition.
352/// Warning.
353pub const DUPLICATE_KEY_LAST_WINS: Code = Code(1014);
354/// An alias whose anchor is not defined earlier in the document, or whose
355/// anchored node is not complete yet (a recursive alias) (§7.1). Error.
356pub const UNDEFINED_ALIAS: Code = Code(1015);
357/// A merge key (`<<`, with `merge_keys` on) whose value is not a mapping or
358/// a sequence of mappings (yaml.org/type/merge). Error.
359pub const INVALID_MERGE_VALUE: Code = Code(1016);
360/// A setting this version cannot honour, e.g. `Emit::line_width(Some(_))`
361/// (line wrapping is not implemented): refused rather than silently ignored.
362/// Error.
363pub const UNSUPPORTED_SETTING: Code = Code(1017);
364
365// ---------------------------------------------------------------------------
366// Y2000–Y2999: limits. The help of every limit diagnostic names the
367// exact setting to raise and its current value.
368// ---------------------------------------------------------------------------
369
370/// Collections nested deeper than `Limits::max_depth` (block and flow
371/// nesting combined). Error.
372pub const DEPTH_LIMIT_EXCEEDED: Code = Code(2000);
373/// A scalar value longer than `Limits::max_scalar_len` bytes. Error.
374pub const SCALAR_TOO_LONG: Code = Code(2001);
375/// Input larger than `Limits::max_document_size` bytes. Error.
376pub const DOCUMENT_TOO_LARGE: Code = Code(2002);
377/// A stream with more documents than `Limits::max_documents`. Error.
378pub const TOO_MANY_DOCUMENTS: Code = Code(2003);
379/// Alias expansion (including merge keys through aliases) produced more
380/// nodes than `Limits::alias_budget` allows; `Value` and serde only.
381/// Error.
382pub const ALIAS_BUDGET_EXCEEDED: Code = Code(2004);
383/// A `Value` consumed by the library (serialized, or deserialized into a
384/// type) nests deeper than `Limits::max_depth`. Error.
385///
386/// Reported by the serializer (`to_string`, `to_writer`, `Serializer`),
387/// which emits `Value`s iteratively; `Document` insertion reports it too.
388pub const VALUE_DEPTH_EXCEEDED: Code = Code(2005);
389/// Input with more elements (nodes, tokens, trivia) than a syntax tree's
390/// `u32` indices can address; the rest of the input is kept as skipped
391/// bytes, so the tree still round-trips. Error.
392pub const TREE_CAPACITY_EXCEEDED: Code = Code(2006);
393/// Deserializing into a *recursive user type* (e.g. `struct Tree(Vec<Tree>)`)
394/// nested deeper than `Limits::max_typed_depth`. serde's visitor
395/// model recurses once per level of such a type, so this bounds the native
396/// stack; `Value` targets are iterative and bounded only by `max_depth`.
397/// Also `Serialize for Value` into third-party serializers, which recurse
398/// once per level: values deeper than the default `max_typed_depth` (128)
399/// are refused. Error.
400pub const TYPED_DEPTH_EXCEEDED: Code = Code(2007);
401/// A `Value` converted to a `serde_json::Value` (feature `serde_json`)
402/// nests deeper than 128 levels. The bound is fixed, whatever `Limits`
403/// say: serde_json's recursion limit, and its `Value` drops recursively.
404/// Error.
405pub const JSON_DEPTH_EXCEEDED: Code = Code(2008);
406/// Alias expansion materialised more bytes than `Limits::alias_byte_budget`
407/// allows: scalar text, keys, and tags copied by expansion (merge keys
408/// through aliases included), each tag use's `%TAG` prefix, and `%TAG` tags
409/// joined into enum variant names; `Value` and serde only.
410/// Error.
411pub const ALIAS_BYTE_BUDGET_EXCEEDED: Code = Code(2009);
412/// More diagnostics than `Limits::max_diagnostics` were found: the list
413/// ends with this one summary, "N more diagnostics suppressed", located
414/// where the first suppressed one was. Not a problem of the
415/// input by itself: a warning, so a strict parse still fails only at an
416/// error. Warning.
417pub const DIAGNOSTICS_SUPPRESSED: Code = Code(2010);
418
419// ---------------------------------------------------------------------------
420// Y3000–Y3999: serde.
421// ---------------------------------------------------------------------------
422
423/// A node's type does not fit the target type, e.g. a mapping for a
424/// `String`, or a quoted scalar for a number. Error.
425pub const TYPE_MISMATCH: Code = Code(3000);
426/// An integer outside the range of the target integer type. Error.
427pub const INTEGER_OUT_OF_RANGE: Code = Code(3001);
428/// A mapping without a field the target struct requires. Error.
429pub const MISSING_FIELD: Code = Code(3002);
430/// An enum variant name the target enum does not have. Error.
431pub const UNKNOWN_VARIANT: Code = Code(3003);
432/// A custom error raised by the target type's `Deserialize` impl. Error.
433pub const CUSTOM: Code = Code(3004);
434/// A mapping key the target struct does not accept
435/// (`deny_unknown_fields`). Error.
436pub const UNKNOWN_FIELD: Code = Code(3005);
437/// A value of the right type that the target type rejects. Error.
438pub const INVALID_VALUE: Code = Code(3006);
439/// A sequence or mapping with a length the target type does not accept,
440/// e.g. a tuple of the wrong arity. Error.
441pub const INVALID_LENGTH: Code = Code(3007);
442/// A struct field given twice (as two keys that differ in YAML but name the
443/// same field). Error.
444pub const DUPLICATE_FIELD: Code = Code(3008);
445/// A single-document entry point (`from_str`, …) given a stream with more
446/// than one document; use the multi-document `Deserializer`. Error.
447pub const MULTIPLE_DOCUMENTS: Code = Code(3009);
448/// Reading the input failed (`from_reader`). Error.
449pub const IO_ERROR: Code = Code(3010);
450/// A document of a multi-document `Deserializer` used after the stream
451/// moved past it, or twice. Error.
452pub const DOCUMENT_UNAVAILABLE: Code = Code(3011);
453/// A custom error raised by the value's `Serialize` impl
454/// (`serde::ser::Error::custom`). Error.
455pub const SERIALIZE_CUSTOM: Code = Code(3012);
456/// Writing the output failed (`to_writer`, `Serializer`). Error.
457pub const WRITE_ERROR: Code = Code(3013);
458/// A mapping being serialized has two equal keys (e.g. a struct field and
459/// a flattened map entry with the same name); YAML 1.2 requires unique
460/// keys, so the output would not read back. Error.
461pub const SERIALIZE_DUPLICATE_KEY: Code = Code(3014);
462/// A value YAML output cannot represent so that it reads back as the same
463/// value: an empty or malformed tag, a tag on a tagged value, or a custom
464/// tag on a non-string scalar (a custom-tagged scalar always reads back as
465/// a string). Error.
466pub const UNREPRESENTABLE_VALUE: Code = Code(3015);
467/// A `Serialize` impl drove the serializer out of order, e.g. a map value
468/// without its key, or a key without a value. Error.
469pub const INVALID_SERIALIZE_CALLS: Code = Code(3016);
470/// A `Value` was serialized or deserialized by oneyaml's own `Serializer`
471/// or `Deserializer` from a thread-local destructor after oneyaml's own
472/// thread-local storage on that thread was destroyed: the value cannot be
473/// handed over between the `Value` and oneyaml (an error, never a
474/// panic or a wrong or lossy value). Serialize or deserialize before the
475/// thread shuts down (or deserialize into a typed target). Error.
476pub const THREAD_LOCAL_UNAVAILABLE: Code = Code(3017);
477/// A `Deserialize` impl ignored an error that oneyaml returned for a
478/// sequence or mapping it had started to read, then went on reading:
479/// the rest of that node was never read, so nothing after it can be read
480/// in step. Reported at the next read, or at the end of the
481/// document, located at the node whose error was ignored; the same for
482/// `from_str` and `from_value`. Propagate the error instead (`?`).
483/// Error.
484pub const READ_AFTER_IGNORED_ERROR: Code = Code(3018);
485
486// ---------------------------------------------------------------------------
487// Y9000–Y9999: reserved.
488// ---------------------------------------------------------------------------
489
490/// An internal invariant of the library was violated: the
491/// release-build outcome of a `debug_assert!`, reported in-band (an error
492/// event, or `Err(Internal)`) instead of a silently wrong result. Always a
493/// bug in oneyaml; please report it with the input. Error.
494pub const INTERNAL_ERROR: Code = Code(9000);
495/// A caller-supplied event stream violates the event contract, e.g. one
496/// passed to `SyntaxTree::from_events` after filtering or reordering the
497/// parser's events. API misuse, not a bug in oneyaml: the result is built
498/// without panicking but may not round-trip. Error.
499pub const INVALID_EVENT_STREAM: Code = Code(9001);
500
501macro_rules! error_entry {
502    ($code:ident, $summary:literal) => {
503        CodeInfo {
504            code: $code,
505            name: stringify!($code),
506            severity: Severity::Error,
507            summary: $summary,
508            deprecated: false,
509        }
510    };
511}
512
513macro_rules! warning_entry {
514    ($code:ident, $summary:literal) => {
515        CodeInfo {
516            code: $code,
517            name: stringify!($code),
518            severity: Severity::Warning,
519            summary: $summary,
520            deprecated: false,
521        }
522    };
523}
524
525/// Every allocated code, in numeric order.
526pub const REGISTRY: &[CodeInfo] = &[
527    error_entry!(
528        DIRECTIVE_WITHOUT_DOCUMENT,
529        "directives not followed by an explicit document start"
530    ),
531    error_entry!(MALFORMED_DIRECTIVE, "malformed directive"),
532    error_entry!(
533        DIRECTIVE_IN_DOCUMENT,
534        "directive inside a document not ended with `...`"
535    ),
536    error_entry!(
537        CONTENT_AFTER_DOCUMENT,
538        "content after the document's root node or end marker"
539    ),
540    error_entry!(INVALID_INDENTATION, "content at an invalid indentation"),
541    error_entry!(
542        BLOCK_COLLECTION_NOT_ALLOWED,
543        "block collection cannot start on this line"
544    ),
545    error_entry!(
546        MULTILINE_IMPLICIT_KEY,
547        "implicit mapping key spans more than one line"
548    ),
549    error_entry!(INVALID_NODE_START, "character cannot start a node"),
550    error_entry!(UNTERMINATED_QUOTED_SCALAR, "quoted scalar not closed"),
551    error_entry!(
552        INVALID_ESCAPE,
553        "invalid escape sequence in a double-quoted scalar"
554    ),
555    error_entry!(
556        QUOTED_SCALAR_INDENTATION,
557        "quoted scalar continuation line not indented enough"
558    ),
559    error_entry!(INVALID_ANCHOR, "empty or malformed anchor or alias name"),
560    error_entry!(INVALID_TAG, "malformed tag"),
561    error_entry!(ALIAS_WITH_PROPERTIES, "alias node with an anchor or tag"),
562    error_entry!(DUPLICATE_PROPERTY, "node with more than one anchor or tag"),
563    error_entry!(TAB_INDENTATION, "tab character used as block indentation"),
564    error_entry!(
565        UNEXPECTED_CONTENT,
566        "unexpected content after a node on the same line"
567    ),
568    error_entry!(MISSING_MAPPING_COLON, "block mapping entry without `:`"),
569    CodeInfo {
570        code: UNSUPPORTED_SYNTAX,
571        name: "UNSUPPORTED_SYNTAX",
572        severity: Severity::Error,
573        summary: "syntax not yet supported by this parser version",
574        deprecated: true,
575    },
576    error_entry!(INVALID_BLOCK_HEADER, "malformed block scalar header"),
577    error_entry!(
578        BLOCK_SCALAR_INDENTATION,
579        "block scalar leading empty line indented more than its content"
580    ),
581    error_entry!(UNTERMINATED_FLOW_COLLECTION, "flow collection not closed"),
582    error_entry!(
583        MISSING_FLOW_SEPARATOR,
584        "flow collection entries not separated by `,`"
585    ),
586    error_entry!(
587        UNEXPECTED_FLOW_INDICATOR,
588        "flow indicator where it cannot appear"
589    ),
590    error_entry!(
591        IMPLICIT_KEY_TOO_LONG,
592        "implicit key longer than 1024 characters"
593    ),
594    error_entry!(
595        INVALID_QUOTED_CHARACTER,
596        "character not allowed in a quoted scalar"
597    ),
598    error_entry!(
599        INLINE_COLON_IN_PLAIN_VALUE,
600        "`: ` inside an unquoted block mapping value"
601    ),
602    warning_entry!(
603        LENIENT_INLINE_COLON,
604        "`: ` inside an unquoted block mapping value read as text (lenient_inline_colons)"
605    ),
606    error_entry!(INVALID_UTF8, "invalid UTF-8 in the input"),
607    error_entry!(INVALID_UTF16, "invalid UTF-16 in the input"),
608    error_entry!(INVALID_UTF32, "invalid UTF-32 in the input"),
609    error_entry!(
610        MISPLACED_BYTE_ORDER_MARK,
611        "byte order mark where no document prefix may start"
612    ),
613    error_entry!(
614        DUPLICATE_YAML_DIRECTIVE,
615        "more than one %YAML directive for a document"
616    ),
617    error_entry!(
618        INVALID_COMMENT_CHARACTER,
619        "non-printable character in a comment"
620    ),
621    error_entry!(
622        UNDECLARED_TAG_HANDLE,
623        "tag handle not declared by a %TAG directive"
624    ),
625    CodeInfo {
626        code: YAML_VERSION_1_1,
627        name: "YAML_VERSION_1_1",
628        severity: Severity::Warning,
629        summary: "%YAML 1.1 directive",
630        deprecated: false,
631    },
632    CodeInfo {
633        code: YAML_VERSION_NEWER_MINOR,
634        name: "YAML_VERSION_NEWER_MINOR",
635        severity: Severity::Warning,
636        summary: "%YAML 1.x (x > 2) document processed as YAML 1.2",
637        deprecated: false,
638    },
639    CodeInfo {
640        code: YAML_VERSION_UNSUPPORTED_MAJOR,
641        name: "YAML_VERSION_UNSUPPORTED_MAJOR",
642        severity: Severity::Error,
643        summary: "unsupported %YAML major version",
644        deprecated: false,
645    },
646    CodeInfo {
647        code: RESERVED_DIRECTIVE_IGNORED,
648        name: "RESERVED_DIRECTIVE_IGNORED",
649        severity: Severity::Warning,
650        summary: "reserved directive ignored",
651        deprecated: false,
652    },
653    error_entry!(DUPLICATE_DIRECTIVE, "%TAG handle declared twice"),
654    CodeInfo {
655        code: UNDEFINED_TAG_HANDLE,
656        name: "UNDEFINED_TAG_HANDLE",
657        severity: Severity::Error,
658        summary: "tag handle not declared by a %TAG directive",
659        deprecated: true,
660    },
661    CodeInfo {
662        code: YAML_VERSION_1_0,
663        name: "YAML_VERSION_1_0",
664        severity: Severity::Warning,
665        summary: "%YAML 1.0 directive",
666        deprecated: false,
667    },
668    error_entry!(
669        INVALID_SCALAR_FOR_TAG,
670        "scalar is not a valid form of its tag"
671    ),
672    error_entry!(COLLECTION_TAG_ON_SCALAR, "collection tag on a scalar"),
673    error_entry!(
674        WRONG_TAG_ON_COLLECTION,
675        "tag does not match the collection kind"
676    ),
677    error_entry!(
678        JSON_UNMATCHED_SCALAR,
679        "plain scalar matches no JSON schema type"
680    ),
681    warning_entry!(
682        MEANINGLESS_SETTINGS,
683        "setting has no effect in this combination"
684    ),
685    error_entry!(
686        INCORRECT_SETTINGS,
687        "settings combination gives incorrect results"
688    ),
689    error_entry!(DUPLICATE_KEY, "duplicate mapping key"),
690    warning_entry!(
691        DUPLICATE_KEY_LAST_WINS,
692        "duplicate mapping key, last value wins (DuplicateKeys::LastWins)"
693    ),
694    error_entry!(
695        UNDEFINED_ALIAS,
696        "alias to an undefined or incomplete anchor"
697    ),
698    error_entry!(
699        INVALID_MERGE_VALUE,
700        "merge key value is not a mapping or a sequence of mappings"
701    ),
702    error_entry!(UNSUPPORTED_SETTING, "setting not supported by this version"),
703    error_entry!(
704        DEPTH_LIMIT_EXCEEDED,
705        "nesting deeper than Limits::max_depth"
706    ),
707    error_entry!(SCALAR_TOO_LONG, "scalar longer than Limits::max_scalar_len"),
708    error_entry!(
709        DOCUMENT_TOO_LARGE,
710        "input larger than Limits::max_document_size"
711    ),
712    error_entry!(
713        TOO_MANY_DOCUMENTS,
714        "more documents than Limits::max_documents"
715    ),
716    error_entry!(
717        ALIAS_BUDGET_EXCEEDED,
718        "alias expansion larger than Limits::alias_budget"
719    ),
720    error_entry!(
721        VALUE_DEPTH_EXCEEDED,
722        "Value nests deeper than Limits::max_depth"
723    ),
724    error_entry!(
725        TREE_CAPACITY_EXCEEDED,
726        "input has more elements than a syntax tree can index"
727    ),
728    error_entry!(
729        TYPED_DEPTH_EXCEEDED,
730        "recursive target type nests deeper than Limits::max_typed_depth"
731    ),
732    error_entry!(
733        JSON_DEPTH_EXCEEDED,
734        "JSON output nests deeper than 128 levels"
735    ),
736    error_entry!(
737        ALIAS_BYTE_BUDGET_EXCEEDED,
738        "alias expansion larger than Limits::alias_byte_budget"
739    ),
740    warning_entry!(
741        DIAGNOSTICS_SUPPRESSED,
742        "more diagnostics than Limits::max_diagnostics; the rest are counted, not kept"
743    ),
744    error_entry!(TYPE_MISMATCH, "node type does not fit the target type"),
745    error_entry!(
746        INTEGER_OUT_OF_RANGE,
747        "integer out of range for the target type"
748    ),
749    error_entry!(MISSING_FIELD, "missing struct field"),
750    error_entry!(UNKNOWN_VARIANT, "unknown enum variant"),
751    error_entry!(CUSTOM, "error raised by the target type"),
752    error_entry!(UNKNOWN_FIELD, "unknown struct field"),
753    error_entry!(INVALID_VALUE, "value rejected by the target type"),
754    error_entry!(
755        INVALID_LENGTH,
756        "collection length rejected by the target type"
757    ),
758    error_entry!(DUPLICATE_FIELD, "struct field given twice"),
759    error_entry!(
760        MULTIPLE_DOCUMENTS,
761        "more than one document for a single-document entry point"
762    ),
763    error_entry!(IO_ERROR, "I/O error while reading the input"),
764    error_entry!(
765        DOCUMENT_UNAVAILABLE,
766        "document no longer available from the multi-document deserializer"
767    ),
768    error_entry!(
769        SERIALIZE_CUSTOM,
770        "error raised by the value's Serialize impl"
771    ),
772    error_entry!(WRITE_ERROR, "I/O error while writing the output"),
773    error_entry!(
774        SERIALIZE_DUPLICATE_KEY,
775        "serialized mapping has two equal keys"
776    ),
777    error_entry!(
778        UNREPRESENTABLE_VALUE,
779        "value cannot be represented in YAML output"
780    ),
781    error_entry!(
782        INVALID_SERIALIZE_CALLS,
783        "Serialize impl drove the serializer out of order"
784    ),
785    error_entry!(
786        THREAD_LOCAL_UNAVAILABLE,
787        "Value serialized or deserialized during thread-local storage teardown"
788    ),
789    error_entry!(
790        READ_AFTER_IGNORED_ERROR,
791        "deserializer used after one of its errors was ignored"
792    ),
793    error_entry!(INTERNAL_ERROR, "internal error (a bug in oneyaml)"),
794    error_entry!(
795        INVALID_EVENT_STREAM,
796        "caller-supplied event stream violates the event contract"
797    ),
798];
799
800#[cfg(test)]
801mod tests {
802    #![allow(clippy::unwrap_used, clippy::indexing_slicing)]
803
804    use super::*;
805
806    const RANGES: [CodeRange; 5] = [
807        CodeRange::Syntax,
808        CodeRange::Schema,
809        CodeRange::Limits,
810        CodeRange::Serde,
811        CodeRange::Reserved,
812    ];
813
814    #[test]
815    fn debug_matches_display() {
816        assert_eq!(format!("{INVALID_INDENTATION:?}"), "Y0005");
817        assert_eq!(format!("{:?}", Some(INVALID_INDENTATION)), "Some(Y0005)");
818        for info in REGISTRY {
819            assert_eq!(format!("{:?}", info.code), info.code.to_string());
820        }
821    }
822
823    #[test]
824    fn registry_is_sequential_within_each_range() {
825        for range in RANGES {
826            let (lo, _) = range.bounds();
827            let codes: Vec<u16> = REGISTRY
828                .iter()
829                .filter(|i| i.code.range() == range)
830                .map(|i| i.code.get())
831                .collect();
832            let expected: Vec<u16> = (0..codes.len())
833                .map(|k| lo.max(1).checked_add(u16::try_from(k).unwrap()).unwrap())
834                .collect();
835            // Retired codes are flagged, never removed, so every range stays
836            // contiguous: a new code is always max + 1.
837            assert_eq!(codes, expected, "{range:?} codes are contiguous");
838        }
839    }
840
841    #[test]
842    fn registry_is_sorted_unique_and_named() {
843        for pair in REGISTRY.windows(2) {
844            assert!(pair[0].code < pair[1].code);
845        }
846        for info in REGISTRY {
847            assert_eq!(info.code.info(), Some(info));
848            assert!(!info.summary.is_empty());
849            assert!(!info.name.is_empty());
850        }
851    }
852
853    #[test]
854    fn range_validation() {
855        assert_eq!(Code::new(0), None);
856        assert_eq!(Code::new(1).unwrap().range(), CodeRange::Syntax);
857        assert_eq!(Code::new(999).unwrap().range(), CodeRange::Syntax);
858        assert_eq!(Code::new(1000).unwrap().range(), CodeRange::Schema);
859        assert_eq!(Code::new(2500).unwrap().range(), CodeRange::Limits);
860        assert_eq!(Code::new(3999).unwrap().range(), CodeRange::Serde);
861        assert_eq!(Code::new(4000), None);
862        assert_eq!(Code::new(8999), None);
863        assert_eq!(Code::new(9000).unwrap().range(), CodeRange::Reserved);
864        assert_eq!(Code::new(10000), None);
865        for range in RANGES {
866            let (lo, hi) = range.bounds();
867            assert!(lo <= hi);
868            assert_eq!(Code::new(hi).unwrap().range(), range);
869        }
870    }
871
872    #[test]
873    fn display_and_parse_round_trip() {
874        assert_eq!(YAML_VERSION_1_1.to_string(), "Y1000");
875        assert_eq!(Code::new(7).unwrap().to_string(), "Y0007");
876        assert_eq!(Code::parse("Y1003"), Some(RESERVED_DIRECTIVE_IGNORED));
877        assert_eq!(Code::parse("Y0007"), Code::new(7));
878        for bad in [
879            "", "Y", "Y0000", "Y123", "Y12345", "X1000", "Y10a0", "Y5000",
880        ] {
881            assert_eq!(Code::parse(bad), None, "{bad}");
882        }
883        assert_eq!(Code::new(999).unwrap().info(), None);
884    }
885}