Mercurial > repo

comparison interps/cfunge/cfunge-src/lib/genx/genx.h @ 996:859f9b4339e6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
<Gregor> tar xf egobot.tar.xz
author HackBot
date Sun, 09 Dec 2012 19:30:08 +0000
parents
children
comparison
equal deleted inserted replaced
995:6883f5911eb7 996:859f9b4339e6
1 /**
2 * @file
3 * genx - C-callable library for generating XML documents
4 */
5
6 #ifndef GENX_H
7 #define GENX_H
8
9 /*
10 * Copyright (c) 2004 by Tim Bray and Sun Microsystems. For copying
11 * permission, see http://www.tbray.org/ongoing/genx/COPYING
12 */
13
14 #include "../../src/global.h"
15
16 #if !defined(CFUN_NO_FLOATS) && !defined(CFUN_NO_TURT)
17
18 #include <stdio.h>
19
20 /**
21 * @defgroup genx Genx - XML generation functions
22 * A library for writing XML.
23 */
24 /*@{*/
25
26 /**
27 * Note on error handling: genx routines mostly return
28 * GENX_SUCCESS (guaranteed to be zero) in normal circumstances, one of
29 * these other GENX_ values on a memory allocation or I/O failure or if the
30 * call would result in non-well-formed output.
31 * You can associate an error message with one of these codes explicitly
32 * or with the most recent error using genxGetErrorMessage() and
33 * genxLastErrorMessage(); see below.
34 */
35 typedef enum {
36 GENX_SUCCESS = 0,
37 GENX_BAD_UTF8,
38 GENX_NON_XML_CHARACTER,
39 GENX_BAD_NAME,
40 GENX_ALLOC_FAILED,
41 GENX_BAD_NAMESPACE_NAME,
42 GENX_INTERNAL_ERROR,
43 GENX_DUPLICATE_PREFIX,
44 GENX_SEQUENCE_ERROR,
45 GENX_NO_START_TAG,
46 GENX_IO_ERROR,
47 GENX_MISSING_VALUE,
48 GENX_MALFORMED_COMMENT,
49 GENX_XML_PI_TARGET,
50 GENX_MALFORMED_PI,
51 GENX_DUPLICATE_ATTRIBUTE,
52 GENX_ATTRIBUTE_IN_DEFAULT_NAMESPACE,
53 GENX_DUPLICATE_NAMESPACE,
54 GENX_BAD_DEFAULT_DECLARATION
55 } genxStatus;
56
57 /** character types */
58 #define GENX_XML_CHAR 1
59 /** character types */
60 #define GENX_LETTER 2
61 /** character types */
62 #define GENX_NAMECHAR 4
63
64 /**
65 * @defgroup genx_types Genx's types
66 */
67 /*@{*/
68 /** An UTF-8 string */
69 typedef unsigned char * utf8;
70 /** A const UTF-8 string */
71 typedef const unsigned char * constUtf8;
72
73 /// A writer, the main struct.
74 typedef struct genxWriter_rec * genxWriter;
75 /// A namespace.
76 typedef struct genxNamespace_rec * genxNamespace;
77 /// An element.
78 typedef struct genxElement_rec * genxElement;
79 /// An attribute.
80 typedef struct genxAttribute_rec * genxAttribute;
81 /*@}*/
82
83 /*
84 * Constructors, set/get
85 */
86
87 /**
88 * Create a new writer. For generating multiple XML documents, it's most
89 * efficient to re-use the same genx object. However, you can only write
90 * one document at a time with a writer.
91 * @return NULL if it fails, which can only be due to an allocation failure.
92 */
93 FUNGE_ATTR_FAST FUNGE_ATTR_MALLOC FUNGE_ATTR_WARN_UNUSED
94 genxWriter genxNew(void);
95
96 /**
97 * Dispose of a writer, freeing all associated memory
98 */
99 FUNGE_ATTR_FAST
100 void genxDispose(genxWriter w);
101
102 /*
103 * Set/get
104 */
105
106 /**
107 * Get the prefix associated with a namespace
108 */
109 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
110 utf8 genxGetNamespacePrefix(genxNamespace ns);
111
112 /*
113 * Declaration functions
114 */
115
116 /**
117 * Declare a namespace. The provided prefix is the default but can be
118 * overridden by genxAddNamespace. If no default prefiix is provided,
119 * genx will generate one of the form g-%d.
120 * On error, returns NULL and signals via statusp
121 */
122 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
123 genxNamespace genxDeclareNamespace(genxWriter w,
124 constUtf8 uri, constUtf8 prefix,
125 genxStatus * statusP);
126
127 /**
128 * Declare an element
129 * If something failed, returns NULL and sets the status code via statusP
130 */
131 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
132 genxElement genxDeclareElement(genxWriter w,
133 genxNamespace ns, constUtf8 type,
134 genxStatus * statusP);
135
136 /**
137 * Declare an attribute
138 */
139 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
140 genxAttribute genxDeclareAttribute(genxWriter w,
141 genxNamespace ns,
142 constUtf8 name, genxStatus * statusP);
143
144 /*
145 * Writing XML
146 */
147
148 /**
149 * Start a new document.
150 */
151 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
152 genxStatus genxStartDocFile(genxWriter w, FILE * file);
153
154 /**
155 * Caller-provided I/O package.
156 * First form is for a null-terminated string.
157 * for second, if you have s="abcdef" and want to send "abc", you'd call
158 * sendBounded(userData, s, s + 3)
159 */
160 typedef struct {
161 genxStatus(* send)(void * userData, constUtf8 s);
162 genxStatus(* sendBounded)(void * userData, constUtf8 start, constUtf8 end);
163 genxStatus(* flush)(void * userData);
164 } genxSender;
165
166 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
167 genxStatus genxStartDocSender(genxWriter w, genxSender * sender);
168
169 /**
170 * End a document. Calls "flush"
171 */
172 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
173 genxStatus genxEndDocument(genxWriter w);
174
175 /**
176 * Write a comment
177 */
178 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
179 genxStatus genxComment(genxWriter w, constUtf8 text);
180
181 /**
182 * Write a PI
183 */
184 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
185 genxStatus genxPI(genxWriter w, constUtf8 target, constUtf8 text);
186
187 /**
188 * Start an element
189 */
190 FUNGE_ATTR_FAST
191 genxStatus genxStartElementLiteral(genxWriter w,
192 constUtf8 xmlns, constUtf8 type);
193
194 /**
195 * Start a predeclared element
196 * - element must have been declared
197 */
198 FUNGE_ATTR_FAST
199 genxStatus genxStartElement(genxElement e);
200
201 /**
202 * Write an attribute
203 */
204 FUNGE_ATTR_FAST
205 genxStatus genxAddAttributeLiteral(genxWriter w, constUtf8 xmlns,
206 constUtf8 name, constUtf8 value);
207
208 /**
209 * Write a predeclared attribute
210 */
211 FUNGE_ATTR_FAST
212 genxStatus genxAddAttribute(genxAttribute a, constUtf8 value);
213
214 /**
215 * Add a namespace declaration
216 */
217 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
218 genxStatus genxAddNamespace(genxNamespace ns, utf8 prefix);
219
220 /**
221 * Clear default namespace declaration
222 */
223 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
224 genxStatus genxUnsetDefaultNamespace(genxWriter w);
225
226 /**
227 * Write an end tag
228 */
229 FUNGE_ATTR_FAST
230 genxStatus genxEndElement(genxWriter w);
231
232 /**
233 * Write some text
234 * You can't write any text outside the root element, except with
235 * genxComment and genxPI
236 */
237 FUNGE_ATTR_FAST
238 genxStatus genxAddText(genxWriter w, constUtf8 start);
239 FUNGE_ATTR_FAST
240 genxStatus genxAddCountedText(genxWriter w, constUtf8 start, int byteCount);
241 FUNGE_ATTR_FAST
242 genxStatus genxAddBoundedText(genxWriter w, constUtf8 start, constUtf8 end);
243
244 /**
245 * Write one character. The integer value is the Unicode character
246 * value, as usually expressed in U+XXXX notation.
247 */
248 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
249 genxStatus genxAddCharacter(genxWriter w, int c);
250
251 /*
252 * Utility routines
253 */
254
255 /**
256 * Return the Unicode character encoded by the UTF-8 pointed-to by the
257 * argument, and advance the argument past the encoding of the character.
258 * @returns
259 * -1 if the UTF-8 is malformed, in which case advances the
260 * argument to point at the first byte past the point past the malformed
261 * ones.
262 */
263 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
264 int genxNextUnicodeChar(constUtf8 * sp);
265
266 /**
267 * Scan a buffer allegedly full of UTF-8 encoded XML characters; return
268 * one of GENX_SUCCESS, GENX_BAD_UTF8, or GENX_NON_XML_CHARACTER
269 */
270 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
271 genxStatus genxCheckText(const genxWriter restrict w, constUtf8 s);
272
273 /**
274 * Return character status, the OR of GENX_XML_CHAR,
275 * GENX_LETTER, and GENX_NAMECHAR
276 */
277 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
278 int genxCharClass(const genxWriter restrict w, int c);
279
280 /**
281 * Silently wipe any non-XML characters out of a chunk of text.
282 * If you call this on a string before you pass it addText or
283 * addAttribute, you will never get an error from genx unless
284 * (a) there's a bug in your software, e.g. a malformed element name, or
285 * (b) there's a memory allocation or I/O error
286 * The output can never be longer than the input.
287 * @returns true if any changes were made.
288 */
289 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
290 int genxScrubText(const genxWriter restrict w, constUtf8 in, utf8 out);
291
292 /**
293 * Return a specific error message.
294 * @param w The genxWriter in question.
295 * @param status What status to look up.
296 */
297 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
298 const char * genxGetErrorMessage(const genxWriter restrict w, genxStatus status);
299 /**
300 * Return last error message.
301 * @param w The genxWriter in question.
302 */
303 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
304 const char * genxLastErrorMessage(const genxWriter restrict w);
305
306 /**
307 * Return version of genx.
308 */
309 FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED
310 const char * genxGetVersion(void);
311
312 /*@}*/
313
314 #ifdef GENX_INTERNAL
315 FUNGE_ATTR_FAST void genxSetCharProps(char * restrict p);
316 #endif
317
318 #endif /* !defined(CFUN_NO_FLOATS) && !defined(CFUN_NO_TURT) */
319
320 #endif /* GENX_H */