Module duplicates 

Duplicates in the address books, looked for and cleaned only when you ask: a number or an address written twice on one card, and two cards that may be one person. Nothing changes without your click, and every change keeps the cards as they were, to put them back.

• On one card: numbers are compared by their international form (phones::key: “04 65 71 12 34” is “+33 4 65 71 12 34”), e-mail addresses case aside. Of the same value written twice, the line kept is the one written internationally, else the one that says most of what it is for; it takes what the others said (“mobile”, “work”, to use first), and its value is never rewritten.
• Two cards: the same number, the same e-mail address, or the same name (case, accents, punctuation and the order of words aside: “DUPONT, Jean” is “Jean Dupont”). What many cards share (a switchboard, an office’s address, a common name) says nothing of one person. “Not the same” is remembered, never asked again.
• Merging keeps the card whose name you keep as it is and adds what only the other one has: numbers, e-mail and postal addresses, web sites, categories, chat addresses; notes joined; a photo, an organisation, a birthday when it has none. The other card is deleted, and the sync deletes it on the server.
• Undo: before any change the cards as they were are kept in $XDG_STATE_HOME/sioul/contacts-undo, thirty days; undoing writes them back, and the sync sends them again.

Structs

Change

One file changed: the card before and after it; none before, it was made; none after, it was deleted.

Cleaning

A card that holds a number or an address twice, and what cleaning it takes off.

Done

What was done to the cards, kept to undo it.

NotTheSame

Pairs of cards said not to be one person: never offered again on this computer.

Pair

Two cards that may be one person, and what they share.

Removed

A value a cleaning takes off, and the one kept for it, as the card writes them.

Constants

AT_MOST 🔒

How many cards may share a number, an address or a name and still say one person: more is a switchboard, an office, a common name.

KEPT_DAYS

How long the cards as they were are kept, to undo: thirty days.

SEVERAL 🔒

Properties of several values the other card brings, unless the leading one has the same.

SINGLE 🔒

Properties of one value: the card that leads keeps its own; the other one fills it when the leading card has none.

Functions

apply

Makes changes, the cards as they were saved first in dir; returns what was done. When one change fails, those made before it are undone.

as_vcard3_line 🔒

A line of a vCard 4.0 card as vCard 3.0 writes it (contacts::as_vcard3); none when 3.0 has no such property.

clean

A card’s values written twice taken off: the same number (phones::key with region), the same e-mail address. Returns its new text, REV renewed, and what goes; none when nothing is there twice.

clean_files

Cleans these cards, one write each, the cards as they were kept first in dir; none when no card holds anything twice any more.

cleanings

The cards holding a number or an address twice, as contacts orders them; cards that can only be read are left out. Only those whose values repeat are read again from their files.

comparable 🔒

A value as compared between two cards: a web site without its scheme, “www.” or last slash; an address by its words; anything case and spaces aside.

done

What was done lately, the newest first. What is older than thirty days goes, with the versions set aside by its undoing.

email_key

An e-mail address as compared: trimmed, without “mailto:”, case aside.

finish 🔒

The card’s lines with added before END and REV renewed, folded.

group_of 🔒

A line’s group as written (“item1” of “item1.TEL;…”); none without one.

identity 🔒

What a card is known by for “not the same”: its UID, else its file.

informative 🔒

Whether a kind says what a value is for: “voice”, “internet” and “pref” do not.

is_companion 🔒

Whether a line only says something of another line of its group: Apple’s labels and address formats (item1.X-ABLabel), not its related names and dates.

is_id 🔒

An id of what was done: letters, digits and dashes, nothing that leaves its folder.

latin 🔒

Latin letters text::fold_char leaves with their marks (it knows French’s).

merge

Two cards made one. lead stays as it is: its name, and its organisation, birthday and photo when it has them. other adds what only it has: numbers and e-mail addresses (the same ones written twice then cleaned, clean), postal addresses, web sites and chat addresses unless the same, its categories, its notes after a blank line (unless one holds the other), and what lead lacks of one value. Apple’s groups get names of their own; a vCard 4.0 line going into a 3.0 card is written as 3.0. REV renewed.

merge_files

Merges two cards (merge): the leading one’s file holds them both, the other’s is deleted; both kept as they were first in dir.

name_key

What two names are compared by: case, accents, punctuation and the order of words aside (“DUPONT, Jean” is “Jean Dupont”, “Zoë” is “Zoe”).

pairs

The pairs of cards that may be one person: the same name, number or e-mail address; cards that can only be read, and pairs said not the same, left out. Those sharing most come first.

put 🔒

replace 🔒

A property’s lines replaced by one, where the first was; added when there was none.

same_group 🔒

says 🔒

How much a value’s line says of what it is for: its kinds (“work”, “cell”), a label of its own (Apple’s), whether it comes first.

undo

Puts the cards back as they were before id, then forgets it. A card changed since (a sync, an edit) is set aside first, as <id>.<n>.vcf beside the record. Files outside root (the address books) are never written; a card whose address book is gone stays gone. Returns the files written back or removed, and how many versions were set aside.

undo_dir

$XDG_STATE_HOME/sioul/contacts-undo: what was done to the cards, with them as they were.

with_kinds 🔒

The line with more kinds in its TYPE and, when asked, marked as the one to use first; its value as it was. Kinds are written in the case its TYPE uses, else upper case in vCard 3.0 and lower case in 4.0.