[BBDB] Changelog 2012-09-23 part 2 (with notes for BBDB lisp hackers)

[Roland W. <wi...@gn...>]

On Wed Aug 1 2012 Roland Winkler wrote:
> Part of BBDB (yes, even v2) has allowed the possibility that a mail
> address in a record is not just a plain "sm...@fo...". But the
> record of, say, Johnathan Smith may also contain an RFC 822 address
> such as "John Smith <sm...@fo...>". 
> 
> Johnathan Smith
>        phone (home): (123) 456-7890
>                mail: sm...@ex..., John Smith <sm...@fo...>,
>                      Joe Smith <jo...@ba...>

The patch below tries to make sure that mail entries containing
RFC-822 mail addresses such as "John Smith <sm...@fo...>" in the
example above are handled properly throughout BBDB. Essentially, it
decomposes such a mail address into a name part "John Smith" and a
stripped mail address "sm...@fo...". The name part is treated as
an AKA. The stripped mail address is used, for example, by BBDB's
MUA interface to identify the record for the sender or recipient of
a message.

However, if all records in your database are of the plain form
"sm...@fo...", the patch below should not be noticeable for you.

To make this work efficiently, BBDB caches "extra AKAs" such as
"John Smith" and the stripped addresses such as "sm...@fo...".
So changing the mail entry for a record requires a bit of extra care
to make sure that the cache gets updated, too. All this is similar
to various extra steps BBDB is taking to ensure the integrity of the
database. To make all this work reliable, I added the following
(taken from the updated README file):

Notes for BBDB lisp hackers:
----------------------------

If you write your own functions and commands to modify BBDB records,
do not call the low-level functions bbdb-record-set-* such as
bbdb-record-set-aka, bbdb-record-set-mail etc. The recommended
sequence of calls is

- one or multiple calls of bbdb-record-set-field for the respective
  fields to be changed. This not only sets the fields, but it also
  ensures the integrity of the database. Also, this makes your code
  more robust with respect to possible future changes of BBDB's
  innermost internals.

- a call of bbdb-change-record which updates the database after a
  change of record.

- If the changed record is displayed in the *BBDB* buffer, call
  bbdb-redisplay-record.


2012-09-23  Roland Winkler  <wi...@gn...>
	Add more complete support for mail entries containing RFC-822
	addresses such as "John Smith <sm...@fo...>" in the record of
	Johnathan Smith.

	* lisp/bbdb.el (bbdb-defstruct): Doc fix.  Improve doc string of
	functions defined via this macro.
	(bbdb-cache-mail-aka, bbdb-cache-mail-canon): New elements of
	bbdb-record-cache.
	(bbdb-record-mail-aka, bbdb-record-mail-canon): New functions.
	(bbdb-hash-p): New function.
	(bbdb-gethash): Use it.
	(bbdb-puthash-mail): New function.
	(bbdb-hash-record): Use it.
	(bbdb-record-field): Renamed from bbdb-record-get-field.
	New field values mail-canon, mail-aka and aka-all.  Doc fix.
	(bbdb-record-get-field): Obsolete function alias.
	(bbdb-record-set-field): Doc fix. Update hash for mail entries
	such as "John Smith <sm...@fo...>".
	(bbdb-delete-record-internal): Use canonical mail addresses and
	all AKAs when cleaning up the hash.

	* lisp/bbdb-com.el (bbdb-search): Use bbdb-record-field.
	(bbdb-search-duplicates): Use bbdb-record-mail-canon.
	(bbdb-message-search): Simplify.
	(bbdb-edit-field): Doc fix.
	(bbdb-ident-point, bbdb-transpose-fields)
	(bbdb-delete-field-or-record): Use bbdb-record-field.
	(bbdb-completion-predicate): Use bbdb-hash-p.
	(bbdb-complete-mail): Compare with all AKAs.  A plain message
	search should be sufficient.

	* lisp/bbdb-mual.el (bbdb-annotate-message): Compare with
	canonical mail addresses.

	* lisp/bbdb-ispell.el (bbdb-ispell-export): Use bbdb-record-field.

	* README: Notes for BBDB lisp hackers added.


BBDB is available at
http://savannah.nongnu.org/projects/bbdb/
To check it out, use
git clone git://git.savannah.nongnu.org/bbdb.git