XML_EZ_Out - Simple Ada utility package for generating XML output.
Ezsi is new Mckae.Xml.Ez_Out.Generic_Medium
(Output_Medium => File_Type,
Put => Put,
New_Line => New_Line[,
Format => Spread_Indented]);
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.
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).
- 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.)
- Boolean indication whether to output an attribute if it has
a null value.
See the Generic_Medium
package specification for details of parameters
and overloaded variations.
- 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.
- Add a processing instruction to the XML document.
- Generate an entire element designated with the given tag
and containing the provided content and attribute values.
- 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.
- Initiate the generation of an XML element with the given
tag and zero or more attribute values.
- 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.
- 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,
- 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
- An attempt was made to end, or add content to, an element
when there were no open elements awaiting text or completion.
- The specified end tag does not match that of the currently
- 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.
- An attempt was made to create a malformed document, such as
inserting a process instruction into an open element.
- Mckae.XML.EZ_Out.Generic_Medium pre-instantiated with the
- 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,
<player lastName="Cuddyer" firstName="Michael"
can be generated as:
("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:
("battingAvg" = Batting_Average,
"atBats" = At_Bats));
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.
Marc A. Criley, McKae Technologies (email@example.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