(** Error types and exception handling for GPX operations *)

(** Main error type *)
type t =
  | Invalid_xml of string                          (** XML parsing/structure error *)
  | Invalid_coordinate of string                   (** Coordinate validation error *)
  | Missing_required_attribute of string * string (** Missing XML attribute (element, attr) *)
  | Missing_required_element of string             (** Missing XML element *)
  | Validation_error of string                     (** GPX validation error *)
  | Xml_error of string                           (** Lower-level XML error *)
  | IO_error of string                            (** File I/O error *)

(** GPX exception *)
exception Gpx_error of t

(** Result type for operations that can fail *)
type 'a result = ('a, t) Result.t

(** {2 Error Operations} *)

(** Convert error to human-readable string *)
val to_string : t -> string

(** Pretty print error *)
val pp : Format.formatter -> t -> unit

(** Compare errors *)
val compare : t -> t -> int

(** Test error equality *)
val equal : t -> t -> bool

(** {2 Error Constructors} *)

(** Create invalid XML error *)
val invalid_xml : string -> t

(** Create invalid coordinate error *)
val invalid_coordinate : string -> t

(** Create missing attribute error *)
val missing_attribute : string -> string -> t

(** Create missing element error *)
val missing_element : string -> t

(** Create validation error *)
val validation_error : string -> t

(** Create XML error *)
val xml_error : string -> t

(** Create IO error *)
val io_error : string -> t

(** {2 Result Helpers} *)

(** Convert exception to result *)
val catch : ('a -> 'b) -> 'a -> 'b result

(** Convert result to exception *)
val get_exn : 'a result -> 'a

(** Map over result *)
val map : ('a -> 'b) -> 'a result -> 'b result

(** Bind over result *)
val bind : 'a result -> ('a -> 'b result) -> 'b result

(** Convert string result to error result *)
val from_string_result : ('a, string) Result.t -> 'a result

(** {2 Error Classification} *)

(** Check if error is XML-related *)
val is_xml_error : t -> bool

(** Check if error is coordinate-related *)
val is_coordinate_error : t -> bool

(** Check if error is validation-related *)
val is_validation_error : t -> bool

(** Check if error is IO-related *)
val is_io_error : t -> bool