1# XML Parsing
2
3
4Data transferred in XML format must be parsed before being put in use. Generally, three types of elements in XML files need to be parsed: [XML tags and tag values](#parsing-xml-tags-and-tag-values), [XML attributes and attribute values](#parsing-xml-attributes-and-attribute-values), and [XML event types and element depths](#parsing-xml-event-types-and-element-depths).
5
6
7The **xml** module provides the **XmlPullParser** class to parse XML files. The input is an object of the ArrayBuffer or DataView type containing XML text, and the output is the parsed information.
8
9
10  **Table 1** XML parsing options
11
12| Name| Type| Mandatory| Description|
13| -------- | -------- | -------- | -------- |
14| supportDoctype | boolean | No| Whether to ignore the document type. The default value is **false**, indicating that the document type is not parsed.|
15| ignoreNameSpace | boolean | No| Whether to ignore the namespace. The default value is **false**, indicating that the namespace is parsed.|
16| tagValueCallbackFunction | (name: string, value: string) => boolean | No| Callback used to return **tagValue**, which consists of a tag and its value. The default value is **null**, indicating that XML tags and tag values are not parsed.|
17| attributeValueCallbackFunction | (name: string, value: string) => boolean | No| Callback used to return **attributeValue**, which consists of an attribute and its value. The default value is **null**, indicating that XML attributes and attribute values are not parsed.|
18| tokenValueCallbackFunction | (eventType: EventType, value: ParseInfo) => boolean | No| Callback used to return **tokenValue**, which consists of the event type and the attributes of **parseInfo**. The default value is **null**, indicating that the event type and the attributes of **parseInfo** are not parsed.|
19
20
21## Precautions
22
23- To ensure successful XML parsing and conversion, the input XML data must comply with the standard format.
24
25- Currently, parsing a given node is not supported.
26
27
28## Parsing XML Tags and Tag Values
29
301. Import the modules.
31
32    ```ts
33    import { xml, util } from '@kit.ArkTS'; // Use the API provided by the util module to encode the file.
34    ```
35
362. Create an **XmlPullParser** object.
37
38   The **XmlPullParser** object can be created based on an object of the ArrayBuffer or DataView type.
39
40    ```ts
41    let strXml: string =
42    '<?xml version="1.0" encoding="utf-8"?>' +
43      '<note importance="high" logged="true">' +
44      '<title>Play</title>' +
45      '<lens>Work</lens>' +
46      '</note>';
47    let textEncoder: util.TextEncoder = new util.TextEncoder();
48    let arrBuffer: Uint8Array = textEncoder.encodeInto(strXml); // Encode the data to prevent garbled characters.
49    // 1. Create an XmlPullParser object based on an object of the ArrayBuffer type.
50    let that: xml.XmlPullParser = new xml.XmlPullParser(arrBuffer.buffer as object as ArrayBuffer, 'UTF-8');
51
52    // 2. Create an XmlPullParser object based on an object of the DataView type.
53    // let dataView: DataView = new DataView(arrBuffer.buffer as object as ArrayBuffer);
54    // let that: xml.XmlPullParser = new xml.XmlPullParser(dataView, 'UTF-8');
55    ```
56
573. Customize a callback function. In this example, the tag and tag value are directly printed.
58
59    ```ts
60    let str: string = '';
61    function func(name: string, value: string): boolean {
62      str = name + value;
63      console.info(str);
64      return true; // The value true means to continue parsing, and false means to stop parsing.
65    }
66    ```
67
684. Set parsing options and call the **parse()** function.
69
70    ```ts
71    let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tagValueCallbackFunction:func};
72    that.parse(options);
73    ```
74
75	The output is as follows:
76
77	```
78	note
79	title
80	Play
81	title
82	lens
83	Work
84	lens
85	note
86	```
87
88
89
90
91## Parsing XML Attributes and Attribute Values
92
931. Import the modules.
94
95    ```ts
96    import { xml, util } from '@kit.ArkTS'; // Use the API provided by the util module to encode the file.
97    ```
98
992. Create an **XmlPullParser** object.
100
101    ```ts
102    let strXml: string =
103      '<?xml version="1.0" encoding="utf-8"?>' +
104        '<note importance="high" logged="true">' +
105        '    <title>Play</title>' +
106        '    <title>Happy</title>' +
107        '    <lens>Work</lens>' +
108        '</note>';
109    let textEncoder: util.TextEncoder = new util.TextEncoder();
110    let arrBuffer: Uint8Array = textEncoder.encodeInto(strXml); // Encode the data to prevent garbled characters.
111    let that: xml.XmlPullParser = new xml.XmlPullParser(arrBuffer.buffer as object as ArrayBuffer, 'UTF-8');
112    ```
113
1143. Customize a callback function. In this example, the attribute and attribute value are directly printed.
115
116    ```ts
117    let str: string = '';
118    function func(name: string, value: string): boolean {
119      str += name + ' ' + value + ' ';
120      return true; // The value true means to continue parsing, and false means to stop parsing.
121    }
122    ```
123
1244. Set parsing options and call the **parse()** function.
125
126    ```ts
127    let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, attributeValueCallbackFunction:func};
128    that.parse(options);
129    console.info(str); // Print all attributes and their values at a time.
130    ```
131
132   The output is as follows:
133   ```
134   importance high logged true // Attributes and attribute values of the note node
135   ```
136
137
138## Parsing XML Event Types and Element Depths
139
1401. Import the modules.
141
142    ```ts
143    import { xml, util } from '@kit.ArkTS'; // Use the API provided by the util module to encode the file.
144    ```
145
1462. Create an **XmlPullParser** object.
147
148    ```ts
149    let strXml: string =
150      '<?xml version="1.0" encoding="utf-8"?>' +
151      '<note importance="high" logged="true">' +
152      '<title>Play</title>' +
153      '</note>';
154    let textEncoder: util.TextEncoder = new util.TextEncoder();
155    let arrBuffer: Uint8Array = textEncoder.encodeInto(strXml); // Encode the data to prevent garbled characters.
156    let that: xml.XmlPullParser = new xml.XmlPullParser(arrBuffer.buffer as object as ArrayBuffer, 'UTF-8');
157    ```
158
1593. Customize a callback function. In this example, the event type and element depth are directly printed.
160
161    ```ts
162    let str: string  = '';
163    function func(name: xml.EventType, value: xml.ParseInfo): boolean {
164      str = name +' ' + value.getDepth(); // getDepth is called to obtain the element depth.
165      console.info(str)
166      return true; // The value true means to continue parsing, and false means to stop parsing.
167    }
168    ```
169
1704. Set parsing options and call the **parse()** function.
171
172     ```ts
173     let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tokenValueCallbackFunction:func};
174     that.parse(options);
175     ```
176
177   The output is as follows:
178
179	```
180	 0 0 // 0: <?xml version="1.0" encoding="utf-8"?>. The event type value of START_DOCUMENT is 0. 0: The depth is 0.
181	 2 1 // 2: <note importance="high" logged="true">. The event type value of START_TAG is 2. 1: The depth is 1.
182	 2 2 // 2: <title>. The event type value of START_TAG is 2. 2: The depth is 2.
183	 4 2 // 4: Play. The event type value of TEXT is 4. 2: The depth is 2.
184	 3 2 // 3: </title>. The event type value of END_TAG is 3. 2: The depth is 2.
185	 3 1 // 3: </note>. The event type value of END_TAG is 3. 1: The depth is 1 (corresponding to <note>).
186	 1 0 // 1: The event type value of END_DOCUMENT is 1. 0: The depth is 0.
187	```
188
189
190
191
192## Example Scenario
193
194In the following example, all parsing options are invoked to parse XML tags, attributes, and event types.
195
196
197```ts
198import { xml, util } from '@kit.ArkTS';
199
200let strXml: string =
201  '<?xml version="1.0" encoding="UTF-8"?>' +
202    '<book category="COOKING">' +
203    '<title lang="en">Everyday</title>' +
204    '<author>Giana</author>' +
205    '</book>';
206let textEncoder: util.TextEncoder = new util.TextEncoder();
207let arrBuffer: Uint8Array = textEncoder.encodeInto(strXml);
208let that: xml.XmlPullParser = new xml.XmlPullParser(arrBuffer.buffer as object as ArrayBuffer, 'UTF-8');
209let str: string = '';
210
211function tagFunc(name: string, value: string): boolean {
212  str = name + value;
213  console.info('tag-' + str);
214  return true;
215}
216
217function attFunc(name: string, value: string): boolean {
218  str = name + ' ' + value;
219  console.info('attri-' + str);
220  return true;
221}
222
223function tokenFunc(name: xml.EventType, value: xml.ParseInfo): boolean {
224  str = name + ' ' + value.getDepth();
225  console.info('token-' + str);
226  return true;
227}
228
229let options: xml.ParseOptions = {
230  supportDoctype: true,
231  ignoreNameSpace: true,
232  tagValueCallbackFunction: tagFunc,
233  attributeValueCallbackFunction: attFunc,
234  tokenValueCallbackFunction: tokenFunc
235};
236that.parse(options);
237```
238
239The output is as follows:
240
241   ```
242   tag-
243   token-0 0
244   tag-book
245   attri-category COOKING
246   token-2 1
247   tag-title
248   attri-lang en
249   token-2 2
250   tag-Everyday
251   token-4 2
252   tag-title
253   token-3 2
254   tag-author
255   token-2 2
256   tag-Giana
257   token-4 2
258   tag-author
259   token-3 2
260   tag-book
261   token-3 1
262   tag-
263   token-1 0
264   ```
265