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 The **XmlPullParser** object can be created based on an object of the ArrayBuffer or DataView type. 38 39 ```ts 40 let strXml: string = 41 '<?xml version="1.0" encoding="utf-8"?>' + 42 '<note importance="high" logged="true">' + 43 '<title>Play</title>' + 44 '<lens>Work</lens>' + 45 '</note>'; 46 let textEncoder: util.TextEncoder = new util.TextEncoder(); 47 let arrBuffer: Uint8Array = textEncoder.encodeInto(strXml); // Encode the data to prevent garbled characters. 48 // 1. Create an XmlPullParser object based on an object of the ArrayBuffer type. 49 let that: xml.XmlPullParser = new xml.XmlPullParser(arrBuffer.buffer as object as ArrayBuffer, 'UTF-8'); 50 51 // 2. Create an XmlPullParser object based on an object of the DataView type. 52 // let dataView: DataView = new DataView(arrBuffer.buffer as object as ArrayBuffer); 53 // let that: xml.XmlPullParser = new xml.XmlPullParser(dataView, 'UTF-8'); 54 ``` 55 563. Customize a callback function. In this example, the tag and tag value are directly printed. 57 58 ```ts 59 let str: string = ''; 60 function func(name: string, value: string): boolean { 61 str = name + value; 62 console.info(str); 63 return true; // The value true means to continue parsing, and false means to stop parsing. 64 } 65 ``` 66 674. Set parsing options and call the **parse()** function. 68 69 ```ts 70 let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tagValueCallbackFunction:func}; 71 that.parse(options); 72 ``` 73 74 The output is as follows: 75 76 ``` 77 note 78 title 79 Play 80 title 81 lens 82 Work 83 lens 84 note 85 ``` 86 87 88 89 90## Parsing XML Attributes and Attribute Values 91 921. Import the modules. 93 94 ```ts 95 import { xml, util } from '@kit.ArkTS'; // Use the API provided by the util module to encode the file. 96 ``` 97 982. Create an **XmlPullParser** object. 99 100 ```ts 101 let strXml: string = 102 '<?xml version="1.0" encoding="utf-8"?>' + 103 '<note importance="high" logged="true">' + 104 ' <title>Play</title>' + 105 ' <title>Happy</title>' + 106 ' <lens>Work</lens>' + 107 '</note>'; 108 let textEncoder: util.TextEncoder = new util.TextEncoder(); 109 let arrBuffer: Uint8Array = textEncoder.encodeInto(strXml); // Encode the data to prevent garbled characters. 110 let that: xml.XmlPullParser = new xml.XmlPullParser(arrBuffer.buffer as object as ArrayBuffer, 'UTF-8'); 111 ``` 112 1133. Customize a callback function. In this example, the attribute and attribute value are directly printed. 114 115 ```ts 116 let str: string = ''; 117 function func(name: string, value: string): boolean { 118 str += name + ' ' + value + ' '; 119 return true; // The value true means to continue parsing, and false means to stop parsing. 120 } 121 ``` 122 1234. Set parsing options and call the **parse()** function. 124 125 ```ts 126 let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, attributeValueCallbackFunction:func}; 127 that.parse(options); 128 console.info(str); // Print all attributes and their values at a time. 129 ``` 130 131 The output is as follows: 132 ``` 133 importance high logged true // Attributes and attribute values of the note node 134 ``` 135 136 137## Parsing XML Event Types and Element Depths 138 1391. Import the modules. 140 141 ```ts 142 import { xml, util } from '@kit.ArkTS'; // Use the API provided by the util module to encode the file. 143 ``` 144 1452. Create an **XmlPullParser** object. 146 147 ```ts 148 let strXml: string = 149 '<?xml version="1.0" encoding="utf-8"?>' + 150 '<note importance="high" logged="true">' + 151 '<title>Play</title>' + 152 '</note>'; 153 let textEncoder: util.TextEncoder = new util.TextEncoder(); 154 let arrBuffer: Uint8Array = textEncoder.encodeInto(strXml); // Encode the data to prevent garbled characters. 155 let that: xml.XmlPullParser = new xml.XmlPullParser(arrBuffer.buffer as object as ArrayBuffer, 'UTF-8'); 156 ``` 157 1583. Customize a callback function. In this example, the event type and element depth are directly printed. 159 160 ```ts 161 let str: string = ''; 162 function func(name: xml.EventType, value: xml.ParseInfo): boolean { 163 str = name +' ' + value.getDepth(); // getDepth is called to obtain the element depth. 164 console.info(str) 165 return true; // The value true means to continue parsing, and false means to stop parsing. 166 } 167 ``` 168 1694. Set parsing options and call the **parse()** function. 170 171 ```ts 172 let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tokenValueCallbackFunction:func}; 173 that.parse(options); 174 ``` 175 176 The output is as follows: 177 178 ``` 179 0 0 // 0: <?xml version="1.0" encoding="utf-8"?>. The event type value of START_DOCUMENT is 0. 0: The depth is 0. 180 2 1 // 2: <note importance="high" logged="true">. The event type value of START_TAG is 2. 1: The depth is 1. 181 2 2 // 2: <title>. The event type value of START_TAG is 2. 2: The depth is 2. 182 4 2 // 4: Play. The event type value of TEXT is 4. 2: The depth is 2. 183 3 2 // 3: </title>. The event type value of END_TAG is 3. 2: The depth is 2. 184 3 1 // 3: </note>. The event type value of END_TAG is 3. 1: The depth is 1 (corresponding to <note>). 185 1 0 // 1: The event type value of END_DOCUMENT is 1. 0: The depth is 0. 186 ``` 187 188 189 190 191## Example Scenario 192 193In the following example, all parsing options are invoked to parse XML tags, attributes, and event types. 194 195 196```ts 197import { xml, util } from '@kit.ArkTS'; 198 199let strXml: string = 200 '<?xml version="1.0" encoding="UTF-8"?>' + 201 '<book category="COOKING">' + 202 '<title lang="en">Everyday</title>' + 203 '<author>Giana</author>' + 204 '</book>'; 205let textEncoder: util.TextEncoder = new util.TextEncoder(); 206let arrBuffer: Uint8Array = textEncoder.encodeInto(strXml); 207let that: xml.XmlPullParser = new xml.XmlPullParser(arrBuffer.buffer as object as ArrayBuffer, 'UTF-8'); 208let str: string = ''; 209 210function tagFunc(name: string, value: string): boolean { 211 str = name + value; 212 console.info('tag-' + str); 213 return true; 214} 215 216function attFunc(name: string, value: string): boolean { 217 str = name + ' ' + value; 218 console.info('attri-' + str); 219 return true; 220} 221 222function tokenFunc(name: xml.EventType, value: xml.ParseInfo): boolean { 223 str = name + ' ' + value.getDepth(); 224 console.info('token-' + str); 225 return true; 226} 227 228let options: xml.ParseOptions = { 229 supportDoctype: true, 230 ignoreNameSpace: true, 231 tagValueCallbackFunction: tagFunc, 232 attributeValueCallbackFunction: attFunc, 233 tokenValueCallbackFunction: tokenFunc 234}; 235that.parse(options); 236``` 237 238The output is as follows: 239 240 ``` 241 tag- 242 token-0 0 243 tag-book 244 attri-category COOKING 245 token-2 1 246 tag-title 247 attri-lang en 248 token-2 2 249 tag-Everyday 250 token-4 2 251 tag-title 252 token-3 2 253 tag-author 254 token-2 2 255 tag-Giana 256 token-4 2 257 tag-author 258 token-3 2 259 tag-book 260 token-3 1 261 tag- 262 token-1 0 263 ``` 264