Category Archives: bbdb

Emacs, BBDB, and getting your contacts on the Android or iPhone

Want your Emacs BBDB contacts on your Android or iPhone?

The easiest way I've found is to export your contacts to CSV, then import them into something like Google Contacts. You can export your BBDB contacts using bbdb-to-outlook.el, which is available in the BBDB package in the bits/ directory. Download bbdb-to-outlook.el from Sourceforge if you can't find it in your BBDB directory. To use:

  1. Load bbdb-to-outlook.el and use M-x eval-buffer to load the code.
  2. Use M-x bbdb to open your BBDB records, and search for . to show all the records. Alternatively, search for a subset of your records.
  3. Type O to run bbdb-to-outlook and choose the file.

Tada! Step one done. Review the file and delete anything you don't want to include.

To import the contacts into Google Contacts, go to Google Mail and click on Contacts. Click on Import and choose your file. After some time and some fiddling, you can get that synchronized onto your Android or iPhone.

I haven't thought about syncing, but I'm trying to keep my BBDB as The Master File for Contacts anyway, as it's so much more flexible than any other contact database I've tried. (Although is pretty cool and I do like the Android's merging of photos, contact info, and updates…)

There was some work on synchronizing BBDB with the Palm, so that might be a possibility.


Emacs, Org, and BBDB: Hyperlinking names to blogs

Back when I used Planner for Emacs, I coded some shortcuts to make it easier to write about the people I met and the conversations I had. I used the hippie-expand module to complete names from my Big Brother Database addressbook, and I wrote a function that converted those names into links to people's blogs or websites whenever I published my blog posts as HTML.

I switched to WordPress for my blog because I got tired of trying to figure out a way to enable comments without getting mired in spam-fighting. That meant I could explore other Emacs personal information managers like Org, which I turned into my main task manager. I often used the WordPress interface to write blog posts. I sometimes used Windows Live Writer to write posts about books (there's a good book review plugin that makes this easy). I also sometimes used Emacs and Org to draft blog posts using Org's friendlier markup, exporting snippets to HTML that I then pasted into my blog posts.

Reading the posts on Planet Emacsen reminded me that my customized configuration was pretty darn sweet. That and the conversation notes I've been blogging lately encouraged me to dust off my configuration files and get them to work under Org. So here's the code:

 (defun sacha/org-bbdb-get (path)
   "Return BBDB record for PATH."
   (car (bbdb-search (bbdb-records) path path path)))
 (defun sacha/org-bbdb-export (path desc format)
   "Create the export version of a BBDB link specified by PATH or DESC.
 If exporting to HTML, it will be linked to the person's blog,
 www, or web address. If exporting to LaTeX FORMAT the link will be
 italicised. In all other cases, it is left unchanged."
      ((eq format 'html)
       (let* ((record
             (sacha/org-bbdb-get path))
       (setq url (and record
                      (or (bbdb-record-getprop record 'blog)
                          (bbdb-record-getprop record 'www)
                          (bbdb-record-getprop record 'web))))
       (if url
           (format "<a href=\"%s\">%s</a>"
                   url (or desc path))
         (format "<em>%s</em>"
                 (or desc path)))))
      ((eq format 'latex) (format "\\textit{%s}" (or desc path)))
      (t (or desc path))))
 (defadvice org-bbdb-export (around sacha activate)
   "Override org-bbdb-export."
   (setq ad-return-value (sacha/org-bbdb-export path desc format)))
 ;;;_+ Hippie expansion for BBDB; map M-/ to hippie-expand for most fun
 (add-to-list 'hippie-expand-try-functions-list 'sacha/try-expand-bbdb-annotation)
 (defun sacha/try-expand-bbdb-annotation (old)
   "Expand from BBDB. If OLD is non-nil, cycle through other possibilities."
   (unless old
     ;; First time, so search through BBDB records for the name
     (he-init-string (he-dabbrev-beg) (point))
     (when (> (length he-search-string) 0)
       (setq he-expand-list nil)
        (lambda (item)
        (let ((name (bbdb-record-name item)))
          (when name
            (setq he-expand-list
                  (cons (org-make-link-string
                       (org-make-link "bbdb:" name)
        (bbdb-search (bbdb-records)
                     nil nil))))
   (while (and he-expand-list
               (or (not (car he-expand-list))
                   (he-string-member (car he-expand-list) he-tried-table t)))
     (setq he-expand-list (cdr he-expand-list)))
   (if (null he-expand-list)
         (if old (he-reset-string))
       (he-substitute-string (car he-expand-list) t)
       (setq he-expand-list (cdr he-expand-list))
If you've got Org and BBDB, drop this into your ~/.emacs and fiddle with it. =)

Emacs: Someone who’s even geekier about BBDB!

Remember all those tweaks I posted for working with contacts using Emacs' Big Brother Database? John Sturdy has even cooler stuff. Check out his BBDB extensions. His bbdb-export-lists.el can divide people into different phone and address lists, and his bbdb-human-names.el will even try to address people properly. Clearly, I don't talk to enough Reverend Doctors to require code like this. (And shouldn't there be "Right Honorables" and "His Grace"s in there, too? ;) )

Emacs: BBDB: Modifying the record creation process

You might want to add fields to the record creation process in M-x bbdb-create. In addition to asking for name, company, e-mail address, addresses, phone numbers, and notes, you may want to make sure you remember to put in birthdates or other information. If you want to prompt for custom fields after the regular BBDB creation form, modify this simple example to suit your needs:

(defadvice bbdb-read-new-record (after wicked activate)
  "Prompt for the birthdate as well."
  (bbdb-record-putprop ad-return-value 'birthdate
		       (bbdb-read-string "Birthdate (YYYY.MM.DD): ")))

Thanks to Kaleb Yilma for the question!

Wicked Cool Emacs: BBDB: Import CSV and vCard Files

If you have many contacts in another address book program, you can import them into BBDB. Two popular formats are comma-separated value files (CSV) and vCard files (VCF).

Project XXX: Import a CSV File into BBDB

To import a CSV file into BBDB, you will need csv.el from and lookout.el from . Save both files to your ~/elisp directory. Make sure that your ~/elisp directory is in your load-path by adding the following line to your ~/.emacs:
(add-to-list 'load-path "~/elisp")
Export your contacts as an Outlook-style CSV file, then open the file in Emacs. After loading the following code, call M-x wicked/bbdb-import-csv-buffer to merge the CSV data into your address book. Emacs will try to update existing records based on the e-mail address or name provided, creating new records if necessary. After Emacs updates the records, the relevant records are displayed in the *BBDB* buffer. Here is the code to make that work: ch6-bbdb-import-csv-buffer.el:
(require 'lookout)
(defconst wicked/lookout-bbdb-mapping-table-outlook
  '(("name" "Name")
    ("net" "E-mail Address")
    ("notes" "Notes")
    ("phones" "Mobile Phone"
     "Home Phone"
     "Home Phone 2"
     "Home Fax"
     "Business Phone"
     "Business Phone 2"
     "Business Fax"
     "Other Phone"
     "Other Fax")
    ("addr1" "Home Address")
    ("addr2" "Business Address")
    ("addr3" "Other Address")
    ("lastname" "Last Name")
    ("firstname" "First Name")
    ("job" "Job Title")
    ("company" "Company")
    ("otherfields" ""))
  "Field mappings for Outlook-type CSVs exported from Outlook, Gmail, LinkedIn, etc.")

(defun wicked/bbdb-import-csv-line (line)
  "Import LINE as a CSV, trying to merge it with existing records."
  (let* (record
	 (name  (lookout-bbdb-get-value "name" line))
	 (lastname (lookout-bbdb-get-value "lastname" line))
	 (firstname (lookout-bbdb-get-value "firstname" line))
	 (company   (lookout-bbdb-get-value "company" line))
         (job       (lookout-bbdb-get-value "job" line))
	 (net       (lookout-bbdb-get-value "net" line))
	 (addr1     (lookout-bbdb-get-value "addr1" line))
	 (addr2     (lookout-bbdb-get-value "addr2" line))
	 (addr3     (lookout-bbdb-get-value "addr3" line))
	 (phones    (lookout-bbdb-get-value "phones" line t)) ;; !
	 (notes     (lookout-bbdb-get-value "notes" line ))
         (j (concat job ", " company))
	 (otherfields (lookout-bbdb-get-value "otherfields" line t))
	 (addrs nil)
	 (message ""))
    (if (string= company "") (setq company nil))
    (if (string= notes "") (setq notes nil))
    (if (string= name "") (setq name nil))
    (setq name-search (concat "^" (or name (concat firstname " " lastname))))
    (setq record (or (bbdb-search (bbdb-records) nil nil net)
		     (bbdb-search (bbdb-records) name-search)))
    (if record
	  ;; Matching records found, update first matching record
	  (setq record (car record))
	  (let ((nets (bbdb-record-net record)))
	    (unless (member net nets)
	      ;; New e-mail address noticed, add to front of list
	      (add-to-list 'nets net)
	      (bbdb-record-set-net record nets)
	      (message "%s: New e-mail address noticed: %s"
		       (or name (concat firstname " " lastname)) net)))
	  ;; Check if job title and company have changed
	  (when (or job company)
	     ((string= (or (bbdb-record-company record) "") "")
	      (bbdb-record-set-company record j))
	     ((string= (bbdb-record-company record) j)
	       (concat "Noticed change from job title of "
		       (bbdb-record-company record)
		       (bbdb-record-notes record)))
	      (message "%s: Noticed change from job title of %s to %s"
		       (or name (concat firstname " " lastname))
		       (bbdb-record-company record) j)
	      (bbdb-record-set-company record j)))))
      ;; No record found, create record
      (if (and addr1 (> (length addr1) 0))
	  (add-to-list 'addrs
		       (vector "Address 1" (list addr1) "" "" "" "")))
      (if (and addr2 (> (length addr2) 0))
	  (add-to-list 'addrs
		       (vector "Address 2" (list addr2) "" "" "" "")))
      (if (and addr3 (> (length addr3) 0))
	  (add-to-list 'addrs
		       (vector "Address 3" (list addr3) "" "" "" "")))
      (setq record (list
		     (or name (concat firstname " " lastname))
		     (concat job ", " company)
(defun wicked/lookout-bbdb-create-entry (name company net addrs phones notes
					      &amp;optional otherfields)
  (when (or t (y-or-n-p (format "Add %s to bbdb? " name)))
    ;;(message "Adding record to bbdb: %s" name)
    (let ((record (bbdb-create-internal name company net addrs phones notes)))
      (unless record (error "Error creating bbdb record"))
      (mapcar (lambda (i)
		(let ((field (make-symbol (aref i 0)))
		      (value (aref i 1)))
		  (when (and value (not (string= "" value)))
		    (bbdb-insert-new-field record field value))))

(defun wicked/bbdb-import-csv-buffer ()
  "Import this buffer."
  (let ((lookout-bbdb-mapping-table
      (csv-parse-buffer t)))))

Project xxx: Import a vCard File into BBDB

To import a vCard file (VCF) into BBDB, you will need vcard.el from and bbdb-vcard-import.el from . By default, these files allow you to import names and e-mail addresses from vCard files exported from various address book programs. Save vcard.el and bbdb-vcard-import.el to your ~/elisp directory and add the following lines to your ~/.emacs:
(add-to-list 'load-path "~/elisp")
(require 'bbdb-vcard-import)
Back up your ~/.bbdb file before calling M-x bbdb-vcard-import to import a file or M-x bbdb-vcard-import-buffer to import the current buffer. WARNING: If your vCard file includes fields with multiline values, you may get silent errors. Verify your import by browsing through the displayed entries. If some of them have been misread, revert to your backup ~/.bbdb by closing Emacs and copying your backup over the ~/.bbdb file. To fix the multi-line error, include the following lines in your ~/.emacs:
(defun wicked/vcard-parse-region (beg end &amp;optional filter)
  "Parse the raw vcard data in region, and return an alist representing data.
This function is just like `vcard-parse-string' except that it operates on
a region of the current buffer rather than taking a string as an argument.

Note: this function modifies the buffer!"
  (or filter
      (setq filter 'vcard-standard-filter))
  (let ((case-fold-search t)
        (vcard-data nil)
        (pos (make-marker))
        (newpos (make-marker))
        properties value)
      (narrow-to-region beg end)
        ;; Unfold folded lines and delete naked carriage returns
        (goto-char (point-min))
        (while (re-search-forward "\r$\\|\n[ \t]" nil t)
          (goto-char (match-beginning 0))
          (delete-char 1))
        (goto-char (point-min))
        (re-search-forward "^begin:[ \t]*vcard[ \t]*\n")
        (set-marker pos (point))
        (while (and (not (looking-at "^end[ \t]*:[ \t]*vcard[ \t]*$"))
                    (re-search-forward ":[ \t]*" nil t))
          (set-marker newpos (match-end 0))
          (setq properties
                (vcard-parse-region-properties pos (match-beginning 0)))
          (set-marker pos (marker-position newpos))
          (re-search-forward "\n[-A-Z0-9;=]+:")   ;; change to deal with multiline
          (set-marker newpos (1+ (match-beginning 0))) ;; change to deal with multiline
          (setq value
                (vcard-parse-region-value properties pos (match-beginning 0)))
          (set-marker pos (marker-position newpos))
          (goto-char pos)
          (funcall filter properties value)
          (setq vcard-data (cons (cons properties value) vcard-data)))))
    (nreverse vcard-data)))
;; Replace vcard.el's definition
(fset 'vcard-parse-region 'wicked/vcard-parse-region)
Because address book programs don't use standard labels for addresses and phone numbers, bbdb-vcard-import.el ignores those fields. For example, Gmail uses the generic field "Label" for address information and does not use separate fields for city, state, zip code, and country. While bbdb-snarf.el makes an attempt to extract addresses from plain text, it seems to be less trouble to export to the Outlook CSV format instead, or even to type the address in yourself. If you want to import addresses, see Project XXX: Import a CSV File into BBDB. Here's a partial workaround to enable you to import phone numbers. I tested this code with vCard files from Gmail and LinkedIn. To try it out, add the following modifications to your ~/.emacs:
(defun wicked/bbdb-vcard-merge (record)
  "Merge data from vcard interactively into bbdb."
  (let* ((name (bbdb-vcard-values record "fn"))
	 (company (bbdb-vcard-values record "org"))
	 (net (bbdb-vcard-get-emails record))
	 (addrs (bbdb-vcard-get-addresses record))
	 (phones (bbdb-vcard-get-phones record))
	 (categories (bbdb-vcard-values record "categories"))
	 (notes (and (not (string= "" categories))
		     (list (cons 'categories categories))))
	 ;; TODO: addrs are not yet imported.  To do this right,
	 ;; figure out a way to map the several labels to
	 ;; `bbdb-default-label-list'.  Note, some phone number
	 ;; conversion may break the format of numbers.
	 (bbdb-north-american-phone-numbers-p nil)
	 (new-record (bbdb-vcard-merge-interactively name
						     nil ;; Skip addresses
						     phones ;; Include phones
    (setq bbdb-vcard-merged-records (append bbdb-vcard-merged-records 
					    (list new-record)))))
;; Replace bbdb-vcard-import.el's definition
(fset 'bbdb-vcard-merge 'wicked/bbdb-vcard-merge)
Evaluate this code or restart Emacs, then call M-x bbdb-import-vcard again, which should merge phone numbers into your BBDB records.

Wicked Cool Emacs: BBDB: Work with Records

Creating Records

Creating a record in BBDB is not like creating a record in graphical address book programs. You will be prompted for each field through the minibuffer, one field at a time. Don't worry about making mistakes while entering data, as you can always edit the records afterwards.

To create a record, use the command M-x bbdb-create. Here are the prompts you'll encounter:

NameFull nameJohn Doe
CompanyCompany or organizationACME
Network AddressE-mail address (comma-separated list)[email protected]
Address DescriptionShort identifier for address (Home, Office, etc.) - tab completion available. Leave blank if you have no address information, or if you are done.Home
Street, line 1Street address, line 1 (not including city, state, postal code or country)1 Acme Road
Street, line ...Street address, more lines - press RET to indicate the end of the street address
CityAcme City
StateAbbreviations are okay. Consistency helps.AC
CountryAcme Country
Phone LocationShort identifier for phone number (Home, Office, etc.) - tab completion available. Leave blank if you have no phone information, or if you are done.Home
PhonePhone number. I tend to specify the full number, using spaces to break it into readable chunks.+1 111 111 1111 x1111
Additional CommentsNotes about the person, such as interests, how you met, and so onLikes rockets

Press RET to skip any fields for which you don't have information. To cancel the entry process, type C-g (keyboard-quit).

After you create the record, Emacs will display the record in another window. You can then switch to the record and edit it. See Project XXX: Edit a BBDB record.

Searching Records

To search for a specific record, type M-x bbdb, or press b (bbdb) while in the BBDB buffer. This prompts for a regular expression and searches the name, company, network address, and notes fields of all the records for a match against the regular expression supplied. M-x bbdb-name, M-x bbdb-company, M-x bbdb-net, M-x bbdb-notes, and M-x bbdb-phones search the corresponding fields only.

Updating Records

After creating or searching for a record, you can switch to the BBDB window to edit it. Press C-o (bbdb-insert-field) to insert custom fields. You can use tab completion on existing field names, and you can also define your own fields by typing any field name. For example, you may want to store people's job titles in a field called "job".

To edit the value of a field, move your cursor to the field and press e (bbdb-edit-current-field) to change the value. To delete a field, move your cursor to the field and press C-k (bbdb-delete-current-field-or-record).

Deleting Records

To delete an entire record, move the text cursor to the name and press C-k (bbdb-delete-current-field-or-record). You will be prompted for confirmation. Be careful! If you mistakenly delete a record, there's no easy way to get it back. Fortunately, BBDB stores its data in a plain text file (~/.bbdb). Back up that file regularly and you'll be able to recover from mistakes. You can also set up automatic file backups in Emacs (see Project XXX: Make Automatic Backups).

Now you know how to work with individual records. How can you import your address book information from other programs?