XML_EZ_Out - Simple Ada utility package for generating XML output.

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

       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.

Linux-XML_EZ_Out                                   2009-12-27                                      XML_EZ_Out(7)

       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.

   GenericSpecification
       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;

   VariablesCurrent_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.

   PackageOperations
       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.

   ErrorsElement_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.

   AuxiliaryPackagesMcKae.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.

       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));

       XML_EZ_Out - Simple Ada utility package for generating XML output.

       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.

withMcKae.XML.EZ_Out.Generic_Medium;withMcKae.XML.EZ_Out.String_Stream;withMcKae.XML.EZ_Out.Text_File;packageEzsiisnewMckae.Xml.Ez_Out.Generic_Medium(Output_Medium=>File_Type,Put=>Put,New_Line=>New_Line[,Format=>Spread_Indented]);