-- $Date: 2003/12/30 05:50:43 $
-- $Revision: 1.9 $
-- $Author: jcrocholl $

with Parsers;

package XML_Parsers is

   type XML_Parser is private;

   -----------------------------
   -- Create and destroy parsers
   -----------------------------

   -- Open an XML parser to read from current input.
   -- Useful to read from a pipe.
   function Current_Input
     return XML_Parser-- The newly created XML_Parser.

   function Open
     (File_Name : in String-- The file to read from.
     return XML_Parser;      -- The newly created XML_Parser.

   procedure Close
     (X : in out XML_Parser); -- The XML_Parser to be closed.

   ---------------
   -- XML elements
   ---------------

   -- Raised if the enclosing element (or document) ends.
   No_More_Elements : exception;

   -- Raised if there are nested elements that have not been read. The
   -- application must call descend and read these elements first.
   Nested_Elements : exception;

   -- Read the name of the next element on the same XML hierarchy
   -- level. The parser must be positioned at the start of the
   -- element, whitespace permitted.
   function Next_Element
     (X : in XML_Parser-- The parser to read from.
     return String;      -- The element name.

   -----------------
   -- XML attributes
   -----------------

   -- Raised if the enclosing element tag ends.
   No_More_Attributes : exception;

   -- Read the name of the next attribute in the current element
   -- tag. The parser must be positioned at the start of the
   -- attribute, whitespace permitted.
   function Next_Attribute
     (X : in XML_Parser-- The parser to read from.
     return String;      -- The attribute name.

   -- Read the associated value of the most recently read attribute
   -- name. The parser must be positioned at the start of the
   -- attribute value (after the '='), whitespace permitted.
   function Attribute_Value
     (X : in XML_Parser-- The parser to read from.
     return String;      -- The attribute value.

   ----------------
   -- XML hierarchy
   ----------------

   -- Go down one level in the document hierarchy.
   procedure Descend
     (X : in XML_Parser); -- The parser to descend.

   -- Go up one level in the document hierarchy.
   procedure Ascend
     (X : in XML_Parser); -- The parser to ascend.

   -----------------
   -- Error handling
   -----------------

   -- Emit a warning about XML or document syntax.
   procedure Warning
     (X       : in XML_Parser-- Get error location from this parser.
      Message : in String);    -- Error message text.

   -- Emit an error about XML or document syntax.
   procedure Error
     (X       : in XML_Parser-- Get error location from this parser.
      Message : in String);    -- Error message text.

private

   -- A data structure to hold the attributes of an XML parser.
   type XML_Parser_Record is record
      Parser : Parsers.Parser-- Regular text parser.
   end record;

   -- Private definition of an XML parser.
   type XML_Parser is access XML_Parser_Record;

end XML_Parsers;