(***********************************************************************)
(*                                                                     *)
(*                               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.                                                        *)
(*                                                                     *)
(***********************************************************************)

(** Implementation of documents as binary trees *)

type node
(** The type of a tree node *)

type t
(** The type of trees *)

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 preorder : t -> node -> int
(** Returns the position of a node in pre-order in the tree. The
    root has preorder 0. [nil] has pre-order [-1].
*)