(*---------------------------------------------------------------------------
  Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
  SPDX-License-Identifier: MIT
 ---------------------------------------------------------------------------*)

(** CSS selector parse error codes.

    These represent all possible errors that can occur when parsing
    CSS selectors.
*)

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.

    Examples:
    - [to_string Empty_selector] returns ["empty-selector"]
    - [to_string (Unexpected_character 'x')] returns ["unexpected-character-x"]
*)

val to_human_string : t -> string
(** Convert to a human-readable error message.

    Examples:
    - [to_human_string Empty_selector] returns ["Empty selector"]
    - [to_human_string Expected_closing_bracket] returns ["Expected \]"]
*)

val pp : Format.formatter -> t -> unit
(** Pretty-print a selector error code using its kebab-case string form. *)