| blob | ab0ce65ca8de64508cfa552b0bf32bf763e3a731 |
1 ;;; bbdb-vcard.el --- vCard import/export for BBDB
3 ;; Copyright (c) 2010 Bert Burgemeister
5 ;; Author: Bert Burgemeister <trebbu@googlemail.com>
6 ;; Keywords: data calendar mail news
7 ;; URL: http://github.com/trebb/bbdb-vcard
8 ;; Version: 0.2
10 ;; This program is free software; you can redistribute it and/or
11 ;; modify it under the terms of the GNU General Public License as
12 ;; published by the Free Software Foundation; either version 2, or (at
13 ;; your option) any later version.
14 ;;
15 ;; This program is distributed in the hope that it will be useful, but
16 ;; WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 ;; General Public License for more details.
19 ;;
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with GNU Emacs; see the file COPYING. If not, write to the
22 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
23 ;; Boston, MA 02111-1307, USA.
25 ;; The exporter functionality is based on code from
26 ;; bbdb-vcard-export.el by Jim Hourihan and Alex Schroeder.
27 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
30 ;;; Commentary:
31 ;;
32 ;; Purpose
33 ;; =======
34 ;;
35 ;; Import and export of vCards as defined in RFC 2425 and RFC 2426
36 ;; to/from The Insidious Big Brother Database (BBDB).
37 ;;
38 ;;
39 ;; Usage
40 ;; =====
41 ;;
42 ;; vCard Import
43 ;; ------------
44 ;;
45 ;; On a file, a buffer or a region containing one or more vCards, use
46 ;; `bbdb-vcard-import-file', `bbdb-vcard-import-buffer', or
47 ;; `bbdb-vcard-import-region' respectively to import them into BBDB.
48 ;;
49 ;; Preferred input format is vCard version 3.0. Version 2.1 vCards
50 ;; are converted to version 3.0 on import.
51 ;;
52 ;;
53 ;; vCard Export
54 ;; ------------
55 ;;
56 ;; In buffer *BBDB*, press v to export the record under point. Press
57 ;; * v to export all records in buffer into one vCard file. Press *
58 ;; C-u v to export them into one file each.
59 ;;
60 ;; To put one or all vCard(s) into the kill ring, press V or * V
61 ;; respectively.
62 ;;
63 ;; Exported vCards are always version 3.0. They can be re-imported
64 ;; without data loss with one exception: North American phone numbers
65 ;; lose their structure and are stored as flat strings.
66 ;;
67 ;;
68 ;; There are a few customization variables grouped under `bbdb-vcard'.
69 ;;
70 ;;
71 ;; Installation
72 ;; ============
73 ;;
74 ;; Put this file and file vcard.el into your `load-path' and add the
75 ;; following line to your Emacs initialization file:
76 ;;
77 ;; (require 'bbdb-vcard)
78 ;;
79 ;;
80 ;; Implementation
81 ;; ==============
82 ;;
83 ;; vCard Import
84 ;; ------------
85 ;;
86 ;; For conversion of v2.1 vCards into v3.0 on import, Noah Friedman's
87 ;; vcard.el is needed.
88 ;;
89 ;; An existing BBDB record is extended by new information from a vCard
90 ;;
91 ;; (a) if name and company and an email address match
92 ;; (b) or if name and company match
93 ;; (c) or if name and an email address match
94 ;; (d) or if name and birthday match
95 ;; (e) or if name and a phone number match.
96 ;;
97 ;; Otherwise, a fresh BBDB record is created.
98 ;;
99 ;; When `bbdb-vcard-try-merge' is set to nil, there is always a fresh
100 ;; record created.
101 ;;
102 ;; In cases (c), (d), and (e), if the vCard has ORG defined, this ORG
103 ;; would overwrite an existing Company in BBDB.
104 ;;
105 ;; Phone numbers are always imported as strings.
106 ;;
107 ;; For vCard types that have more or less direct counterparts in BBDB,
108 ;; labels and parameters are translated and structured values
109 ;; (lastname; firstname; additional names; prefixes etc.) are
110 ;; converted appropriately with the risk of some (hopefully
111 ;; unessential) information loss. For labels of the vCard types ADR
112 ;; and TEL, parameter translation is defined in
113 ;; `bbdb-vcard-import-translation-table'.
114 ;;
115 ;; If there is a REV element, it is stored in BBDB's creation-date in
116 ;; newly created BBDB records, or discarded for existing ones.
117 ;;
118 ;; VCard type prefixes (A.ADR:..., B.ADR:... etc.) are stripped off
119 ;; and discarded from the following types: N, FN, NICKNAME, ORG (first
120 ;; occurrence), ADR, TEL, EMAIL, URL, BDAY (first occurrence), NOTE.
121 ;;
122 ;; VCard types that are prefixed `X-BBDB-' are stored in BBDB without
123 ;; the prefix.
124 ;;
125 ;; VCard type X-BBDB-ANNIVERSARY may contain (previously exported)
126 ;; newline-separated non-birthday anniversaries that are meant to be
127 ;; read by org-mode.
128 ;;
129 ;; All remaining vCard types that don't match the regexp in
130 ;; `bbdb-vcard-skip-on-import' and that have a non-empty value are
131 ;; stored unaltered in the BBDB Notes alist where, for instance,
132 ;; `TZ;VALUE=text:-05:00' is stored as `(tz\;value=text . "-05:00")'.
133 ;; From the BBDB data fields AKA, Phones, Addresses, Net Addresses,
134 ;; and Notes, duplicates are removed, respectively.
135 ;;
136 ;; VCards found inside other vCards (as values of type AGENT) are
137 ;; imported as well.
138 ;;
139 ;;
140 ;; Handling of the individual types defined in RFC2426 during import
141 ;; (assuming default label translation and no vCard type exclusion):
142 ;; "
143 ;; |----------------------+----------------------------------------|
144 ;; | VCARD TYPE; | STORAGE IN BBDB |
145 ;; | PARAMETERS | |
146 ;; |----------------------+----------------------------------------|
147 ;; | VERSION | - |
148 ;; |----------------------+----------------------------------------|
149 ;; | N | First occurrence: |
150 ;; | | Firstname |
151 ;; | | Lastname |
152 ;; | | |
153 ;; | | Rest: |
154 ;; | | AKAs (append) |
155 ;; |----------------------+----------------------------------------|
156 ;; | FN | AKAs (append) |
157 ;; | NICKNAME | AKAs (append) |
158 ;; |----------------------+----------------------------------------|
159 ;; | ORG | First occurrence: |
160 ;; | | Company |
161 ;; | | |
162 ;; | | Rest: |
163 ;; | | Notes<org |
164 ;; | | (repeatedly) |
165 ;; |----------------------+----------------------------------------|
166 ;; | ADR;TYPE=x,HOME,y | Addresses<Home |
167 ;; | ADR;TYPE=x;TYPE=HOME | Addresses<Home |
168 ;; | ADR;TYPE=x,WORK,y | Addresses<Office |
169 ;; | ADR;TYPE=x;TYPE=WORK | Addresses<Office |
170 ;; | ADR;TYPE=x,y,z | Addresses<x,y,z |
171 ;; | ADR;TYPE=x;TYPE=y | Addresses<x,y |
172 ;; | ADR | Addresses<Office |
173 ;; |----------------------+----------------------------------------|
174 ;; | TEL;TYPE=x,HOME,y | Phones<Home (append) |
175 ;; | TEL;TYPE=x;TYPE=HOME | Phones<Home (append) |
176 ;; | TEL;TYPE=x,WORK,y | Phones<Office (append) |
177 ;; | TEL;TYPE=x;TYPE=WORK | Phones<Office (append) |
178 ;; | TEL;TYPE=x,CELL,y | Phones<Mobile (append) |
179 ;; | TEL;TYPE=x;TYPE=CELL | Phones<Mobile (append) |
180 ;; | TEL;TYPE=x,y,z | Phones<x,y,z (append) |
181 ;; | TEL;TYPE=x;TYPE=y | Phones<x,y (append) |
182 ;; | TEL | Phones<Office (append) |
183 ;; |----------------------+----------------------------------------|
184 ;; | EMAIL;TYPE=x,y,z | Net-Addresses (append) |
185 ;; | URL | Notes<www |
186 ;; |----------------------+----------------------------------------|
187 ;; | BDAY | Notes<anniversary (append as birthday) |
188 ;; | X-BBDB-ANNIVERSARY | Notes<anniversary (append) |
189 ;; |----------------------+----------------------------------------|
190 ;; | NOTE | Notes<notes (append) |
191 ;; | REV | Notes<creation-date |
192 ;; | CATEGORIES | Notes<mail-alias (append) |
193 ;; | SORT-STRING | Notes<sort-string |
194 ;; | KEY | Notes<key |
195 ;; | GEO | Notes<geo |
196 ;; | TZ | Notes<tz |
197 ;; | PHOTO | Notes<photo |
198 ;; | LABEL | Notes<label |
199 ;; | LOGO | Notes<logo |
200 ;; | SOUND | Notes<sound |
201 ;; | TITLE | Notes<title |
202 ;; | ROLE | Notes<role |
203 ;; | AGENT | Notes<agent |
204 ;; | MAILER | Notes<mailer |
205 ;; | UID | Notes<uid |
206 ;; | PRODID | Notes<prodid |
207 ;; | CLASS | Notes<class |
208 ;; | X-foo | Notes<x-foo |
209 ;; | X-BBDB-bar | Notes<bar |
210 ;; |----------------------+----------------------------------------|
211 ;; | anyJunK;a=x;b=y | Notes<anyjunk;a=x;b=y |
212 ;; |----------------------+----------------------------------------|
213 ;; "
214 ;;
215 ;; vCard Export
216 ;; ------------
217 ;;
218 ;; VCard types N (only fields lastname, firstname) and FN both come
219 ;; from BBDB's Name.
220 ;;
221 ;; Members of BBDB field AKA are stored comma-separated under the
222 ;; vCard type NICKNAME.
223 ;;
224 ;; Labels of Addresses and Phones are translated as defined in
225 ;; `bbdb-vcard-export-translation-table' into type parameters of
226 ;; vCard types ADR and TEL, respectively.
227 ;;
228 ;; In vCard type ADR, fields postbox and extended address are always
229 ;; empty. Newlines which subdivide BBDB Address fields are converted
230 ;; into commas subdividing vCard ADR fields.
231 ;;
232 ;; The value of 'anniversary in Notes is supposed to be subdivided by
233 ;; newlines. The birthday part (either just a date or a date followed
234 ;; by \"birthday\") is stored under vCard type BDAY. The rest is
235 ;; stored newline-separated in the non-standard vCard type
236 ;; X-BBDB-ANNIVERSARY.
237 ;;
238 ;; Field names listed in `bbdb-vcard-x-bbdb-candidates' are in the
239 ;; exported vCard prepended by `X-BBDB-'.
240 ;;
241 ;; The creation-date of the BBDB record is stored as vCard type REV.
242 ;;
243 ;; Remaining members of BBDB Notes are exported to the vCard without
244 ;; change.
245 ;;
248 ;;; History:
249 ;;
252 ;;; Code:
260 "Version of the vCard importer/exporter.
263 \f
265 ;;;; User Variables
268 "Customizations for vCards"
272 "Regexp describing vCard elements that are to be discarded during import.
278 "Skip vCard element types with an empty value.
279 Nil means insert empty types into BBDB."
288 "Label translation on vCard import.
289 Alist with translations of location labels for addresses and phone
290 numbers. Cells are (VCARD-LABEL-REGEXP . BBDB-LABEL). One entry
292 corresponds to unlabelled vCard elements."
299 "Try to merge vCards into existing BBDB records.
300 Nil means create a fresh bbdb record each time a vCard is read."
305 "Function to apply to vCard type names on export.
306 Most reasonable choices are `upcase' and `downcase'."
312 finger-host
313 gnus-score
314 mark-char
315 mail-name
316 face
317 tex-name
319 "List of translatable BBDB user field names.
320 On export to a vCard, they are transformed into vCard-compliant
321 extended types by prepending `X-BBDB-'. On (re-)import, this prefix
322 is removed again."
329 "Label translation on vCard export.
330 Alist with translations of location labels for addresses and phone
331 numbers. Cells are (BBDB-LABEL-REGEXP . VCARD-LABEL)."
339 "Coding system to use when writing vCard files."
344 "Default storage directory for exported vCards.
345 Nil means current directory."
349 \f
351 ;;;; User Functions
353 ;;;###autoload
355 "Import the vCards between BEGIN and END into BBDB.
356 Existing BBDB records may be altered."
361 ;;;###autoload
363 "Import vCards from VCARD-BUFFER into BBDB.
364 Existing BBDB records may be altered."
369 ;;;###autoload
371 "Import vCards from VCARD-FILE into BBDB.
372 If VCARD-FILE is a wildcard, import each matching file. Existing BBDB
373 records may be altered."
380 ;;;###autoload
383 "From Buffer *BBDB*, write one or more record(s) as vCard(s) to file(s).
387 records currently
388 in the *BBDB* buffer. If used with prefix argument, store records
389 in individual files."
400 "Write vCards to file: "
401 bbdb-vcard-default-dir
402 nil nil
405 bbdb-vcard-default-dir nil nil default-filename))
406 all-records-p ; argument all-records-p
418 used-up-basenames)))
434 ;;;###autoload
436 "From Buffer *BBDB*, copy one or more record(s) as vCard(s) to the kill ring.
441 then export all records currently in
442 the *BBDB* buffer."
455 ;;;###autoload (define-key bbdb-mode-map [(v)] 'bbdb-vcard-export)
457 ;;;###autoload (define-key bbdb-mode-map [(V)] 'bbdb-vcard-export-to-kill-ring)
460 \f
463 "Apply VCARD-PROCESSOR successively to each vCard in string VCARDS.
464 When VCARDS is nil, return nil. Otherwise, return t."
468 ;; Change CRLF into CR if necessary, dealing with inconsistent line
469 ;; endings.
475 "^\\([[:alnum:]-]*\\.\\)?*BEGIN:VCARD[\n[:print:][:cntrl:]]*?\\(^\\([[:alnum:]-]*\\.\\)?END:VCARD\\)"
476 nil t)
485 "Return version number string of VCARD."
491 "Store VCARD (version 3.0) in BBDB.
492 Extend existing BBDB records where possible."
496 ;; Name suitable for storing in BBDB:
499 ;; Name to search for in BBDB now:
502 raw-name
504 " .*"
506 ;; Additional names from prefixed types like A.N, B.N, etc.:
520 ;; Company suitable for storing in BBDB:
525 ;; Company to search for in BBDB now:
527 ;; Email suitable for storing in BBDB:
529 ;; Email to search for in BBDB now:
533 ;; Phone numbers suitable for storing in BBDB:
540 ;; Phone numbers to search for in BBDB now:
547 ;; Addresses
554 ;; Birthday suitable for storing in BBDB (usable by org-mode):
556 ;; Birthday to search for in BBDB now:
558 ;; Non-birthday anniversaries, probably exported by ourselves:
565 ;; The BBDB record to change:
569 ;; Try to find an existing one ...
570 ;; (a) try company and net and name:
574 name-to-search-for
575 org-to-search-for email-to-search-for)))
576 ;; (b) try company and name:
580 ;; (c) try net and name; we may change company here:
584 name-to-search-for nil email-to-search-for)))
585 ;; (d) try birthday and name; we may change company here:
589 name-to-search-for nil nil bday-to-search-for)))
590 ;; (e) try phone and name; we may change company here:
594 name-to-search-for nil nil nil tel-to-search-for)))
595 ;; No existing record found; make a fresh one:
601 fresh-record 'creation-date
604 vcard-rev))
607 fresh-record)))
613 notes
614 other-vcard-type)
622 bbdb-record
627 other-names
628 vcard-formatted-names
629 bbdb-akas))))
637 ;; prepare bbdb's notes:
640 ;; Put vCard NOTEs under key 'notes (append if necessary).
649 ;; Put vCard BDAY and vCard X-BBDB-ANNIVERSARY's under key
650 ;; 'anniversary (append if necessary) where org-mode can find it.
660 ;; Put vCard CATEGORIES under key 'mail-alias (append if necessary).
666 vcard-categories
671 ;; Notice other vCards inside the current one.
682 bbdb-record
685 ;; Tell the user what we've done.
687 record-freshness-info
694 "Return BBDB RECORD as a vCard."
715 raw-anniversaries)
722 bbdb-define-all-aliases-field))
741 "TEL;TYPE="
748 "ADR;TYPE="
771 "CATEGORIES"
774 ;; prune raw-notes...
777 ;; ... and output what's left
786 \f
789 "Convert VCARD from v2.1 to v3.0.
790 Return a version 3.0 vCard as a string. Don't bother about the vCard
791 v3.0 mandatory elements N and FN."
792 ;; Prevent customization of vcard.el's from being changed behind our back:
810 INPUT is its representation in vcard.el. Return empty string if INPUT
811 is nil."
816 \f
820 "Return in a list the values of PARAMETER of vCard element of TYPE.
821 The VCard element is read and deleted from current buffer which is
822 supposed to contain a single vCard. If ONE-IS-ENOUGH-P is non-nil,
823 read and delete only the first element of TYPE. If PARAMETER is
825 at semi-colons into a list."
828 type one-is-enough-p split-value-at-semi-colon-p)))
832 "From current buffer read and delete the vCard elements of TYPE.
833 The current buffer is supposed to contain a single vCard. If
834 ONE-IS-ENOUGH-P is non-nil, read and delete only the first element of
835 TYPE. Return a list of alists, one per element. Each alist has a
837 other elements of the form \(parameter-name . parameter-value). If
838 SPLIT-VALUE-AT-SEMI-COLON-P is non-nil, split the value at key
848 nil t))
855 parameters)
862 ;; collect vCard parameter list `;a=x;a=y;a=z'
863 ;; into vCard value list `;a=x,y,z'; becoming ("a" . "x,y,z")
866 ;; vCard parameter pair `;key=value;' with new key
874 "From current buffer read and delete the topmost vCard element.
875 Buffer is supposed to contain a single vCard. Return (TYPE . VALUE)."
884 "Insert a vCard element comprising TYPE, `:', VALUES into current buffer.
885 Take care of TYPE canonicalization, line folding, and closing newline.
886 Do nothing if TYPE is non-nil and VALUES are empty. Insert just a
887 newline if TYPE is nil."
896 \f
899 "Return folded vCard lines from VCARDS unfolded."
903 "Insert after every 75th position in LONG-LINE a newline and a space."
914 ESCAPED-STRINGS may be a string or a sequence of strings."
923 UNESCAPED-STRINGS may be a string or a sequence of strings."
932 "Apply STRING-PROCESSOR to STRINGS.
933 STRINGS may be a string or a sequence of strings."
938 \f
941 "Remove the `X-BBDB-' prefix from the type part of VCARD-ELEMENT if any."
947 "If BBDB-FIELDNAME is in `bbdb-vcard-x-bbdb-candidates', prepend `X-BBDB'."
953 "Convert VCARD-NAME (type N) into (FIRSTNAME LASTNAME)."
971 "Convert VCARD-ORG (type ORG), which may be a list, into a string."
974 vcard-org ; Company, unit 1, unit 2...
978 "Convert VCARD-ADR into BBDB format.
979 Turn a vCard element of type ADR into (TYPE STREETS CITY STATE ZIP
980 COUNTRY)."
997 streets
1004 "Replace escaped newlines in ADDRESS-ELEMENT by commas."
1008 "Translate LABEL from vCard to BBDB or, if EXPORTP is non-nil, vice versa.
1009 Translations are defined in `bbdb-vcard-import-translation-table' and
1010 `bbdb-vcard-export-translation-table' respectively."
1015 bbdb-vcard-export-translation-table
1017 label))))
1020 "Merge strings successively from list NEW-STRINGS into OLD-STRING.
1021 If an element of NEW-STRINGS is already in OLD-STRING, leave
1022 OLD-STRING unchanged. Otherwise append SEPARATOR and NEW-STRING."
1034 "Split TEXT at unescaped occurrences of SEPARATOR; return parts in a list.
1035 Return text unchanged if there aren't any separators and RETURN-ALWAYS-LIST-P
1036 is nil."
1047 string-elements))))
1050 "Concatenate STRINGS and apply `bbdb-vcard-type-canonicalizer' to them."
1054 "Write current buffer to VCARD-FILE-NAME.
1055 Create directories where necessary."
1061 "Come up with a vCard filename given a BBDB-RECORD.
1062 Make it unique against the list USED-UP-BASENAMES."
1066 filename)
1078 used-up-basenames)
1080 filename))
1084 "Search RECORDS for records that match each non-nil argument."
1088 records))
1091 phone-search))
1094 notes-search))
1097 net-search))
1100 company-search)))
1101 name-search))
1103 \f
1107 ;;; bbdb-vcard.el ends here