XMLCoder
Encoder & Decoder for XML using Swift's Codable protocols.
This package is a fork of the original ShawnMoore/XMLParsing with more features and improved test coverage. Automatically generated documentation is available on our GitHub Pages.
Example
import XMLCoder
import Foundation
let sourceXML = """
<note>
<to>Bob</to>
<from>Jane</from>
<heading>Reminder</heading>
<body>Don't forget to use XMLCoder!</body>
</note>
"""
struct Note: Codable {
let to: String
let from: String
let heading: String
let body: String
}
let note = try! XMLDecoder().decode(Note.self, from: Data(sourceXML.utf8))
let encodedXML = try! XMLEncoder().encode(note, withRootKey: "note")
Advanced features
The following features are available in 0.4.0 release or later (unless stated otherwise):
Stripping namespace prefix
Sometimes you need to handle an XML namespace prefix, like in the XML below:
<h:table xmlns:h="http://www.w3.org/TR/html4/">
<h:tr>
<h:td>Apples</h:td>
<h:td>Bananas</h:td>
</h:tr>
</h:table>
Stripping the prefix from element names is enabled with shouldProcessNamespaces property:
struct Table: Codable, Equatable {
struct TR: Codable, Equatable {
let td: [String]
}
let tr: [TR]
}
let decoder = XMLDecoder()
// Setting this property to `true` for the namespace prefix to be stripped
// during decoding so that key names could match.
decoder.shouldProcessNamespaces = true
let decoded = try decoder.decode(Table.self, from: xmlData)
Dynamic node coding
XMLCoder provides two helper protocols that allow you to customize whether nodes are encoded and decoded as attributes or elements: DynamicNodeEncoding and DynamicNodeDecoding.
The declarations of the protocols are very simple:
protocol DynamicNodeEncoding: Encodable {
static func nodeEncoding(for key: CodingKey) -> XMLEncoder.NodeEncoding
}
protocol DynamicNodeDecoding: Decodable {
static func nodeDecoding(for key: CodingKey) -> XMLDecoder.NodeDecoding
}
The values returned by corresponding static functions look like this:
enum NodeDecoding {
// decodes a value from an attribute
case attribute
// decodes a value from an element
case element
// the default, attempts to decode as an element first,
// otherwise reads from an attribute
case elementOrAttribute
}
enum NodeEncoding {
// encodes a value in an attribute
case attribute
// the default, encodes a value in an element
case element
// encodes a value in both attribute and element
case both
}
Add conformance to an appropriate protocol for types you'd like to customize. Accordingly, this example code:
struct Book: Codable, Equatable, DynamicNodeEncoding {
let id: UInt
let title: String
let categories: [Category]
enum CodingKeys: String, CodingKey {
case id
case title
case categories = "category"
}
static func nodeEncoding(for key: CodingKey) -> XMLEncoder.NodeEncoding {
switch key {
case Book.CodingKeys.id: return .both
default: return .element
}
}
}
works for this XML:
<book id="123">
<id>123</id>
<title>Cat in the Hat</title>
<category>Kids</category>
<category>Wildlife</category>
</book>
Please refer to PR #70 by @JoeMatt for more details.
Coding key value intrinsic
Suppose that you need to decode an XML that looks similar to this:
<?xml version="1.0" encoding="UTF-8"?>
<foo id="123">456</foo>
By default you'd be able to decode foo as an element, but then it's not possible to decode the id attribute. XMLCoder handles certain CodingKey values in a special way to allow proper coding for this XML. Just add a coding key with stringValue that equals "" (empty string). What follows is an example type declaration that encodes the XML above, but special handling of coding keys with those values works for both encoding and decoding.
struct Foo: Codable, DynamicNodeEncoding {
let id: String
let value: String
enum CodingKeys: String, CodingKey {
case id
case value = ""
}
static func nodeEncoding(forKey key: CodingKey)
-> XMLEncoder.NodeEncoding {
switch key {
case CodingKeys.id:
return .attribute
default:
return .element
}
}
}
Thanks to @JoeMatt for implementing this in in PR #73.
Preserving whitespaces in element content
By default whitespaces are trimmed in element content during decoding. This includes string values decoded with value intrinsic keys. Starting with version 0.5 you can now set a property trimValueWhitespaces to false (the default value is true) on XMLDecoder instance to preserve all whitespaces in decoded strings.
Choice element coding
Starting with version 0.8, you can encode and decode enums with associated values by conforming your CodingKey type additionally to XMLChoiceCodingKey. This allows decoding XML elements similar in structure to this example:
<container>
<int>1</int>
<string>two</string>
<string>three</string>
<int>4</int>
<int>5</int>
</container>
To decode these elements you can use this type:
enum IntOrString: Equatable {
case int(Int)
case string(String)
}
extension IntOrString: Codable {
enum CodingKeys: String, XMLChoiceCodingKey {
case int
case string
}
func encode(to encoder: Encoder) throws {
var container = encoder.container(keyedBy: CodingKeys.self)
switch self {
case let .int(value):
try container.encode(value, forKey: .int)
case let .string(value):
try container.encode(value, forKey: .string)
}
}
init(from decoder: Decoder) throws {
let container = try decoder.container(keyedBy: CodingKeys.self)
do {
self = .int(try container.decode(Int.self, forKey: .int))
} catch {
self = .string(try container.decode(String.self, forKey: .string))
}
}
}
This is described in more details in PR #119 by @jsbean and @bwetherfield.
Integrating with Combine
Starting with XMLCoder version 0.9, when Apple's Combine framework is available, XMLDecoder conforms to the TopLevelDecoder protocol, which allows it to be used with the decode(type:decoder:) operator:
import Combine
import Foundation
import XMLCoder
func fetchBook(from url: URL) -> AnyPublisher<Book, Error> {
return URLSession.shared.dataTaskPublisher(for: url)
.map(\.data)
.decode(type: Book.self, decoder: XMLDecoder())
.eraseToAnyPublisher()
}
This was implemented in PR #132 by @sharplet.
Additionally, starting with XMLCoder 0.11 XMLEncoder conforms to the TopLevelEncoder protocol:
import Combine
import XMLCoder
func encode(book: Book) -> AnyPublisher<Data, Error> {
return Just(book)
.encode(encoder: XMLEncoder())
.eraseToAnyPublisher()
}
The resulting XML in the example above will start with <book, to customize capitalization of the root element (e.g. <Book) you'll need to set an appropriate keyEncoding strategy on the encoder. To change the element name altogether you'll have to change the name of the type, which is an unfortunate limitation of the TopLevelEncoder API.
Root element attributes
Sometimes you need to set attributes on the root element, which aren't directly related to your model type. Starting with XMLCoder 0.11 the encode function on XMLEncoder accepts a new rootAttributes argument to help with this:
struct Policy: Encodable {
var name: String
}
let encoder = XMLEncoder()
let data = try encoder.encode(Policy(name: "test"), rootAttributes: [
"xmlns": "http://www.nrf-arts.org/IXRetail/namespace",
"xmlns:xsd": "http://www.w3.org/2001/XMLSchema",
"xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance",
])
The resulting XML will look like this:
<policy xmlns="http://www.nrf-arts.org/IXRetail/namespace"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<name>test</name>
</policy>
This was implemented in PR #160 by @portellaa.
Installation
Requirements
Apple Platforms
- Xcode 11.0 or later
- IMPORTANT: compiling XMLCoder with Xcode 11.2.0 (11B52) and 11.2.1 (11B500) is not recommended due to crashes with
EXC_BAD_ACCESScaused by a compiler bug, please use Xcode 11.3 or later instead. Please refer to #150 for more details.
- IMPORTANT: compiling XMLCoder with Xcode 11.2.0 (11B52) and 11.2.1 (11B500) is not recommended due to crashes with
- Swift 5.1 or later
- iOS 9.0 / watchOS 2.0 / tvOS 9.0 / macOS 10.10 or later deployment targets
Linux
- Ubuntu 18.04 or later
- Swift 5.1 or later
Swift Package Manager
Swift Package Manager is a tool for managing the distribution of Swift code. It’s integrated with the Swift build system to automate the process of downloading, compiling, and linking dependencies on all platforms.
Once you have your Swift package set up, adding XMLCoder as a dependency is as easy as adding it to the dependencies value of your Package.swift.
dependencies: [
.package(url: "https://github.com/MaxDesiatov/XMLCoder.git", from: "0.12.0")
]
If you're using XMLCoder in an app built with Xcode, you can also add it as a direct dependency using Xcode's GUI.
CocoaPods
CocoaPods is a dependency manager for Swift and Objective-C Cocoa projects for Apple's platfoms. You can install it with the following command:
$ gem install cocoapods
Navigate to the project directory and create Podfile with the following command:
$ pod install
Inside of your Podfile, specify the XMLCoder pod:
# Uncomment the next line to define a global platform for your project
# platform :ios, '9.0'
target 'YourApp' do
# Comment the next line if you're not using Swift or don't want
# to use dynamic frameworks
use_frameworks!
# Pods for YourApp
pod 'XMLCoder', '~> 0.12.0'
end
Then, run the following command:
$ pod install
Open the the YourApp.xcworkspace file that was created. This should be the file you use everyday to create your app, instead of the YourApp.xcodeproj file.
Carthage
Carthage is a dependency manager for Apple's platfoms that builds your dependencies and provides you with binary frameworks.
Carthage can be installed with Homebrew using the following command:
$ brew update
$ brew install carthage
Inside of your Cartfile, add GitHub path to XMLCoder:
github "MaxDesiatov/XMLCoder" ~> 0.12.0
Then, run the following command to build the framework:
$ carthage update
Drag the built framework into your Xcode project.
Contributing
This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected].
Sponsorship
If this library saved you any amount of time or money, please consider sponsoring the work of its maintainer. While some of the sponsorship tiers give you priority support or even consulting time, any amount is appreciated and helps in maintaining the project.
Coding Style
This project uses SwiftFormat and SwiftLint to enforce formatting and coding style. We encourage you to run SwiftFormat within a local clone of the repository in whatever way works best for you either manually or automatically via an Xcode extension, build phase or git pre-commit hook etc.
To guarantee that these tools run before you commit your changes on macOS, you're encouraged to run this once to set up the pre-commit hook:
brew bundle # installs SwiftLint, SwiftFormat and pre-commit
pre-commit install # installs pre-commit hook to run checks before you commit
Refer to the pre-commit documentation page for more details and installation instructions for other platforms.
SwiftFormat and SwiftLint also run on CI for every PR and thus a CI build can fail with incosistent formatting or style. We require CI builds to pass for all PRs before merging.
Test Coverage
Our goal is to keep XMLCoder stable and to serialize any XML correctly according to XML 1.0 standard. All of this can be easily tested automatically and we're slowly improving test coverage of XMLCoder and don't expect it to decrease. PRs that decrease the test coverage have a much lower chance of being merged. If you add any new features, please make sure to add tests, likewise for changes and any refactoring in existing code.
![[WIP / Proof of concept] Add Decoding support for enums with associated values](https://avatars.githubusercontent.com/u/7040073?v=4)
1.3k Jan 3, 2023
24 Mar 31, 2022
99 Sep 6, 2022
109 Jan 6, 2023
994 Jan 2, 2023
824 Dec 15, 2022
2.3k Dec 31, 2022
531 Jan 1, 2023
2.6k Dec 14, 2022
15 Dec 7, 2022
65 Dec 29, 2020
5 Nov 26, 2022
1.1k Dec 16, 2022
48 Nov 22, 2022
3.7k Jan 6, 2023
14 Dec 31, 2022
1 Jun 18, 2022
12 Sep 22, 2022
24 Aug 30, 2022
975 Dec 26, 2022