minor doc update
[bbdb-csv-import] / bbdb-csv-import.el
index eb1de9d7ed4c5f4c106fb307f92232d877213f0b..f062617f096cb2cf615b8a35d394204d01a428bf 100644 (file)
@@ -24,7 +24,7 @@
 ;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 ;;; Commentary:
-
+;;
 ;; Importer of csv (comma separated value) text into Emacs’s bbdb database,
 ;; version 3+. Works out of the box with csv exported from Thunderbird, Gmail,
 ;; Linkedin, Outlook.com/hotmail, and probably others. 
 ;;
 ;; Else, note the min versions of dependencies above in "Package-Requires:",
 ;; and load this file. The exact minimum bbdb version is unknown, something 3+.
-
-;;; Usage:
 ;;
-;; You may want to back up existing data in ~/.bbdb and ~/.emacs.d/bbdb in case
-;; you don't like the newly imported data.
+;;; Basic Usage:
+;;
+;; Back up bbdb by copying `bbdb-file' in case things go wrong.
 ;;
 ;; Simply M-x `bbdb-csv-import-buffer' or `bbdb-csv-import-file'.
 ;; When called interactively, they prompt for file or buffer arguments.
+
+;;; Advanced usage / notes:
 ;;
-;; Tested to work with thunderbird, gmail, linkedin, outlook.com/hotmail.com For
+;; Tested to work with thunderbird, gmail, linkedin, outlook.com/hotmail.com. For
 ;; those programs, if it's exporter has an option of what kind of csv format,
 ;; choose it's own native format if available, if not, choose an outlook
-;; compatible format. If you're exporting from some other program, and its csv
+;; compatible format. If you're exporting from some other program and its csv
 ;; exporter claims outlook compatibility, there is a good chance it will work
 ;; out of the box.
 ;;
+;; Duplicate contacts (according to email address) are skipped if
+;; bbdb-allow-duplicates is nil (default). Any duplicates found are echoed at
+;; the end of the import.
+;;
 ;; If things don't work, you can probably fix it with a custom field mapping
 ;; variable. It should not be too hard. Use the existing tables as an
 ;; example. By default, we use a combination of most predefined mappings, and
@@ -76,8 +81,9 @@
 ;; also be useful. Please send any new mapping tables to the maintainer listed
 ;; in this file. The maintainer should be able to help with any issues and may
 ;; create a new mapping table given sample data.
+
+;;; Misc tips/troubleshooting:
 ;;
-;; Misc tips/troubleshooting:
 ;; - ASynK looks promising for syncing bbdb/google/outlook.
 ;; - The git repo contains a test folder with exactly tested version info and working
 ;;   test data.
 ;; - After changing a mapping table variable, don't forget to re-execute
 ;;   (setq bbdb-csv-import-mapping-table ...) so that it propagates.
 
+;;; Bugs, patches, discussion, feedback
+;;
+;; Patches and bugs are very welcome via https://gitlab.com/iankelling/bbdb-csv-import
+;; 
+;; Questions, feedback, etc are very welcome via email to Ian Kelling
+;; <ian@iankelling.org>. I will add any useful questions, answers, etc. to this
+;; file. The scope/userbase of this project doesn't justify a mailing list, but if
+;; it ever did I would start a mailman or discourse to act as a mailing list
+;; and forum.
+
 
 ;;; Code:
 (require 'pcsv)
@@ -313,7 +329,7 @@ a tree (a list with lists inside it)"
          (cons it acc)
        (setq it (cdr it))
        (let* ((i 1)
-              (first-field (car (flatten it))))
+              (first-field (car (-flatten it))))
          (setq acc (cons it acc))
          ;; use first-field to test if there is another repetition.
          (while (member
@@ -357,13 +373,13 @@ Defaults to current buffer."
   (let* ((csv-data (pcsv-parse-buffer (get-buffer (or buffer-or-name (current-buffer)))))
          (csv-fields (car csv-data))
          (csv-data (cdr csv-data))
-         (initial-duplicate-value bbdb-allow-duplicates)
-         csv-record rd assoc-plus map-bbdb)
+         (allow-dupes bbdb-allow-duplicates)
+         csv-record rd assoc-plus map-bbdb dupes)
     ;; convenient function names
     (fset 'rd 'bbdb-csv-import-rd)
     (fset 'assoc-plus 'bbdb-csv-import-assoc-plus)
     (fset 'map-bbdb (-partial 'bbdb-csv-import-map-bbdb csv-fields))
-    ;; better to allow duplicates rather than fail
+    ;; we handle duplicates ourselves
     (setq bbdb-allow-duplicates t)
     ;; loop over the csv records
     (while (setq csv-record (map 'list 'cons csv-fields (pop csv-data)))
@@ -426,8 +442,20 @@ Defaults to current buffer."
                                (setq e (make-symbol (downcase e)))
                                (cons e (cadr list)))) ;; change from (a b) to (a . b)
                            (rd #'assoc-expand (map-bbdb :xfields)))))
-          (bbdb-create-internal name affix aka organization mail phone address xfields t))))
-    (setq bbdb-allow-duplicates initial-duplicate-value)))
+          ;; we copy and subvert bbdb's duplicate detection instead of catching
+          ;; errors so that we don't interfere with other errors, and can print
+          ;; them nicely at the end.
+          (let (found-dupe)
+            (dolist (elt mail)
+              (when (bbdb-gethash elt '(mail))
+                (push elt dupes)
+                (setq found-dupe t)))
+            (when (or allow-dupes (not found-dupe))
+              (bbdb-create-internal name affix aka organization mail phone address xfields t))))))
+    (when dupes (if allow-dupes
+                    (message "Warning, contacts with duplicate email addresses were imported:\n%s" dupes)
+                  (message "Skipped contacts with duplicate email addresses:\n%s" dupes)))
+    (setq bbdb-allow-duplicates allow-dupes)))
 
 (defun bbdb-csv-import-rd (func list)
   "like mapcar but don't build nil results into the resulting list"