Swiftpack.co - Package - sersoft-gmbh/XMLWrangler

XMLWrangler

GitHub release Tests Codacy Badge codecov jazzy

Easily deal with XMLs in Swift.

Installation

Add the following dependency to your Package.swift:

.package(url: "https://github.com/sersoft-gmbh/xmlwrangler.git", from: "5.0.0"),

Compatibility

  • For Swift up to version 5.2, use XMLWrangler version 3.x.y.
  • For Swift as of version 5.3, use XMLWrangler version 5.x.y.

Usage

XMLElement

Every element in an XML is represented by the XMLElement struct. It has three properties, name which reflects the element's tag name, attributes which contains all attributes of the element and content which describes the content of the element. The content is an collection whose Element is an enum. The enum has two cases: .string and .element. The order in the collection is the order in which the content has been found. So if an element first contains some text, then contains a child element and finally again some text, content will contain a .string whose associated StringPart is the first text. Next there would be a .element whose associated XMLElement would be the child element. Finally, there would be another .string with the last text.

While you can create an XMLElement with a content of [.string("abc"), .string("def"), .element(XMLElement(name: "test"))], and it would also lead to valid XML, it could be cleaned up to [.string("abcdef"), .element(XMLElement(name: "test"))]. To achieve that, it's recommended to use the various append functions on XMLElement.content or even XMLElement directly when you can't assure that the content is cleaned upon creation. If your element was created with an empty content ([]), and you append each of the content elements above, the append functions make sure that they append the "def" string to the first "abc" string instead of adding another .string to the content. If for some reason you still end up with a situation where your content has consecutive .string elements, there's a convenience function compress() (or it's non-mutating sibling compressed()), which merges these .string elements into one.

An XMLElement can be compared to another element and is considered equal if all three properties (name, attributes and content) are equal. This means that for a big tree, all children of the root element will be compared. So be careful when comparing big trees and fall back to manually comparing name and/or attributes if necessary. XMLElement also conforms to Identifiable and uses the name as id.

Both, serializing and parsing XMLs with XMLWrangler relies on XMLElement.

Parsing XMLs

Parsing existing XMLs can be done using the Parser class. You can instantiate a parser with either a given Data object or a String containing the XML.

Once you have a parser ready, you can call parse() on it, and it'll try to parse the XML. If that succeeds, it'll return the parsed root object. Otherwise it throws whatever error happend along the way. Errors thrown are the ones created by Foundation.XMLParser.

do {
    let xml = """
              <?xml version='1.0' encoding='UTF-8'?>
              <root myattr='myvalue'>
                  <child1/>
                  <child2>some text</child2>
              </root>
              """
    let parser = Parser(string: xml)
    let rootElement = try parser.parse()
} catch {
    print("Something went wrong while parsing: \(error)")
}

In this example, root.name.rawValue would of course be "root". rootElement.content would contain two .elements. The first would have a associated XMLElement with a name of "child1" and an empty content. The name of XMLElement of the second .element would be "child2" and its content would contain one .string having "some text" associated. root.attributes would contain the value "myvalue" for the key "myattr".

Serializing XMLElements

Since you can parse XMLs, you can also convert an XMLElement to a String. For this, there are two initializers on String added in XMLWrangler. The first one just converts an XMLElement into a String. This happens by creating an opening and ending tag (where the beginning tag contains the attributes if available) and putting the content of the element in between. If content is empty, then no ending tag is created and the opening tag is directly closed with />. Also, content is compressed (using the aforementioned compress function) before being serialized.

var root = XMLElement(name: "root", attributes: ["myattr": "myvalue"])
root.content.append(element: "child1")
root.content.append(element: XMLElement(name: "child2", content: "some text"))

let xml = String(xml: root) // -> "<root myattr=\"myvalue\"><child1/><child2>some text</child2></root>"

If the traditional XML header should also be added, there's a second initializer which takes a version and a document encoding as additional parameters, but otherwise follows the same rules:

var root = XMLElement(name: "root", attributes: ["myattr": "myvalue"])
root.content.append(element: "child1")
root.content.append(element: XMLElement(name: "child2", content: "some text"))

let xml = String(xmlDocumentRoot: root, version: Version(major: 1), encoding: .utf8)
// -> "<?xml version=\"1.0\" encoding=\"UTF-8\"?><root myattr=\"myvalue\"><child1/><child2>some text</child2></root>"

For more information on Version see SemVer but note that only major and minor are used for XMLs. Please note that currently XMLWrangler only supports serializing documents for the following encodings:

  • UTF-8
  • UTF-16
  • ASCII

Both initializers can take an additional parameter options which contains a set of options to control the serialization behaviour. Currently the following options are possible:

  • .pretty: Use pretty formatting. This adds newlines around the tags to make the resulting XML more readable. This is usually not needed for processing XML.
  • .singleQuoteAttributes: When this option is present, then attributes of elements will be enclosed in single quotes (') instead of double quotes (").

Type safety

XMLWrangler will always extract all content and attributes as String. This is because XML itself does not differentiate between types like e.g. JSON does. However, there are many helper functions to safely look up and convert content and attributes of an XMLElement:

  • First, there are helpers to extract all child elements with a given name: XMLElement.elements(named:)
  • Next, there are helpers to extract an element at a given path: XMLElement.element(at:)
  • Another helper allows to extract attributes of an element: XMLElement.attribute(for:).
  • It is then also possible to convert those attributes (for some types like e.g. RawRepresentable you don't need to pass a converter): XMLElement.convertedAttribute(for:converter:)
  • Last but not least you can extract the string content of an Element: XMLElement.stringContent()
  • And of course as you can with attributes, you can also convert string content: XMLElement.convertedStringContent(converter:)

All these methods throw an error (LookupError) when something went wrong instead of returning optionals. If you prefern an optional, you can always use try?. For more information also check the header docs which describe these methods a little closer.

Possible Features

While not yet integrated, the following features might provide added value and could make it into XMLWrangler in the future:

  • Indention support for serializing and parsing.
  • Extracting "KeyPaths": It could be useful to directly extract a path. It would not be necessary to extract every single element then.

Documentation

The API is documented using header doc. If you prefer to view the documentation as a webpage, there is an online version available for you.

Contributing

If you find a bug / like to see a new feature in XMLWrangler there are a few ways of helping out:

  • If you can fix the bug / implement the feature yourself please do and open a PR.
  • If you know how to code (which you probably do), please add a (failing) test and open a PR. We'll try to get your test green ASAP.
  • If you can do neither, then open an issue. While this might be the easiest way, it will likely take the longest for the bug to be fixed / feature to be implemented.

License

See LICENSE file.

Github

link
Stars: 3

Dependencies

Used By

Total: 0

Releases

v5.0 RC1 - 2020-10-16 06:52:05

This is the first release candidate for a version 5.0.

Changes

  • Massive internal refactoring (addendum to version 4.0)
  • Element is now named XMLElement with a typealias XWElement for disambiguation with Foundation.XMLElement
  • All References to object that referred to an XMLElement have been replaced with element.
  • XMLElement.Content is now a custom collection implementation containing the enum that was previously Element.Content.
  • XMLElement.Attributes is now a custom collection implementation that works similar to a dictionary. The XMLElement.Attributes.Key is what was previously Element.AttributeKey. XMLElement.Attributes.Content is what was previously Element.AttributeValue.
  • The XMLAttributeContentConvertible, ExpressibleByXMLAttributeContent and XMLAttributeRepresentableProtocol (which is the combination of the former two) can now be used to create attributes with dictionary literals. This allows e.g. the following code to work:
let existingString = "abc"
let attributeContent = XMLElement.Attributes.Content("some value")
let attributes: XMLElement.Attributes = [
    "testKey": existingString,
    "otherAttribute": "whatever",
    "existingContent": attributeContent,
]

v4.0.0 - 2020-10-11 15:47:25

Version 4.0.0

  • Adds support for Swift 5.3, dropping support for previous Swift versions.
  • Removes previously deprecated APIs
  • Renames the package to xmlwrangler (from XMLWrangler). Please adjust your target dependency definition to: .product(name: "XMLWrangler", package: "xmlwrangler")
  • Adds ExpressibleByXMLElement and XMLElementConvertible protocols for dealing with Elements and types easier. There is also XMLElementRepresentable which is simply the combination of the two aforementioned protocols.
  • Some convenience APIs that were simply a chain of calling other public APIs were removed (e.g. convertedStringContent(ofElementAt:)). Please use the corresponding public APIs directly (e.g. element(at: /*...*/).convertedStringContent().

v3.4.2 - 2020-04-09 17:04:09

Fixes #11.

v3.4.1 - 2020-03-25 12:50:25

Add support for Swift 5.2

v3.4.0 - 2019-09-26 14:18:09

This adds support for Swift 5.1 while keeping Swift 5.0 support

v3.3.1 - 2019-07-28 18:25:00

  • Extend Travis configuration
  • Add documentation

v3.3.0 - 2019-04-18 12:58:49

This adds a new function to remove Elements at a given path. The functions for replacing elements were not consistently named. This was fixed by adding new functions with the correct naming and deprecating the old ones.

v3.2.0 - 2019-03-26 08:07:28

Add support for Swift 5 (backwards compatible with Swift 4.2)

v3.1.3 - 2019-01-22 11:26:56

Add mutating access methods to Element. See #7.

v3.1.2 - 2019-01-21 18:50:00

Fix some overload ambiguities (see #6)

v3.1.1 - 2019-01-18 17:05:46

Slight project restructuring for enabling CodeCov

v3.1.0 - 2019-01-03 15:55:18

This adds a standalone Xcode project (in the Xcode subfolder) for integration with "normal" Xcode projects (outside of the Swift Package Manager) and some new tests.

v3.0.1 - 2018-09-19 06:49:25

Thanks to a new linux CI integration, a problem building on linux was fixed in this version.

v3.0.0 - 2018-08-29 15:56:50

This adds support for Swift 4.2 and adds a Travis CI integration. Also, Parser can now be created from a String non-optionally.

v2.0.0 - 2018-08-29 15:55:45

Swift 4.1 support

Version 1.2.1 - 2018-01-05 08:36:41

Fixed a compile order issue caused by a file name.

Version 1.2.0 - 2018-01-04 18:01:12

This includes a major change in how the API works. First of all, Element.Content.object now only contains one Element. This makes it easier since we only have to deal with one array of objects when using allObjects of Element.content. Lookup methods were adapted/removed.

Next, this contains a whole new set of lookup methods. They throw an error if something goes wrong (using try? you can always get an Optional). They allow going down a path of elements to access nested elements. They allow conversion of attributes and string content. All existing conversion methods were deprecated or removed.

Element.name is now of type Element.Name to allow static typing of element names.

Serialization now correctly deals with mixed contents. A new method compress on Element.content allows to merge consecutive .string elements into one.

Version 1.1.0 - 2017-12-29 07:59:31

  • Allow mixed content: content is now an Array<Element.Content> so that mixed content is possible (first a string, then some child objects, then again string, etc.). Except for code that does directly deal with the content property of Element, this should mostly be a non-breaking change since extensions assure most of the functionality again. E.g. appending works fine on the array, too, due to extensions on the Collection protocols.

  • A few more convenience extensions.

Version 1.0.2 - 2017-12-27 15:08:29

Swift 4

1.0.1 - 2017-07-31 14:23:15

This adds a few more convenience interfaces

1.0.0 - 2017-07-30 12:14:25

Initial Release