iksemel

Copyright (c) 2000-2026 Gurer Ozen

iks is an XML parser library for Jabber/XMPP and general XML processing applications. It aims to be easy to use, fast, and usable in resource-constrained environments.

Features

• SAX API for minimal memory usage.
• DOM API for flexible and powerful document querying and editing.
• Stream API for efficient XMPP stream processing.
• Sans-IO XMPP client protocol.
• A simple blocking IO XMPP client API.
• Experimental basic XPath support.
• Python bindings.

XMPP Compliance

Non-features

• Only accepts UTF-8 encoded XML.
• Document Type Definitions (DTD, the DOCTYPE element basically) are syntactically parsed but not used for validation or custom entity substitution.
• Processing instructions and comments are parsed but not passed to the application.

These are all intentional decisions rather than technical limitations, and will never be implemented. See DESIGN.md file for the rationale and alternative solutions.

Installation

You can use it in your rust projects by adding the following to your Cargo.toml:

[dependencies]
iks = "0.7.0"

This adds Rustls and a bunch of its dependencies to be able to securely communicate with the XMPP servers. If you only need XML parsing and not the XMPP functionality, you can use Iksemel with zero external dependencies like this:

[dependencies]
iks = { version = "0.7.0", default-features = false }

You can install the command line tools with:

cargo install iks

Usage

See API documentation for detailed examples and information.

Here is a simple example:

use iks::Document;
use std::str::FromStr;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let doc = Document::from_str("<doc><a>123</a><b><a>456</a><a>789</a></b></doc>")?;

    let count = doc
        .root()
        .descendant_or_self()
        .filter(|element| element.name() == "a")
        .enumerate()
        .map(|(index, element)| element.set_attribute("nr", Some(&index.to_string())))
        .count();

    assert!(count == 3);
    assert!(
        doc.to_string()
            == "<doc><a nr=\"0\">123</a><b><a nr=\"1\">456</a><a nr=\"2\">789</a></b></doc>"
    );

    Ok(())
}

Tools

Iksemel provides a few command line tools for quick XML processing:

• ikslint: validates XML files
• ikspath: loads XML files into a DOM tree and runs XPath queries on them
• iksjab: send messages and manage your roster over XMPP

Python

Source code of Python bindings can be found at iksemel-python project, and the wheels are uploaded on PyPI as pyiks package.

Contributing

There are many ways to contribute to the project. See also the design decisions document.

Thanks

This code would not be possible without Cargo Mutants and Miri.

No library should ever be released without Semver Checks.

License

Iksemel is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Iksemel is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with Iksemel. If not, see https://www.gnu.org/licenses/.