iks 0.7.0

Fast, easy to use XML parser library for Jabber/XMPP and general XML processing
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151

# iksemel

Copyright (c) 2000-2026 Gurer Ozen <meduketto at gmail.com>

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

[![Crates.io Version](https://img.shields.io/crates/v/iks)](https://crates.io/crates/iks)
[![Crates.io Size](https://img.shields.io/crates/size/iks)](https://crates.io/crates/iks)
[![Crates.io Downloads (recent)](https://img.shields.io/crates/dr/iks)](https://crates.io/crates/iks)
![GitHub License](https://img.shields.io/github/license/meduketto/iksemel-rust)

# 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][SANSIO] XMPP client protocol.
* A simple blocking IO XMPP client API.
* Experimental basic XPath support.
* Python bindings.

# XMPP Compliance

| Document | Title               | Status       |
|----------|---------------------|--------------|
| RFC 6120 | XMPP Core           | Mostly done
| RFC 6121 | XMPP IM             | In progress
| RFC 7622 | XMPP Address Format | In progress

# 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](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`:

```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:

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

You can install the command line tools with:

```sh
cargo install iks
```

# Usage

See [API documentation][IKSAPI] for detailed examples and information.

Here is a simple example:

```rust
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][IKSEMELPYTHON]
project, and the wheels are uploaded on PyPI as [pyiks][PYIKS] package.

# Contributing

There are many [ways to contribute](CONTRIBUTING.md) to the project. See also
the [design decisions](DESIGN.md) document.

# Thanks

This code would not be possible without [Cargo Mutants][MUTANTS]
and [Miri][MIRI].

No library should ever be released without
[Semver Checks][SEMVER].

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


[iks]: https://github.com/meduketto/iksemel-rust
[IKSAPI]: https://docs.rs/iks/latest/iks/
[XMPP]: https://xmpp.org
[SANSIO]: https://sans-io.readthedocs.io/how-to-sans-io.html
[MUTANTS]: https://github.com/sourcefrog/cargo-mutants
[MIRI]: https://github.com/rust-lang/miri
[SEMVER]: https://github.com/obi1kenobi/cargo-semver-checks
[IKSEMELPYTHON]: https://github.com/meduketto/iksemel-python
[PYIKS]: https://pypi.org/project/pyiks/