Pure OCaml Yaml 1.2 reader and writer using Bytesrw
anil.recoil.org
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** {1 Error Handling}
7
8 Comprehensive error reporting for YAML parsing and emission.
9
10 This module provides detailed error types that correspond to various
11 failure modes in YAML processing, as specified in the
12 {{:https://yaml.org/spec/1.2.2/}YAML 1.2.2 specification}. *)
13
14(** {2 Error Classification} *)
15
16type kind =
17 (* Scanner errors *)
18 | Unexpected_character of char
19 | Unexpected_eof
20 | Invalid_escape_sequence of string
21 | Invalid_unicode_escape of string
22 | Invalid_hex_escape of string
23 | Invalid_tag of string
24 | Invalid_anchor of string
25 | Invalid_alias of string
26 | Invalid_comment
27 | Unclosed_single_quote
28 | Unclosed_double_quote
29 | Unclosed_flow_sequence
30 | Unclosed_flow_mapping
31 | Invalid_indentation of int * int
32 | Invalid_flow_indentation
33 | Tab_in_indentation
34 | Invalid_block_scalar_header of string
35 | Invalid_quoted_scalar_indentation of string
36 | Invalid_directive of string
37 | Invalid_yaml_version of string
38 | Invalid_tag_directive of string
39 | Reserved_directive of string
40 | Illegal_flow_key_line
41 | Block_sequence_disallowed
42
43 (* Parser errors *)
44 | Unexpected_token of string
45 | Expected_document_start
46 | Expected_document_end
47 | Expected_block_entry
48 | Expected_key
49 | Expected_value
50 | Expected_node
51 | Expected_scalar
52 | Expected_sequence_end
53 | Expected_mapping_end
54 | Duplicate_anchor of string
55 | Undefined_alias of string
56 | Alias_cycle of string
57 | Multiple_documents
58 | Mapping_key_too_long
59
60 (* Loader errors *)
61 | Invalid_scalar_conversion of string * string
62 | Type_mismatch of string * string
63 | Unresolved_alias of string
64 | Key_not_found of string
65 | Alias_expansion_node_limit of int
66 | Alias_expansion_depth_limit of int
67
68 (* Emitter errors *)
69 | Invalid_encoding of string
70 | Scalar_contains_invalid_chars of string
71 | Anchor_not_set
72 | Invalid_state of string
73
74 (* Generic *)
75 | Custom of string
76
77(** {2 Error Value} *)
78
79type t = {
80 kind : kind;
81 span : Span.t option;
82 context : string list;
83 source : string option;
84}
85
86(** {2 Exception} *)
87
88exception Yamlrw_error of t
89(** The main exception type raised by all yamlrw operations. *)
90
91(** {2 Error Construction} *)
92
93val make : ?span:Span.t -> ?context:string list -> ?source:string -> kind -> t
94(** Construct an error value. *)
95
96val raise : ?span:Span.t -> ?context:string list -> ?source:string -> kind -> 'a
97(** Construct and raise an error. *)
98
99val raise_at : Position.t -> kind -> 'a
100(** Raise an error at a specific position. *)
101
102val raise_span : Span.t -> kind -> 'a
103(** Raise an error at a specific span. *)
104
105val with_context : string -> (unit -> 'a) -> 'a
106(** Execute a function and add context to any raised error. *)
107
108(** {2 Error Formatting} *)
109
110val kind_to_string : kind -> string
111(** Convert an error kind to a human-readable string. *)
112
113val to_string : t -> string
114(** Convert an error to a human-readable string. *)
115
116val pp : Format.formatter -> t -> unit
117(** Pretty-print an error. *)
118
119val pp_with_source : source:string -> Format.formatter -> t -> unit
120(** Pretty-print an error with source context. *)