iksemel

Copyright (c) 2000-2025 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.

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.5.0"

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

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/.