more errors

lib/html5rw/html5rw.ml

···
     ]}
 *)
 
+(** {1 Error Handling} *)
+
+(** Global error type that wraps all errors raised by the Html5rw library.
+
+    This provides a unified error type for all parsing and selector errors,
+    along with printers for display and debugging.
+*)
+module Error = struct
+  (** The unified error type for the Html5rw library. *)
+  type t =
+    | Parse_error of {
+        code : Parse_error_code.t;
+        line : int;
+        column : int;
+      }
+        (** An HTML parse error, including location information. *)
+    | Selector_error of Selector.Error_code.t
+        (** A CSS selector parse error. *)
+
+  let of_parse_error (err : Parser.parse_error) : t =
+    Parse_error {
+      code = Parser.error_code err;
+      line = Parser.error_line err;
+      column = Parser.error_column err;
+    }
+
+  let of_selector_error (code : Selector.Error_code.t) : t =
+    Selector_error code
+
+  let to_string = function
+    | Parse_error { code; line; column } ->
+        Printf.sprintf "Parse error at %d:%d: %s" line column
+          (Parse_error_code.to_string code)
+    | Selector_error code ->
+        Printf.sprintf "Selector error: %s"
+          (Selector.Error_code.to_human_string code)
+
+  let pp fmt err = Format.pp_print_string fmt (to_string err)
+
+  (** Get the error code as a kebab-case string. *)
+  let code_string = function
+    | Parse_error { code; _ } -> Parse_error_code.to_string code
+    | Selector_error code -> Selector.Error_code.to_string code
+end
+
 (** {1 Sub-modules} *)
 
 (** Parse error code types *)

lib/html5rw/html5rw.mli

···
     Column numbers count from 1 and reset at each newline. *)
 val error_column : parse_error -> int
 
+(** {1 Error Handling} *)
+
+(** Global error type that wraps all errors raised by the Html5rw library.
+
+    This module provides a unified error type for all parsing and selector
+    errors, along with printers and conversion functions. Use this when you
+    want to handle all possible errors from the library in a uniform way.
+
+    {2 Usage}
+
+    {[
+      (* Converting parse errors *)
+      let errors = Html5rw.errors result in
+      List.iter (fun err ->
+        let unified = Html5rw.Error.of_parse_error err in
+        Printf.eprintf "%s\n" (Html5rw.Error.to_string unified)
+      ) errors
+
+      (* Catching selector errors *)
+      match Html5rw.query result selector with
+      | nodes -> (* success *)
+      | exception Html5rw.Selector.Selector_error code ->
+        let unified = Html5rw.Error.of_selector_error code in
+        Printf.eprintf "%s\n" (Html5rw.Error.to_string unified)
+    ]}
+*)
+module Error : sig
+  (** The unified error type for the Html5rw library. *)
+  type t =
+    | Parse_error of {
+        code : Parse_error_code.t;
+        line : int;
+        column : int;
+      }
+        (** An HTML parse error, including location information.
+
+            Parse errors occur during HTML tokenization and tree construction.
+            The location indicates where in the input the error was detected.
+
+            @see <https://html.spec.whatwg.org/multipage/parsing.html#parse-errors>
+                 WHATWG: Parse errors *)
+
+    | Selector_error of Selector.Error_code.t
+        (** A CSS selector parse error.
+
+            Selector errors occur when parsing malformed CSS selectors passed
+            to {!query} or {!matches}. *)
+
+  val of_parse_error : parse_error -> t
+  (** Convert a parse error to the unified error type.
+
+      {[
+        let errors = Html5rw.errors result in
+        let unified_errors = List.map Html5rw.Error.of_parse_error errors
+      ]} *)
+
+  val of_selector_error : Selector.Error_code.t -> t
+  (** Convert a selector error code to the unified error type.
+
+      {[
+        match Html5rw.query result "invalid[" with
+        | _ -> ()
+        | exception Html5rw.Selector.Selector_error code ->
+          let err = Html5rw.Error.of_selector_error code in
+          Printf.eprintf "%s\n" (Html5rw.Error.to_string err)
+      ]} *)
+
+  val to_string : t -> string
+  (** Convert to a human-readable error message with location information.
+
+      Examples:
+      - ["Parse error at 5:12: unexpected-null-character"]
+      - ["Selector error: Expected \]"] *)
+
+  val pp : Format.formatter -> t -> unit
+  (** Pretty-printer for use with [Format] functions. *)
+
+  val code_string : t -> string
+  (** Get just the error code as a kebab-case string (without location).
+
+      This is useful for programmatic error handling or logging.
+
+      Examples:
+      - ["unexpected-null-character"]
+      - ["expected-closing-bracket"] *)
+end
+
+(** {1 Fragment Parsing} *)
+
 (** Context element for HTML fragment parsing (innerHTML).
 
     When parsing HTML fragments (like the [innerHTML] of an element), you

lib/html5rw/selector/selector.ml

···
     ]}
 *)
 
+(** {1 Error Types} *)
+
+(** CSS selector error codes. *)
+module Error_code = Selector_error_code
+
 (** {1 Exceptions} *)
 
 (** Raised when a selector string is malformed.
 
-    The exception contains an error message describing the parse error.
+    The exception contains a typed error code describing the parse error.
 *)
 exception Selector_error = Selector_lexer.Selector_error
 

lib/html5rw/selector/selector.mli

···
     ]}
 *)
 
+(** {1 Error Types} *)
+
+(** CSS selector error codes.
+
+    This module provides the {!Error_code.t} variant type that represents
+    all possible errors when parsing CSS selectors.
+*)
+module Error_code : sig
+  type t =
+    | Empty_selector
+        (** The selector string was empty or contained only whitespace. *)
+    | Unterminated_string
+        (** A quoted string was not closed before end of input. *)
+    | Unterminated_escape
+        (** An escape sequence was not completed before end of input. *)
+    | Expected_identifier_after_hash
+        (** Expected an identifier after [#] for ID selector. *)
+    | Expected_identifier_after_dot
+        (** Expected an identifier after [.] for class selector. *)
+    | Expected_attribute_name
+        (** Expected an attribute name inside an attribute selector. *)
+    | Expected_closing_bracket
+        (** Expected [\]] to close an attribute selector. *)
+    | Expected_equals_after_operator of char
+        (** Expected [=] after an attribute operator like [~], [|], [^], [$], or [*]. *)
+    | Unexpected_character_in_attribute_selector
+        (** Found an unexpected character inside an attribute selector. *)
+    | Expected_pseudo_class_name
+        (** Expected a pseudo-class name after [:]. *)
+    | Expected_closing_paren
+        (** Expected [)] to close a pseudo-class argument. *)
+    | Unexpected_character of char
+        (** Found an unexpected character in the selector. *)
+    | Expected_attribute_value
+        (** Expected a value after the attribute operator. *)
+    | Expected_closing_bracket_or_operator
+        (** Expected [\]] or an attribute operator like [=]. *)
+    | Expected_selector_after_combinator
+        (** Expected a selector after a combinator ([>], [+], [~], or space). *)
+    | Unexpected_token
+        (** Found an unexpected token in the selector. *)
+    | Expected_end_of_selector
+        (** Expected end of selector but found more tokens. *)
+
+  val to_string : t -> string
+  (** Convert to a kebab-case string identifier suitable for programmatic use. *)
+
+  val to_human_string : t -> string
+  (** Convert to a human-readable error message. *)
+end
+
 (** {1 Exceptions} *)
 
-exception Selector_error of string
+exception Selector_error of Error_code.t
 (** Raised when a selector string is malformed.
 
-    The exception contains an error message describing the parse error.
+    The exception contains a typed error code describing the parse error.
+    Use {!Error_code.to_string} or {!Error_code.to_human_string} to get
+    a string representation.
 *)
 
 (** {1 Sub-modules} *)

lib/html5rw/selector/selector_lexer.ml

···
 (* CSS selector lexer *)
 
-exception Selector_error of string
+exception Selector_error of Selector_error_code.t
 
 type t = {
   input : string;
···
   let buf = Buffer.create 32 in
   let rec loop () =
     match peek t with
-    | None -> raise (Selector_error "Unterminated string")
+    | None -> raise (Selector_error Selector_error_code.Unterminated_string)
     | Some c when c = quote -> advance t
     | Some '\\' ->
       advance t;
       (match peek t with
        | Some c -> Buffer.add_char buf c; advance t; loop ()
-       | None -> raise (Selector_error "Unterminated escape"))
+       | None -> raise (Selector_error Selector_error_code.Unterminated_escape))
     | Some c ->
       Buffer.add_char buf c;
       advance t;
···
       | '#' ->
         advance t;
         let name = read_name t in
-        if name = "" then raise (Selector_error "Expected identifier after #");
+        if name = "" then raise (Selector_error Selector_error_code.Expected_identifier_after_hash);
         tokens := Selector_token.Id name :: !tokens
       | '.' ->
         advance t;
         let name = read_name t in
-        if name = "" then raise (Selector_error "Expected identifier after .");
+        if name = "" then raise (Selector_error Selector_error_code.Expected_identifier_after_dot);
         tokens := Selector_token.Class name :: !tokens
       | '[' ->
         advance t;
         tokens := Selector_token.Attr_start :: !tokens;
         skip_whitespace t;
         let attr_name = read_name t in
-        if attr_name = "" then raise (Selector_error "Expected attribute name");
+        if attr_name = "" then raise (Selector_error Selector_error_code.Expected_attribute_name);
         tokens := Selector_token.Tag attr_name :: !tokens;
         skip_whitespace t;
 
···
            in
            tokens := Selector_token.String value :: !tokens;
            skip_whitespace t;
-           if peek t <> Some ']' then raise (Selector_error "Expected ]");
+           if peek t <> Some ']' then raise (Selector_error Selector_error_code.Expected_closing_bracket);
            advance t;
            tokens := Selector_token.Attr_end :: !tokens
          | Some ('~' | '|' | '^' | '$' | '*') as op_char ->
            let op_c = Option.get op_char in
            advance t;
            if peek t <> Some '=' then
-             raise (Selector_error ("Expected = after " ^ String.make 1 op_c));
+             raise (Selector_error (Selector_error_code.Expected_equals_after_operator op_c));
            advance t;
            tokens := Selector_token.Attr_op (String.make 1 op_c ^ "=") :: !tokens;
            skip_whitespace t;
···
            in
            tokens := Selector_token.String value :: !tokens;
            skip_whitespace t;
-           if peek t <> Some ']' then raise (Selector_error "Expected ]");
+           if peek t <> Some ']' then raise (Selector_error Selector_error_code.Expected_closing_bracket);
            advance t;
            tokens := Selector_token.Attr_end :: !tokens
-         | _ -> raise (Selector_error "Unexpected character in attribute selector"))
+         | _ -> raise (Selector_error Selector_error_code.Unexpected_character_in_attribute_selector))
 
       | ',' ->
         advance t;
···
         advance t;
         tokens := Selector_token.Colon :: !tokens;
         let name = read_name t in
-        if name = "" then raise (Selector_error "Expected pseudo-class name");
+        if name = "" then raise (Selector_error Selector_error_code.Expected_pseudo_class_name);
         tokens := Selector_token.Tag name :: !tokens;
 
         if peek t = Some '(' then begin
···
           done;
           let arg = String.trim (String.sub t.input start (t.pos - start)) in
           if arg <> "" then tokens := Selector_token.String arg :: !tokens;
-          if peek t <> Some ')' then raise (Selector_error "Expected )");
+          if peek t <> Some ')' then raise (Selector_error Selector_error_code.Expected_closing_paren);
           advance t;
           tokens := Selector_token.Paren_close :: !tokens
         end
···
         let name = read_name t in
         tokens := Selector_token.Tag (String.lowercase_ascii name) :: !tokens
       | _ ->
-        raise (Selector_error ("Unexpected character: " ^ String.make 1 c))
+        raise (Selector_error (Selector_error_code.Unexpected_character c))
     end
   done;
 

lib/html5rw/selector/selector_parser.ml

···
 open Selector_ast
 open Selector_token
 
-exception Parse_error of string
+(* Re-use the Selector_error exception from the lexer for consistency *)
+let raise_error code = raise (Selector_lexer.Selector_error code)
 
 type t = {
   tokens : Selector_token.t list;
···
 let expect t expected =
   let tok = peek t in
   if tok <> expected then
-    raise (Parse_error ("Expected " ^ (match expected with EOF -> "EOF" | _ -> "token")))
+    raise_error (match expected with EOF -> Selector_error_code.Expected_end_of_selector | _ -> Selector_error_code.Unexpected_token)
   else
     advance t
 
···
     advance t;
     let attr_name = match peek t with
       | Tag name -> advance t; name
-      | _ -> raise (Parse_error "Expected attribute name")
+      | _ -> raise_error Selector_error_code.Expected_attribute_name
     in
     (match peek t with
      | Attr_end ->
···
        advance t;
        let value = match peek t with
          | String v -> advance t; v
-         | _ -> raise (Parse_error "Expected attribute value")
+         | _ -> raise_error Selector_error_code.Expected_attribute_value
        in
        (match peek t with
         | Attr_end -> advance t
-        | _ -> raise (Parse_error "Expected ]"));
+        | _ -> raise_error Selector_error_code.Expected_closing_bracket);
        Some (make_simple Type_attr ~name:attr_name ~operator:op ~value ())
-     | _ -> raise (Parse_error "Expected ] or attribute operator"))
+     | _ -> raise_error Selector_error_code.Expected_closing_bracket_or_operator)
   | Colon ->
     advance t;
     let name = match peek t with
       | Tag n -> advance t; n
-      | _ -> raise (Parse_error "Expected pseudo-class name")
+      | _ -> raise_error Selector_error_code.Expected_pseudo_class_name
     in
     let arg = match peek t with
       | Paren_open ->
···
         in
         (match peek t with
          | Paren_close -> advance t
-         | _ -> raise (Parse_error "Expected )"));
+         | _ -> raise_error Selector_error_code.Expected_closing_paren);
         a
       | _ -> None
     in
···
       | Combinator comb ->
         advance t;
         (match parse_compound_selector t with
-         | None -> raise (Parse_error "Expected selector after combinator")
+         | None -> raise_error Selector_error_code.Expected_selector_after_combinator
          | Some compound ->
            parts := (Some comb, compound) :: !parts;
            loop ())
···
          advance t;
          loop (sel :: acc)
        | EOF -> sel :: acc
-       | _ -> raise (Parse_error "Unexpected token"))
+       | _ -> raise_error Selector_error_code.Unexpected_token)
   in
   let selectors = List.rev (loop []) in
   (match peek t with
   | EOF -> ()
-  | _ -> raise (Parse_error "Expected end of selector"));
+  | _ -> raise_error Selector_error_code.Expected_end_of_selector);
   match selectors with
-  | [] -> raise (Parse_error "Empty selector")
+  | [] -> raise_error Selector_error_code.Empty_selector
   | [sel] -> Complex sel
   | sels -> List (make_list sels)
 
 let parse_selector input =
   if String.trim input = "" then
-    raise (Selector_lexer.Selector_error "Empty selector");
+    raise_error Selector_error_code.Empty_selector;
   let tokens = Selector_lexer.tokenize input in
   parse tokens