------------------------------------------------------------------------------
--                     XML/Ada - An XML suite for Ada95                     --
--                                                                          --
--                     Copyright (C) 2005-2012, AdaCore                     --
--                                                                          --
-- This library is free software;  you can redistribute it and/or modify it --
-- under terms of the  GNU General Public License  as published by the Free --
-- Software  Foundation;  either version 3,  or (at your  option) any later --
-- version. This library is distributed in the hope that it will be useful, --
-- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- --
-- TABILITY or FITNESS FOR A PARTICULAR PURPOSE.                            --
--                                                                          --
--                                                                          --
--                                                                          --
--                                                                          --
--                                                                          --
-- You should have received a copy of the GNU General Public License and    --
-- a copy of the GCC Runtime Library Exception along with this program;     --
-- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
-- <http://www.gnu.org/licenses/>.                                          --
--                                                                          --
------------------------------------------------------------------------------

--  This package implements the content models as described in the DTDs.
--  They are not strictly part of the SAX 2.0 standard, however they are
--  used to simply the handling in users' applications.

with Sax.Symbols;
with Unicode.CES;

package Sax.Models is

   type content_spec is
     (character_data,   --  Characters, but no child node  (#PCDATA)
     element_ref,      --  A specific child
     any_of,           --  child is one of many choices
     sequence,         --  a sequence of elements (order is imposed)
     repeat,           --  A repeated element
     empty,            --  Element must be empty  (EMPTY)
     anything          --  Content is not described, and can be anything (ANY)
     );

   type element_model;
   type element_model_ptr is access element_model;
   type element_model_array is array (Natural range <>) of element_model_ptr;
   type element_model_array_ptr is access element_model_array;

   type element_model (Content : content_spec) is record
      case Content is
         when character_data | empty | anything =>
            null;

         when element_ref =>
            Name : Sax.Symbols.symbol; --  Name of the element

         when any_of | sequence =>
            List : element_model_array_ptr; --  all the possible choices

         when repeat =>
            Min  : Natural;
            Max  : Positive;
            Elem : element_model_ptr;
      end case;
   end record;
   --  Type used to describe the model used for an element, as described in
   --  the DTD (see 3.2.* in XML specifications). For instance, the following
   --  model "(#PCDATA|emph)*" is translated to:
   --     (Content => Repeat,
   --      Min     => 0,
   --      Max     => Positive'Last,
   --      Elem    => (Content => Any_Of,
   --                  Choices => (0 => (Content => Character_Data),
   --                              1 => (Content => Element,
   --                                    Name    => "emp"))))

   type content_model is private;
   Unknown_Model : constant content_model;
   --  This is a reference counted type that represents a content model defined
   --  in an XML document's DTD.

   procedure Ref (Model : content_model);
   procedure Unref (Model : in out content_model);
   --  Increment or decrement the reference counting for Model.
   --  When the reference counting reaches 0, the model is freed. You need to
   --  call these methods automatically if you intend to keep a copy of the
   --  model in your own structures.

   function Create_Model (Element : element_model_ptr) return content_model;
   --  Create a content model based on a description.
   --  No copy of Element is done, and the returned content model becomes
   --  responsible for freeing that data structure when no longer needed

   procedure Free (Model : in out element_model_ptr);
   --  Free the memory allocated for the model.

   function Get_Element_Model (Model : content_model) return element_model_ptr;
   --  Return a description of the content model. Do not free the resulting
   --  pointer, since this points directly into the Content_Model structure

   function To_String (Model : content_model) return Unicode.CES.byte_sequence;
   --  Return the string to put in an XML file to describe Model
   --  Invalid_Content_Model is raised if Model can not be described in a
   --  DTD.

   function Is_Mixed (M : element_model_ptr) return Boolean;
   --  Return True if M represents a Mixed content model (3.2.2 in XML
   --  specifications).

   Invalid_Content_Model : exception;
   --  Raised by To_String, when the model is invalid

private

   type model_item;
   type model_list is access model_item;
   type model_item is record
      State : element_model_ptr;
      Next  : model_list;
   end record;

   type natural_access is access Natural;
   type content_model is record
      Ref_Count : natural_access;
      Model     : element_model_ptr;
   end record;

   Unknown_Model : constant content_model := (null, null);

end Sax.Models;