Provided by: libxmlezout0_1.06-2_i386 bug

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.