Customization Hooks
-------------------
All of the hooks variables described below may be set to a symbol or
lambda expression, which will be funcalled; or may be set to a list of
symbols or lambda expressions, each of which will be funcalled in turn.
Almost all hooks in Emacs work this way. But notice that some of the
hooks described below are called with arguments.
`bbdb-list-hook'
Hook or hooks invoked after the bbdb-list-buffer is filled in.
Invoked with no arguments.
`bbdb-create-hook'
Hook or hooks invoked each time a new bbdb-record is created.
Invoked with one argument, the new record. This is called
_before_ the record is added to the database. Note that
`bbdb-change-hook' will be called as well.
`bbdb-change-hook'
Hook or hooks invoked each time a bbdb-record is altered. Invoked
with one argument, the record. This is called _before_ the
database buffer is modified. Note that if a new bbdb record is
created, both this hook and `bbdb-create-hook' will be called.
`bbdb-mode-hook'
Hook or hooks invoked when the `*BBDB*' buffer is created.
`bbdb-notice-hook'
Hook or hooks invoked each time a bbdb-record is "noticed," that
is, each time it is displayed by the news or mail interfaces.
Invoked with one argument, the new record. The record need not
have been modified for this to be called - use `bbdb-change-hook'
for that. You can use this to, for example, add something to the
notes field based on the subject of the current message. It is up
to your hook to determine whether it is running in GNUS, VM, MH,
or RMAIL, and to act appropriately.
Also note that `bbdb-change-hook' will _not_ be called as a result
of any modifications you may make to the record inside this hook.
Beware that if the variable `bbdb-message-caching-enabled' is true
(a good idea) then when you are using VM, MH, or RMAIL, this hook
will be called only the first time that message is selected. (The
GNUS interface does not use caching.) When debugging the value of
this hook, it is a good idea to set caching-enabled to `nil'.
`bbdb-after-read-db-hook'
Hook or hooks invoked (with no arguments) just after the Insidious
Big Brother Database is read in. Note that this can be called
more than once if the BBDB is reverted. One possible use for this
is to rename the `.bbdb' buffer; for example
`(setq bbdb-after-read-db-hook '(lambda () (rename-buffer "
bbdb")))'
will cause the buffer visiting the `bbdb-file' to be called
`" bbdb"'. The leading space in its name will prevent it from
showing up in the buffer list.
`bbdb-load-hook'
Hook or hooks invoked (with no arguments) when the Insidious Big
Brother Database code is first loaded. WARNING: Slow functions
should not be put on this hook, as the BBDB code will, if not
loaded before, be loaded during the first use of BBDB-related
Customization functions. Slow functions should be put on
`bbdb-initialize-hook'.
`bbdb-initialize-hook'
Hook or hooks invoked (with no arguments) when the
`bbdb-initialize' function is called.
`bbdb-canonicalize-net-hook'
If this is non-`nil', it should be a function of one argument: a
network address string. (Note that, unlike the other
hook-variables described above, this may not be a list of
functions.) Whenever the Insidious Big Brother Database "notices"
a message, the corresponding network address will be passed to
this function first, as a kind of "filter" to do whatever
transformations upon it you like before it is compared against or
added to the database. For example: it is the case that
`CS.CMU.EDU' is a valid return address for all mail originating at
a machine in the `.CS.CMU.EDU' domain. So, if you wanted all such
addresses to be canonically hashed as `user@CS.CMU.EDU', instead
of as `user@somehost.CS.CMU.EDU', you might set this variable to a
function like this:
(setq bbdb-canonicalize-net-hook
'(lambda (addr)
(cond ((string-match
"\\`\\([^@]+@\\).*\\.\\(CS\\.CMU\\.EDU\\)\\'"
addr)
(concat (substring addr
(match-beginning 1) (match-end 1))
(substring addr
(match-beginning 2) (match-end 2))))
(t addr))))
You could also use this function to rewrite UUCP-style addresses
into domain-style addresses, or any number of other things.
This function will be called repeatedly until it returns a value
EQ to the value passed in. So multiple rewrite rules might apply
to a single address.
There is an example of the use of this variable in the file
`bbdb-hooks.el': the function `sample-bbdb-canonicalize-net-hook'.
The `bbdb-canonicalize-net-hook' is powerful in that it allows
arbitrary rewriting of addresses, however, in many cases that is
overkill. The function `bbdb-delete-redundant-nets' can be used as a
value of `bbdb-change-hook' to cause network addresses which appear to
be "redundant" to be deleted each time a modification is made to a
record.
This works as follows: suppose one gets mail from `user@foo.bar.com',
and then later gets mail from `user@bar.com'. At this point, one can
generally delete the `user@foo.bar.com' address, since the
`user@bar.com' address is more general. (See also the variable
`bbdb-canonicalize-redundant-nets-p', which has the effect of ignoring
subsequent addresses from `user@quux.bar.com' if the address
`user@bar.com' is already known.)