src/tree.ml

   1 (***********************************************************************)
   2 (*                                                                     *)
   3 (*                               TAToo                                 *)
   4 (*                                                                     *)
   5 (*                     Kim Nguyen, LRI UMR8623                         *)
   6 (*                   Université Paris-Sud & CNRS                       *)
   7 (*                                                                     *)
   8 (*  Copyright 2010-2012 Université Paris-Sud and Centre National de la *)
   9 (*  Recherche Scientifique. All rights reserved.  This file is         *)
  10 (*  distributed under the terms of the GNU Lesser General Public       *)
  11 (*  License, with the special exception on linking described in file   *)
  12 (*  ../LICENSE.                                                        *)
  13 (*                                                                     *)
  14 (***********************************************************************)
  15
  16 (** The different kind of XML nodes and utility functions *)
  17
  18 module NodeKind =
  19   struct
  20     type t =
  21       Document | Element | Text | Comment | Attribute
  22     | ProcessingInstruction | Node
  23
  24     let to_string =
  25       function
  26     Document -> "document"
  27     | Element -> "element"
  28     | Attribute -> "attribute"
  29     | Text -> "text"
  30     | Comment -> "comment"
  31     | ProcessingInstruction -> "processing-instruction"
  32     | Node -> "node"
  33
  34     let print ppf k = Format.fprintf ppf "%s" (to_string k)
  35
  36
  37     let is_a k1 k2 =
  38       k1 == Node || k2 == Node || k1 == k2
  39 end
  40
  41 (** Signatures for trees *)
  42
  43 exception Parse_error of string
  44
  45 module type S =
  46 sig
  47   type node
  48   (** The type of a tree node *)
  49
  50   type t
  51   (** The type of trees *)
  52
  53   val size : t -> int
  54   (** Return the number of nodes *)
  55
  56   val nil : node
  57   (** Nil node, denoting the first/second child of a leaf or the parent of
  58       the root *)
  59
  60   val dummy : node
  61   (** Dummy node that is guaranteed to never occur in any tree *)
  62
  63   val load_xml_file : in_channel -> t
  64   (** Takes a file descriptor and returns the XML data stored in the
  65       corresponding file. Start at the current position in the file
  66       descriptor (which is not necessarily the begining of file)
  67   *)
  68
  69   val load_xml_string : string -> t
  70   (** Loads XML data stored in a string *)
  71
  72   val print_xml : out_channel -> t -> node -> unit
  73   (** Outputs the tree as an XML document on the given output_channel *)
  74
  75   val root : t -> node
  76   (** Returns the root of the tree *)
  77
  78   val first_child : t -> node -> node
  79   (** [first_child t n] returns the first child of node [n] in tree [t].
  80       Returns [nil] if [n] is a leaf. Returns [nil] if [n == nil].
  81   *)
  82
  83   val next_sibling : t -> node -> node
  84   (** [next_sibling t n] returns the next_sibling of node [n] in tree [t].
  85       Returns [nil] if [n] is the last child of a node.
  86       Returns [nil] if [n == nil].
  87   *)
  88
  89   val parent : t -> node -> node
  90   (** [next_sibling t n] returns the parent of node [n] in tree [t].
  91       Returns [nil] if [n] is the root of the tree.
  92       Returns [nil] if [n == nil].
  93   *)
  94
  95   val tag : t -> node -> QName.t
  96   (** Returns the label of a given node *)
  97
  98   val data : t -> node -> string
  99   (** Returns the character data associated with a node.
 100       The only node having character data are those whose label is
 101       QName.text, QName.cdata_section or QName.comment
 102   *)
 103
 104   val kind : t -> node -> NodeKind.t
 105   (** Returns the kind of the given node *)
 106
 107   val preorder : t -> node -> int
 108   (** [preorder t n] returns the pre-order position of [n] in [t].
 109       [preodrder t (root t) == 0] and [preorder t nil < 0].
 110   *)
 111
 112   val by_preorder : t -> int -> node
 113   (** [by_preorder t i] returns the node with preorder [i]
 114   *)
 115   val print_node : Format.formatter -> node -> unit
 116
 117   val is_first_child : t -> node -> bool
 118   val is_next_sibling : t -> node -> bool
 119   val prev_sibling : t -> node -> node
 120  (** [prev_sibling t n] returns the previous_sibling of node [n] in tree [t].
 121       Returns [nil] if [n] is the first child of a node.
 122   *)
 123   val parent_of_first : t -> node -> node
 124  (** [parent_of_first t n] returns the parent of node [n] in tree [t] .
 125       Returns [nil] if [n] isn't the first child of a node.
 126   *)
 127 end