ical_vcard

ical_vcard provides a parser and a writer implementation for the content line format that is the base of both the iCalendar (RFC 5545) and the vCard (RFC 6350) data formats. It is NOT a full implementation of either of the standards. Rather, ical_vcard is intended as a foundation on top of which a full-fledged iCalendar or vCard parser and writer can be built.

This crate can of course be used to parse iCalendar or vCard files. However, it cannot provide the convenience or all of the features a specialized iCalendar or vCard library could.

Features

• Content line parser
• Content line writer / formatter
• Conforms to RFC 5545 and RFC 6350. In particular, the parser and the writer adhere to section 3.1 of RFC5545 and section 3 of RFC 6350, which describe the content line format.
• Conforms to RFC 6868, which updates RFC 5545 and RFC 6350 with escape rules for encoding double quotes and line breaks in parameter values.

Example: Parsing Birthdays

This example shows how to transform a vCard file into a HashMap that maps names to birthdays.

use {
    ical_vcard::Parser,
    std::collections::HashMap,
};

let vcard_file = "\
BEGIN:VCARD\r
FN:Mark Daniels\r
BDAY:19830525\r
END:VCARD\r
BEGIN:VCARD\r
FN:Peter Smith\r
BDAY:19770525\r
EMAIL:peter.smith@sw.com\r
END:VCARD\r
BEGIN:VCARD\r
BDAY:19800521\r
FN:Jack Black\r
END:VCARD\r
".as_bytes();

let birthdays: HashMap<_, _> = Parser::new(vcard_file)
    .collect::<Result<Vec<_>, _>>()
    .expect("valid vcard file")
    .split(|contentline| contentline.name == "BEGIN" && contentline.value == "VCARD")
    .flat_map(|vcard| {
        let name = vcard
            .iter()
            .find(|contentline| contentline.name == "FN")?
            .value
            .value()
            .to_owned();
        let birthday = vcard
            .iter()
            .find(|contentline| contentline.name == "BDAY")?
            .value
            .value()
            .to_owned();

        Some((name, birthday))
    })
    .collect();

assert_eq!(birthdays["Peter Smith"], "19770525");
assert_eq!(birthdays["Jack Black"], "19800521");
assert_eq!(birthdays["Mark Daniels"], "19830525");

Example: Names & Email Addresses

This example illustrates how to write a vCard file.

use ical_vcard::{Contentline, Identifier, Param, ParamValue, Value, Writer};

let names = [
    "Aristotle",
    "Plato",
    "Pythagoras",
    "Thales",
];

let contentlines = names.into_iter().flat_map(|name| [
    Contentline {
        group: None,
        name: Identifier::new("BEGIN").unwrap(),
        params: Vec::new(),
        value: Value::new("VCARD").unwrap(),
    },
    Contentline {
        group: None,
        name: Identifier::new("FN").unwrap(),
        params: Vec::new(),
        value: Value::new(name).unwrap(),
    },
    Contentline {
        group: None,
        name: Identifier::new("N").unwrap(),
        params: Vec::new(),
        value: Value::new(format!(";{name};;;")).unwrap(),
    },
    Contentline {
        group: None,
        name: Identifier::new("EMAIL").unwrap(),
        params: vec![Param::new(
            Identifier::new("TYPE").unwrap(),
            vec![ParamValue::new("work").unwrap()]
        ).unwrap()],
        value: Value::new(
            format!("{name}@ancient-philosophers.gr", name = name.to_lowercase())
        ).unwrap(),
    },
    Contentline {
        group: None,
        name: Identifier::new("END").unwrap(),
        params: Vec::new(),
        value: Value::new("VCARD").unwrap(),
    },
]);

let vcard = {
    let mut buffer = Vec::new();
    let mut writer = Writer::new(&mut buffer);
    writer.write_all(contentlines).expect("write to Vec should cause no errors");
    buffer
};

let expected = "\
BEGIN:VCARD\r
FN:Aristotle\r
N:;Aristotle;;;\r
EMAIL;TYPE=work:aristotle@ancient-philosophers.gr\r
END:VCARD\r
BEGIN:VCARD\r
FN:Plato\r
N:;Plato;;;\r
EMAIL;TYPE=work:plato@ancient-philosophers.gr\r
END:VCARD\r
BEGIN:VCARD\r
FN:Pythagoras\r
N:;Pythagoras;;;\r
EMAIL;TYPE=work:pythagoras@ancient-philosophers.gr\r
END:VCARD\r
BEGIN:VCARD\r
FN:Thales\r
N:;Thales;;;\r
EMAIL;TYPE=work:thales@ancient-philosophers.gr\r
END:VCARD\r
".as_bytes();

assert_eq!(vcard, expected);

License

This project is licensed under the MIT License or version 2.0 of the Apache License.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.