small doc update

[bbdb-csv-import] / bbdb3-csv-import.el

diff --git a/bbdb3-csv-import.el b/bbdb3-csv-import.el
index 34f910705c9af12f44f48151cb19266b4db00e1d..ec782afe678a4318ac0836ee7d51ac1933ea413e 100644 (file)
--- a/bbdb3-csv-import.el
+++ b/bbdb3-csv-import.el
@@ -1,12 +1,14 @@
-;;; bbdb3-csv-import.el  --- import csv to bbdb version 3+ -*- lexical-binding: t -*-
+;;; bbdb3-csv-import.el  --- import csv to bbdb version 3+

 
 ;; Copyright (C) 2014 by Ian Kelling
 
 ;; Maintainer: Ian Kelling <ian@iankelling.org>
 ;; Author: Ian Kelling <ian@iankelling.org>
 ;; Created: 1 Apr 2014
 
 ;; Copyright (C) 2014 by Ian Kelling
 
 ;; Maintainer: Ian Kelling <ian@iankelling.org>
 ;; Author: Ian Kelling <ian@iankelling.org>
 ;; Created: 1 Apr 2014

-;; Version: 1.0
+;; Version: 1.1
+;; Package-Requires: ((pcsv "1.3.3") (dash "2.5.0"))

 ;; Keywords: csv, util, bbdb
 ;; Keywords: csv, util, bbdb

+;; Homepage: https://gitlab.com/iankelling/bbdb3-csv-import

 
 ;; This program is free software; you can redistribute it and/or modify
 ;; it under the terms of the GNU General Public License as published by
 
 ;; This program is free software; you can redistribute it and/or modify
 ;; it under the terms of the GNU General Public License as published by


@@ -30,14 +32,12 @@
 
 ;;; Installation:
 ;;
 
 ;;; Installation:
 ;;

-;; dependencies: pcsv.el, dash.el, bbdb
-;; These are available via marmalade/melpa or the internet
-;;
-;; Add to init file or execute manually as this may be a one time usage:
-;; (load-file FILENAME-OF-THIS-FILE)
-;; or
-;; (add-to-list 'load-path DIRECTORY-CONTAINING-THIS-FILE)
+;; Install bbdb. If you installed this file with a package manager, just
+;; 

 ;; (require 'bbdb3-csv-import)
 ;; (require 'bbdb3-csv-import)

+;;
+;; Else, note the min versions of dependencies above in "Package-Requires:",
+;; and load this file. I don't know the exact minimum bbdb version.

 
 ;;; Usage:
 ;;
 
 ;;; Usage:
 ;;


@@ -45,7 +45,7 @@
 ;; you don't like the newly imported data.
 ;;
 ;; Simply M-x `bbdb3-csv-import-buffer' or `bbdb3-csv-import-file'.
 ;; you don't like the newly imported data.
 ;;
 ;; Simply M-x `bbdb3-csv-import-buffer' or `bbdb3-csv-import-file'.

-;; Interactively they prompt for file or buffer.
+;; When called interactively, they prompt for file or buffer arguments.

 ;;
 ;; 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,
 ;;
 ;; 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,


@@ -69,14 +69,15 @@
 ;; If you need to define your own mapping table, it should not be too hard. Use
 ;; the existing tables as an example. Probably best to ignore the combined table
 ;; as it is an unnecessary complexity when working on a new table. The doc
 ;; If you need to define your own mapping table, it should not be too hard. Use
 ;; the existing tables as an example. Probably best to ignore the combined table
 ;; as it is an unnecessary complexity when working on a new table. The doc

-;; string for `bbdb-create-internal' may also be useful. The test csv data &
-;; test version info within this project could also be helpful. Please send any
+;; string for `bbdb-create-internal' may 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.
 ;;
 ;; 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:
+;; Misc tips/troubleshooting:

 ;; - ASynK looks promising for syncing bbdb/google/outlook.
 ;; - ASynK looks promising for syncing bbdb/google/outlook.

+;; - The git repo contains a test folder with exactly tested version info and working
+;;   test data.

 ;; - bbdb doesn't work if you delete the bbdb database file in
 ;;   the middle of an emacs session. If you want to empty the current bbdb database,
 ;;   do M-x bbdb then .* then C-u * d on the beginning of a record.
 ;; - bbdb doesn't work if you delete the bbdb database file in
 ;;   the middle of an emacs session. If you want to empty the current bbdb database,
 ;;   do M-x bbdb then .* then C-u * d on the beginning of a record.


@@ -84,15 +85,13 @@
 ;;   (setq bbdb3-csv-import-mapping-table ...) so that it propagates.
 
 
 ;;   (setq bbdb3-csv-import-mapping-table ...) so that it propagates.
 
 

+;;; Code:
+

 (require 'pcsv)
 (require 'dash)
 (require 'bbdb-com)
 (eval-when-compile (require 'cl))
 
 (require 'pcsv)
 (require 'dash)
 (require 'bbdb-com)
 (eval-when-compile (require 'cl))
 

-(defvar bbdb3-csv-import-mapping-table bbdb3-csv-import-combined
-  "The table which maps bbdb3 fields to csv fields. The default should work for most cases.
-See the commentary section of this file for more details.
-")

 
 (defconst bbdb3-csv-import-thunderbird
   '(("firstname" "First Name")
 
 (defconst bbdb3-csv-import-thunderbird
   '(("firstname" "First Name")


@@ -194,12 +193,6 @@ See the commentary section of this file for more details.
    people don't use those labels and using the default labels
    would create useless custom fields.")
 
    people don't use those labels and using the default labels
    would create useless custom fields.")
 

-(defconst bbdb3-csv-import-outlook-typed-email
-  (append  (car (last bbdb3-csv-import-outlook-web)) '((repeat "E-mail 1 - Type")))
-  "Like the previous var, but for outlook-web.
-Adds email labels as custom fields.")
-
-

 (defconst bbdb3-csv-import-outlook-web
   '(("firstname" "First Name")
     ("lastname" "Last Name")
 (defconst bbdb3-csv-import-outlook-web
   '(("firstname" "First Name")
     ("lastname" "Last Name")


@@ -234,6 +227,32 @@ Adds email labels as custom fields.")
 Based on 'Export for outlook.com and other services',
 not the export for Outlook 2010 and 2013.")
 
 Based on 'Export for outlook.com and other services',
 not the export for Outlook 2010 and 2013.")
 

+(defconst bbdb3-csv-import-outlook-typed-email
+  (append  (car (last bbdb3-csv-import-outlook-web)) '((repeat "E-mail 1 - Type")))
+  "Like the previous var, but for outlook-web.
+Adds email labels as custom fields.")
+
+
+(defun bbdb3-csv-import-flatten1 (list)
+  "flatten LIST by 1 level."
+  (--reduce-from (if (consp it)
+                     (-concat acc it)
+                   (-snoc acc it))
+                 nil list))
+
+
+(defun bbdb3-csv-import-merge-map (root)
+  "Combine two root mappings."
+  (bbdb3-csv-import-flatten1
+   (list root
+         (-distinct
+          (append
+           (cdr (assoc root bbdb3-csv-import-thunderbird))
+           (cdr (assoc root bbdb3-csv-import-linkedin))
+           (cdr (assoc root bbdb3-csv-import-gmail))
+           (cdr (assoc root bbdb3-csv-import-outlook-web)))))))
+
+

 (defconst bbdb3-csv-import-combined
   (list
    (bbdb3-csv-import-merge-map "firstname")
 (defconst bbdb3-csv-import-combined
   (list
    (bbdb3-csv-import-merge-map "firstname")


@@ -269,16 +288,9 @@ not the export for Outlook 2010 and 2013.")
    (bbdb3-csv-import-merge-map "organization")
    (bbdb3-csv-import-merge-map "xfields")))
 
    (bbdb3-csv-import-merge-map "organization")
    (bbdb3-csv-import-merge-map "xfields")))
 

-(defun bbdb3-csv-import-merge-map (root)
-  (bbdb3-csv-import-flatten1
-   (list root
-         (-distinct
-          (append
-           (cdr (assoc root bbdb3-csv-import-thunderbird))
-           (cdr (assoc root bbdb3-csv-import-linkedin))
-           (cdr (assoc root bbdb3-csv-import-gmail))
-           (cdr (assoc root bbdb3-csv-import-outlook-web)))))))
-
+(defvar bbdb3-csv-import-mapping-table bbdb3-csv-import-combined
+  "The table which maps bbdb3 fields to csv fields. The default should work for most cases.
+See the commentary section of this file for more details.")

 
 
 ;;;###autoload
 
 
 ;;;###autoload


@@ -287,7 +299,6 @@ not the export for Outlook 2010 and 2013.")
   (interactive "fCSV file containg contact data: ")
   (bbdb3-csv-import-buffer (find-file-noselect filename)))
 
   (interactive "fCSV file containg contact data: ")
   (bbdb3-csv-import-buffer (find-file-noselect filename)))
 

-

 ;;;###autoload
 (defun bbdb3-csv-import-buffer (&optional buffer-or-name) 
   "Parse and import csv BUFFER-OR-NAME to bbdb3.
 ;;;###autoload
 (defun bbdb3-csv-import-buffer (&optional buffer-or-name) 
   "Parse and import csv BUFFER-OR-NAME to bbdb3.


@@ -413,15 +424,7 @@ Defaults to current buffer."
           (bbdb-create-internal name affix aka organization mail phone address xfields t))))
     (setq bbdb-allow-duplicates initial-duplicate-value)))
 
           (bbdb-create-internal name affix aka organization mail phone address xfields t))))
     (setq bbdb-allow-duplicates initial-duplicate-value)))
 

-;;;###autoload
-(defun bbdb3-csv-import-flatten1 (list)
-  "flatten LIST by 1 level."
-  (--reduce-from (if (consp it)
-                     (-concat acc it)
-                   (-snoc acc it))
-                 nil list))

 
 

-;;;###autoload

 (defun bbdb3-csv-import-rd (func list)
   "like mapcar but don't build nil results into the resulting list"
   (--reduce-from (let ((funcreturn (funcall func it)))
 (defun bbdb3-csv-import-rd (func list)
   "like mapcar but don't build nil results into the resulting list"
   (--reduce-from (let ((funcreturn (funcall func it)))


@@ -430,7 +433,6 @@ Defaults to current buffer."
                      acc))
                  nil list))
 
                      acc))
                  nil list))
 

-;;;###autoload

 (defun bbdb3-csv-import-assoc-plus (key list)
   "Like (cdr assoc ...) but turn an empty string result to nil."
   (let ((result (cdr (assoc key list))))
 (defun bbdb3-csv-import-assoc-plus (key list)
   "Like (cdr assoc ...) but turn an empty string result to nil."
   (let ((result (cdr (assoc key list))))