iOS/Pods/AEXML/README.md

   1 # AEXML
   2 **Simple and lightweight XML parser written in Swift**
   3
   4 [![Language Swift 4.0](https://img.shields.io/badge/Language-Swift%204.0-orange.svg?style=flat)](https://swift.org)
   5 [![Platforms iOS | watchOS | tvOS | OSX](https://img.shields.io/badge/Platforms-iOS%20%7C%20watchOS%20%7C%20tvOS%20%7C%20OS%20X-lightgray.svg?style=flat)](http://www.apple.com)
   6 [![License MIT](https://img.shields.io/badge/License-MIT-lightgrey.svg?style=flat)](https://github.com/tadija/AEXML/blob/master/LICENSE)
   7
   8 [![CocoaPods Version](https://img.shields.io/cocoapods/v/AEXML.svg?style=flat)](https://cocoapods.org/pods/AEXML)
   9 [![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-brightgreen.svg?style=flat)](https://github.com/Carthage/Carthage)
  10 [![Swift Package Manager compatible](https://img.shields.io/badge/Swift%20Package%20Manager-compatible-brightgreen.svg)](https://github.com/apple/swift-package-manager)
  11
  12 > This is not a robust full featured XML parser, but rather simple,
  13 lightweight and easy to use utility for casual XML handling.
  14
  15 ## Index
  16 - [Features](#features)
  17 - [Usage](#usage)
  18     - [Read XML](#read-xml)
  19     - [Write XML](#write-xml)
  20 - [Installation](#installation)
  21 - [License](#license)
  22
  23 ## Features
  24 - **Read XML** data
  25 - **Write XML** string
  26 - Covered with [unit tests](https://github.com/tadija/AEXML/blob/master/Tests/AEXMLTests.swift)
  27 - Covered with inline docs
  28
  29 ## Usage
  30
  31 ### Read XML
  32 Let's say this is some XML string you picked up somewhere and made a variable `data: Data` from that.
  33
  34 ```xml
  35 <?xml version="1.0" encoding="utf-8"?>
  36 <animals>
  37     <cats>
  38         <cat breed="Siberian" color="lightgray">Tinna</cat>
  39         <cat breed="Domestic" color="darkgray">Rose</cat>
  40         <cat breed="Domestic" color="yellow">Caesar</cat>
  41         <cat></cat>
  42     </cats>
  43     <dogs>
  44         <dog breed="Bull Terrier" color="white">Villy</dog>
  45         <dog breed="Bull Terrier" color="white">Spot</dog>
  46         <dog breed="Golden Retriever" color="yellow">Betty</dog>
  47         <dog breed="Miniature Schnauzer" color="black">Kika</dog>
  48     </dogs>
  49 </animals>
  50 ```
  51
  52 This is how you can use AEXML for working with this data:
  53 (for even more examples, look at the unit tests code included in project)
  54
  55 ```swift
  56 guard let
  57     let xmlPath = Bundle.main.path(forResource: "example", ofType: "xml"),
  58     let data = try? Data(contentsOf: URL(fileURLWithPath: xmlPath))
  59 else { return }
  60
  61 do {
  62     let xmlDoc = try AEXMLDocument(xml: data, options: options)
  63
  64     // prints the same XML structure as original
  65     print(xmlDoc.xml)
  66
  67     // prints cats, dogs
  68     for child in xmlDoc.root.children {
  69         print(child.name)
  70     }
  71
  72     // prints Optional("Tinna") (first element)
  73     print(xmlDoc.root["cats"]["cat"].value)
  74
  75     // prints Tinna (first element)
  76     print(xmlDoc.root["cats"]["cat"].string)
  77
  78     // prints Optional("Kika") (last element)
  79     print(xmlDoc.root["dogs"]["dog"].last?.value)
  80
  81     // prints Betty (3rd element)
  82     print(xmlDoc.root["dogs"].children[2].string)
  83
  84     // prints Tinna, Rose, Caesar
  85     if let cats = xmlDoc.root["cats"]["cat"].all {
  86         for cat in cats {
  87             if let name = cat.value {
  88                 print(name)
  89             }
  90         }
  91     }
  92
  93     // prints Villy, Spot
  94     for dog in xmlDoc.root["dogs"]["dog"].all! {
  95         if let color = dog.attributes["color"] {
  96             if color == "white" {
  97                 print(dog.string)
  98             }
  99         }
 100     }
 101
 102     // prints Tinna
 103     if let cats = xmlDoc.root["cats"]["cat"].all(withValue: "Tinna") {
 104         for cat in cats {
 105             print(cat.string)
 106         }
 107     }
 108
 109     // prints Caesar
 110     if let cats = xmlDoc.root["cats"]["cat"].all(withAttributes: ["breed" : "Domestic", "color" : "yellow"]) {
 111         for cat in cats {
 112             print(cat.string)
 113         }
 114     }
 115
 116     // prints 4
 117     print(xmlDoc.root["cats"]["cat"].count)
 118
 119     // prints Siberian
 120     print(xmlDoc.root["cats"]["cat"].attributes["breed"]!)
 121
 122     // prints <cat breed="Siberian" color="lightgray">Tinna</cat>
 123     print(xmlDoc.root["cats"]["cat"].xmlCompact)
 124
 125     // prints Optional(AEXML.AEXMLError.elementNotFound)
 126     print(xmlDoc["NotExistingElement"].error)
 127 }
 128 catch {
 129     print("\(error)")
 130 }
 131 ```
 132
 133 ### Write XML
 134 Let's say this is some SOAP XML request you need to generate.
 135 Well, you could just build ordinary string for that?
 136
 137 ```xml
 138 <?xml version="1.0" encoding="utf-8"?>
 139 <soap:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 140   <soap:Header>
 141     <m:Trans xmlns:m="http://www.w3schools.com/transaction/" soap:mustUnderstand="1">234</m:Trans>
 142   </soap:Header>
 143   <soap:Body>
 144     <m:GetStockPrice>
 145       <m:StockName>AAPL</m:StockName>
 146     </m:GetStockPrice>
 147   </soap:Body>
 148 </soap:Envelope>
 149 ```
 150
 151 Yes, but, you can also do it in a more structured and elegant way with AEXML:
 152
 153 ```swift
 154 // create XML Document
 155 let soapRequest = AEXMLDocument()
 156 let attributes = ["xmlns:xsi" : "http://www.w3.org/2001/XMLSchema-instance", "xmlns:xsd" : "http://www.w3.org/2001/XMLSchema"]
 157 let envelope = soapRequest.addChild(name: "soap:Envelope", attributes: attributes)
 158 let header = envelope.addChild(name: "soap:Header")
 159 let body = envelope.addChild(name: "soap:Body")
 160 header.addChild(name: "m:Trans", value: "234", attributes: ["xmlns:m" : "http://www.w3schools.com/transaction/", "soap:mustUnderstand" : "1"])
 161 let getStockPrice = body.addChild(name: "m:GetStockPrice")
 162 getStockPrice.addChild(name: "m:StockName", value: "AAPL")
 163
 164 // prints the same XML structure as original
 165 print(soapRequest.xml)
 166 ```
 167
 168 ## Installation
 169
 170 - [Swift Package Manager](https://swift.org/package-manager/):
 171
 172         ```
 173         .Package(url: "https://github.com/tadija/AEXML.git", majorVersion: 4)
 174         ```
 175
 176 - [Carthage](https://github.com/Carthage/Carthage):
 177
 178         ```ogdl
 179         github "tadija/AEXML"
 180         ```
 181
 182 - [CocoaPods](http://cocoapods.org/):
 183
 184         ```ruby
 185         pod 'AEXML'
 186         ```
 187
 188 ## License
 189 AEXML is released under the MIT license. See [LICENSE](LICENSE) for details.