NAME

       XML_EZ_Out - Simple Ada utility package for generating XML output.

SYNOPSIS

       with McKae.XML.EZ_Out.Generic_Medium;
       with McKae.XML.EZ_Out.String_Stream;
       with McKae.XML.EZ_Out.Text_File;

       package Ezsi is new Mckae.Xml.Ez_Out.Generic_Medium
              (Output_Medium => File_Type,
               Put           => Put,
               New_Line      => New_Line[,
               Format        => Spread_Indented]);

DESCRIPTION

       XML_EZ_Out is a small set of packages intended to aid the creation of XML-formatted output
       from within Ada programs.  It basically wraps the tags and data provided to  it  with  XML
       syntax and writes them to a user-supplied medium.

       This medium can be any sort of writable entity, such as a file, a memory buffer, or even a
       communications link, such as a socket.  The only functionality required of the  medium  is
       that it supply a meaningful "Put" (for writing a string) and "New_Line" procedure.

       XML_EZ_Out package instantiations are explicitly designed to be made directly visible with
       the aid of  a  "use"  clause.  Declining  to  use  a  "use"  will  make  using  XML_EZ_Out
       inordinately verbose and awkward.

   Generic Specification
       generic

          type Output_Medium is limited private;
          -- Output_Medium is whatever entity is going to received the formatted
          -- XML output. It can be a file, a stream, a buffer, a socket, whatever.
          -- All interaction with it takes place solely through the supplied Put and
          -- New_Line procedures, which are modeled after the Ada.Text_IO procedures.

          with procedure Put(F : in Output_Medium;
                             S : in String) is <>;
          -- Procedure writing a string to the instantiating output medium.

          with procedure New_Line
             (F       : in Output_Medium;
              Spacing : in Ada.Text_IO.Positive_Count := 1) is <>;
          -- Procedure writing a line break to the instantiating output medium.

          Format : Formatting_Options := Spread_Indented;
          -- Specify whether the XML being written is to be indented, i.e. be
          -- "prettified". (DEPRECATED, control formatting by setting the
          -- Current_Format variable available in the package spec.)

          Max_Element_Nesting : Positive := 200;
          -- The maximum element nesting depth of an XML document (used to set
          -- size of tag checking stack).

       package McKae.XML.EZ_Out.Generic_Medium;

   Variables
       Current_Format
              The  indentation  format  of  the XML that is utilized.  This can be altered at any
              time. Available settings are  Continuous_Stream  and  Spread_Indented.  (Supersedes
              deprecated generic parameter Format.)

       Default_Output_Null_Attributes
              Boolean indication whether to output an attribute if it has a null value.

   Package Operations
       See  the  Generic_Medium  package  specification  for details of parameters and overloaded
       variations.

       Output_XML_Header
              Procedure to output a  standard  XML  header  line,  as  amended  by  the  supplied
              arguments.  To omit a standard attribute, pass an empty string as its value.

       Output_Processing_Instruction
              Add a processing instruction to the XML document.

       Output_Element
              Generate  an  entire  element  designated  with  the  given  tag and containing the
              provided content and attribute values.

       Output_Tag
              Generate an element tag containing zero or more attributes.  By default the element
              is  created  using  the  compact,  no-end-tag  notation;  to force generation of an
              element that has both start and end tags while containing no content,  set  End_Tag
              to True.

       Start_Element
              Initiate  the  generation  of  an  XML  element with the given tag and zero or more
              attribute values.

       End_Element
              Indicate the completion of the output of an XML element.  If a  Tag  is  specified,
              compare   it   against   the   element  tag  that  is  currently  open,  and  raise
              Element_End_Mismatch if the two do not match.  If there is no  open  element,  then
              raise Element_Not_Open.

       Output_Content
              Place  the  text,  as  is,  as  the  content  of  the  currently  open XML element.
              Output_Content can be called repeatedly, and will simply  continue  to  append  the
              additional content.  If there is no open element, raise Element_Not_Open.

       =      Associate  an  attribute name with a value. There are several overloaded variations
              of the "="  function  for  defining  attribute  name/value  pairs.  For  each,  the
              attribute  name,  Attr,  can  be  of  either  the predefined Ada String type or the
              Unbounded_String type from Ada.Strings.Unbounded. The provided "=" functions accept
              a Value of a predefined Integer-based, Float-based, String, or Character type.

   Errors
       Element_Not_Open
              An  attempt  was made to end, or add content to, an element when there were no open
              elements awaiting text or completion.

       Element_End_Mismatch
              The specified end tag does not match that of the currently open element.

       Nesting_Too_Deep
              The number of open, nested  elements  has  exceeded  the  maximum  level  that  was
              specified.   Consider  increasing  the  value  of  the  Max_Element_Nesting generic
              parameter.

       Invalid_Construction
              An attempt was made to create a malformed document, such  as  inserting  a  process
              instruction into an open element.

   Auxiliary Packages
       McKae.XML.EZ_Out.Text_File
              Mckae.XML.EZ_Out.Generic_Medium pre-instantiated with the
               predefined Ada.Text_IO.File_Type.

       Mckae.XML.EZ_Out.String_Stream
              McKae.XML.EZ_Out.Generic_Medium  pre-instantiated  with a limited functionality in-
              memory string buffering package, nested within  the  Mckae.XML.EZ_Out.String_Stream
              package as String_Buffering.

EXAMPLES

       The  key facilitator of making XML_EZ_Out usage readable when generating XML documentation
       is the overloading of a number of variations of the "=" function.  By doing this, a simple
       XML element having no content, such as:

       <player lastName="Cuddyer" firstName="Michael" team="Twins"/>

       can be generated as:
       Output_Tag(F,
                  "player",
                  ("lastName"  = "Cuddyer",
                   "firstName" = "Michael",
                   "team"      = "Twins"));

       To  simplify  the  specification of the attributes, variations of "=" are provided.  Given
       these declarations:
           Batting_Average : Float;
           At_Bats         : Natural;
       One can directly reference the variables:

       Output_Tag(F,
                  "stats",
                  ("battingAvg" = Batting_Average,
                   "atBats"     = At_Bats));

NOTES

       XML_EZ_Out is designed in such a way that instantiations of it are meant to be  "used"  by
       the  application.  When accompanied with a "use" clause, specifying the XML to be produced
       is very simple and clear.  Insisting on using qualified names will make  for  very  obtuse
       code.   Likewise,  "named parameter" notation would obscure the complementarity of the Ada
       and XML, so apply for a waiver from any such style standards.

       The medium must be open and ready to accept content  before  invoking  any  of  these  XML
       output subprograms.

       If  the  medium raises any exceptions as a result of invoking the supplied Put or New_Line
       procedures, those exceptions will be passed through to the caller.

AUTHOR

       Marc A. Criley, McKae Technologies (mc@mckae.com)

CAVEATS

       XML_EZ_Out does no validation of the XML content it is being asked to output,  and  it  is
       possible  to  generate  malformed  documents.   That  includes  the  handling of character
       encoding.  While XML_EZ_Out will claim the document is "UTF-8" or otherwise as set by  the
       application, it is up to the application to ensure that correct content is provided in the
       strings that are passed to its various subprograms.  Used appropriately,  though,  it  can
       provide  a  clear  and  readable means to aid the dynamic generation of XML content by Ada
       programs.