XML_EZ_Out(7)

✨ XML_EZ_Out(7) ✨

okay bestie sit DOWN because this is XML_EZ_Out, section 7 of the manual, straight out of Linux-XML_EZ_Out 💅 and it's literally the cutest little Ada package for making XML output and I'm obsessed 🦋

---

🌸 NAME 🌸

XML_EZ_Out — a Simple Ada utility package for generating XML output. no cap, that's the whole vibe 🎀

---

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

that's it. that's the instantiation. slay ✨

---

💖 DESCRIPTION 💖

so XML_EZ_Out is a lil' set of packages that helps you build XML-formatted output from inside Ada programs. what it does is basically wrap up the tags and the data you hand it in proper XML syntax and write them out to whatever medium you provide. main character energy tbh 👑

and that medium? it can be literally anything writable — a file, a memory buffer, even a communications link like a socket 🦋 the only thing it has to bring to the table is a meaningful Put (for writing a string) and a New_Line procedure. that's the whole vibe check.

XML_EZ_Out package instantiations are explicitly designed to be made directly visible with the aid of a use clause. and fr fr, declining to use a use will make using XML_EZ_Out inordinately verbose and awkward 😭 like, why would you do that to yourself.

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

so let me walk you through those real quick 💕

• Output_Medium is whatever entity is gonna receive the formatted XML output. could be a file, a stream, a buffer, a socket, whatever. all the interaction with it happens solely through the Put and New_Line procedures you supply, and those are modeled after the Ada.Text_IO procedures. periodt.
• Put — the procedure that writes a string to the instantiating output medium 🎀
• New_Line — the procedure that writes a line break to the instantiating output medium 🌸
• Format — specifies whether the XML being written gets indented, i.e. "prettified". > DEPRECATED!! control formatting by setting the Current_Format variable available in the package spec instead, bestie 🙈
• Max_Element_Nesting — the maximum element nesting depth of an XML document (used to set the size of the tag checking stack). default is 200 ⭐

---

🎀 Variables

• Current_Format — the indentation format of the XML that is utilized. you can change this at any time, iconic. available settings are Continuous_Stream and Spread_Indented. (this supersedes the deprecated generic parameter Format) ✨
• Default_Output_Null_Attributes — a Boolean indication of whether to output an attribute if it has a null value 👑

---

💅 Package Operations

peep the Generic_Medium package specification for the deets on parameters and overloaded variations, iykyk.

• 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 — adds a processing instruction to the XML document 🌈
• Output_Element — generates an entire element designated with the given tag and containing the provided content and attribute values ⭐
• Output_Tag — generates 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 — initiates the generation of an XML element with the given tag and zero or more attribute values 💖
• End_Element — indicates the completion of the output of an XML element. if a Tag is specified, it gets compared against the element tag that is currently open, and it raises Element_End_Mismatch if the two do not match. and if there is no open element, then it raises Element_Not_Open 😭
• Output_Content — places 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, it raises Element_Not_Open 💀
• = — associates an attribute name with a value. there are several overloaded variations of the = function for defining attribute name/value pairs. for each one, the attribute name, Attr, can be of either the predefined Ada String type or the Unbounded_String type from Ada.Strings.Unbounded. and 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. rude tbh.
• 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));

see?? the way that just reads. ate. 💅

---

💜 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 the XML, so apply for a waiver from any such style standards, bestie. do it. 🎀

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. no hiding, no absorbing, straight through 🌈

---

👑 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. so like, be careful, that's on you bestie 🙈

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) — that's the source, the version and the date, and that's a wrap 🌸 mwah, go make some XML, you got this 💅🦋