vstorage 0.10.0

Common API for various icalendar/vcard storages.
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

//! Collection properties.
//!
//! Storages expose properties for collections. Valid properties vary depending on a storage's
//! item kind. Items themselves cannot have properties.

use std::str::FromStr;

use crate::ItemKind;

/// Property which can be read, written or unset for collections.
///
/// These were known as "metadata" in the original vdirsyncer implementation.
///
/// See also [`Storage::get_property`] and [`Storage::set_property`].
///
/// [`Storage::get_property`]: crate::base::Storage::get_property
/// [`Storage::set_property`]: crate::base::Storage::set_property
#[derive(Clone, Copy, Debug, std::hash::Hash, PartialEq, Eq)]
#[non_exhaustive]
pub enum Property {
    /// User-friendly name for a collection.
    ///
    /// It is recommended to show this name in user interfaces.
    DisplayName,
    /// Human readable description of the collection.
    Description,
    /// Colour to be used when displaying this collection.
    ///
    /// Graphical interfaces may use this for the collection itself or its items.
    ///
    /// Only valid for calendars.
    Colour,
    /// Sorting order for this collection.
    ///
    /// Only valid for calendars.
    Order,
}

impl Property {
    /// Return a friendly name for this property.
    #[must_use]
    pub fn name(&self) -> &'static str {
        match self {
            Property::DisplayName => "displayname",
            Property::Colour => "color",
            Property::Description => "description",
            Property::Order => "order",
        }
    }

    /// Return all known properties of a given kind.
    #[must_use]
    pub fn known_properties(item_kind: ItemKind) -> &'static [Self] {
        match item_kind {
            ItemKind::Calendar => &[
                Property::DisplayName,
                Property::Colour,
                Property::Description,
                Property::Order,
            ],
            ItemKind::AddressBook => &[Property::DisplayName, Property::Description],
        }
    }

    /// Whether this property is valid for the given item kind.
    #[must_use]
    pub fn is_valid_for(&self, item_kind: ItemKind) -> bool {
        match self {
            Property::DisplayName | Property::Description => true,
            Property::Colour | Property::Order => item_kind == ItemKind::Calendar,
        }
    }
}

impl std::fmt::Display for Property {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Property::Colour => f.write_str("colour"),
            Property::DisplayName => f.write_str("display name"),
            Property::Description => f.write_str("description"),
            Property::Order => f.write_str("order"),
        }
    }
}

/// Error type when parsing an invalid string as [`Property`].
#[derive(Debug, thiserror::Error)]
#[error("Not a valid property name.")]
pub struct Invalid;

impl FromStr for Property {
    type Err = Invalid;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s {
            "color" => Ok(Property::Colour),
            "displayname" => Ok(Property::DisplayName),
            "description" => Ok(Property::Description),
            "order" => Ok(Property::Order),
            _ => Err(Invalid),
        }
    }
}

#[cfg(test)]
mod test {
    use crate::{ItemKind, property::Property};

    #[test]
    fn parses_all_values() {
        for property in Property::known_properties(ItemKind::Calendar) {
            assert_eq!(&property.name().parse::<Property>().unwrap(), property);
        }
    }
}