README.md — sigil-xmpp

1# sigil-xmpp

A [Sigil](https://codeberg.org/sigil/sigil) library for XMPP (Jabber) messaging. Provides a full-featured client with STARTTLS, SASL authentication, roster management, presence tracking, and Multi-User Chat (MUC) support.

5## Features

7- **Connection management** -- STARTTLS upgrade, SASL authentication (SCRAM-SHA-1, PLAIN)

8- **JID handling** -- parse and format JIDs, extract user/domain/resource

9- **Stanza construction** -- build and inspect messages, presence, and IQ stanzas

10- **Roster management** -- fetch, add, remove contacts, handle subscription requests

11- **Presence tracking** -- monitor availability by resource, set your own status

12- **Multi-User Chat** -- join/leave rooms, occupant tracking, group/private messaging (XEP-0045)

13- **Cooperative I/O** -- blocking (`xmpp-run`) or non-blocking (`xmpp-tick`) event loops

15## Usage

17Add `sigil-xmpp` as a dependency in your `package.sgl`:

19```scheme

20(from-git url: "codeberg:sigil/sigil-xmpp" package: "sigil-xmpp")

21```

23Then import and connect:

25```scheme

26(import (sigil xmpp))

28(define conn (make-xmpp-connection

29 host: "xmpp.example.com"

30 jid: "[email protected]"

31 password: "secret"))

33;; Install roster, presence, and MUC handling

34(xmpp-install-features conn)

36;; Set up message handler

37(xmpp-on conn 'message

38 (lambda (stanza)

39 (display (stanza-body stanza))))

41;; Connect and run

42(xmpp-connect conn)

43(xmpp-set-status conn "Online")

44(xmpp-run conn)

45```

47## Modules

49| Module | Description |

50|--------|-------------|

51| `(sigil xmpp)` | Top-level re-exports |

52| `(sigil xmpp stanza)` | JID parsing, stanza construction and inspection |

53| `(sigil xmpp sasl)` | SASL authentication (SCRAM-SHA-1, PLAIN) |

54| `(sigil xmpp connection)` | Connection lifecycle, event handling, I/O loop |

55| `(sigil xmpp roster)` | Roster management and subscription handling |

56| `(sigil xmpp presence)` | Presence tracking by resource |

57| `(sigil xmpp muc)` | Multi-User Chat rooms and occupant tracking |

59## Dependencies

61- sigil-stdlib

62- sigil-socket

63- sigil-tls

64- sigil-crypto

65- sigil-sxml

67## Building

69```bash

70sigil deps install

71sigil build

72sigil test

73```

75## License

77BSD-3-Clause