1 | /**
|
2 | * Copyright (C) 2016-2020 Michael Kourlas
|
3 | *
|
4 | * Licensed under the Apache License, Version 2.0 (the "License");
|
5 | * you may not use this file except in compliance with the License.
|
6 | * You may obtain a copy of the License at
|
7 | *
|
8 | * http://www.apache.org/licenses/LICENSE-2.0
|
9 | *
|
10 | * Unless required by applicable law or agreed to in writing, software
|
11 | * distributed under the License is distributed on an "AS IS" BASIS,
|
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
13 | * See the License for the specific language governing permissions and
|
14 | * limitations under the License.
|
15 | */
|
16 | /**
|
17 | * The options associated with parsing an object and formatting the resulting
|
18 | * XML.
|
19 | */
|
20 | export interface IOptions {
|
21 | /**
|
22 | * If an object or map contains a key that, when converted to a string,
|
23 | * is equal to the value of `aliasString`, then the name of the XML element
|
24 | * containing the object will be replaced with the value associated with
|
25 | * said key.
|
26 | *
|
27 | * For example, if `aliasString` is `"="`, then the following object:
|
28 | * ```javascript
|
29 | * {
|
30 | * "abc": {
|
31 | * "=": "def"
|
32 | * "#": "ghi"
|
33 | * }
|
34 | * }
|
35 | * ```
|
36 | * will result in the following XML for a root element named `"root"`:
|
37 | * ```xml
|
38 | * <root>
|
39 | * <def>ghi</def>
|
40 | * </root>
|
41 | * ```
|
42 | *
|
43 | * The default alias string is `"="`.
|
44 | */
|
45 | aliasString?: string;
|
46 | /**
|
47 | * If an object or map contains a key that, when converted to a string,
|
48 | * begins with the value of `attributeString`, then the value mapped by
|
49 | * said key will be interpreted as attributes for the XML element for that
|
50 | * object.
|
51 | *
|
52 | * The keys of the value of `attributeString` are interpreted as attribute
|
53 | * names, while the values mapping to those keys are interpreted as
|
54 | * attribute values.
|
55 | *
|
56 | * For example, if `attributeString` is `"@"`, then the following object:
|
57 | * ```javascript
|
58 | * {
|
59 | * "abc": {
|
60 | * "@1": {
|
61 | * "ghi": "jkl",
|
62 | * "mno": "pqr"
|
63 | * },
|
64 | * "stu": "vwx",
|
65 | * "@2": {
|
66 | * "yza": "bcd"
|
67 | * },
|
68 | * }
|
69 | * }
|
70 | * ```
|
71 | * will result in the following XML for a root element named `"root"`:
|
72 | * ```xml
|
73 | * <root>
|
74 | * <abc ghi='jkl' mno='pqr' yza='bcd'>
|
75 | * <stu>vwx</stu>
|
76 | * </abc>
|
77 | * </root>
|
78 | * ```
|
79 | *
|
80 | * The default attribute string is `"@"`.
|
81 | */
|
82 | attributeString?: string;
|
83 | /**
|
84 | * Whether to enclose any text containing the characters `<` or `&`
|
85 | * in CDATA sections. If this is false, these characters shall be replaced
|
86 | * with XML escape characters instead.
|
87 | *
|
88 | * By default, this is disabled.
|
89 | */
|
90 | cdataInvalidChars?: boolean;
|
91 | /**
|
92 | * If an object or map contains a key that, when converted to a string, is
|
93 | * equal to an item in `cdataKeys`, then the value mapped by said key will
|
94 | * be enclosed in a CDATA section.
|
95 | *
|
96 | * For example, if `cdataKeys` is:
|
97 | * ```javascript
|
98 | * [
|
99 | * "abc"
|
100 | * ]
|
101 | * ```
|
102 | * then the following object:
|
103 | * ```javascript
|
104 | * {
|
105 | * "abc": "def&",
|
106 | * "ghi": "jkl",
|
107 | * "mno": "pqr<"
|
108 | * }
|
109 | * ```
|
110 | * will result in the following XML for a root element named `"root"`:
|
111 | * ```xml
|
112 | * <root>
|
113 | * <abc><![CDATA[def&]]></ghi>
|
114 | * <ghi>jlk</ghi>
|
115 | * <mno>pqr<</mno>
|
116 | * </root>
|
117 | * ```
|
118 | *
|
119 | * If `cdataKeys` has a key named `"*"`, then that entry will match all
|
120 | * keys.
|
121 | *
|
122 | * By default, this is an empty array.
|
123 | */
|
124 | cdataKeys?: string[];
|
125 | /**
|
126 | * The options associated with the XML declaration.
|
127 | */
|
128 | declaration?: IDeclarationOptions;
|
129 | /**
|
130 | * The options associated with the XML document type definition.
|
131 | */
|
132 | dtd?: IDtdOptions;
|
133 | /**
|
134 | * The options associated with the formatting of the XML document.
|
135 | */
|
136 | format?: IFormatOptions;
|
137 | /**
|
138 | * Whether to replace any characters that are not valid in XML in particular
|
139 | * contexts with the Unicode replacement character, U+FFFD.
|
140 | *
|
141 | * At present this is limited to attribute names and values; element names
|
142 | * and character data; CDATA sections; and comments. This may be extended
|
143 | * in future.
|
144 | *
|
145 | * By default, this is disabled.
|
146 | */
|
147 | replaceInvalidChars?: boolean;
|
148 | /**
|
149 | * If a value has a type (as defined by calling `Object.prototype.toString`
|
150 | * on the value) equal to a key in `typeHandlers`, then said value will be
|
151 | * replaced by the return value of the function mapped to by the key in
|
152 | * `typeHandlers`. This function is called with the value as a parameter.
|
153 | *
|
154 | * If one of these functions returns the sole instance of {@link Absent},
|
155 | * then the value will be suppressed from the XML output altogether.
|
156 | *
|
157 | * For example, if `typeHandlers` is:
|
158 | * ```javascript
|
159 | * {
|
160 | * "[object Date]": function(value) {
|
161 | * return value.getYear();
|
162 | * },
|
163 | * "[object Null]": function(value) {
|
164 | * return Absent.instance;
|
165 | * }
|
166 | * }
|
167 | * ```
|
168 | * then the following object:
|
169 | * ```javascript
|
170 | * {
|
171 | * "abc": new Date(2012, 10, 31),
|
172 | * "def": null
|
173 | * }
|
174 | * ```
|
175 | * will result in the following XML for a root element named `"root"`:
|
176 | * ```xml
|
177 | * <root>
|
178 | * <abc>2012</abc>
|
179 | * </root>
|
180 | * ```
|
181 | *
|
182 | * If `typeHandlers` has a key named `"*"`, then that entry will match all
|
183 | * values, unless there is a more specific entry.
|
184 | *
|
185 | * Note that normal parsing still occurs for the value returned by the
|
186 | * function; it is not directly converted to a string.
|
187 | *
|
188 | * The default value is an empty object.
|
189 | */
|
190 | typeHandlers?: ITypeHandlers;
|
191 | /**
|
192 | * Whether to use a self-closing tag for empty elements.
|
193 | *
|
194 | * For example, the following element will be used:
|
195 | * ```xml
|
196 | * <element/>
|
197 | * ```
|
198 | * instead of:
|
199 | * ```xml
|
200 | * <element></element>
|
201 | * ```
|
202 | *
|
203 | * By default, this is enabled.
|
204 | */
|
205 | useSelfClosingTagIfEmpty?: boolean;
|
206 | /**
|
207 | * Whether to throw an exception if basic XML validation fails while
|
208 | * building the document.
|
209 | *
|
210 | * By default, this is enabled.
|
211 | */
|
212 | validation?: boolean;
|
213 | /**
|
214 | * If an object or map contains a key that, when converted to a string,
|
215 | * begins with the value of `valueString`, then the value mapped by said key
|
216 | * will be represented as bare text within the XML element for that object.
|
217 | *
|
218 | * For example, if `valueString` is `"#"`, then the following object:
|
219 | * ```javascript
|
220 | * new Map([
|
221 | * ["#1", "abc"],
|
222 | * ["def", "ghi"],
|
223 | * ["#2", "jkl"]
|
224 | * ])
|
225 | * ```
|
226 | * will result in the following XML for a root element named `"root"`:
|
227 | * ```xml
|
228 | * <root>
|
229 | * abc
|
230 | * <def>ghi</def>
|
231 | * jkl
|
232 | * </root>
|
233 | * ```
|
234 | *
|
235 | * The default value is `"#"`.
|
236 | */
|
237 | valueString?: string;
|
238 | /**
|
239 | * If an object or map contains a key that, when converted to a string, is
|
240 | * equal to a key in `wrapHandlers`, and the key in said object or map maps
|
241 | * to an array or set, then all items in the array or set will be wrapped
|
242 | * in an XML element with the same name as the key.
|
243 | *
|
244 | * The key in `wrapHandlers` must map to a function that is called with the
|
245 | * key name, as well as the array or set, as parameters. This function must
|
246 | * return a string or value that can be converted to a string, which will
|
247 | * become the name for each XML element for each item in the array or set.
|
248 | * Alternatively, this function may return `null` to indicate that no
|
249 | * wrapping should occur.
|
250 | *
|
251 | * For example, if `wrapHandlers` is:
|
252 | * ```javascript
|
253 | * {
|
254 | * "abc": function(key, value) {
|
255 | * return "def";
|
256 | * }
|
257 | * }
|
258 | * ```
|
259 | * then the following object:
|
260 | * ```javascript
|
261 | * {
|
262 | * "ghi": "jkl",
|
263 | * "mno": {
|
264 | * "pqr": ["s", "t"]
|
265 | * },
|
266 | * "uvw": {
|
267 | * "abc": ["x", "y"]
|
268 | * }
|
269 | * }
|
270 | * ```
|
271 | * will result in the following XML for a root element named `"root"`:
|
272 | * ```xml
|
273 | * <root>
|
274 | * <ghi>jkl</ghi>
|
275 | * <mno>
|
276 | * <pqr>s</pqr>
|
277 | * <pqr>t</pqr>
|
278 | * </mno>
|
279 | * <uwv>
|
280 | * <abc>
|
281 | * <def>x</def>
|
282 | * <def>y</def>
|
283 | * </abc>
|
284 | * </uwv>
|
285 | * </root>
|
286 | * ```
|
287 | *
|
288 | * If `wrapHandlers` has a key named `"*"`, then that entry will
|
289 | * match all arrays and sets, unless there is a more specific entry.
|
290 | *
|
291 | * The default value is an empty object.
|
292 | */
|
293 | wrapHandlers?: IWrapHandlers;
|
294 | }
|
295 | /**
|
296 | * Implementation of the IOptions interface used to provide default values
|
297 | * to fields.
|
298 | */
|
299 | export declare class Options implements IOptions {
|
300 | aliasString: string;
|
301 | attributeString: string;
|
302 | cdataInvalidChars: boolean;
|
303 | cdataKeys: string[];
|
304 | declaration: DeclarationOptions;
|
305 | dtd: DtdOptions;
|
306 | format: FormatOptions;
|
307 | replaceInvalidChars: boolean;
|
308 | typeHandlers: TypeHandlers;
|
309 | useSelfClosingTagIfEmpty: boolean;
|
310 | validation: boolean;
|
311 | valueString: string;
|
312 | wrapHandlers: WrapHandlers;
|
313 | constructor(options?: IOptions);
|
314 | }
|
315 | /**
|
316 | * The options associated with the XML declaration. An example of an XML
|
317 | * declaration is as follows:
|
318 | *
|
319 | * ```xml
|
320 | * <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
|
321 | * ```
|
322 | */
|
323 | export interface IDeclarationOptions {
|
324 | /**
|
325 | * Whether to include a declaration in the generated XML. By default,
|
326 | * one is included.
|
327 | */
|
328 | include?: boolean;
|
329 | /**
|
330 | * The encoding attribute to be included in the declaration. If defined,
|
331 | * this value must be a valid encoding. By default, no encoding attribute
|
332 | * is included.
|
333 | */
|
334 | encoding?: string;
|
335 | /**
|
336 | * The value of the standalone attribute to be included in the declaration.
|
337 | * If defined, this value must be "yes" or "no". By default, no standalone
|
338 | * attribute is included.
|
339 | */
|
340 | standalone?: string;
|
341 | /**
|
342 | * The XML version to be included in the declaration. If defined, this
|
343 | * value must be a valid XML version number. Defaults to "1.0".
|
344 | */
|
345 | version?: string;
|
346 | }
|
347 | /**
|
348 | * Implementation of the IDeclarationOptions interface used to provide default
|
349 | * values to fields.
|
350 | */
|
351 | export declare class DeclarationOptions implements IDeclarationOptions {
|
352 | include: boolean;
|
353 | encoding?: string;
|
354 | standalone?: string;
|
355 | version?: string;
|
356 | constructor(declarationOptions?: IDeclarationOptions);
|
357 | }
|
358 | /**
|
359 | * The options associated with the XML document type definition (DTD). An
|
360 | * example of a DTD is as follows:
|
361 | *
|
362 | * ```xml
|
363 | * <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
364 | * "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
365 | * ```
|
366 | */
|
367 | export interface IDtdOptions {
|
368 | /**
|
369 | * Whether to include a DTD in the generated XML. By default, no DTD is
|
370 | * included.
|
371 | */
|
372 | include?: boolean;
|
373 | /**
|
374 | * The name of the DTD. This value cannot be left undefined if `include`
|
375 | * is true.
|
376 | */
|
377 | name?: string;
|
378 | /**
|
379 | * The system identifier of the DTD, excluding quotation marks. By default,
|
380 | * no system identifier is included.
|
381 | */
|
382 | sysId?: string;
|
383 | /**
|
384 | * The public identifier of the DTD, excluding quotation marks. If a public
|
385 | * identifier is provided, a system identifier must be provided as well.
|
386 | * By default, no public identifier is included.
|
387 | */
|
388 | pubId?: string;
|
389 | }
|
390 | /**
|
391 | * Implementation of the IDtdOptions interface used to provide default values
|
392 | * to fields.
|
393 | */
|
394 | export declare class DtdOptions implements IDtdOptions {
|
395 | include: boolean;
|
396 | name?: string;
|
397 | sysId?: string;
|
398 | pubId?: string;
|
399 | constructor(validation: boolean, dtdOptions?: IDtdOptions);
|
400 | }
|
401 | /**
|
402 | * The options associated with the formatting of the XML document.
|
403 | */
|
404 | export interface IFormatOptions {
|
405 | /**
|
406 | * Whether double quotes or single quotes should be used in XML attributes.
|
407 | * By default, single quotes are used.
|
408 | */
|
409 | doubleQuotes?: boolean;
|
410 | /**
|
411 | * The indent string used for pretty-printing. The default indent string is
|
412 | * four spaces.
|
413 | */
|
414 | indent?: string;
|
415 | /**
|
416 | * The newline string used for pretty-printing. The default newline string
|
417 | * is "\n".
|
418 | */
|
419 | newline?: string;
|
420 | /**
|
421 | * Whether pretty-printing is enabled. By default, pretty-printing is
|
422 | * enabled.
|
423 | */
|
424 | pretty?: boolean;
|
425 | }
|
426 | /**
|
427 | * Implementation of the IFormatOptions interface used to provide default values
|
428 | * to fields.
|
429 | */
|
430 | export declare class FormatOptions implements IFormatOptions {
|
431 | doubleQuotes?: boolean;
|
432 | indent?: string;
|
433 | newline?: string;
|
434 | pretty?: boolean;
|
435 | constructor(formatOptions?: IFormatOptions);
|
436 | }
|
437 | /**
|
438 | * Map for the `typeHandlers` property in the {interface.
IOptions} |
439 | */
|
440 | export interface ITypeHandlers {
|
441 | /**
|
442 | * Mapping between the type of a value in an object to a function taking
|
443 | * this value and returning a replacement value.
|
444 | */
|
445 | [type: string]: (value: any) => unknown;
|
446 | }
|
447 | /**
|
448 | * Implementation of the ITypeHandlers interface used to provide default values
|
449 | * to fields.
|
450 | */
|
451 | export declare class TypeHandlers implements ITypeHandlers {
|
452 | [type: string]: (value: any) => unknown;
|
453 | constructor(typeHandlers?: ITypeHandlers);
|
454 | }
|
455 | /**
|
456 | * Map for the `wrapHandlers` property in the {interface.
IOptions} |
457 | */
|
458 | export interface IWrapHandlers {
|
459 | /**
|
460 | * Mapping between the string version of a key in an object or map with a
|
461 | * value that is an array or set to a function taking the string version
|
462 | * of that key, as well as that array or set.
|
463 | *
|
464 | * This function returns either a string that will become the name for each
|
465 | * XML element for each item in the array or set, or `null` to indicate that
|
466 | * wrapping should not occur.
|
467 | */
|
468 | [key: string]: (key: string, value: any) => string | null;
|
469 | }
|
470 | /**
|
471 | * Implementation of the IWrapHandlers interface used to provide default values
|
472 | * to fields.
|
473 | */
|
474 | export declare class WrapHandlers implements IWrapHandlers {
|
475 | [key: string]: (key: string, value: any) => string | null;
|
476 | constructor(wrapHandlers?: IWrapHandlers);
|
477 | }
|