Module contacts 

Contacts: one vCard per person (RFC 6350; 3.0 from RFC 2426 too), as the address books on disk hold them (vdir).

Sioul shows and edits the fields people use: the name, addresses, phone numbers, the organisation, postal addresses, the birthday, notes and web sites. Whatever else a card holds (a photo, another application’s fields) is kept as it was when Sioul writes it back. New cards are written in vCard 3.0, which every server and phone reads.

Structs

Contact

A contact as the window shows it.

ContactEdit

What the contact form gives back.

Labeled

A value with what it is for: “work”, “home”, “cell”…; empty when the card does not say.

Line 🔒

A content line taken apart: its group, name and parameters; the value stays in the line.

Functions

address_lines 🔒

ADR’s seven parts (box, extended, street, locality, region, code, country) on lines: the street, then “code locality”, the region, the country.

address_parts 🔒

Lines back into ADR’s parts, for an address typed or changed here: a line whose first word is a postal code is “code locality”; after it, a last line is the country; the lines before make the street.

all

Every contact of every address book, by name.

apply

The card’s text with what the form changed, and nothing else: an unchanged value keeps its line byte for byte (its group, its PREF, its spelling), so what another application wrote is never rewritten for nothing. A card nothing changed in comes back exactly as it was.

as_vcard3

A card as vCard 3.0 (RFC 2426), for servers that take nothing newer (Google): what only 4.0 has goes, PREF=1 becomes TYPE=pref, a photo given as a data: address is written inline. A 3.0 card comes back as is.

birthday_of 🔒

“1984-05-12”, or “–05-12” without the year: from “19840512”, “1984-05-12T00:00:00”, and Apple’s way of saying “no year” (X-APPLE-OMIT-YEAR).

by_address

The contact with this e-mail address.

categories_in_use

The categories the cards have, to filter by: the most used first, then by name; each name once (category_key), as first written.

categories_line 🔒

The one CATEGORIES line of these names, each escaped (A\,B).

categories_of 🔒

A card’s categories: every CATEGORIES line, its names split at unescaped commas, each name once (category_key), as first written.

category_key

What two category names are compared by: trimmed, case and accents folded (text::fold), so “Amis”, “ amis“ and “AMIS” are one category. The sender lists match categories the same way (porch.rs).

completions

Addresses to complete what is typed in a To field: “Jane jane@example.org”.

components 🔒

The parts of a structured value (N, ADR, ORG), split at unescaped semicolons, unescaped.

contact 🔒

The contact a card’s lines stand for.

default_book

Where a new contact goes: the first address book that can be written to.

display_name 🔒

The name a card is shown by: its FN, else its structured name, else its organisation, else its first e-mail address.

folded 🔒

in_category

Whether a contact has this category, case and accents aside.

is_code_line 🔒

Whether a line is “code locality”: its first word four or five digits (“69000 Lyon Cedex 03”, “1000 Bruxelles”), not a street number (“1 allée…”).

is_preferred 🔒

Whether the card marks this value as the one to use first (TYPE=PREF, PREF=1).

known_type 🔒

label_of 🔒

“work”, “home”, “cell”…; “internet”, “voice” and “pref” say nothing.

merge 🔒

One property of several values: an unchanged value keeps its line; a new label rewrites only that line (keeping its group and PREF); new values are added; values gone are removed, with the lines their group carried (Apple’s item1.X-ABLabel). Returns whether anything changed.

new_card

A new card from the form, in vCard 3.0, with its own UID.

new_card_with_uid

A new card from the form, with the UID given (an import that must find it again).

new_path

The file a new contact gets in an address book.

now_stamp 🔒

“20261003T120000Z”, for REV.

one_line 🔒

A value written as it is (a date, a web address): without line breaks or other control characters, which would start another line of the card.

parse

Reads one card with calcard, to tell whether it is valid vCard.

photo_in 🔒

photo_of 🔒

A card’s picture, to show: an embedded photo (vCard 3.0 ENCODING=b, vCard 4.0 data: address) written once into the cache, named by what it holds, so the same picture is one file; a web address (https only) as it is.

read

One contact from its file.

search

Contacts whose name, organisation, addresses or numbers hold the query.

set_categories 🔒

The card’s categories made these (category_key once each): its CATEGORIES lines untouched when they say the same, else one line where the first was. Returns whether anything changed.

shown 🔒

What the window shows of a line, by property: the same reading for showing and for editing.

sort_key 🔒

Names sort without their accents and case: “Émile” next to “Emma”.

split_line 🔒

split_unescaped 🔒

A value split at the separators that are not escaped (A\,B stays one), each part unescaped.

structured_name 🔒

“Jane van Exemple” → N: family “van Exemple”? Names do not split by rule; the last word is taken as the family name, the rest as given names.

tidy_address

An address as it reads back once written: its lines, their parts found.

types_of 🔒

Every TYPE value of a line, lower case: “TYPE=HOME,PREF” and “TYPE=home;TYPE=pref” alike.

write_value 🔒

A value’s line, as vCard 3.0 writes it.