io_vdir/
item.rs

1//! Vdir items: the [`VdirItem`] handle and its [`VdirItemKind`], plus
2//! the I/O-free coroutines for the item lifecycle (store, get, list,
3//! locate, copy, move, delete).
4//!
5//! An item is a single vCard ([RFC 6350]) or iCalendar ([RFC 5545])
6//! file, as laid out by the [vdir specification]. The coroutine
7//! submodules own one operation each; this module owns the shared
8//! handle and the file extensions they key off.
9//!
10//! [RFC 6350]: https://www.rfc-editor.org/rfc/rfc6350
11//! [RFC 5545]: https://www.rfc-editor.org/rfc/rfc5545
12//! [vdir specification]: https://vdirsyncer.pimutils.org/en/stable/vdir.html
13
14use core::hash::{Hash, Hasher};
15
16use alloc::vec::Vec;
17
18use crate::path::VdirPath;
19
20pub mod copy;
21pub mod delete;
22pub mod get;
23pub mod list;
24pub mod locate;
25pub mod r#move;
26pub mod store;
27
28/// File extension of vCard items.
29pub(crate) const VCF: &str = "vcf";
30
31/// File extension of iCalendar items.
32pub(crate) const ICS: &str = "ics";
33
34/// Temporary file extension used while atomically replacing an item
35/// or a metadata file.
36pub(crate) const TMP: &str = "tmp";
37
38/// Kind of a Vdir item.
39///
40/// Either an iCalendar component (`.ics`) or a vCard (`.vcf`).
41#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
42#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
43pub enum VdirItemKind {
44    /// iCalendar variant: event, task, alarm, or any valid iCalendar
45    /// component.
46    Ical,
47    /// vCard variant: a contact.
48    Vcard,
49}
50
51impl VdirItemKind {
52    /// Returns the file extension associated with the item kind.
53    pub fn extension(&self) -> &'static str {
54        match self {
55            Self::Ical => ICS,
56            Self::Vcard => VCF,
57        }
58    }
59
60    /// Parses an extension string into a [`VdirItemKind`].
61    pub fn from_extension(ext: &str) -> Option<Self> {
62        match ext {
63            ICS => Some(Self::Ical),
64            VCF => Some(Self::Vcard),
65            _ => None,
66        }
67    }
68}
69
70/// A Vdir collection's item.
71///
72/// Carries the on-disk path, the parsed kind (from the file
73/// extension) and the raw file bytes. The bytes stay raw: io-vdir
74/// never decodes them, leaving the choice of vCard or iCalendar
75/// parser to the caller.
76#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd)]
77#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
78pub struct VdirItem {
79    /// On-disk path of the item file.
80    pub path: VdirPath,
81    /// Kind of the item, derived from the file extension.
82    pub kind: VdirItemKind,
83    /// Raw file bytes.
84    pub contents: Vec<u8>,
85}
86
87impl VdirItem {
88    /// Returns the item id: the file stem (final path component
89    /// without the extension), or the whole file name when no
90    /// extension is present.
91    pub fn id(&self) -> Option<&str> {
92        let name = self.path.file_name()?;
93        Some(match name.rsplit_once('.') {
94            Some((stem, _)) if !stem.is_empty() => stem,
95            _ => name,
96        })
97    }
98
99    /// Returns the item bytes.
100    pub fn contents(&self) -> &[u8] {
101        &self.contents
102    }
103}
104
105impl Hash for VdirItem {
106    fn hash<H: Hasher>(&self, state: &mut H) {
107        self.path.hash(state);
108    }
109}
110
111impl AsRef<VdirPath> for VdirItem {
112    fn as_ref(&self) -> &VdirPath {
113        &self.path
114    }
115}
116
117impl From<(VdirPath, VdirItemKind, Vec<u8>)> for VdirItem {
118    fn from((path, kind, contents): (VdirPath, VdirItemKind, Vec<u8>)) -> Self {
119        Self {
120            path,
121            kind,
122            contents,
123        }
124    }
125}
io_vdir/item.rs

io_vdir/
item.rs
