#vcard API reference

Build and parse vCard (RFC 6350, vCard 4.0): a Card of contact fields encoded to a VCARD and parsed back. The contacts counterpart to ical - it shares the same content-line codec (TEXT escaping, 75-char line folding) through the included ical_vcard_shared.inc.j. Pure Jennifer over strings / lists; both binaries.

A Card carries a formatted name (FN), a full structured name (N: family / given / additional / prefixes / suffixes), a nickname, organisation / title, any number of emails / phones / addresses (each with an optional TYPE like work / home), a birthday, a photo URI, categories, a URL, and a note. encode writes FN and VERSION:4.0 and omits empty fields; parse reads one or many VCARDs, including the TYPE parameter on emails / phones / addresses. Text values are escaped / unescaped and long lines folded, so parse(encode(card)) round-trips.

Import with import "vcard.j" as vcard;. See the vcard guide for prose and examples.

#Functions

#vcard.addAddress(c as Card, a as Address)

A copy of the card with a postal address appended.

Parameters

• c {Card} - the card
• a {Address} - the address

Returns {Card} - a fresh card with the address added

#vcard.addCategory(c as Card, category as string)

A copy of the card with a category (CATEGORIES tag) appended.

Parameters

• c {Card} - the card
• category {string} - the category tag

Returns {Card} - a fresh card with the category added

#vcard.addEmail(c as Card, email as string)

A copy of the card with an email appended.

Parameters

• c {Card} - the card
• email {string} - the email address

Returns {Card} - a fresh card with the email added

#vcard.addEmailTyped(c as Card, email as string, type as string)

A copy of the card with a TYPEd email appended (e.g. type "work" / "home").

Parameters

• c {Card} - the card
• email {string} - the email address
• type {string} - the TYPE (e.g. "work" / "home"; "" for none)

Returns {Card} - a fresh card with the email added

#vcard.addPhone(c as Card, phone as string)

A copy of the card with a phone number appended.

Parameters

• c {Card} - the card
• phone {string} - the phone number

Returns {Card} - a fresh card with the phone added

#vcard.addPhoneTyped(c as Card, phone as string, type as string)

A copy of the card with a TYPEd phone number appended (e.g. type "cell").

Parameters

• c {Card} - the card
• phone {string} - the phone number
• type {string} - the TYPE (e.g. "work" / "home" / "cell"; "" for none)

Returns {Card} - a fresh card with the phone added

#vcard.address(street as string, locality as string, region as string, postalCode as string, country as string)

A postal address.

Parameters

• street {string} - the street address
• locality {string} - the city / locality
• region {string} - the state / province / region
• postalCode {string} - the postal / ZIP code
• country {string} - the country name

Returns {Address} - the address

#vcard.addressTyped(street as string, locality as string, region as string, postalCode as string, country as string, type as string)

A postal address with a TYPE (e.g. "work" / "home").

Parameters

• street {string} - the street address
• locality {string} - the city / locality
• region {string} - the state / province / region
• postalCode {string} - the postal / ZIP code
• country {string} - the country name
• type {string} - the TYPE ("work" / "home"; "" for none)

Returns {Address} - the address

#vcard.card(formattedName as string)

A card with just its formatted name (FN). Other fields are empty until set.

Parameters

• formattedName {string} - the display name

Returns {Card} - the card

#vcard.encode(c as Card)

Render a single card to vCard 4.0 text (a VCARD, CRLF-terminated). Empty optional fields are omitted.

Parameters

• c {Card} - the card to encode

Returns {string} - the vCard text

#vcard.encodeAll(cards as list of Card)

Render many cards to one vCard text (concatenated VCARDs).

Parameters

• cards {list of Card} - the cards to encode

Returns {string} - the vCard text

#vcard.parse(text as string)

Parse vCard text into a list of Cards (one entry per VCARD). Unfolds folded lines, ignores property parameters (the ;KEY=VALUE after a name), reads the structured N / ADR values, and unescapes text values.

Parameters

• text {string} - the vCard text

Returns {list of Card} - the parsed cards (empty when the text has none)

#vcard.withBday(c as Card, bday as string)

A copy of the card with its birthday (BDAY) set. The value is stored verbatim (a YYYYMMDD date, or a partial date like --0315).

Parameters

• c {Card} - the card
• bday {string} - the birthday value

Returns {Card} - a fresh card with the birthday set

#vcard.withFullName(c as Card, family as string, given as string, additional as string, prefixes as string, suffixes as string)

A copy of the card with its full structured name (N) set: family, given, additional (middle) name(s), and honorific prefixes / suffixes.

Parameters

• c {Card} - the card
• family {string} - the family (last) name
• given {string} - the given (first) name
• additional {string} - the additional (middle) name(s)
• prefixes {string} - the honorific prefixes (e.g. "Dr.")
• suffixes {string} - the honorific suffixes (e.g. "Jr.", "PhD")

Returns {Card} - a fresh card with the full name set

#vcard.withName(c as Card, family as string, given as string)

A copy of the card with its structured name (N family / given) set. The additional (middle) name and honorific prefixes / suffixes are left empty; use withFullName to set all five components.

Parameters

• c {Card} - the card
• family {string} - the family (last) name
• given {string} - the given (first) name

Returns {Card} - a fresh card with the name set

#vcard.withNickname(c as Card, nickname as string)

A copy of the card with its nickname (NICKNAME) set.

Parameters

• c {Card} - the card
• nickname {string} - the nickname

Returns {Card} - a fresh card with the nickname set

#vcard.withNote(c as Card, note as string)

A copy of the card with its note set.

Parameters

• c {Card} - the card
• note {string} - the note text

Returns {Card} - a fresh card with the note set

#vcard.withOrg(c as Card, organization as string, title as string)

A copy of the card with its organisation and title set.

Parameters

• c {Card} - the card
• organization {string} - the organisation name
• title {string} - the job title

Returns {Card} - a fresh card with the org / title set

#vcard.withPhoto(c as Card, photo as string)

A copy of the card with its photo (PHOTO) URI set.

Parameters

• c {Card} - the card
• photo {string} - the photo URI

Returns {Card} - a fresh card with the photo set

#vcard.withUrl(c as Card, url as string)

A copy of the card with its URL set.

Parameters

• c {Card} - the card
• url {string} - the URL

Returns {Card} - a fresh card with the URL set

#Structs

#vcard.Address

A postal address (ADR). The RFC's PO-box and extended components are not modelled; the five common fields are, plus an optional TYPE.

#vcard.Card

A contact card.

#vcard.Typed

A value with an optional TYPE parameter (e.g. an email or phone marked work / home). type is "" when unspecified.