# I/O Vdir [](https://docs.rs/io-vdir/latest/io_vdir) [](https://matrix.to/#/#pimalaya:matrix.org) [](https://fosstodon.org/@pimalaya) [](https://pimalaya.org/sponsor/)
Vdir client library for Rust
This library is composed of 2 feature-gated layers:
- Low-level **I/O-free** coroutines: no_std-compatible state machines containing the whole Vdir logic, usable anywhere
- Mid-level **standard client**: a blocking client that runs the coroutines against the local filesystem for you
## Table of contents
- [Features](#features)
- [Specification coverage](#specification-coverage)
- [Usage](#usage)
- [Examples](#examples)
- [AI policy](https://github.com/pimalaya/.github/blob/master/AI_POLICY.md)
- [License](#license)
- [Social](#social)
- [Contributing](./CONTRIBUTING.md)
- [Sponsoring](#sponsoring)
## Features
- **I/O-free core**: state machines carrying the whole Vdir logic, with no filesystem calls and no async runtime, so the same operations drive blocking, async or test harnesses.
- **Standard client**: a blocking client running every operation against the local filesystem (requires `client` feature).
- **Collections**: create, delete, list, rename and update collection directories, including the optional display name, description and color metadata markers.
- **Items**: store, get, list, locate, copy, move and delete contact and calendar files, written atomically through a temporary file and a rename.
> [!TIP]
> Each layer is toggled through a cargo feature; the default set is listed in [Cargo.toml](./Cargo.toml) and on [docs.rs](https://docs.rs/crate/io-vdir/latest/features).
## Specification coverage
The library implements the [Vdir storage format](https://vdirsyncer.pimutils.org/en/stable/vdir.html): collections are directories, items are files inside them, and metadata lives in a small set of marker files. Items are either contacts ([vCard](https://www.rfc-editor.org/rfc/rfc6350)) or calendar objects ([iCalendar](https://www.rfc-editor.org/rfc/rfc5545)); io-vdir treats them as opaque bytes and leaves parsing to the consumer.
## Usage
See documentation at [docs.rs](https://docs.rs/io-vdir/latest/io_vdir).
## Examples
See complete examples at [./examples](./examples).
## License
This project is licensed under either of:
- [MIT license](LICENSE-MIT)
- [Apache License, Version 2.0](LICENSE-APACHE)
## Social
- Chat on [Matrix](https://matrix.to/#/#pimalaya:matrix.org)
- News on [Mastodon](https://fosstodon.org/@pimalaya) or [RSS](https://fosstodon.org/@pimalaya.rss)
- Mail at [pimalaya.org@posteo.net](mailto:pimalaya.org@posteo.net)
## Sponsoring
[](https://nlnet.nl/)
Special thanks to the [NLnet foundation](https://nlnet.nl/) and the [European Commission](https://www.ngi.eu/) that have been financially supporting the project for years:
- 2022 → 2023: [NGI Assure](https://nlnet.nl/project/Himalaya/)
- 2023 → 2024: [NGI Zero Entrust](https://nlnet.nl/project/Pimalaya/)
- 2024 → 2026: [NGI Zero Core](https://nlnet.nl/project/Pimalaya-PIM/)
- 2026 → 2027: [NGI Zero Commons Fund](https://nlnet.nl/project/Pimalaya-pimdir/)
This program is part of Pimalaya, free software funded entirely by grants and donations. If you find it useful, consider [sponsoring](https://pimalaya.org/sponsor/) its development:
[](https://github.com/sponsors/soywod)
[](https://ko-fi.com/pimalaya)
[](https://www.buymeacoffee.com/pimalaya)
[](https://liberapay.com/pimalaya)
[](https://thanks.dev/u/gh/soywod)
[](https://www.paypal.com/paypalme/soywod)