# -*- sentence-end-double-space: t -*-
#+TEXINFO_CLASS: info
#+TEXINFO_HEADER: @syncodeindex vr cp
#+TEXINFO_HEADER: @syncodeindex fn cp
#+TEXINFO_HEADER: @syncodeindex ky cp
#+AUTHOR: Eric Abrahamsen <eric@ericabrahamsen.net>
#+TITLE: EBDB Manual
#+SUBTITLE: This manual is for version 0.6.7, updated 19 April, 2019
#+TEXINFO_DIR_CATEGORY: Emacs
#+TEXINFO_DIR_TITLE: EBDB: (ebdb)
#+TEXINFO_DIR_DESC: Contact management package
#+OPTIONS: *:nil num:t toc:2 h:4 num:3
#+MACRO: buf \ast{}$1\ast{}
#+MACRO: kbd @@texinfo:@kbd{$1}@@

* Copying
:PROPERTIES:
:COPYING:  t
:END:

Copyright \copy 2016 Free Software Foundation, Inc.

#+BEGIN_QUOTE
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover Texts being “A GNU Manual,”
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled “GNU Free Documentation License.”

(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
modify this GNU manual.”
#+END_QUOTE
* Getting Started
EBDB is a contact management package: it records information about
people and organizations, and integrates with other Emacs software
packages, mostly those concerned with sending and reading mail.  The
principle parts of EBDB are records, which represent people and
organizations; fields, representing detailed data about records; and
databases, which hold and persist records.

It's easiest to install EBDB from the ELPA package repositories,
though it's also possible to clone the package from [[https:github.com/girzel/ebdb][Github]] and put it
on your load path.  Questions and bug reports can be raised on the
Github issues page, or on the Emacs bug tracker or mailing lists,
provided you cc the maintainer.

There are a large number of configuration options listed in this
manual, but the only one you might want to tweak in advance is
~ebdb-sources~ (see [[id:9a02f8fb-01e2-4cd8-8166-608814a031f7][The EBDB Database]]), which controls where EBDB
stores its records.

EBDB comes with integration for a few other Emacs packages, including
Org and a number of mail user agents; see the following sections below
for details.

- Emergency Escape Hatch :: EBDB strives to be bug-free, naturally,
  but due to the nature of the package, when bugs /do/ arise they can
  potentially interfere with the reading and sending of email.  No one
  likes it when their email is interfered with.  If, God forbid, you
  do encounter such a bug, you can prevent it from doing harm by
  running:

#+begin_src emacs-lisp
  (setq ebdb-mua-auto-update-p nil)
#+end_src

  That will ensure that EBDB only runs when you explicitly command it
  to do so; it won't interpose itself in other MUA operations.  If you
  really need to kill it and make it go away, use ~M-x ebdb-shutdown~.

** Starting a New Database
#+FINDEX: ebdb-open
If you have no records you want to migrate from other contact
management software, start by calling the command ~ebdb-open~.  This
will open a new buffer in ~ebdb-mode~, and prompt you to create a
database, if one doesn't already exist.  From there, you can use
{{{kbd(c)}}} to make new records (see [[id:692cde31-73be-4faf-b436-7eae8a5d02d1][Creating Records]]).  You can also
hook EBDB into a mail-user agent (see [[id:6a16bc3a-dd20-48af-b532-d5a39da6ab55][MUA Interaction]]) and allow it to
create records automatically.

Otherwise, you'll want to migrate your contact information from other
contact management software as described in the sections below.
Currently EBDB only knows about migrating from BBDB and Org Contacts.
** Migration from BBDB
#+CINDEX: Migration from BBDB
*** Record Migration
#+FINDEX: ebdb-migrate-from-bbdb
It's possible to migrate records from a BBDB database.  The
~bbdb-file~ variable should point to your current BBDB file;
alternately EBDB will look in the default location, found using
~(locate-user-emacs-file "bbdb" ".bbdb)~.  Then call
~ebdb-migrate-from-bbdb~.  You'll be prompted to create the new
database, and upgrade from BBDB.  If any records could not be
upgraded, they will be displayed in an {{{buf(EBDB Migration
Errors)}}} buffer.  Migration bug reports are very welcome.
*** Variables and Options
Many of the old BBDB customization options have been changed or
removed entirely in EBDB.  It's probably best to put your BBDB
customizations aside, and set new EBDB options as you come across
them.  The most important options are detailed in this manual, you can
also customize the "EBDB" group to see what's available.
** Migration from Org Contacts
#+CINDEX: Migration from Org Contacts
#+FINDEX: ebdb-migrate-from-org-contacts
EBDB also provides limited support for migrating from Org Contacts:
simply call the command ~ebdb-migrate-from-org-contacts~.  Your
contacts database will be scanned, and all contacts will be migrated.
Any field values that could not be migrated will be displayed in a
{{{buf(EBDB Migration Errors)}}} buffer.

At present, addresses cannot be migrated automatically.  Org Contacts
stores addresses as a free-form string, which is simply too difficult
to parse accurately.  Address values will be inserted into the
migration errors buffer, and will have to be added to the records
manually.
* The EBDB Database
:PROPERTIES:
:ID:       9a02f8fb-01e2-4cd8-8166-608814a031f7
:END:
EBDB supports multiple databases, and each database definition is
saved in a file on disk.  The default database class, ~ebdb-db-file~,
stores its contacts in the same file as the database itself, though
other database classes may store contacts elsewhere.

#+CINDEX: Creating a database
#+CINDEX: Databases
#+TEXINFO: @defopt ebdb-sources
User option specifying one or more databases to load.  It can be a
single element, or a list of elements.  Each element can be a
filename, from which a database is loaded, or it can be an instance of
a subclass of the ~ebdb-db~ class.  The database at the head of the
list will be considered the default database.
#+TEXINFO: @end defopt

Databases have a few user-facing settings:

#+ATTR_TEXINFO: :options Database @code{boolean} read-only
#+begin_deftypeivar
If non-nil, records can only be read from the database, not edited or
deleted.
#+end_deftypeivar

#+ATTR_TEXINFO: :options Database @code{boolean} auto-save
#+begin_deftypeivar
If non-nil, the database's records will not be autosaved.
#+end_deftypeivar

#+ATTR_TEXINFO: :options Database @code{character} buffer-char
#+begin_deftypeivar
A single character that will be displayed next to records in the
{{{buf(EBDB)}}} buffer, indicating which database they belong to.
#+end_deftypeivar

#+ATTR_TEXINFO: :options Database @code{boolean} disabled
#+begin_deftypeivar
When non-nil , the database will essentially be ignored---no records
will be read from it.  Setting this to t will only take effect on next
restart; to disable a database immediately, use
~ebdb-disable-database~ below.
#+end_deftypeivar

#+ATTR_TEXINFO: :options Database @code{symbol} record-class
#+begin_deftypeivar
The default record class to use when creating new records in this
database.  The default is ~ebdb-default-record-class~.
#+end_deftypeivar

While it's possible to edit database definitions directly in the file,
it's safer to use the customization interface to do so from the
{{{buf(EBDB)}}} buffer.

#+attr_texinfo: :indic @kbd
- d e ::

     #+KINDEX: d e
     Use the customize interface to edit the definition of a database
     (~ebdb-customize-database~).

Records can be moved or copied from one database to another. It's also
possible for a single record to live in more than one database, though
this functionality is experimental. When a record is loaded from more
than one database, the two copies are compared using the timestamp
field, and the older copy is discarded.  In an {{{buf(EBDB)}}} buffer,
the following keys can be used to manipulate databases and their
records.

#+attr_texinfo: :indic @kbd
- d m ::

     #+KINDEX: d m
     Move a record from its current database to another
     (~ebdb-move-record~).

- d c ::

     #+KINDEX: d c
      Copy a record into a new database, leaving it in its existing
     database(s) (~ebdb-copy-record~).

Other database-related commands:

#+attr_texinfo: :indic @kbd
- d r ::

     #+KINDEX: d r
     Reload all records from a database.  This also redisplays any of
     those records that were visible in {{{buf(EBDB)}}} buffers
     (~ebdb-reload-database~).

- d d ::

     #+KINDEX: d d
     This command (~ebdb-disable-database~) disables a database,
     unloading all of its records and essentially ignoring it from now
     on.  The disabled state persists between restarts.  To re-enable
     a database, edit it using ~ebdb-customize-database~, set
     ~disabled~ to nil, and then reload it with
     ~ebdb-reload-database~.

#+CINDEX: Saving the database
#+VINDEX: ebdb-save-on-exit
Typically, databases are saved using the {{{kbd(s)}}} binding in
~ebdb-mode~ buffers, which runs ~ebdb-save~.  If you have open
{{{buf(EBDB)}}} buffers and unsaved changes, you'll also be prompted
to save the database when running ~save-some-buffers~.  If this isn't
enough, you can also set ~ebdb-save-on-exit~ to non-nil to have EBDB
saved automatically (and silently) when killing Emacs. Because killing
Emacs already runs ~save-some-buffers~, this option is typically
redundant and defaults to nil.

#+CINDEX: Loading databases
#+CINDEX: Database load times
#+VINDEX: ebdb-try-speedups
Loading and initializing the EBDB can be slow for large databases.  If
you find yourself annoyed by the wait, try setting ~ebdb-try-speedups~
to non-nil.  This will disable some checks performed during the object
creation process, which theoretically shouldn't make a difference.  If
something does go wrong at load-time, however, try setting this back
to ~nil~ first.
* Creating Records
:PROPERTIES:
:ID:       692cde31-73be-4faf-b436-7eae8a5d02d1
:END:
#+CINDEX: Creating records
#+KINDEX: c
#+FINDEX: ebdb-create-record
Create a record using {{{kbd(c)}}} (~ebdb-create-record~) in the
{{{buf(EBDB)}}} buffer.  This command will create an instance of the
default record class, in the database at the head of ~ebdb-sources~.

#+ATTR_TEXINFO: :options ebdb-default-record-class
#+begin_defopt
The default record class to use when creating new records.  Defaults
to ~ebdb-record-person~.
#+end_defopt

#+FINDEX: ebdb-create-record-extended
#+KINDEX: C
Alternately create a record using {{{kbd(C)}}}
(~ebdb-create-record-extended~), which will prompt for a record class to use,
as well as a database to store the record in, if there is more than
one.

You can also tell EBDB which record represents you:

#+ATTR_TEXINFO: :options ebdb-record-self
#+begin_defopt
The value of this option should be the UUID of your own record.  You
can find this by pressing {{{kbd(T)}}} (to show all fields) on your
record.
#+end_defopt

Currently this option's only use is to serve as a source for
~ebdb-user-mail-address-re~.
** Record classes
EBDB comes with two record classes, representing individuals
(~ebdb-record-person~) and organizations (~ebdb-record-organization~).
Records can have "roles" at organizations, [[id:1398bd78-b380-4f36-ab05-44ea5ca8632f][Role Fields]].
** Record names
EBDB comes with two classes for name fields: "simple" and "complex".
Simple names are just a single string, complex names are split out
into surname, given names, suffix, etc.  All records have a single
canonical name: person records have a complex name, organization
records have a simple name.

In addition, person records can have one or more "aka" names, and
these akas can be either simple or complex.  When adding fields to a
record, the simple name class is labeled "nickname", and the complex
class is labeled "alt name".
* Record Fields
:PROPERTIES:
:ID:       4170bd36-64bf-44b4-87d0-29fbed968851
:END:
** Inserting New Fields
#+CINDEX: Inserting new fields
#+KINDEX: i
#+FINDEX: ebdb-insert-field
Pressing {{{kbd(i)}}} (~ebdb-insert-field~) with point on a record
will prompt for a field type, then field values, and add the field to
the record.  See below for more information about the various kinds of
fields.

When entering field data, optional data can be skipped by entering a
blank string, or by pressing {{{kbd(C-g)}}}.  The first {{{kbd(C-g)}}}
will cancel the current data prompt; the second {{{kbd(C-g)}}} will
cancel the creation of the field altogether.  For instance, when
creating address fields, EBDB will allow you to create an arbitrary
number of street lines.  When you've added enough, either enter a
blank string, or hit {{{kbd(C-g)}}}.
** Editing Existing Fields
#+CINDEX: Editing fields
#+KINDEX: e
#+FINDEX: ebdb-edit-field
Pressing {{{kbd(e)}}} (~ebdb-edit-field~) with point on a field will
allow you to edit an existing field, with the previous values as
defaults.

#+KINDEX: E
#+FINDEX: ebdb-edit-field-customize
Alternately, press {{{kbd(E)}}} (~ebdb-edit-field-customize~) to edit
the field's values using the Customize interface.  Some fields have
slots that can only be edited this way; other fields have slots that
cannot be edited at all once the field is created.
** Deleting Records and Fields
#+CINDEX: Deleting records
#+CINDEX: Deleting fields
#+KINDEX: C-k
#+FINDEX: ebdb-delete-record-or-field
Pressing {{{kbd(C-k)}}} on a field will ask you for confirmation, then
delete the field.  Pressing {{{kbd(C-k)}}} while point is on or before
a record's main name will instead prompt to delete the whole record.
** Field Types
:PROPERTIES:
:ID:       cb2190f4-f2e6-4082-9671-24e11e5cc0c6
:END:
Fields can be classed in a few different categories.  Some are
"plumbing" fields, that are present for all records, but not generally
visible or user-editable: these include the creation date, timestamp,
and UUID.  You can view these fields by hitting {{{kbd(T)}}} on the
record.  Other fields are "built-in": basic fields that get special
treatment.  These include the name, mail, phone, address, and notes
fields.  EBDB comes with default classes for these fields: if you
would like to use different defaults, you can create new classes
(inheriting from the existing ones) and use those instead.  See
[[id:a58993a8-0631-459f-8bd6-7155bb6df605][Hacking EBDB]] for more information.

Besides the "plumbing" and "built-in" fields, all other fields are
referred to as "user" fields.  These can hold any kind of information
you want to associate with a record.  Some user fields are simple
string keys and string values; others have more complicated data
structures and behavior.

When adding a field to a record, you'll be prompted for a field type.
The list will include the built-in fields, more complicated field
types, and also all the simple string keys you've defined so far.  If
you enter a string key that EBDB hasn't seen before, it will prompt
for confirmation, then define that key for future use.

EBDB comes with more complicated classes including "anniversary",
"url", "id", "relation", "role" and more.  Many of these fields have
their own list of labels: for instance, anniversary fields may be
labeled "birthday" or "wedding", and URL fields might be labeled
"homepage" or "file-sharing".

In the case of fields with labels, you'll first choose the general
field ("anniversary"), then enter the field data, and lastly choose a
label ("birthday").  Again, if you choose a label that hasn't been
seen before, EBDB will first prompt for confirmation, then define the
label for future use.  You can also enter an empty string or hit
{{{kbd(C-g)}}} to omit the label altogether.

Loading secondary libraries may make more field types available.
*** Role fields
:PROPERTIES:
:ID:       1398bd78-b380-4f36-ab05-44ea5ca8632f
:END:
One type of field worth mentioning in particular is the role field.
EBDB records come in two types at present: person and organization.
People have roles at organizations: jobs, volunteer positions, etc.
People are also likely to have roles at more than one organization.

When adding a role field to a record, you'll be prompted for a string
label denoting eg.@@texinfo:@:@@ a job title, prompted for an
organization, and prompted for a mail address that belongs only to
this role field (ie.@@texinfo:@:@@ an institutional email address).
If the organization has a "domain" field type, and the person has an
existing mail address that matches that domain, you'll be prompted to
move that address to the role field.

When viewing organization records, the role fields for all related
person records are also displayed as part of the organization record.

If a person's role at an organization later comes to an end, the role
field can be deleted, or marked as "defunct", if record keeping is
desired.  This can only be done using the customize-based editing
interface (the {{{kbd(E)}}} key on the role field).

In fact, in addition to a mail field, role fields can contain an
arbitrary number of other fields, representing metadata about the role
(an employee number, employment start date, etc).  The author has yet
to come up with a good interface for viewing and manipulating these
extra fields, however, so the functionality remains hidden.
Suggestions are very welcome.

#+FINDEX: ebdb-create-record-and-role
It can often feel a little clunky creating a new organization to
associate with a person, or vice versa.  EBDB provides a convenience
function to create a new person or organization record, and associate
it with the existing record under point, in one step, using the
{{{kbd(F)}}}.  This will create a new organization if point is on a
person record, or a new person if point is on an organization.

*** Tag field
:PROPERTIES:
:ID:       d9073bc7-8731-4919-9fc0-7d1dcf98426e
:END:
EBDB comes with a field holding arbitrary tags for records.  When
searching on the tags field (using {{{kbd(/ t)}}} and selecting
"tags"), EBDB provides the same tag search syntax as Org does,
eg.@@texinfo:@:@@ "work|laptop+night".  @@texinfo:@xref{Matching
tags and properties,,,org}@@ for more information.

The @@texinfo:@file{@@ebdb-org@@texinfo:}@@ library alters the
behavior of this class, offering all the user's Org-file tags for
completion.  [[id:ee6b5ccb-a7a6-4c42-84a5-9eb0bbdc040f][Org Integration]].
*** Mail folder field
The "mail folder" field is used to indicate which folder or group
incoming mail from the contact should be filed into.  Currently only
Gnus supports this; support in other MUAs is forthcoming.
* MUA Interaction
:PROPERTIES:
:ID:       6a16bc3a-dd20-48af-b532-d5a39da6ab55
:END:
One of EBDB's most important features is the ability to create, update
and display records based on messages received or sent in your mail
user agent(s).  In theory, EBDB can be integrated with any software
package, but it's most common to use it in conjunction with sending
and receiving emails.
** Loading MUA Code

MUA code is activated simply by loading the relevant library.  Keep in
mind that mail-reading clients and mail-sending clients are considered
separate MUAs.  For instance, if you use the Gnus package for reading
mail, and Message for sending it, you'll want two require statements:

#+BEGIN_SRC elisp
(require 'ebdb-gnus)
(require 'ebdb-message)
#+END_SRC

There are other packages that provide other MUA integration: these are
likewise activated simply by requiring the relevant library, named
"ebdb-<MUA>".  MUAs supported by EBDB include gnus, message, mh-e,
mu4e, wl, and rmail.
** Display and Updating

#+CINDEX: MUA Display
#+CINDEX: MUA Updating
When a message is opened in an MUA, EBDB can do certain things with
the records referenced in that message. It can:

- Pop up a buffer displaying the records.
- Create new records, or alter existing records, based on information
   provided by the MUA.
- Run automatic rules to edit the records.
- Provide keybindings to manually edit the records.

Each of these functionalities is optional, and can be customized
independently of the others.
*** Pop-up Buffers
#+CINDEX: Pop-up buffers
Each MUA creates its own EBDB pop-up buffer, with a name like
{{{buf(EBDB-Gnus)}}} or {{{buf(EBDB-Rmail)}}}.  MUAs will re-use their
own buffers, and will not interfere with buffers the user has created
using the ~ebdb~ command, or by cloning or renaming existing buffers.

#+ATTR_TEXINFO: :options ebdb-mua-pop-up
#+begin_defopt
If nil, MUAs will not automatically pop up buffers.  It is still
possible to manually create the buffer using interactive commands (see
below).
#+end_defopt

#+ATTR_TEXINFO: :options ebdb-mua-default-formatter
#+begin_defopt
The default formatter to use for MUA pop-up buffers.  The value of
this option should be an instance of either the
~ebdb-formatter-ebdb-multiline~ or the ~ebdb-formatter-ebdb-oneline~
class; it defaults to ~ebdb-default-multiline-formatter~.  Other
likely options would be the value of ~ebdb-default-oneline-formatter~,
or a custom-made formatter, see [[id:20fc7a2a-55a9-43ef-9534-9e5887682a88][Customizing Record Display]].
#+end_defopt

EBDB can also integrate with atomic windows (@@texinfo:@xref{Atomic
Windows,,,elisp}@@).

#+ATTR_TEXINFO: :options ebdb-join-atomic-windows
#+begin_defopt
When non-nil (the default), EBDB buffers that are popped up within
existing atomic windows will become part of the atomic window.
Otherwise they will be opened to one side of the atomic window.
#+end_defopt

#+ATTR_TEXINFO: :options ebdb-default-window-size
#+begin_defopt
Set to a float between 0 and 1 to specify how much of an existing
window the popped-up {{{buf(EBDB)}}} buffer should occupy.
#+end_defopt

In addition, each MUA has its own customization option for controlling
the window size of pop-up buffers.  Each option is named as
~ebdb-<MUA>-window-size~, and each defaults to
~ebdb-default-window-size~.

#+VINDEX: ebdb-gnus-window-configuration
#+VINDEX: ebdb-message-window-configuration
The Gnus and Message MUAs have their own special window
configuration system (@@texinfo:@xref{Window Layout,,,Gnus}@@).  If
you're not making special use of that system, EBDB will default to
taking up a percentage of the article and message composition
windows.  If you are using that system for more control, you use the
~ebdb-gnus-window-configuration~ and
~ebdb-message-window-configuration~ options to do so.  They should be
set to two arbitrary (but distinct) symbols, which will be added to
the ~gnus-window-to-buffer~ alist, and can be used in
~gnus-add-configuration~ calls, for example:

#+begin_src elisp
  (gnus-add-configuration
   '(article
     (vertical 1.0
               (summary 0.25 point)
               (horizontal 1.0
                           (article 1.0)
                           (ebdb-gnus 0.4)))))
#+end_src

Because Gnus and Message use separate EBDB buffers for record update
and display, the two options must be separate, and used in the
appropriate article-display vs message-composition window
configurations.
*** Auto-Updating Records
EBDB can automatically update the name and mail addresses of records
based on information in an MUA message. The first and most important
option governing this behavior is:

#+ATTR_TEXINFO: :options ebdb-mua-auto-update-p
#+begin_defopt
This option determines how EBDB acts upon mail addresses found in
incoming messages.  If nil, nothing will happen.  Other options
include the symbols ~existing~ (only search for and display existing
records), ~update~ (only find existing records, and update their name
and mail fields as necessary), ~query~ (find existing records, and
query about the editing and creation of new records), and ~create~
(automatically create new records).  A value of ~t~ is considered
equivalent to ~create~.  The option can also be set to a function
(called with no arguments) which returns one of the above symbols.
#+end_defopt

For instance, say you want to automatically create records for
addresses you send mail to, but _not_ when sending messages to
newsgroups.  If you're using ~message-mode~, you could use the
following:

#+begin_src elisp
  (setq ebdb-message-auto-update-p
        (lambda ()
          (unless (ebdb-mua-message-header "Newsgroups")
            'query)))
#+end_src

This option only governs what EBDB does automatically, each time a
message is displayed.  The same process can be run interactively using
the commands below.

In many cases it's useful to have different auto-update behavior in
different MUAs.  In particular, you might want to automatically create
records for addresses as you send messages to them, but retain manual
control over creating records from messages you receive.  EBDB
provides two more-specific versions of ~ebdb-mua-auto-update-p~:

#+ATTR_TEXINFO: :options ebdb-mua-sender-update-p
#+begin_defopt
The default "update-p" value for all mail-sending MUAs.
#+end_defopt

#+ATTR_TEXINFO: :options ebdb-mua-reader-update-p
#+begin_defopt
The default "update-p" value for all mail-reading MUAs.
#+end_defopt

#+VINDEX: ebdb-gnus-auto-update-p
#+VINDEX: ebdb-message-auto-update-p
#+VINDEX: ebdb-rmail-auto-update-p
#+VINDEX: ebdb-mhe-auto-update-p
#+VINDEX: ebdb-mu4e-auto-update-p
#+VINDEX: ebdb-wl-auto-update-p
#+VINDEX: ebdb-vm-auto-update-p
Even finer-grained control is available using per-MUA versions of the
option, all of them named after the pattern
~ebdb-<MUA>-auto-update-p~.

When updating records either automatically or interactively, a few
more options come into play:

#+ATTR_TEXINFO: :options ebdb-add-name
#+begin_defopt
Whether to automatically change record names.  See docstring for
details.
#+end_defopt

#+ATTR_TEXINFO: :options ebdb-add-aka
#+begin_defopt
Whether to automatically add new names as akas.  See docstring for
details.
#+end_defopt

#+ATTR_TEXINFO: :options ebdb-add-mails
#+begin_defopt
How to handle apparently new mail addresses.  See docstring for
details.
#+end_defopt

There are also options governing whether EBDB will consider a mail
address or not:

#+ATTR_TEXINFO: :options ebdb-accept-header-list
#+begin_defopt
An alist governing which addresses in which headers will be accepted.
See docstring for details.
#+end_defopt

#+ATTR_TEXINFO: :options ebdb-ignore-header-list
#+begin_defopt
An alist governing which addresses in which headers will be ignored.
See docstring for details.
#+end_defopt

#+VINDEX: ebdb-record-self
#+ATTR_TEXINFO: :options ebdb-user-name-address-re
#+begin_defopt
A regular expression matching the user's own mail address(es).  In
addition to a regexp, this can also be the symbol ~message~, in which
case the value will be copied from ~message-alternative-emails~, or
the symbol ~self~, in which case the value will be constructed from
the record pointed to by the option ~ebdb-record-self~.
#+end_defopt

When auto update is set to ~query~, and the user has already told EBDB
not to automatically create or update a record for a given mail
address, it can be annoying when opening the message a second timed to
be prompted again.  It is possible to permanently ignore a mail
address, by saving it to disk.

#+CINDEX: Permanently ignoring mail addresses
#+ATTR_TEXINFO: :options ebdb-permanent-ignores-file
#+begin_defopt
A file in which to save permanently-ignored mail addresses.  This
defaults to ".ebdb-permanent-ignores" in the user's Emacs directory,
but can be set to a different location, or to nil to disable saving of
the ignored list altogether.
#+end_defopt

When EBDB queries to create or update a record, the {{{kbd(i)}}} key
will ignore the mail permanently; the {{{kbd(I)}}} key will ignore the
entire domain.  If the above option is nil, the mail will be ignored
for this session only, otherwise it will be saved to disk the next
time EBDB is saved.

It's also possible to add addresses manually, while EBDB is shut down.
The format is one address per line, with no attached name or angle
brackets.  Domains to be ignored should start with the "@" symbol.
The addresses are matched literally (though case-insensitively); it's
not possible to use regexps.
*** Noticing and Automatic Rules
:PROPERTIES:
:ID:       0e6d846d-de48-498f-99a3-25ceef0b6fde
:END:

#+CINDEX: Automatic Rules
In addition to updating records' name and mail fields, it's possible
to run other arbitrary edits on records when they are referenced in a
message.  This process is called "noticing".  Two hooks are run as a
part of noticing:

#+ATTR_TEXINFO: :options ebdb-notice-record-hook
#+begin_defopt
This hook is run once per record noticed, with two arguments: the
record, and one of the symbols ~sender~ and ~recipient~, indicating
where in the message headers the record was found.
#+end_defopt

#+ATTR_TEXINFO: :options ebdb-notice-mail-hook
#+begin_defopt
This hook is run once per mail message noticed: if multiple addresses
belong to a single record, it will be called once per address.  The
hook is run with one argument: the record.
#+end_defopt

#+FINDEX: ebdb-notice-field
When a record is noticed, it will also call the method
~ebdb-notice-field~ on all of its fields.  Using this method requires
a bit of familiarity with @@texinfo:@ref{Generic
Functions,,,elisp}@@; suffice it to say that the first argument is the
field instance being noticed, the second argument is one of the
symbols ~sender~ or ~recipient~, and the third argument is the record
being noticed.

#+FINDEX: ebdb-mua-message-header
A useful function here is ~ebdb-mua-message-header~, which can be used
to extract the value of arbitrary headers from the current message.
The header should be provided as a string, for example
~(ebdb-mua-message-header "Subject")~.  There is currently no shortcut
for extracting the text of the message body; code to do this will have
to be written per-MUA.

For functions that can be used to edit a record's field data,
[[id:4a6d956e-54ee-4b67-a462-5b826678aa97][Manipulating Field Data Programmatically]].

*** Interactive Commands
:PROPERTIES:
:ID:       38166454-6750-48e9-a5e5-313ff9264c6d
:END:
Some interactive commands are also provided for operating on the
relevant EBDB records.  In message-reading MUAs, EBDB creates its own
keymap, and binds it to the key ";".  The following list assumes this
binding, and only specifies the further binding.  Ie, press ";:" to
call ~ebdb-mua-update-records~.

#+attr_texinfo: :indic @kbd
- : ::

     #+KINDEX: ; :
     #+FINDEX: ebdb-mua-update-records
     If the option ~ebdb-mua-auto-update-p~ is nil, this command
     (~ebdb-mua-update-records~) can be used to do the same thing, and
     will behave as if that option were set to ~query~.

- ; ::

     #+KINDEX: ; ;
     #+FINDEX: ebdb-mua-display-all-records
     If the option ~ebdb-mua-pop-up~ is nil, this command can be used
     to do the same thing (~ebdb-mua-display-all-records~).

- ' ::

     #+KINDEX: ; '
     #+FINDEX: ebdb-mua-edit-sender-notes
     Edit the notes field of the message sender
     (~ebdb-mua-edit-sender-notes~).

- @@texinfo:@quotedblright{}@@ ::

     #+KINDEX: ; "
     #+FINDEX: ebdb-mua-in-ebdb-buffer
     This command moves point to the relevant EBDB pop-up buffer
     (popping the buffer up first, if necessary).  You can then issue
     commands in the EBDB buffer as usual, with the exception that
     {{{kbd(q)}}} will move point back to the previously-selected
     window, rather than quitting the EBDB buffer.

- s ::

     #+KINDEX: ; s
     #+FINDEX: ebdb-mua-snarf-article
     This command scans the body text of the current message, and
     attempts to snarf new record information from it.  Email
     addresses and names in the body text will be handled, as will
     information in the headers of forwarded mail, and information in
     the signature will be associated with the sender.  The user is
     always prompted before edits are made.  This functionality is
     highly unreliable, and probably won't work as advertised.

- t ::

     #+KINDEX: ; t
     #+FINDEX: ebdb-mua-toggle-records-format
     This command toggles the displayed records between the multiline
     and oneline display formats.

Other command are not bound by default:

#+attr_texinfo: :options Command ebdb-mua-yank-cc
#+begin_deffn
Prompt for an existing {{{buf(EBDB)}}} buffer, and add addresses for
all the records displayed there to the "CC:" line of the message being
composed.  This command is not bound by default, because the EBDB
keymap is not bound by default in message composition MUAs.
#+end_deffn

#+attr_texinfo: :options Command ebdb-mua-display-sender
#+begin_deffn
Only display the sender.
#+end_deffn

#+attr_texinfo: :options Command ebdb-mua-display-recipients
#+begin_deffn
Only display the recipients.
#+end_deffn

#+attr_texinfo: :options Command ebdb-mua-display-all-recipients
#+begin_deffn
Only display recipients, using all mail addresses from the message.
#+end_deffn
** EBDB and MUA summary buffers

EBDB can affect the way message senders are displayed in your MUA's
summary buffer.  It can do this in two ways: 1) by changing the way
the contact name is displayed, and 2) by optionally displaying a
one-character mark next to the contact's name.
*** Sender name display
EBDB can "unify" the name displayed for a sender that exists in the
database.  In general, an MUA will display the name part of the From:
header in the mailbox summary buffer.  EBDB can replace that display
name with information from the database.  This only works for Gnus,
which allows for overriding how message senders are displayed.  The
format letter (see below) should be added to
~gnus-summary-line-format~ for Gnus (which see).

#+attr_texinfo: :options ebdb-message-clean-name-function
#+begin_defopt
A function used to clean up the name extracted from the headers of a
message.
#+end_defopt

#+attr_texinfo: :options ebdb-message-mail-as-name
#+BEGIN_defopt
If non-nil, the mail address will be used as a fallback for new record
names.
#+END_defopt

#+attr_texinfo: :options ebdb-mua-summary-unification-list
#+BEGIN_defopt
A list of fields used by ~ebdb-mua-summary-unify~ to return a value
for unification.  See docstring for details.
#+END_defopt

#+attr_texinfo: :options ebdb-mua-summary-unify-format-letter
#+BEGIN_defopt
Format letter to use for the EBDB-unified sender name in a Gnus
summary buffer.  Defaults to "E".
#+END_defopt

*** Summary buffer marks
EBDB can display a one-character mark next to the name of senders that
are in the database---at present this is only possible in the Gnus
and VM MUAs.  This can be done in one of three ways.  From most
general to most specific:

#+attr_texinfo: :options ebdb-mua-summary-mark
#+BEGIN_defopt
Set to a single-character string to use for all senders in the EBDB
database.  Set to nil to not mark senders at all.
#+END_defopt

#+attr_texinfo: :options ebdb-record ebdb-mua-make-summary-mark record
#+BEGIN_defmethod
This generic function accepts @@texinfo:@var{record}@@ as a single
argument, and returns a single-character string to be used as a mark.
#+END_defmethod

Alternately, give a record an instance of the "summary mark" field
class to use that specific mark for that record.

Marks are displayed in MUA summary buffers by customizing the format
string provided by Gnus, and adding the EBDB-specific format code:

#+attr_texinfo: :options ebdb-mua-summary-mark-format-letter
#+BEGIN_defopt
Format letter to use in the summary buffer format string to mark a
record.  Defaults to "e".
#+END_defopt
** Mail Address Completion
:PROPERTIES:
:ID:       f035aefc-53b1-4d05-b980-8ae0ac851275
:END:
Emacs' two message-composition modes are ~message-mode~ and
~mail-mode~, the former having somewhat obsoleted the latter -- EBDB
supports both.

The main use of EBDB in message composition is to complete email
addresses of contacts, obviously.  The following options govern this
behavior:

#+ATTR_TEXINFO: :options ebdb-complete-mail
#+BEGIN_defopt
If non-nil, EBDB will provide mail completion in mail composition
buffers.  If it is the symbol ~capf~, EBDB will add it's own
completion function to the local value of
~completion-at-point-functions~.  Otherwise, it will clobber the
existing binding of {{{kbd(@key{TAB})}}} and replace it with the
function ~ebdb-complete-mail~.  (Technically, in ~message-mode~, it
will ensure this function is called instead of ~message-expand-name~.)
#+END_defopt

#+ATTR_TEXINFO: :options ebdb-mail-avoid-redundancy
#+BEGIN_defopt
If nil, mail completion will always insert a full "First Last
<first.last@example.com>" string, even when the contact's name is
deemed to be redundant with the email address itself.  If set to the
symbol ~mail-only~, the name will never be inserted.  If any other
non-nil value, the name will be elided if it appears to be redundant.
#+END_defopt

#+ATTR_TEXINFO: :options ebdb-complete-mail-allow-cycling
#+BEGIN_defopt
If non-nil, cycle mail addresses when completing mails.  The exact
behavior of this setting depends a bit on the value of
~ebdb-complete-mail~.  If completion at point is being used, this can
be set to an integer N, specifying that cycling may take place if
there are N or fewer candidate completion strings.  If the function
~ebdb-complete-mail~ is being used, a non-nil value will allow cycling
among all of a single contact's mail addresses, once the contact
itself has been selected.
#+END_defopt

#+ATTR_TEXINFO: :options ebdb-completion-display-record
#+BEGIN_defopt
If non-nil, display each newly-completed record in a pop-up
{{{buf(EBDB)}}} buffer.
#+END_defopt

#+ATTR_TEXINFO: :options ebdb-complete-mail-hook
#+BEGIN_defopt
A hook run after a successful completion.
#+END_defopt

#+ATTR_TEXINFO: :options ebdb-mail-abbrev-expand-hook
#+BEGIN_defopt
A single function called each time an alias is expanded in a
composition buffer.  The function is called with two arguments: the
alias name, and the list of corresponding mail addresses.
#+END_defopt

*** A Note on Completion
As mentioned above, EBDB completion can be done either using the
completion at point framework, or its own ~ebdb-complete-mail~
function.  The two don't behave exactly the same, however: completion
at point works from a pre-constructed list of strings, while
~ebdb-complete-mail~ conducts an actual search of the database.  This
means that the former is faster, but the latter will find more
records, particularly if search options like ~ebdb-case-fold-search~
are in effect.

* Specific MUAs
** Gnus
EBDB has a little more support for Gnus than the other MUAs, for no
other reason than that Gnus is what the author uses.
*** Posting Styles
Gnus provides a "posting styles" mechanism which allows the user to
set up specific mail composition styles (custom headers and
signatures, etc) when writing mails to certain recipients.  The
mechanism examines Gnus group names to determine which styles to use.
EBDB can fake this mechanism so that different styles are used when
composing messages to different records.

#+attr_texinfo: :options ebdb-gnus-post-style-function
#+BEGIN_defopt
Set this option to a callable which accepts two arguments, a record
instance and a mail instance.  The callable should examine these
arguments and return the string name of a Gnus group to use for
looking up posting styles, or nil to use Gnus' defaults.
#+END_defopt

When writing this function, functions such as ~ebdb-record-field~ and
~ebdb-record-current-fields~ may come in handy.  Here's a less-obvious
example that dispatches styles depending on which database the record
belongs to:

#+BEGIN_SRC elisp
  (setq ebdb-gnus-post-style-function
        (lambda (rec _mail)
          (let ((dbs (ebdb-record-databases rec)))
            (if (object-assoc "File: work.dat" 'label dbs)
                "nnimap+WorkAccount:INBOX"
              "nnimap+PersonalAccount:INBOX"))))
#+END_SRC

A current limitation of this functionality is that it only works when
composing a mail to a single recipient.  If you mark several records
in a {{{buf(EBDB)}}} buffer and compose a mail to them collectively,
the mechanism will be bypassed.
* EBDB Buffers
:PROPERTIES:
:ID:       877ca77a-06d6-4fbf-87ec-614d03c37e30
:END:
EBDB can create several separate buffers for displaying contacts.
Typically, each MUA creates its own buffer, with names like
{{{buf(EBDB-Gnus)}}}, etc.  Users can also create their own buffers
that won't be interfered with by MUA pop-up action.  Calling the
~ebdb~ command directly will create such a "user-owned" buffer; it's
also possible to create more by using the ~ebdb-clone-buffer~ and
~ebdb-rename-buffer~ commands within existing EBDB buffers.

#+attr_texinfo: :options ebdb-buffer-name
#+BEGIN_defopt
The base string that is used to create EBDB buffers, without
asterisks.  Defaults to "EBDB".
#+END_defopt

#+attr_texinfo: :indic @kbd
- b c ::

     #+KINDEX: b c
     #+FINDEX: ebdb-clone-buffer
     Prompt for a buffer name, and create a new EBDB buffer displaying
     the same records as the original buffer (~ebdb-clone-buffer~).

- b r ::

     #+KINDEX: b r
     #+FINDEX: ebdb-rename-buffer
     Rename the current EBDB buffer (~ebdb-rename-buffer~).  If this
     is done in a MUA pop-up buffer, the original buffer will be
     recreated next time the MUA requests another pop up.
** Searching
#+CINDEX: Searching the EBDB
#+KINDEX: / /
The most general search is performed with {{{kbd(/ /)}}}, which
searches on many different record fields and displays the results.

The EBDB major mode provides many keys for searching on specific
record fields.  Most of these keys are used after one of three prefix
keys, which change the behavior of the search: {{{kbd(/)}}} clears the
buffer and searches the whole database, {{{kbd(|)}}} searches only
among the records already displayed, and {{{kbd(+)}}} searches the
whole database and appends the results to the records already
displayed.

For instance, record name search is on the key {{{kbd(n)}}}, meaning
you can use {{{kbd(/ n)}}}, {{{kbd(| n)}}}, or {{{kbd(+ n)}}}.
Search keys that work this way are:

#+attr_texinfo: :indic @kbd
- n :: Search names
- o :: Search organizations
- p :: Search phones
- a :: Search addresses
- m :: Search mails
- t :: Search tags
- x :: Search user fields (prompts for which field to search on)
- c :: Search records that have been modified since last save
- C :: Search by record class
- D :: Prompt for a database and display all records belonging to that
  database

Search commands that currently only work with the {{{kbd(/)}}} prefix
are:

#+attr_texinfo: :indic @kbd
- / 1 :: Prompt for a single record, and display it
- / d :: Search duplicate records

#+CINDEX: Inverting searches
Searches can be inverted:

#+attr_texinfo: :indic @kbd
- ! ::
     #+KINDEX: !
     #+FINDEX: ebdb-search-invert
     Invert the results of the next search (~ebdb-search-invert~).

#+CINDEX: Search history
Each user-created {{{buf(EBDB)}}} buffer keeps track of search history
in that buffer.  To pop back to previous searches, use:

#+attr_texinfo: :indic @kbd
- ^ ::
     #+KINDEX: ^
     #+FINDEX: ebdb-search-pop
     ~ebdb-search-pop~
*** Changing Search Behavior
#+CINDEX: Customizing search
There are three ways to alter the behavior of EBDB searches.

#+attr_texinfo: :options ebdb-case-fold-search
#+BEGIN_defopt
An equivalent to the regular ~case-fold-search~ variable, which
see.  Defaults to the value of that variable.
#+END_defopt

#+attr_texinfo: :options ebdb-char-fold-search
#+BEGIN_defopt
Controls whether character folding is used when matching search
strings against record values.
#+END_defopt

#+attr_texinfo: :options ebdb-search-transform-functions
#+BEGIN_defopt
A list of functions that can be used to arbitrarily transform search
strings.  Each function should accept a single string argument, and
return the transformed string.  If the search criterion is not a
string (some fields produce sexp search criteria) these functions
will not be used.
#+END_defopt

Be careful of potential interaction between character folding and
transform functions.  Character folding works by calling
~char-fold-to-regexp~ on the search string, effectively replacing
foldable characters within the string using regular expressions.  This
process happens _after_ the transform functions have run, so there is
a possibility for unexpected search behavior.
** The Basics of ebdb-mode
EBDB buffers inherit from special-mode, and so the usual special-mode
keybindings apply.

#+attr_texinfo: :indic @kbd
- n ::

     #+KINDEX: n
     #+FINDEX: ebdb-next-record
     Move point to the next record (~ebdb-next-record~).

- p ::

     #+KINDEX: p
     #+FINDEX: ebdb-prev-record
     Move point to the previous record (~ebdb-prev-record~).

- N ::

     #+KINDEX: N
     #+FINDEX: ebdb-next-field
     Move point to the next field (~ebdb-next-field~).

- P ::

     #+KINDEX: P
     #+FINDEX: ebdb-prev-field
     Move point to the previous field (~ebdb-prev-field~).

- c ::

     #+KINDEX: c
     #+FINDEX: ebdb-create-record
     Create a new person record in the primary database
     (~ebdb-create-record~).

- C ::

     #+KINDEX: C
     #+FINDEX: ebdb-create-record-extended
     Prompt for database and record class, then create a new record
     (~ebdb-create-record-extended~).

- i ::

     #+KINDEX: i
     #+FINDEX: ebdb-insert-field
     Insert a new field into the record under point, or the marked
     records (~ebdb-insert-field~).

- e ::

     #+KINDEX: e
     #+FINDEX: ebdb-edit-field
     Edit the field under point (~ebdb-edit-field~).

- E ::

     #+KINDEX: E
     #+FINDEX: ebdb-edit-field-customize
     Use the extended customize interface to edit the field under
     point (~ebdb-edit-field-customize~).

- ; ::

     #+KINDEX: ;
     #+FINDEX: ebdb-edit-foo
     Either insert/edit the record's notes field or, with a prefix
     arg, prompt for an existing field and edit it (~ebdb-edit-foo~).

- C-k ::

     #+KINDEX: C-k
     #+FINDEX: ebdb-delete-field-or-record
     With point on a record field, offer to delete that field.  With
     point on a record header, offer to delete the whole
     record (~ebdb-delete-field-or-record~).

- @@texinfo:@kbd{@key{RET}}@@ ::

     #+KINDEX: RET
     #+FINDEX: ebdb-record-action
     #+CINDEX: Field actions
     Run an "action" on the field under point
     (~ebdb-record-action~). If multiple actions are provided, you'll
     be prompted to choose one.  Not all fields provide actions.
     {{{kbd(@key{RET})}}} on a mail field will compose a message to
     that mail address.

- m ::

     #+KINDEX: m
     #+FINDEX: ebdb-mail
     Begin composing a message to the record under point
     (~ebdb-mail~).  With a prefix arg, prompt for the mail address to
     use; otherwise use the record's primary address.

- M ::

     #+KINDEX: M
     #+FINDEX: ebdb-mail-each
     Begin composing a separate message to each marked record in the
     current {{{buf(EBDB)}}} buffer, or all records in the buffer if
     none are marked.  In addition, prompt for a common subject header
     line to use for each message, as well as records to add to the
     "Cc" and "Bcc" headers.  Then optionally prompt for a character,
     interpreted as the name of a register.  If that register contains
     text, insert the text as the body of each message.

     This function works as a sort of poor-man's mail merge; it lacks
     the ability to interpolate variables in the body text.

- t ::

     #+KINDEX: t
     #+FINDEX: ebdb-toggle-records-format
     Toggle between a multi-line, one-line, and full display (see [[id:20fc7a2a-55a9-43ef-9534-9e5887682a88][Customizing
     Record Display]]) (~ebdb-toggle-records-format~).

- T ::

     #+KINDEX: T
     #+FINDEX: ebdb-toggle-all-records-format
     Toggle the display of all the records in the current
     {{{buf(EBDB)}}} buffer.  (~ebdb-toggle-all-records-format~).

- r ::

     #+KINDEX: r
     #+FINDEX: ebdb-reformat-records
     Redisplay the record under point (~ebdb-reformat-records~).

- o ::

     #+KINDEX: o
     #+FINDEX: ebdb-omit-records
     Remove the record under point (or marked records) from the buffer
     (does not delete the records) (~ebdb-omit-records~).

- I ::

     #+KINDEX: I
     #+FINDEX: ebdb-cite-records-ebdb
     Put a "citation" for the record under point (or marked records)
     onto the kill ring (~ebdb-cite-records-ebdb~).  A "citation" is a
     name-and-mail string for the record.  Prompt for a style, meaning
     a textual mode.  With a prefix arg, arrange citations in a list,
     otherwise inline.

- w f ::

     #+KINDEX: w f
     #+FINDEX: ebdb-copy-fields-as-kill

     Copy the string value of the field under point to the kill ring
     (~ebdb-copy-fields-as-kill~).

- w r ::

     #+KINDEX: w r
     #+FINDEX: ebdb-copy-records-as-kill
     Copy a string representation of the whole record under point to
     the kill ring (~ebdb-copy-records-as-kill~).

- w m ::

     #+KINDEX: w m
     #+FINDEX: ebdb-copy-mail-as-kill
     Copy a name-plus-mail string citation for the record under point
     to the kill ring (~ebdb-copy-mail-as-kill~).  These strings look
     like "John Q Public <john@public.com>".  By default this will use
     the record's primary address; supply a prefix arg to be prompted
     for which address to use.

- g ::

     #+KINDEX: g
     #+FINDEX: revert-buffer
     Redisplay all visible records (~revert-buffer~).

- ? ::

     #+KINDEX: ?
     #+FINDEX: ebdb-help
     Show a very brief help message (~ebdb-help~).

- h ::

     #+KINDEX: h
     #+FINDEX: ebdb-info
     Open this manual (~ebdb-info~).

- s ::

     #+KINDEX: s
     #+FINDEX: ebdb-save
     Save all databases (~ebdb-save~).

- q ::

     #+KINDEX: q
     #+FINDEX: quit-window
     Delete the {{{buf(EBDB)}}} window (~quit-window~).

[[id:692cde31-73be-4faf-b436-7eae8a5d02d1][Creating Records]] and [[id:4170bd36-64bf-44b4-87d0-29fbed968851][Record Fields]] for more on record creation and
field manipulation.
** Customizing Record Display
:PROPERTIES:
:ID:       20fc7a2a-55a9-43ef-9534-9e5887682a88
:END:
#+VINDEX: ebdb-default-multiline-formatter
#+VINDEX: ebdb-default-oneline-formatter
The appearance of records in {{{buf(EBDB)}}} buffers can be
customized.  The display of records is controlled by objects called
formatters, and two such objects are provided by default, one creating
a multi-line display of records (the value of
~ebdb-default-multiline-formatter~), and another creating a
single-line display (~ebdb-default-oneline-formatter~).  Some
customization options are provided to influence the behavior of these
formatters (see the ~ebdb-record-display~ group), but users familiar
with EIEIO objects can also manipulate formatter slot-values directly,
override display methods, or write entirely new formatters.  Any
formatter that inherits from ~ebdb-formatter-ebdb~ will be made
available for cycling with the {{{kbd(t)}}} key in {{{buf(EBDB)}}}
buffers.

#+attr_texinfo: :options ebdb-dedicated-window
#+BEGIN_defopt
If non-nil, {{{buf(EBDB)}}} windows will be dedicated.  Set to ~ebdb~
to make the window weakly dedicated, and to ~t~ to make it strongly
dedicated.
#+END_defopt

#+attr_texinfo: :options ebdb-join-atomic-windows
#+BEGIN_defopt
If non-nil, {{{buf(EBDB)}}} buffers will join atomic windows when
popped up from such a window.
#+END_defopt

#+attr_texinfo: :options ebdb-fill-field-values
#+BEGIN_defopt
If non-nil, long values will be filled in {{{buf(EBDB)}}} buffers.
#+END_defopt

The following options affect how various fields are displayed in
{{{buf(EBDB)}}} buffers.  The values of these options are always lists
of field types as symbols: either the actual names of the field
classes (~ebdb-field-*~), or one of the following shortcuts:

- ~mail~
- ~phone~
- ~address~
- ~notes~
- ~tags~
- ~role~
- ~mail-primary~
- ~mail-defunct~
- ~mail-not-defunct~
- ~role-defunct~
- ~role-not-defunct~

#+attr_texinfo: :options ebdb-default-multiline-include
#+BEGIN_defopt
A list of field types to include in the multiline formatter.
#+END_defopt

#+attr_texinfo: :options ebdb-default-multiline-exclude
#+BEGIN_defopt
A list of field types to exclude in the multiline formatter.  If the
previous option is set, this one is ignored.  Defaults to a list of
the "plumbing" field types such as uuid and creation date, as well as
defunct mail and role fields.
#+END_defopt

#+attr_texinfo: :options ebdb-default-multiline-combine
#+BEGIN_defopt
A list of field types to combine in the multiline formatter.  Multiple
instances of "combined" field types are gathered onto a single line,
instead of one per line.  This defaults to the mail and phone fields.
#+END_defopt

#+attr_texinfo: :options ebdb-default-multiline-collapse
#+BEGIN_defopt
A list of field types to collapse in the multiline formatter.  The
meaning of "collapse" may vary between formatters: in the
{{{buf(EBDB)}}} buffers it means that field values are truncated to a
single line; in LaTeX or HTML it might mean the values must be clicked
to be displayed completely.  By default, address fields are collapsed.
In {{{buf(EBDB)}}} buffers, it's still possible to see the complete
field value either in a tooltip when mousing over the field, or by
putting point on the field and hitting {{{kbd(w f)}}}.
#+END_defopt

#+attr_texinfo: :options ebdb-default-oneline-include
#+BEGIN_defopt
A list of field types to include in the default oneline format.  The
oneline formatters can handle the same options as the multiline
formatters, but because "include" is the only option that really makes
sense, it's the only one that has its own customization option.
#+END_defopt

There are also a number of faces that can be manipulated; see the
~ebdb-faces~ group.

Users who wish for more fine-grained control over output can override
the formatting methods ~ebdb-fmt-record~, ~ebdb-fmt-field-label~, and
~ebdb-fmt-field~.  It may be necessary to poke around in the source
code to get things exactly right, but the general signature looks
like:

#+BEGIN_SRC elisp
  (cl-defmethod ebdb-fmt-field ((_fmt ebdb-formatter-ebdb)
                                (field ebdb-field)
                                _style
                                (_record ebdb-record))
    (ebdb-string field))
#+END_SRC

Possible values for the "style" argument are ~nil~, ~oneline~,
~compact~, and ~collapse~.

** Marking
:PROPERTIES:
:ID:       73462a5d-2ec7-4a83-8b38-f5be8e62b376
:END:
Records can be marked and acted on in bulk.  The {{{kbd(#)}}} key will
toggle the mark of the record under point.  {{{kbd(M-#)}}} will toggle
the marks of all the records in the buffer, and {{{kbd(C-#)}}} unmarks
all records in the buffer.  Many  editing commands can act on multiple
marked records.
** Exporting/Formatting
:PROPERTIES:
:ID:       0f72cc06-99e4-45b1-aa32-14e909f0765e
:END:
It is possible to export (referred to as "formatting") records in
various ways.  The most common export format is that of the
{{{buf(EBDB)}}} buffers themselves, but other formats are possible.

At present, the only other supported format is VCard, and support is
imperfect: not all fields can be exported correctly.  VCard version
2.1 is unsupported: the only options are version 3.0 and 4.0.

#+attr_texinfo: :indic @kbd
- f ::

     #+KINDEX: f
     #+FINDEX: ebdb-format-to-tmp-buffer
     This command prompts for a formatter, and formats the record
     under point to a temporary buffer (~ebdb-format-to-tmp-buffer~).
     Use [[id:73462a5d-2ec7-4a83-8b38-f5be8e62b376][marking]] to format multiple records.

- F ::

     #+KINDEX: F
     #+FINDEX: ebdb-format-these-records
     Export all records in the current EBDB buffer to a different
     format (~ebdb-format-these-records~).

It's possible to write new formatters, documentation is forthcoming.
* Completion
There are many Emacs completion frameworks out there, and EBDB
provides custom commands for a few of them: ~ebdb-helm~,
~ebdb-counsel~, and ~ebdb-company~.  Counsel and company are made to
be hooked into Emacs' existing completion frameworks; the helm command
must be called explicitly.  For information about completion in mail
composition buffers, see [[id:f035aefc-53b1-4d05-b980-8ae0ac851275][Mail Address Completion]].

Another built-in library,
@@texinfo:@file{@@ebdb-complete@@texinfo:}@@, uses an ephemeral pop-up
{{{buf(EBDB)}}} buffer for record completion.  The command
~ebdb-complete~ provides an interactive entry point, or you can enable
it for {{{kbd(@key{TAB})}}} in ~message-mode~ by calling
~ebdb-complete-enable~.

* Snarfing
#+CINDEX: Snarfing text
"Snarfing" refers to scanning free-form text and extracting
information related to EBDB records from it.  For example, calling
~ebdb-snarf~ while the region contains the text "John Doe
<j.doe@email.com>" will find an existing contact or prompt to create a
new one, and then display that contact.

Snarfing is a work in progress: at present, only mail addresses, phone
numbers, URLs, and nearby names are acted upon, and it often doesn't
work correctly.

#+attr_texinfo: :options Command ebdb-snarf &optional string start end recs
#+BEGIN_deffn
Extract record-related information from a piece of text.  Find,
update, or create records as necessary, and then display them.  When
the region is active, this command snarfs the current region,
otherwise it snarfs the entire current buffer.  Called as a function,
it can accept a string as the first argument and snarfs that.  The
RECS argument, which cannot be passed interactively, is a list of
records that are assumed to be related to snarfable data in STRING.
#+END_deffn

#+attr_texinfo: :options ebdb-snarf-routines
#+BEGIN_defopt
An alist of field class symbols and related regexps.  The regexps are
used to collect text that is likely parseable by the ~ebdb-parse~
method of the field class.
#+END_defopt

#+attr_texinfo: :options ebdb-snarf-name-re
#+BEGIN_defopt
A list of regular expressions used to recognize names for a snarfed
contact.  Searching names directly is mostly impossible, so names are
only looked for in close proximity to other field data.
#+END_defopt

#+CINDEX: Article snarfing
In MUAs, EBDB can also snarf the body of the article being displayed.
This is separate from the updating process, which only examines the
article headers.

#+attr_texinfo: :options Command ebdb-mua-snarf-article &optional arg
#+BEGIN_defopt
Snarf the body of the current article.  This will also snarf the
headers of forwarded emails, and the signature.  With a prefix
argument, only snarf the signature.
#+END_defopt
* Internationalization
#+CINDEX: Internationalization
EBDB comes with an internationalization framework that can provide
country- and region-specific behavior for certain fields.  This
functionality is initialized by loading the
@@texinfo:@file{@@ebdb-i18n@@texinfo:}@@ library.  This library does
nothing by itself, it simply provides hooks for other country-specific
libraries.

Country libraries that do not depend on other external libraries may
live within the EBDB codebase, in which case they will be loaded
automatically when ~ebdb-i18n~ is loaded.  Libraries with external
dependencies may be installed from the package repositories.  Because
function autoloading doesn't work with generic methods, you'll need to
require the libraries in addition to simply installing them.

There is currently only one country library written for EBDB,
@@texinfo:@file{@@ebdb-i18n-chn@@texinfo:}@@, for Chinese-related
fields.  It parses and displays phone numbers and names correctly, and
also allows users to search on Chinese names using pinyin.  It can be
installed from ELPA, and requires the ~pyim~ package, available on
MELPA.

The present dearth of libraries is a result of the author scratching
his own itch.  Contributions of new libraries are very welcome (see
[[id:5446ff9c-78ca-4e12-89cc-6d4ccd9b2b83][Writing Internationalization Libraries]]).  Also welcome, though less
enthusiastically, are requests for new libraries.

Internationalization libraries do not modify the database, and can be
safely unloaded.  They simply alter the way EBDB reads, parses and
displays field values, and can also store extra information
(eg.@@texinfo:@:@@ for searching purposes) in a record's cache.
Loading internationalization libraries may slow down initial database
loading, though they should not significantly impact search or display
performance.

Actually, the internationalization library does alter database storage
in one way: address countries can be either stored as a string
(non-international-aware), or a three-letter symbol representing the
country code (international-aware).  EBDB will correctly display the
country name for either type of storage, regardless of whether the
internationalization library is loaded or not.

#+VINDEX: ebdb-i18n-countries
Country names are displayed in English by default, but users can alter
the display of some country names if they choose.

#+ATTR_TEXINFO: :options ebdb-i18n-countries-pref-scripts
#+BEGIN_defopt
This is an alist of conses pairing string country names to symbol
labels---see the value of ~ebdb-i18n-countries~ for the correct
format, and to find the correct symbol label.  Values set in this
option will shadow the values in the variable.
#+end_defopt

* Diary Integration
#+CINDEX: Diary integration
Some EBDB fields hold dates or anniversaries (most notably the
~ebdb-field-anniversary~ field).  It's possible to integrate this
information with Emacs' diary package (and from there to Org, via the
~org-agenda-include-diary~ option).  At present, you'll need to have
an actual diary file present at the location indicated by
~diary-file~, though the file can be blank.

#+ATTR_TEXINFO: :options ebdb-use-diary
#+BEGIN_defopt
If non-nil, EBDB fields with date information will attempt to add that
information to the diary.
#+END_defopt

When viewing the calendar, you can use the {{{kbd(d)}}} key to see
diary information for that day.

Support for this feature is rudimentary.  More customization options
are forthcoming.
* Mail Aliases
#+CINDEX: Mail aliases
You can give records a mail alias with the "mail alias" field,
available in the list of choices for inserting new fields.  You'll be
prompted for an alias, and an email address to use for the alias, if
the record has more than one.  If multiple records have the same
alias, then entering that alias in the "To:" or "Cc:" field of a
message composition buffer will expand to a comma-separated list of
record addresses.

Mail aliases are updated every time an EBDB buffer is created.  It's
also possible to force an update using the {{{kbd(A)}}} key in a
{{{buf(EBDB)}}} buffer.

* vCard Support
EBDB has rudimentary support for exporting to vCard format; this
functionality will be expanded in the future.  After loading the
@@texinfo:@file{@@ebdb-vcard@@texinfo:}@@ library, a vCard formatter
will be available when formatting EBDB records (see
[[id:0f72cc06-99e4-45b1-aa32-14e909f0765e][Exporting/Formatting]]).

Support for importing vCard files is on the EBDB roadmap, as is,
eventually, support for CardDav servers.
* Org Integration
:PROPERTIES:
:ID:       ee6b5ccb-a7a6-4c42-84a5-9eb0bbdc040f
:END:
EBDB has standard support for Org functionality: creating links to
EBDB records works as expected with {{{kbd(C-c l)}}}, and following a
link will open an {{{buf(EBDB)}}} buffer and display the linked
record.

Typically, links are created using the record's UUID field---these
links are fast and accurate---but it's also possible to create links
that initiate an EBDB search, and return multiple records.  EBDB links
are of the format "ebdb:<field type>/<search string>".  The
@@texinfo:@samp{field type}@@ is typically the name of an EBDB field
class (for instance, "ebdb-field-anniversary"), and opening a link of
this sort results in a search of all records for which
@@texinfo:@samp{search string}@@ matches the string value of that
particular field type.

For convenience, a few field type shorthands are recognized: in
addition to "uuid", there is "mail", "phone", "address", "notes" and
"tags" (see below).  For instance, to create a link to all records
with a 206 phone area code, use "ebdb:phone/206", and to create a link
to all records who work at Google, use "ebdb:mail/google.com".

The @@texinfo:@file{@@ebdb-org@@texinfo:}@@ library also contains the
~ebdb-org-field-tags~ field class, allowing users to tag their
contacts with existing Org tags.  Completion is offered as expected.
[[id:d9073bc7-8731-4919-9fc0-7d1dcf98426e][Tag Field]].

This library comes with one other function that allows you to pop up
an {{{buf(EBDB)}}} buffer alongside an Org Agenda buffer.

#+attr_texinfo: :options Command ebdb-org-agenda-popup
#+BEGIN_deffn
Pop up an EBDB buffer displaying contacts matching the tags used to
create the Agenda buffer.  Only does anything in a tags search Agenda
buffer.
#+END_deffn

This function could also be added to the ~org-agenda-mode-hook~, to
pop up a buffer any time relevant records are found.
* Citing Records
Often one wants to share contact information into other channels: for
instance, pasting a contact's name and mail address in a message
you're sending to someone else.  EBDB refers to this as "citing", and
provides a general interface to this through:

#+attr_texinfo: :options Command ebdb-cite-records
#+BEGIN_deffn
This command is not bound in any mode, but can be called
interactively.  It prompts for a record, then inserts a citation for
the record into the current buffer.  In most text-mode buffers, the
citation looks like "Some Name <some@email.com>".  In Org buffers, it
is a link with a "mailto:" prefix.
#+END_deffn
* Hacking EBDB
:PROPERTIES:
:ID:       a58993a8-0631-459f-8bd6-7155bb6df605
:END:
EBDB is designed to be highly extensible.  In addition to the usual
customization options, it provides for subclassing of the three main
classes: database, record, and field.  The behavior of EBDB can be
radically changed by creating new classes, or overriding the existing
methods of classes, without touching the original source code.  This
manual won't go into details about Emacs' object-orientation support:
see [[info:eieio#Top][EIEIO]] for information on defining classes, and [[info:elisp#Generic%20Functions][Generic Functions]]
for information on writing generic functions and methods.

Some information about EBDB's various classes can had from Emacs'
built-in help system: examining the function definition of a class
symbol like ~ebdb-field-anniversary~ will show a documentation string,
and details of the class's slot and method definitions.

The simplest customization involves changing the default classes used
for basic record and field types.

#+ATTR_TEXINFO: :options ebdb-default-record-class
#+BEGIN_defopt
The default class used for creating records.  This class will be used
when creating records with {{{kbd(c)}}} in ebdb-mode, or when
automatically creating records (ie, from snarfing).  It's always
possible to create a record of a different class by using {{{kbd(C)}}}
in ebdb-mode.
#+END_defopt

#+ATTR_TEXINFO: :options ebdb-default-name-class
#+BEGIN_defopt
The default class for complex names.  Simple names (used for
organizations and nicknames) are always plain strings---this option
only governs the class used for articulated names of individuals, with
separate slots for surname, given names, suffixes, etc.
#+END_defopt

#+ATTR_TEXINFO: :options ebdb-default-mail-class
#+BEGIN_defopt
The default class for mail fields.
#+END_defopt

#+ATTR_TEXINFO: :options ebdb-default-phone-class
#+BEGIN_defopt
The default class for phone fields.
#+END_defopt

#+ATTR_TEXINFO: :options ebdb-default-address-class
#+BEGIN_defopt
The default class for address fields.
#+END_defopt

#+ATTR_TEXINFO: :options ebdb-default-notes-class
#+BEGIN_defopt
The default class for notes fields.
#+END_defopt

If, for instance, you'd like to create a custom mail field and have
all records use that instead of the built-in one:

#+BEGIN_SRC emacs-lisp
  (defclass my-mail-field (ebdb-field-mail)
    ;; custom slots
    )

  (setq ebdb-default-mail-class my-mail-field)
#+END_SRC

Note that there are currently no facilities for changing the class of
existing objects.  This may be addressed in the future.
** Field Classes
It's fairly easy to create your own custom field classes in EBDB.  All
such fields should subclass the ~ebdb-field-user~ class, which sets up
basic behavior.  That base class provides for no slots at all, so your
class must define the slots where the field data will be held.  It
should also provide a class option holding a human-readable string for
the class type.  As an example:

#+BEGIN_SRC emacs-lisp
  (defclass ebdb-field-gender (ebdb-field-user)
    ((gender
      :initarg :gender
      :initform unknown
      :type symbol
      :custom (choice
	       (const :tag "Female" female)
	       (const :tag "Male" male)
	       (const :tag "Other" other)
	       (const :tag "Unknown" unknown)
	       (const :tag "None/Not Applicable" none))))
    :human-readable "gender"
    :documentation "A field holding gender information about this record.")
#+END_SRC

Once the class itself is defined, there are three basic methods which
must be provided: ~ebdb-read~, which prompts the user for values used
to create a new field instance, ~ebdb-parse~, which accepts a string
or other data and creates a new field instance from it, and
~ebdb-string~, which returns a string representation of the field
instance.  The simplest field types only need to provide these three
methods.

The ~ebdb-read~ and ~ebdb-parse~ methods are static (class-level)
methods.  Both take an optional ~slots~ argument, which is a plist of
slot values that will eventually be fed to ~make-instance~.  If values
are already present in the plist, these methods should _not_ override
them.  In addition, ~ebdb-read~ takes an optional ~obj~ argument,
which, if present, is an existing field instance that can be used to
provide default values for the new object.

#+BEGIN_SRC emacs-lisp
  (cl-defmethod ebdb-read ((class (subclass ebdb-field-gender))
                           &optional slots obj)
    (unless (plist-get slots :gender)
      (let ((gender (intern (completing-read
                             "Gender: " '(female male other unknown none)
                             nil t
                             (when obj (symbol-name (slot-value obj 'gender)))))))
        (setq slots (plist-put slots :gender gender))))
    (cl-call-next-method class slots obj))

  (cl-defmethod ebdb-parse ((class (subclass ebdb-field-gender))
                            str &optional slots)
    (when (and (null (plist-get slots :gender))
               (member str '("female" "male" "other" "unknown" "none")))
      (setq slots (plist-put slots :gender (intern str)))
    (cl-call-next-method class str slots))

  (cl-defmethod ebdb-string ((field ebdb-field-gender))
    (symbol-name (slot-value field 'gender)))
#+END_SRC
*** Init and Delete Methods
It's also very common to define ~ebdb-init-field~ and
~ebdb-delete-field~ methods for classes.  These methods can be used to
maintain secondary data structures, or set up extra hashing for
records, or do any other supplemental work.  The one restriction is
that they must not change the database: they may not edit records or
their fields.

#+attr_texinfo: :options Method ebdb-init-field field record
#+BEGIN_deffn
Initialize @@texinfo:@var{field}@@ against @@texinfo:@var{record}@@.
#+END_deffn

#+attr_texinfo: :options Method ebdb-delete-field field record &optional unload
#+BEGIN_deffn
Delete @@texinfo:@var{field}@@ of record @@texinfo:@var{record}@@.  If
the optional argument @@texinfo:@var{unload}@@ is non-nil, it means
the record is only being unloaded
#+END_deffn

Both methods should always end with a call to ~cl-call-next-method~.

~ebdb-init-field~ is called:

1. When loading for the first time (records call ~ebdb-init-field~ on
   all of their fields after they're loaded).
2. When adding a new field instance to a record.
3. When editing an existing field instance (editing is a
   delete-and-create operation).

~ebdb-delete-field~ is called:

1. When deleting a field instance.
2. When deleting the record owning the field instance.
3. When editing an existing field instance (editing is a
   delete-and-create operation).
4. When unloading a record from the database (the optional third
   @@texinfo:@var{unload}@@ argument will be non-nil).
*** Manipulating Field Data Programmatically
:PROPERTIES:
:ID:       4a6d956e-54ee-4b67-a462-5b826678aa97
:END:
While ebdb-mode provides interactive commands for editing record data
in an {{{buf(EBDB)}}} buffer, it can also be useful to do this inside
Elisp functions, especially as a part of [[id:0e6d846d-de48-498f-99a3-25ceef0b6fde][Noticing and Automatic Rules]].
Instead of manipulating field data directly, it's important to go
through accessors that give a record's database(s) a chance to handle,
persist, or update the field data.  There are three functions for
doing this:

#+ATTR_TEXINFO: :options ebdb-record-insert-field rec field &optional slot
#+BEGIN_defun
Insert FIELD into REC.
#+END_defun

#+ATTR_TEXINFO: :options ebdb-record-delete-field rec field &optional slot
#+BEGIN_defun
Delete FIELD from REC.  You'll need to get a handle to FIELD first,
probably with ~ebdb-record-field~.
#+END_defun

#+ATTR_TEXINFO: :options ebdb-record-change-field rec old-field &optional new-field
#+BEGIN_defun
Editing a field in EBDB is actually a delete-then-insert operation.
If the NEW-FIELD argument is nil, the user will be prompted for a
value for the new field, using the OLD-FIELD's value as a default.
#+END_defun

The optional SLOT argument to the first two functions can almost
always be omitted.

Two convenience functions are provided for common editing operations:

#+ATTR_TEXINFO: :options ebdb-record-add-tag rec tag
#+begin_defun
Add string TAG to REC's list of tags.
#+end_defun

#+ATTR_TEXINFO: :options ebdb-record-update rec note &optional replace
#+begin_defun
Add string NOTE to REC's note field.  The text will be appended to any
existing notes, unless the optional argument REPLACE is non-nil.
#+end_defun

*** The Labeled Field Class
Many field classes maintain their own list of labels: ie, anniversary
fields can be labeled "birthday", "wedding", etc.  This functionality
can be added to fields by additionally subclassing the
~ebdb-field-labeled~ class, and then defining a variable that will be
used to hold labels, and pointing to it in the class-allocated
"label-list" slot.  Everything else is taken care of automatically.

#+BEGIN_SRC emacs-lisp
  (defvar my-field-label-list '("default1" "default2")
    "A list of labels for the my-labeled-field class.")

  (defclass my-labeled-field (ebdb-field-user ebdb-field-labeled)
    ((label-list :initform my-field-label-list)))
#+END_SRC
*** The Singleton Field Class
Another abstract mix-in class is the ~ebdb-field-singleton~ class.
Its only function is to ensure that a record only ever has one
instance of the class in question.  If the user tries to add a second
instance, the existing instance is deleted.
*** Actions
#+CINDEX: Field actions
All field classes have a class-allocated slot called "actions".  The
value of this slot is a list of conses, for instance: ~("Browse URL"
. ebdb-field-url-browse)~.  Users can trigger these actions by
pressing {{{kbd(@key{RET})}}}" while point is on the field in the
{{{buf(EBDB)}}} buffer, using a numeric prefix arg to select from
multiple possible actions, or the 0 prefix arg to be prompted for
which action to take.

The functions in this list should accept two arguments, the record and
the field instance under point.
*** Custom Field Searching
In most cases, searching the EBDB database is a matter of prompting
for a regular expression, then matching that regexp against the result
of ~ebdb-string~ called on a field instance.

However, it is possible for field classes to provide more
sophisticated searching behavior, if desired.  When the user calls
~ebdb-search-user-fields~ in the {{{buf(EBDB)}}} buffer, he or she will be
prompted for a field class to search on.  When a field class is
chosen, it has the option to prompt for more complex search criteria.
This is done by overriding two matching methods: ~ebdb-search-read~,
and ~ebdb-field-search~.

#+FINDEX: ebdb-search-read
~ebdb-search-read~ is a static (class-level) method.  Its only
argument is the field class being searched on.  It should prompt the
user for whatever search criterion it wants, then return that
criterion.  This can be nearly anything, so long as the matching
~ebdb-field-search~ can accept it.

#+FINDEX: ebdb-field-search
The ~ebdb-field-search~ method accepts a field instance as the first
argument, and the search criterion as the second.  It should return
non-nil if the criterion somehow matches the field.  Note that it's
perfectly possible to write several ~ebdb-field-search~ methods,
dispatching on different criterion types, if that makes things easier.

In addition, fields that subclass ~ebdb-field-labeled~ can accept
search criterion as a cons: ~("label string"
. other-search-criteria)~.  The label string will first be matched
against the label of the instance, and then other-search-criteria will
be passed to the ~ebdb-field-search~ method as usual.

That might sound a bit confusing, here's an example.  These are the
search methods for the ~ebdb-field-tags~ class.

#+BEGIN_SRC emacs-lisp
(cl-defmethod ebdb-search-read ((_class (subclass ebdb-field-tags)))
  (cdr
   (org-make-tags-matcher
    (ebdb-read-string
     "Search for tags (eg +tag1-tag2|tag3): "))))

(cl-defmethod ebdb-field-search ((field ebdb-field-tags)
				 func)
  (when (functionp func)
    (funcall func t (slot-value field 'tags) 1)))

(cl-defmethod ebdb-field-search ((field ebdb-field-tags)
				 (tag string))
  (seq-find (lambda (tg) (string-match-p tag tg))
	    (slot-value field 'tags)))
#+END_SRC

The ~ebdb-search-read~ method returns a lambda (the ~cdr~ of the
return value of ~org-make-tags-matcher~.  The first
~ebdb-field-search~ method handles that lambda, simply by calling it.
The second ~ebdb-field-search~ method handles a string search
criterion; though no EBDB code would create this search, external code
conceivably might.
*** Fast Lookups
Usually, searches of the database are conducted by looping over all
the records and testing each search clause against each record.
Theoretically, this could be a slow process.

#+VINDEX: ebdb-hashtable
By contrast, "fast lookups" use a central hashtable, the
~ebdb-hashtable~, to look up search strings quickly.  By default,
records names, email addresses, and tags are indexed in this central
hashtable.  To short-circuit the usual slow lookup and use the fast
hashtable lookup, specify one of those three field names as the ~car~
of the search criteria, and prefix the string ~cdr~ of the criteria
with a "^" (the behavior of ~all-completions~ requires a string
prefix):

#+BEGIN_SRC emacs-lisp
  (ebdb-search (ebdb-records) '((ebdb-field-tag "^client")))
#+END_SRC

It's possible to use these fast lookups in interactive searches, when
selecting a specific field type to search on, but the time spent
typing a "^" will undoubtedly outweigh the time saved in the search.
This is mostly useful in non-interactive searches.

It's also possible to specify additional field types which can be used
with fast lookups.  The first step is to write ~ebdb-init-field~ and
~ebdb-delete-field~ methods that hash and unhash the record against
the field string in the ~ebdb-hashtable~.

#+VINDEX: ebdb-hash-extra-predicates
Next, add an element to the ~ebdb-hash-extra-predicates~ variable.
The element should be a cons cell where the ~car~ is the field class
name, as a symbol, and the ~cdr~ is a lambda which accepts the search
string and a record, and returns ~t~ if the search string does indeed
match the instance of that field (and not some other field string).
*** Formatting in the EBDB Buffer
Most fields will be displayed in the {{{buf(EBDB)}}} buffer simply
using ~ebdb-string~.  It's possible to customize this display by
overriding the ~ebdb-fmt-field~ method.  Without going into too much
detail, this method dispatches on four arguments: the formatter, the
field, a "style" symbol argument (typically ~normal~, ~oneline~,
~compact~, ~collapse~ or ~expanded~), and the record being formatted.

Specify an ebdb formatter for the first argument to target
{{{buf(EBDB)}}} formatting.  Choices are ~ebdb-formatter-ebdb~ (for
all cases), or one of ~ebdb-formatter-ebdb-multiline~ or
~ebdb-formatter-ebdb-oneline~.  Keep in mind that many field classes
are not displayed at all in the oneline format.

An example: most fields are output with style set to ~normal~, meaning
that it will use the value of ~ebdb-string~.  By default, formatters
display address fields in the ~collapse~ style, which is mapped to the
~oneline~ style, which simply drops everything after the first
newline.

Say you still wanted addresses output on a single line, but you wanted
to provide a little more information on that line: the first line of
the street addresses, plus the city, plus the country.  You could
achieve that by overriding the ~collapse~ style like so:

#+BEGIN_SRC emacs-lisp
  (cl-defmethod ebdb-fmt-field ((_fmt ebdb-formatter)
				(field ebdb-field-address)
				(_style (eql collapse))
				(_record ebdb-record))
    "Give address fields a special 'collapse formatting."
    (with-slots (streets locality country) field
     (format "%s (%s, %s)" (car streets) locality country)))

#+END_SRC

The leading underscores on parameters are there to keep the compiler
quiet: the arguments are necessary for dispatch, but aren't actually
used in the body of the method.

** Writing Internationalization Libraries
:PROPERTIES:
:ID:       5446ff9c-78ca-4e12-89cc-6d4ccd9b2b83
:END:
Writing new internationalization libraries involves using generic
functions. [[info:elisp#Generic%20Functions][Generic Functions]].  It will also require a bit of
familiarity with EBDB's internals.

Internationalization affects three different field types: addresses,
phone numbers, and names.  It works by providing "i18n" versions of
common methods for those three fields:

| Regular method    | Internationalized method |
|-------------------+--------------------------|
| ebdb-read         | ebdb-read-i18n           |
| ebdb-parse        | ebdb-parse-i18n          |
| ebdb-string       | ebdb-string-i18n         |
| ebdb-init-field   | ebdb-init-field-i18n     |
| ebdb-delete-field | ebdb-delete-field-i18n   |

When the "ebdb-i18n" library is loaded and the left-column ("vanilla")
versions of field methods are called, EBDB first checks to see if a
valid "internationalized" (right-column) method exists.  If it does,
that method is used instead of the vanilla one.

What is a "valid internationalized method"?  That depends on the field
type.  Each field type uses a different key or "spec" to determine the
nationality or locality of the field instance.

- Address fields use a three-character symbol derived from the [[https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3][ISO
  316601 alpha 3]] country codes.  These codes can be found in the
  variable ~ebdb-i18n-countries~.
- Phone fields use the phone number's numerical country code as a
  spec.  These codes can be found in the variable
  ~ebdb-i18n-phone-codes~.
- Name fields are keyed to the symbol representing the script used to
  write them. Specifically, the first character CHAR of the name is
  tested in this way: ~(aref char-script-table CHAR)~, which returns a
  symbol.

How are these "specs" used?  Each internationalized version of the
above methods accepts the spec as an additional argument, which it is
able to specialize on.  Every country-specific method should check the
spec to see if it is relevant to that library. If so, it handles the
necessary behavior; if not, it passes by using ~cl-call-next-method~.
See the function signatures of each internationalized method to find
how to handle the extra argument, called @@texinfo:@var{spec}@@.

Here's a concrete example:

Say we want to make sure all French phone numbers are represented by a
string that looks like "+33 05 12 34 56 79".  This is not how they are
stored in the database, but this is how they should be represented to
the user.  We need to override the ~ebdb-string-i18n~ method for the
phone field class.  This method takes two arguments---the field
instance, and the country-code spec---and needs to specialize on both
arguments.  The method signature will look like this:

#+BEGIN_SRC emacs-lisp
  (cl-defmethod ebdb-string-i18n ((phone ebdb-field-phone)
                                  (_cc (eql 33))))
#+END_SRC

See the manual on generic functions for details; suffice it to say
that this method will only run when the first argument is an instance
of the ~ebdb-field-phone~ class (or a subclass), and the second
argument is ~eql~ to the number 33.

We know that this method will only run for French phone numbers, so we
can format the number correctly:

#+BEGIN_SRC emacs-lisp
  (cl-defmethod ebdb-string-i18n ((phone ebdb-field-phone)
                                  (_cc (eql 33)))
    (with-slots (area-code number extension) phone
      (concat
       "+33 "
       (when area-code
         (format "%02d" area-code))
       (format "%s%s %s%s %s%s %s%s"
               (split-string number "" t))
       (when extension
         (format "X%d" extension)))))
#+END_SRC

Again this only affects the display of numbers, not how they are
stored in the database.

Note that, while phone numbers themselves are stored as strings (they
do not represent a quantity, after all), the country and area codes
are stored as numbers, precisely so that they can be specialized on
using ~eql~.

See the signatures of the other internationalized methods for how to
use them.  The symbol specs for country codes and script names can
also be specialized on with the ~eql~ specializer.
** Writing Integration For New MUAs
Theoretically EBDB can be incorporated into any Emacs package, but
it's most commonly used in conjunction with a mail user agent.  It
comes with support for a few MUAs out of the box, but integration with
a new one can be written fairly easily.

#+FINDEX: ebdb-mua-auto-update
The first step of integration involves hooking the function
~ebdb-mua-auto-update~ somewhere into the MUA's operation.  For most
MUAs, the appropriate place is when a message or article is opened for
viewing by the user.  This allows EBDB to act on the information found
in that message.

The second step requires providing new versions of a handful of
generic functions.  All MUA-specific generic functions specialize on
the current major-mode, using the ~&context~ specializer.  See below
for examples.

#+FINDEX: ebdb-mua-message-header
When ~ebdb-mua-auto-update~ runs, it scans the headers of the current
article/message for name/mail data, and uses that data to locate,
create, edit, and display records.  It does this by calling the
generic function ~ebdb-mua-message-header~ with the string header name; it
is the responsibility of the MUA to implement this function, and
return the contents of the appropriate header.  For instance, in Gnus:

#+BEGIN_SRC emacs-lisp
  (cl-defmethod ebdb-mua-message-header ((header string)
                                     &context (major-mode gnus-summary-mode))
    "Return value of HEADER for current Gnus message."
    (set-buffer gnus-article-buffer)
    (gnus-fetch-original-field header))
#+END_SRC

The first argument is the string header, and the second is the
specializer on the current major-mode.  Possible header values include
those found in ~ebdb-message-headers~. Note that if you expect this
function to be called in more than one major-mode, you'll have to
provide multiple versions of the function.  The &context specializer
uses ~derived-mode-p~ behind the scenes, though, so if all the modes
derive from a single parent mode (and the behavior should be the same
in all derived modes) it is enough to specialize on the parent mode.

Some MUAs might need to do a bit of work to ensure that the article in
question is opened and set up properly:

#+attr_texinfo: :options Method ebdb-mua-prepare-article
#+BEGIN_deffn
Called with no argument but the mode specializer, this function
should do whatever is necessary to prepare the article.
#+END_deffn

Providing {{{buf(EBDB)}}} buffer pop-up support involves implementing
two separate functions:

#+attr_texinfo: :options Method ebdb-make-buffer-name
#+BEGIN_deffn
Called with no arguments but the mode specializer, this function
should return the string name of the {{{buf(EBDB)}}} buffer to be
associated with this MUA.  Usually the function body will look like:
~(format "*%s-<mua>" ebdb-buffer-name)~.
#+END_deffn

#+attr_texinfo: :options Method ebdb-popup-window
#+BEGIN_deffn
Called with no arguments but the mode specializer, this function
should return a list of two elements: the window to be split to make
room for the {{{buf(EBDB)}}} buffer window, and a float value between
0 and 1 indicating the size of the new {{{buf(EBDB)}}} buffer window,
as a percentage of the window being split.
#+END_deffn

#+VINDEX: ebdb-mua-keymap
In addition, it might be nice to bind the ~ebdb-mua-keymap~ in the
MUA's mode-map.  This map provides bindings for some commonly-used
EBDB functions.

*** Article snarfing
#+CINDEX: Article snarfing
EBDB can scan articles or messages for likely field information, and
prompt the user to add the fields to new or existing records---this is
done by the user with the interactive command
~ebdb-mua-snarf-article~.  In order to work, the MUA must be able to
provide that function with the text of the message body, and the text
of the message signature (if any).  This is done with two generic
functions:

#+attr_texinfo: :options Method ebdb-mua-article-body
#+BEGIN_deffn
Return the text of the article body, or nil.
#+END_deffn

#+attr_texinfo: :options Method ebdb-mua-article-signature
#+BEGIN_deffn
Return the text of the article signature, or nil.
#+END_deffn
* Index
:PROPERTIES:
:INDEX:    cp
:END: