Debian Codegraph @

README

raw
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 ("&quot;" and &apos;")
184 within attribute values.
185
186 Changes since 1.02:
187
188 o Corrected bug in "&amp;" 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