SWXMLHash

SWXMLHash 是在 Swift 中解析 XML 的相对简单方法。如果您熟悉 NSXMLParser，这个库是其简单封装。从概念上来说，它提供 XML 到数组和字典（即散列）的转换。

API 从 SwiftyJSON 中汲取了很多灵感。

内容

• 要求
• 安装
• 入门
• 配置
• 示例
• 常见问题
• 更改日志
• 贡献
• 许可证

要求

• iOS 8.0+/ Mac OS X 10.9+/ tvOS 9.0+/ watchOS 2.0+
• Xcode 8.0+

安装

SWXMLHash 可以使用 CocoaPods、Carthage、Swift 包管理器 或手动方式安装。

CocoaPods

要安装 CocoaPods，请运行

$ gem install cocoapods

然后创建一个具有以下内容的 Podfile

platform :ios, '10.0'
use_frameworks!

target 'YOUR_TARGET_NAME' do
  pod 'SWXMLHash', '~> 7.0.0'
end

最后，运行以下命令进行安装

$ pod install

Carthage

要安装 Carthage，请运行（使用 Homebrew）

$ brew update
$ brew install carthage

然后在你的 Cartfile 中添加以下行

github "drmohundro/SWXMLHash" ~> 7.0

Swift 包管理器

Swift 包管理器需要 Swift 版本 4.0 或更高。首先，创建一个 Package.swift 文件。它应如下所示

dependencies: [
    .package(url: "https://github.com/drmohundro/SWXMLHash.git", from: "7.0.0")
]

然后运行 swift build，这将为您下载并编译 SWXMLHash，以便您开始使用。

手动安装

要手动安装，您需要克隆SWXMLHash存储库。您可以在单独的目录中执行此操作，或者可以使用git子模块——在这种情况下，建议使用git子模块，这样您的存储库将包含有关您正在使用的SWXMLHash的哪个提交的详细信息。一旦完成，您只需将所有相关的swift文件放入项目中即可。

如果您正在使用工作区，则可以仅包含整个SWXMLHash.xcodeproj。

入门指南

如果你刚开始使用SWXMLHash，我建议克隆存储库并打开工作区。我在工作区中包括了一个Swift playground，这使得在API和调用上进行实验变得容易。

配置

SWXMLHash允许在解析方法方面进行有限的配置。要设置任何配置选项，您使用如下的configure方法

let xml = XMLHash.config {
              config in
              // set any config options here
          }.parse(xmlToParse)

目前可用的选项包括

• shouldProcessLazily
  • 此选项确定是否使用XML的懒加载。如果您的大型XML，则这可以显着提高解析性能。
  • 默认为false
• shouldProcessNamespaces
  • 此设置将传递给内部NSXMLParser实例。它将返回不带其命名空间部分的任何XML元素（即，“<h:table>”将返回为“<table>”）
  • 默认为false
• caseInsensitive
  • 此设置允许进行不区分大小写的键查找。通常，XML是一种区分大小写的语言，但此选项可以在必要时绕过此限制。
  • 默认为false
• encoding
  • 此设置允许在将XML字符串传递给parse时显式指定字符编码。
  • 默认为String.encoding.utf8
• userInfo
  • 此设置模仿Codable的userInfo属性，使用户能够添加将用于反序列化的上下文信息。
  • 参阅 Codable的userInfo文档
  • 默认为 [:]
• detectParsingErrors
  • 此设置尝试检测XML解析错误。如果在解析过程中发现任何问题，parse将返回一个XMLIndexer.parsingError。
  • 默认为false（因为向后兼容性，以及许多用户尝试使用此库解析HTML）

示例

下面所有的示例都可以在包含的规范中找到。

初始化

let xml = XMLHash.parse(xmlToParse)

如果正在解析一个大型XML文件并且需要最佳性能，可以选择将解析配置为懒加载。懒加载 avoidsloading the entire XML document into memory, 因此在性能方面可能更可取。有关有关懒加载的一个注意事项，请参阅错误处理。

let xml = XMLHash.config {
              config in
              config.shouldProcessLazily = true
          }.parse(xmlToParse)

上述方法使用新的config方法，但还有XMLHash的直接lazy方法。

let xml = XMLHash.lazy(xmlToParse)

单个元素查找

给定

<root>
  <header>
    <title>Foo</title>
  </header>
  ...
</root>

将返回 "Foo"。

xml["root"]["header"]["title"].element?.text

多个元素查找

给定

<root>
  ...
  <catalog>
    <book><author>Bob</author></book>
    <book><author>John</author></book>
    <book><author>Mark</author></book>
  </catalog>
  ...
</root>

下面将返回 "John"。

xml["root"]["catalog"]["book"][1]["author"].element?.text

属性使用

给定

<root>
  ...
  <catalog>
    <book id="1"><author>Bob</author></book>
    <book id="123"><author>John</author></book>
    <book id="456"><author>Mark</author></book>
  </catalog>
  ...
</root>

以下将返回 "123"。

xml["root"]["catalog"]["book"][1].element?.attribute(by: "id")?.text

或者，您可以查找具有特定属性的事件。以下将返回 "John"。

xml["root"]["catalog"]["book"].withAttribute("id", "123")["author"].element?.text

在当前级别返回所有元素

给定

<root>
  ...
  <catalog>
    <book><genre>Fiction</genre></book>
    <book><genre>Non-fiction</genre></book>
    <book><genre>Technical</genre></book>
  </catalog>
  ...
</root>

使用 all 方法将遍历索引级别的所有节点。以下将返回 "Fiction, Non-fiction, Technical"。

", ".join(xml["root"]["catalog"]["book"].all.map { elem in
    elem["genre"].element!.text!
})

您还可以迭代all方法

for elem in xml["root"]["catalog"]["book"].all {
    print(elem["genre"].element!.text!)
}

在当前级别返回所有子元素

给定

<root>
  <catalog>
    <book>
      <genre>Fiction</genre>
      <title>Book</title>
      <date>1/1/2015</date>
    </book>
  </catalog>
</root>

以下将 print "root", "catalog", "book", "genre", "title", 和 "date"（注意children方法）。

func enumerate(indexer: XMLIndexer) {
    for child in indexer.children {
        print(child.element!.name)
        enumerate(child)
    }
}

enumerate(indexer: xml)

筛选元素

给定

<root>
  <catalog>
    <book id="bk101">
      <author>Gambardella, Matthew</author>
      <title>XML Developer's Guide</title>
      <genre>Computer</genre><price>44.95</price>
      <publish_date>2000-10-01</publish_date>
    </book>
    <book id="bk102">
      <author>Ralls, Kim</author>
      <title>Midnight Rain</title>
      <genre>Fantasy</genre>
      <price>5.95</price>
      <publish_date>2000-12-16</publish_date>
    </book>
    <book id="bk103">
      <author>Corets, Eva</author>
      <title>Maeve Ascendant</title>
      <genre>Fantasy</genre>
      <price>5.95</price>
      <publish_date>2000-11-17</publish_date>
    </book>
  </catalog>
</root>

以下将返回 "Midnight Rain"。筛选可以基于XMLElement类的任何部分或索引。

let subIndexer = xml!["root"]["catalog"]["book"]
    .filterAll { elem, _ in elem.attribute(by: "id")!.text == "bk102" }
    .filterChildren { _, index in index >= 1 && index <= 3 }

print(subIndexer.children[0].element?.text)

错误处理

使用 Swift 2.0 的新错误处理功能

do {
    try xml!.byKey("root").byKey("what").byKey("header").byKey("foo")
} catch let error as IndexingError {
    // error is an IndexingError instance that you can deal with
}

或者 使用现有的索引功能

switch xml["root"]["what"]["header"]["foo"] {
case .element(let elem):
    // everything is good, code away!
case .xmlError(let error):
    // error is an IndexingError instance that you can deal with
}

请注意，如上所示的错误处理方式不适用于懒加载的 XML。懒解析实际上在调用 element 或 all 方法时才会发生 - 因此，在请求元素之前，无法知道元素是否已存在。

XML 对象反序列化

更频繁的情况下，您可能希望将 XML 树反序列化为自定义类型的数组。这就是 XMLObjectDeserialization 发挥作用的地方。

给定

<root>
  <books>
    <book isbn="0000000001">
      <title>Book A</title>
      <price>12.5</price>
      <year>2015</year>
      <categories>
        <category>C1</category>
        <category>C2</category>
      </categories>
    </book>
    <book isbn="0000000002">
      <title>Book B</title>
      <price>10</price>
      <year>1988</year>
      <categories>
        <category>C2</category>
        <category>C3</category>
      </categories>
    </book>
    <book isbn="0000000003">
      <title>Book C</title>
      <price>8.33</price>
      <year>1990</year>
      <amount>10</amount>
      <categories>
        <category>C1</category>
        <category>C3</category>
      </categories>
    </book>
  </books>
</root>

使用实现了 XMLObjectDeserialization 的 Book 结构体

struct Book: XMLObjectDeserialization {
    let title: String
    let price: Double
    let year: Int
    let amount: Int?
    let isbn: Int
    let category: [String]

    static func deserialize(_ node: XMLIndexer) throws -> Book {
        return try Book(
            title: node["title"].value(),
            price: node["price"].value(),
            year: node["year"].value(),
            amount: node["amount"].value(),
            isbn: node.value(ofAttribute: "isbn"),
            category : node["categories"]["category"].value()
        )
    }
}

以下将返回 Book 结构体的数组

let books: [Book] = try xml["root"]["books"]["book"].value()

您可以通过为任何非叶节点（例如上面示例中的 ``）实现 XMLObjectDeserialization 来将任何 XML 转换为您自定义的类型。

对于叶节点（例如上面的 `