Files
craft-libs/crates/vcard/src/write.rs
Dylan M. TaylorandMartin Ball f3944ba991 Add craft-vcard: vCard reader and writer from MailCraft (#942)
* craft-mime: strict base64, mailto links and code page labels from MailCraft

What MailCraft's mime and charset crates still had that craft-mime did not:
strict RFC 4648 base64 (crates/charset), mailto: links (RFC 6068,
crates/mime) and the Windows code page to charset label table (crates/pst).
With these, MailCraft's charset crate has nothing craft-mime lacks.

* Add craft-vcard: vCard reader and writer from MailCraft

MailCraft crates/vcard at a44a450: vCard 2.1, 3.0 and 4.0 read, 3.0 written,
with its limits and tests. The model is the crate's own Contact (the vCard
fields of MailCraft's); the birthday is a chrono::NaiveDate. Character sets
and strict base64 come from craft-mime.

---------

Co-authored-by: Martin Ball <98639962+benandez@users.noreply.github.com>
2026-11-11 18:50:38 -05:00

327 lines
13 KiB
Rust

//! Writing contacts as vCard 3.0.
use crate::Contact;
use chrono::{Datelike, NaiveDate};
use crate::lines::fold;
use crate::text::{escape, multi, single};
/// Write vCard 3.0 cards, CRLF line endings, lines folded at 75 octets on char boundaries.
///
/// `FN` is the contact's [`name`](Contact::name). Values are escaped. Every field but the notes is
/// one line: its line breaks and other control characters become spaces. A label the format has a
/// `TYPE` for (`work`, `home`, `other`; for phones also `mobile`, `fax`, `pager`) is written as
/// that type; any other label is written as the `X-ABLabel` of a group (`item1.TEL` +
/// `item1.X-ABLabel:Car`), which is how address books exchange custom labels. E-mail addresses,
/// phone numbers, postal addresses and web sites with nothing in them are left out. Keys are
/// written as `KEY;TYPE=X509;ENCODING=b:` and `KEY;TYPE=PGP;ENCODING=b:`; one that would not read
/// back as itself is left out, and so is the address of a key, which vCard 3.0 has no form for.
pub fn write(contacts: &[&Contact]) -> String {
let mut out = String::new();
for contact in contacts {
card(&mut out, contact);
}
out
}
/// A one-line field, escaped.
fn field(s: &str) -> String {
escape(&single(s))
}
/// `NAME:value` when there is a value.
fn optional(out: &mut String, name: &str, value: &str) {
let value = field(value);
if !value.is_empty() {
fold(out, &format!("{name}:{value}"));
}
}
/// The `TYPE` of an e-mail or postal address label, when the format has one for it.
fn place_type(label: &str) -> Option<&'static str> {
match label {
"work" => Some("WORK"),
"home" => Some("HOME"),
"other" => Some("OTHER"),
_ => None,
}
}
fn phone_type(label: &str) -> Option<&'static str> {
match label {
"mobile" => Some("CELL"),
"fax" => Some("FAX"),
"pager" => Some("PAGER"),
_ => place_type(label),
}
}
/// One labelled property. `kind` is the type the property always has (`INTERNET`), `known` the
/// type its label stands for; a label without one goes into an `X-ABLabel` of the same group.
fn labeled(out: &mut String, groups: &mut u32, name: &str, kind: Option<&str>, known: Option<&str>, label: &str, value: &str) {
let types: Vec<&str> = kind.into_iter().chain(known).collect();
let params = if types.is_empty() { String::new() } else { format!(";TYPE={}", types.join(",")) };
let custom = if known.is_some() { String::new() } else { field(label) };
if custom.is_empty() {
fold(out, &format!("{name}{params}:{value}"));
} else {
*groups = groups.saturating_add(1);
fold(out, &format!("item{groups}.{name}{params}:{value}"));
fold(out, &format!("item{groups}.X-ABLabel:{custom}"));
}
}
fn card(out: &mut String, c: &Contact) {
fold(out, "BEGIN:VCARD");
fold(out, "VERSION:3.0");
fold(out, &format!("N:{};{};{};;", field(&c.last), field(&c.first), field(&c.middle)));
fold(out, &format!("FN:{}", field(&c.name())));
optional(out, "NICKNAME", &c.nickname);
let (company, department) = (field(&c.company), field(&c.department));
if !department.is_empty() {
fold(out, &format!("ORG:{company};{department}"));
} else if !company.is_empty() {
fold(out, &format!("ORG:{company}"));
}
optional(out, "TITLE", &c.title);
let mut groups = 0u32;
for email in &c.emails {
let value = field(&email.value);
if !value.is_empty() {
labeled(out, &mut groups, "EMAIL", Some("INTERNET"), place_type(&email.label), &email.label, &value);
}
}
for phone in &c.phones {
let value = field(&phone.value);
if !value.is_empty() {
labeled(out, &mut groups, "TEL", None, phone_type(&phone.label), &phone.label, &value);
}
}
for address in c.addresses.iter().filter(|a| !a.is_empty()) {
// Post office box and extended address stay empty: the model keeps them in the street.
let value = format!(
";;{};{};{};{};{}",
field(&address.street),
field(&address.city),
field(&address.region),
field(&address.postal_code),
field(&address.country)
);
labeled(out, &mut groups, "ADR", None, place_type(&address.label), &address.label, &value);
}
for site in &c.websites {
optional(out, "URL", site);
}
if let Some(day) = c.birthday {
// A date that exists, whatever the fields say.
// A year a card can say (1 to 9999), whatever the date's is.
let year = day.year().clamp(1, 9999);
let day = day.with_year(year).or_else(|| NaiveDate::from_ymd_opt(year, day.month(), 28)).unwrap_or_default();
fold(out, &format!("BDAY:{}", day.format("%Y-%m-%d")));
}
let notes = escape(&multi(&c.notes));
if !notes.is_empty() {
fold(out, &format!("NOTE:{notes}"));
}
let categories: Vec<String> = c.categories.iter().map(|name| field(name)).filter(|name| !name.is_empty()).collect();
if !categories.is_empty() {
fold(out, &format!("CATEGORIES:{}", categories.join(",")));
}
for key in c.keys.iter().filter_map(crate::key::line).take(Contact::MAX_KEYS) {
fold(out, &key);
}
optional(out, "UID", &c.uid);
if c.favorite {
fold(out, "X-MAILCRAFT-FAVORITE:TRUE");
}
fold(out, "END:VCARD");
}
#[cfg(test)]
mod tests {
use crate::{Labeled, PostalAddress};
use super::*;
fn lines(c: &Contact) -> Vec<String> {
let out = write(&[c]);
assert!(out.ends_with("END:VCARD\r\n"));
let mut cursor = crate::lines::Lines::new(&out);
std::iter::from_fn(|| cursor.next_line(false)).collect()
}
fn nadia() -> Contact {
Contact {
display_name: "Dr. Nadia Okafor".into(),
first: "Nadia".into(),
middle: "Chidi".into(),
last: "Okafor".into(),
nickname: "Nadi".into(),
company: "Example Research, Inc.".into(),
title: "Lead Scientist; Field".into(),
department: "Field Lab".into(),
emails: vec![
Labeled::new("work", "nadia.okafor@example.org"),
Labeled::new("", "nadia@example.org"),
Labeled::new("Family", "nadia@family.example.org"),
Labeled::new("home", " "),
],
phones: vec![
Labeled::new("mobile", "+1 (555) 010-0142"),
Labeled::new("fax", "+1 555 010 0144"),
Labeled::new("Car, old", "+1 555 010 0145"),
Labeled::new("", "+1 555 010 0146"),
],
addresses: vec![
PostalAddress {
label: "work".into(),
street: "Suite 300, 41 Harbor Road".into(),
city: "Riverton".into(),
region: "CA".into(),
postal_code: "94000".into(),
country: "USA".into(),
},
PostalAddress { label: "home".into(), ..Default::default() },
PostalAddress { label: "Cabin".into(), city: "Pinewood".into(), ..Default::default() },
],
websites: vec!["https://example.org/~nadia".into(), "".into()],
birthday: NaiveDate::from_ymd_opt(1985, 4, 12),
notes: "Met at the 2024 symposium.\r\nPrefers e-mail, not calls.".into(),
categories: vec!["Research".into(), "Field Team, West".into(), " ".into()],
favorite: true,
uid: "7f1c2f6e-0001-4a5b-9c3d-000000000042".into(),
..Default::default()
}
}
#[test]
fn writes_a_whole_card() {
assert_eq!(
lines(&nadia()),
[
"BEGIN:VCARD",
"VERSION:3.0",
"N:Okafor;Nadia;Chidi;;",
"FN:Dr. Nadia Okafor",
"NICKNAME:Nadi",
"ORG:Example Research\\, Inc.;Field Lab",
"TITLE:Lead Scientist\\; Field",
"EMAIL;TYPE=INTERNET,WORK:nadia.okafor@example.org",
"EMAIL;TYPE=INTERNET:nadia@example.org",
"item1.EMAIL;TYPE=INTERNET:nadia@family.example.org",
"item1.X-ABLabel:Family",
"TEL;TYPE=CELL:+1 (555) 010-0142",
"TEL;TYPE=FAX:+1 555 010 0144",
"item2.TEL:+1 555 010 0145",
"item2.X-ABLabel:Car\\, old",
"TEL:+1 555 010 0146",
"ADR;TYPE=WORK:;;Suite 300\\, 41 Harbor Road;Riverton;CA;94000;USA",
"item3.ADR:;;;Pinewood;;;",
"item3.X-ABLabel:Cabin",
"URL:https://example.org/~nadia",
"BDAY:1985-04-12",
"NOTE:Met at the 2024 symposium.\\nPrefers e-mail\\, not calls.",
"CATEGORIES:Research,Field Team\\, West",
"UID:7f1c2f6e-0001-4a5b-9c3d-000000000042",
"X-MAILCRAFT-FAVORITE:TRUE",
"END:VCARD",
]
);
}
#[test]
fn an_empty_contact_is_still_a_card() {
assert_eq!(write(&[&Contact::default()]), "BEGIN:VCARD\r\nVERSION:3.0\r\nN:;;;;\r\nFN:\r\nEND:VCARD\r\n");
assert_eq!(write(&[]), "");
}
#[test]
fn the_formatted_name_falls_back_as_the_model_does() {
let named = Contact { first: "Ada".into(), last: "Lovelace".into(), ..Default::default() };
assert!(lines(&named).contains(&"FN:Ada Lovelace".to_string()));
let company = Contact { company: "Analytical Engines Ltd".into(), ..Default::default() };
assert_eq!(lines(&company).get(2..5).unwrap(), ["N:;;;;", "FN:Analytical Engines Ltd", "ORG:Analytical Engines Ltd"]);
let mail = Contact { emails: vec![Labeled::new("home", "x@example.org")], department: "Only a department".into(), ..Default::default() };
assert_eq!(lines(&mail).get(3..6).unwrap(), ["FN:x@example.org", "ORG:;Only a department", "EMAIL;TYPE=INTERNET,HOME:x@example.org"]);
}
#[test]
fn every_known_label_is_a_type() {
let c = Contact {
emails: ["work", "home", "other", "mobile", "Work"].map(|l| Labeled::new(l, "a@example.org")).to_vec(),
phones: ["mobile", "work", "home", "fax", "pager", "other", "HOME"].map(|l| Labeled::new(l, "1")).to_vec(),
..Default::default()
};
let got = lines(&c);
assert_eq!(
got.get(4..20).unwrap(),
[
"EMAIL;TYPE=INTERNET,WORK:a@example.org",
"EMAIL;TYPE=INTERNET,HOME:a@example.org",
"EMAIL;TYPE=INTERNET,OTHER:a@example.org",
"item1.EMAIL;TYPE=INTERNET:a@example.org",
"item1.X-ABLabel:mobile",
"item2.EMAIL;TYPE=INTERNET:a@example.org",
"item2.X-ABLabel:Work",
"TEL;TYPE=CELL:1",
"TEL;TYPE=WORK:1",
"TEL;TYPE=HOME:1",
"TEL;TYPE=FAX:1",
"TEL;TYPE=PAGER:1",
"TEL;TYPE=OTHER:1",
"item3.TEL:1",
"item3.X-ABLabel:HOME",
"END:VCARD",
]
);
}
#[test]
fn lines_end_in_crlf_and_stay_within_75_octets() {
let mut c = nadia();
c.notes = "Ünïcödé — 東京 🎉 ".repeat(60);
c.display_name = "é".repeat(200);
let out = write(&[&c, &c]);
assert_eq!(out.matches("BEGIN:VCARD\r\n").count(), 2);
assert!(!out.replace("\r\n", "").contains(['\r', '\n']));
assert!(out.split("\r\n").all(|line| line.len() <= 75), "{out}");
assert!(out.contains("\r\n "));
}
#[test]
fn text_cannot_inject_lines() {
let c = Contact {
display_name: "Ada\r\nEND:VCARD\r\nBEGIN:VCARD".into(),
first: "A\nTEL:666".into(),
nickname: "x\rEMAIL:evil@example.org".into(),
emails: vec![Labeled::new("work\r\nTEL:1", "a@example.org\r\nTEL:2")],
notes: "one\r\nEND:VCARD\rtwo\u{0}".into(),
categories: vec!["a\nb".into()],
uid: "u\nUID:2".into(),
..Default::default()
};
let got = lines(&c);
assert_eq!(got.iter().filter(|l| l.starts_with("BEGIN:") || l.starts_with("END:")).count(), 2, "{got:?}");
assert!(!got.iter().any(|l| l.starts_with("TEL")), "{got:?}");
assert_eq!(got.iter().filter(|l| l.starts_with("UID") || l.contains("EMAIL")).count(), 3, "{got:?}");
assert!(got.contains(&"FN:Ada END:VCARD BEGIN:VCARD".to_string()));
assert!(got.contains(&"NOTE:one\\nEND:VCARD\\ntwo".to_string()));
assert!(got.contains(&"item1.X-ABLabel:work TEL:1".to_string()));
}
#[test]
fn hostile_birthdays_are_written_as_real_dates() {
for hostile in [
NaiveDate::MIN,
NaiveDate::MAX,
NaiveDate::from_ymd_opt(0, 1, 1).unwrap(),
NaiveDate::from_ymd_opt(-4, 2, 29).unwrap(),
NaiveDate::from_ymd_opt(10_000, 2, 29).unwrap(),
] {
let c = Contact { birthday: Some(hostile), ..Default::default() };
let back = crate::parse(&write(&[&c]));
assert!(back[0].birthday.is_some(), "{hostile:?}");
}
}
}