src/utils/xml-light/xml.mli

   1 (*
   2  * Xml Light, an small Xml parser/printer with DTD support.
   3  * Copyright (C) 2003 Nicolas Cannasse (ncannasse@motion-twin.com)
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2.1 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General Public
  16  * License along with this library; if not, write to the Free Software
  17  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  18  *)
  19
  20 open Xml_types
  21
  22 (** Xml Light
  23
  24   Xml Light is a minimal Xml parser & printer for OCaml.
  25   It provide few functions to parse a basic Xml document into
  26   an OCaml data structure and to print back the data structures
  27   to an Xml document.
  28
  29   Xml Light has also support for {b DTD} (Document Type Definition).
  30
  31   {i (c)Copyright 2002-2003 Nicolas Cannasse}
  32 *)
  33
  34 (** {6 Xml Data Structure} *)
  35
  36 (** An Xml node is either
  37         [Element (tag-name, attributes, children)] or [PCData text] *)
  38
  39 (** {6 Xml Parsing} *)
  40
  41 (** For easily parsing an Xml data source into an xml data structure,
  42         you can use theses functions. But if you want advanced parsing usage,
  43         please look at the {!XmlParser} module.
  44         All the parsing functions can raise some exceptions, see the
  45         {{:#exc}Exceptions} section for more information. *)
  46
  47 (** Parse the named file into an Xml data structure. *)
  48 val parse_file : string -> xml
  49
  50 (** Read the content of the in_channel and parse it into an Xml data
  51  structure. *)
  52 val parse_in : in_channel -> xml
  53
  54 (** Parse the string containing an Xml document into an Xml data
  55  structure. *)
  56 val parse_string : string -> xml
  57
  58 (** {6:exc Xml Exceptions} *)
  59
  60 (** Several exceptions can be raised when parsing an Xml document : {ul
  61         {li {!Xml.Error} is raised when an xml parsing error occurs. the
  62                 {!Xml.error_msg} tells you which error occured during parsing
  63                 and the {!Xml.error_pos} can be used to retreive the document
  64                 location where the error occured at.}
  65         {li {!Xml.File_not_found} is raised when and error occured while
  66                 opening a file with the {!Xml.parse_file} function or when a
  67                 DTD file declared by the Xml document is not found {i (see the
  68                 {!XmlParser} module for more information on how to handle the
  69                 DTD file loading)}.}
  70         }
  71         If the Xml document is containing a DTD, then some other exceptions
  72         can be raised, see the module {!Dtd} for more information.
  73  *)
  74
  75 exception Error of error
  76
  77 exception File_not_found of string
  78
  79 (** Get a full error message from an Xml error. *)
  80 val error : error -> string
  81
  82 (** Get the Xml error message as a string. *)
  83 val error_msg : error_msg -> string
  84
  85 (** Get the line the error occured at. *)
  86 val line : error_pos -> int
  87
  88 (** Get the relative character range (in current line) the error occured at.*)
  89 val range : error_pos -> int * int
  90
  91 (** Get the absolute character range the error occured at. *)
  92 val abs_range : error_pos -> int * int
  93
  94 (** {6 Xml Functions} *)
  95
  96 exception Not_element of xml
  97 exception Not_pcdata of xml
  98 exception No_attribute of string
  99
 100 (** [tag xdata] returns the tag value of the xml node.
 101  Raise {!Xml.Not_element} if the xml is not an element *)
 102 val tag : xml -> string
 103
 104 (** [pcdata xdata] returns the PCData value of the xml node.
 105  Raise {!Xml.Not_pcdata} if the xml is not a PCData *)
 106 val pcdata : xml -> string
 107
 108 (** [attribs xdata] returns the attribute list of the xml node.
 109  First string if the attribute name, second string is attribute value.
 110  Raise {!Xml.Not_element} if the xml is not an element *)
 111 val attribs : xml -> (string * string) list
 112
 113 (** [attrib xdata "href"] returns the value of the ["href"]
 114  attribute of the xml node (attribute matching is case-insensitive).
 115  Raise {!Xml.No_attribute} if the attribute does not exists in the node's
 116  attribute list
 117  Raise {!Xml.Not_element} if the xml is not an element *)
 118 val attrib : xml -> string -> string
 119
 120 (** [children xdata] returns the children list of the xml node
 121  Raise {!Xml.Not_element} if the xml is not an element *)
 122 val children : xml -> xml list
 123
 124 (*** [enum xdata] returns the children enumeration of the xml node
 125  Raise {!Xml.Not_element} if the xml is not an element *)
 126 (* val enum : xml -> xml Enum.t *)
 127
 128 (** [iter f xdata] calls f on all children of the xml node.
 129  Raise {!Xml.Not_element} if the xml is not an element *)
 130 val iter : (xml -> unit) -> xml -> unit
 131
 132 (** [map f xdata] is equivalent to [List.map f (Xml.children xdata)]
 133  Raise {!Xml.Not_element} if the xml is not an element *)
 134 val map : (xml -> 'a) -> xml -> 'a list
 135
 136 (** [fold f init xdata] is equivalent to
 137  [List.fold_left f init (Xml.children xdata)]
 138  Raise {!Xml.Not_element} if the xml is not an element *)
 139 val fold : ('a -> xml -> 'a) -> 'a -> xml -> 'a
 140
 141 (** {6 Xml Printing} *)
 142
 143 (** Print the xml data structure into a compact xml string (without
 144  any user-readable formating ). *)
 145 val to_string : xml -> string
 146
 147 (** Append string escaped as xml pcdata to buffer *)
 148 val buffer_escape : Buffer.t -> string -> unit
 149
 150 (** Escape string as xml pcdata *)
 151 val escape : string -> string
 152
 153 (** Print the xml data structure into an user-readable string with
 154  tabs and lines break between different nodes. *)
 155 val to_string_fmt : xml -> string
 156
 157 val xml_of : xml -> string * (string * string) list * xml list
 158