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}