io_vdir/lib.rs
1#![no_std]
2#![cfg_attr(docsrs, feature(doc_cfg))]
3
4//! # io-vdir
5//!
6//! I/O-free Vdir coroutines: every filesystem operation on a [vdir]
7//! tree is a resumable state machine that emits requests (create a
8//! directory, read a file, rename a path, draw random bytes) instead
9//! of performing the I/O itself. The caller services each request and
10//! resumes the coroutine, so the same logic drives blocking, async or
11//! in-memory harnesses without change.
12//!
13//! ## Layers
14//!
15//! The core [`coroutine`] layer is `no_std` and pulls no runtime: it
16//! defines the [`coroutine::VdirCoroutine`] trait, the shared
17//! [`coroutine::VdirYield`] request and [`coroutine::VdirReply`]
18//! response enums, and the `vdir_try!` macro that chains one
19//! coroutine into another. The optional `client` feature adds
20//! [`client::VdirClient`], a blocking client that runs any coroutine
21//! against the local filesystem through `std::fs`.
22//!
23//! ## Layout
24//!
25//! The source tree mirrors the two Vdir concepts. [`collection`] owns
26//! the [`collection::VdirCollection`] handle and one coroutine per
27//! directory operation (create, delete, list, rename, update).
28//! [`item`] owns the [`item::VdirItem`] handle, its
29//! [`item::VdirItemKind`] and one coroutine per item operation
30//! (store, get, list, locate, copy, move, delete). [`path`] holds the
31//! forward-slash [`path::VdirPath`] newtype shared across both.
32//!
33//! ## Encoding
34//!
35//! Items are opaque bytes at every level: io-vdir never parses them,
36//! leaving the choice of vCard or iCalendar parser to the caller. The
37//! `serde` feature derives (de)serialization on the public handles.
38//!
39//! [vdir]: https://vdirsyncer.pimutils.org/en/stable/vdir.html
40
41#[macro_use]
42extern crate alloc;
43#[cfg(feature = "client")]
44extern crate std;
45
46#[cfg(feature = "client")]
47pub mod client;
48pub mod collection;
49pub mod coroutine;
50pub mod item;
51pub mod path;