(***********************************************************************)
(*                                                                     *)
(*                               TAToo                                 *)
(*                                                                     *)
(*                     Kim Nguyen, LRI UMR8623                         *)
(*                   Université Paris-Sud & CNRS                       *)
(*                                                                     *)
(*  Copyright 2010-2012 Université Paris-Sud and Centre National de la *)
(*  Recherche Scientifique. All rights reserved.  This file is         *)
(*  distributed under the terms of the GNU Lesser General Public       *)
(*  License, with the special exception on linking described in file   *)
(*  ../LICENSE.                                                        *)
(*                                                                     *)
(***********************************************************************)

(** The different kind of XML nodes and utility functions *)

module NodeKind =
  struct
    type t =
        Document | Element | Text | Comment | Attribute | ProcessingInstruction | Node

    let to_string =
      function
    Document -> "document"
    | Element -> "element"
    | Attribute -> "attribute"
    | Text -> "text"
    | Comment -> "comment"
    | ProcessingInstruction -> "processing-instruction"
    | Node -> "node"

    let print ppf k = Format.fprintf ppf "%s" (to_string k)


    let is_a k1 k2 =
      k1 == Node || k2 == Node || k1 == k2
end

(** Signatures for trees *)

exception Parse_error of string

module type S =
sig
  type node
  (** The type of a tree node *)

  type t
  (** The type of trees *)

  val size : t -> int
  (** Return the number of nodes *)

  val nil : node
  (** Nil node, denoting the first/second child of a leaf or the parent of
      the root *)

  val dummy : node
  (** Dummy node that is guaranteed to never occur in any tree *)

  val load_xml_file : in_channel -> t
  (** Takes a file descriptor and returns the XML data stored in the
      corresponding file. Start at the current position in the file
      descriptor (which is not necessarily the begining of file)
  *)

  val load_xml_string : string -> t
  (** Loads XML data stored in a string *)

  val print_xml : out_channel -> t -> node -> unit
  (** Outputs the tree as an XML document on the given output_channel *)

  val root : t -> node
  (** Returns the root of the tree *)

  val first_child : t -> node -> node
  (** [first_child t n] returns the first child of node [n] in tree [t].
      Returns [nil] if [n] is a leaf. Returns [nil] if [n == nil].
  *)

  val next_sibling : t -> node -> node
  (** [next_sibling t n] returns the next_sibling of node [n] in tree [t].
      Returns [nil] if [n] is the last child of a node.
      Returns [nil] if [n == nil].
  *)

  val parent : t -> node -> node
  (** [next_sibling t n] returns the parent of node [n] in tree [t].
      Returns [nil] if [n] is the root of the tree.
      Returns [nil] if [n == nil].
  *)

  val tag : t -> node -> QName.t
  (** Returns the label of a given node *)

  val data : t -> node -> string
  (** Returns the character data associated with a node.
      The only node having character data are those whose label is
      QName.text, QName.cdata_section or QName.comment
  *)

  val kind : t -> node -> NodeKind.t
  (** Returns the kind of the given node *)

  val preorder : t -> node -> int
  (** [preorder t n] returns the pre-order position of [n] in [t].
      [preodrder t (root t) == 0] and [preorder t nil < 0].
  *)

  val by_preorder : t -> int -> node
  (** [by_preorder t i] returns the node with preorder [i]
  *)
  val print_node : Format.formatter -> node -> unit
end