| 1 |
XML EZ_Out |
| 2 |
|
| 3 |
Version 1.06 |
| 4 |
============ |
| 5 |
|
| 6 |
XML EZ_Out is a small set of packages intended to aid the creation of |
| 7 |
XML-formatted output from within Ada programs. It basically wraps the |
| 8 |
tags and data provided to it with XML syntax and writes them to a |
| 9 |
user-supplied medium. |
| 10 |
|
| 11 |
This medium can be any sort of writable entity, such as a file, a |
| 12 |
memory buffer, or even a communications link, such as a socket. The |
| 13 |
only functionality required of the medium is that it supply a |
| 14 |
meaningful "Put" (for writing a string) and "New_Line" procedure. |
| 15 |
|
| 16 |
Usage |
| 17 |
===== |
| 18 |
|
| 19 |
IMPORTANT!! |
| 20 |
|
| 21 |
XML EZ_Out package instantiations are explicitly designed to be made |
| 22 |
directly visible with the aid of a "use" clause! Declining to use a |
| 23 |
"use" will make using EZ_Out inordinately verbose and awkward to use. |
| 24 |
So use "use", and get a waiver from your programming standard if you |
| 25 |
have to! |
| 26 |
|
| 27 |
The key facilitator of making XML EZ_Out usage readable when |
| 28 |
generating XML documentation is the overloading of a number of |
| 29 |
variations of the "=" function. By doing this, a simple XML element |
| 30 |
having no content, such as: |
| 31 |
|
| 32 |
<player lastName="Cuddyer" firstName="Michael" team="Twins"/> |
| 33 |
|
| 34 |
can be generated as: |
| 35 |
|
| 36 |
Output_Tag(F, |
| 37 |
"player", |
| 38 |
("lastName" = "Cuddyer", |
| 39 |
"firstName" = "Michael", |
| 40 |
"team" = "Twins")); |
| 41 |
|
| 42 |
To simplify the specification of the attributes, variations of "=" are |
| 43 |
provided. Given these declarations: |
| 44 |
|
| 45 |
Batting_Average : Float; |
| 46 |
At_Bats : Natural; |
| 47 |
|
| 48 |
One can directly reference the variables: |
| 49 |
|
| 50 |
Output_Tag(F, |
| 51 |
"stats", |
| 52 |
("battingAvg" = Batting_Average, |
| 53 |
"atBats" = At_Bats)); |
| 54 |
|
| 55 |
Elements that contain a number of nested sub-elements begin with a |
| 56 |
Start_Element call and are terminated with an End_Element invocation. |
| 57 |
Attribute/value pairs can be specified in the Start_Element call, |
| 58 |
which is then followed by calls to Output_Tag, more |
| 59 |
Start_Element/End_Element calls, and an Output_Content for any data |
| 60 |
that makes up the textual body of the element. |
| 61 |
|
| 62 |
The only functions that you really need to know to use XML EZ_Out are: |
| 63 |
Output_XML_Header |
| 64 |
Output_Processing_Instruction |
| 65 |
Output_Element |
| 66 |
Output_Tag |
| 67 |
Start_Element |
| 68 |
End_Element |
| 69 |
Output_Content |
| 70 |
|
| 71 |
The "use" of the instantiated package will take of the rest. |
| 72 |
|
| 73 |
For an example set of intantiations and usages of the file and |
| 74 |
buffering capabilities of XML EZ_Out, see the tmeztf.adb program. |
| 75 |
|
| 76 |
|
| 77 |
The generic specification for EZ_Out is: |
| 78 |
|
| 79 |
generic |
| 80 |
|
| 81 |
type Output_Medium is limited private; |
| 82 |
|
| 83 |
with procedure Put(F : in Output_Medium; |
| 84 |
S : in String) is <>; |
| 85 |
with procedure New_Line (F : in Output_Medium; |
| 86 |
Spacing : in Ada.Text_IO.Positive_Count := 1) is <>; |
| 87 |
|
| 88 |
-- DEPRECATED |
| 89 |
-- Control formatting by setting the Current_Format variable in the |
| 90 |
-- package spec. |
| 91 |
-- |
| 92 |
-- Specify whether the XML that is created is to have indenting and |
| 93 |
-- line breaks. |
| 94 |
Format : Formatting_Options := Spread_Indented; |
| 95 |
-- DEPRECATED |
| 96 |
|
| 97 |
-- The maximum element nesting depth of an XML document |
| 98 |
Max_Element_Nesting : Positive := 200; |
| 99 |
|
| 100 |
package McKae.XML.EZ_Out.Generic_Medium; |
| 101 |
|
| 102 |
|
| 103 |
Output_Medium is whatever entity is going to received the formatted |
| 104 |
XML output. As mentioned previously, it can be a file, a stream, a |
| 105 |
buffer, a socket, whatever. All interaction with it takes place |
| 106 |
solely through the supplied Put and New_Line procedures, which are |
| 107 |
obviously modeled after the Ada.Text_IO versions. |
| 108 |
|
| 109 |
The Format parameter is now deprecated. Its functionality is now |
| 110 |
provided by the Current_Format variable in the package specification. |
| 111 |
The value for the generic Format parameter is now simply used as the |
| 112 |
inital setting for Current_Format. Format may be removed in some |
| 113 |
future release. |
| 114 |
|
| 115 |
Format, or better yet, its replacement, Current_Format, can be set to |
| 116 |
either Continuous_Stream or Spread_Indented. Continuous_Stream simply |
| 117 |
produces a continuous stream of XML content, with no indentation or |
| 118 |
line breaks. This mode reduces bandwidth and storage requirements, at |
| 119 |
the cost of not being the easiest to read in its raw form. |
| 120 |
Spread_Indented provides a more human-readable arrangement of the |
| 121 |
content. |
| 122 |
|
| 123 |
Max_Element_Nesting is used to set the size of an internal stack that |
| 124 |
keeps track of the start and end tags of the document under |
| 125 |
construction. Documents probably aren't going to exceed the default |
| 126 |
200-level nesting very often, but if that happens, simply increase it. |
| 127 |
|
| 128 |
To see the exceptions that can be raised by misusing XML EZ_Out, check |
| 129 |
the definitions in McKae.XML.EZ_Out. |
| 130 |
|
| 131 |
Auxiliary Packages |
| 132 |
================== |
| 133 |
|
| 134 |
Two auxiliary packages are provided with this distribution: |
| 135 |
McKae.XML.EZ_Out.Text_File, and McKae.XML.EZ_Out.String_Stream. |
| 136 |
|
| 137 |
Text_File is simply an instantiation of the core Generic_Medium |
| 138 |
package with Ada.Text_IO.File_Type, providing a ready-to-go package |
| 139 |
for writing XML to ordinary text files. |
| 140 |
|
| 141 |
String_Stream uses an in-memory buffer to hold the generated XML text, |
| 142 |
with a Get_String function for retrieving the entire generated |
| 143 |
document as a string with one call. |
| 144 |
|
| 145 |
|
| 146 |
Caveats |
| 147 |
======= |
| 148 |
|
| 149 |
Be aware that XML EZ_Out does no validation of the XML content it is |
| 150 |
being asked to output, and it is possible to generate malformed |
| 151 |
documents. That includes the handling of character encoding. While |
| 152 |
XML_EZ_Out will claim the document is "UTF-8" or otherwise as set by |
| 153 |
the application, it is up to the application to ensure that correct |
| 154 |
content is provided in the strings that are passed to its various |
| 155 |
subprograms. Used appropriately, though, it can provide a clear and |
| 156 |
readable means to aid the dynamic generation of XML content by Ada |
| 157 |
programs. |
| 158 |
|
| 159 |
Revision History |
| 160 |
================ |
| 161 |
|
| 162 |
Changes since 1.05: |
| 163 |
|
| 164 |
o Fixed bug where calling Output_Content with a negative integer or |
| 165 |
float argument would drop the leading minus sign |
| 166 |
|
| 167 |
o Added ability to completely deallocate memory used by the |
| 168 |
String_Stream package. [Patch provided by Xavier Grave.] |
| 169 |
|
| 170 |
Changes since 1.04: |
| 171 |
|
| 172 |
o Deprecated the Format generic parameter, replacing it with a |
| 173 |
Current_Format variable in the package specification. |
| 174 |
|
| 175 |
o Added a package variable Default_Output_Null_Attributes. If True, |
| 176 |
attributes whose value is an empty string will be output with that |
| 177 |
empty string as the attribute's value. If False (which is the |
| 178 |
default), output of the attribute is omitted. [Requested by Niklas |
| 179 |
Holsti.] |
| 180 |
|
| 181 |
Changes since 1.03: |
| 182 |
|
| 183 |
o Added quote and apostrophe substitution (""" and '") |
| 184 |
within attribute values. |
| 185 |
|
| 186 |
Changes since 1.02: |
| 187 |
|
| 188 |
o Corrected bug in "&" for "&" substition. |
| 189 |
|
| 190 |
Changes since 1.01: |
| 191 |
|
| 192 |
o Added attribute specification functions ("=") for single character |
| 193 |
values. |
| 194 |
|
| 195 |
Changes since 1.00: |
| 196 |
|
| 197 |
o Fixed problem with attributes being given negative numeric values. |
| 198 |
The minus sign was being dropped. |
| 199 |
|
| 200 |
o If an attribute value is an empty string ("") or |
| 201 |
Null_Unbounded_String, then generation of that attribute specification |
| 202 |
is skipped. |
| 203 |
|
| 204 |
================== |
| 205 |
Marc A. Criley |
| 206 |
McKae Technologies |
| 207 |
www.mckae.com |
| 208 |
Last updated: 23 Sep 2006 |