Copyright (C) 2000-2012 |
GNU Info (bbdb.info)InternalsInternals ========= This section is currently a dumping ground for things that should eventually go here, but were found elsewhere in the file. INFORMATION IN THIS SECTION IS FOR INFORMATIONAL PURPOSES ONLY. IT SHOULD NOT BE TAKEN AS DOCUMENTATION OF AN EXTERNAL API. EVERYTHING LISTED BELOW IS SUBJECT TO CHANGE WITHOUT NOTICE The first time you use one of the BBDB commands, this file is read into an emacs buffer, and remains there. As you make changes to the database, this buffer is changed as well, ensuring that if it is auto-saved, it will be saved in its most current state. BBDB data file format --------------------- The data file is arranged in a hierarchical fashion. At the top level are vectors, with one vector per database record. It is very important that each vector be on its own line, as the BBDB builds and stores markers based on this layout. The markers are then used to increase the speed of database modifications (more on this later). The record vectors contain the individual fields of the record. These fields can be of any type, but are currently integers, strings, lists of strings, alists, vectors, or lists of vectors. In the case of fields that contain one or more vectors, they can be further broken down in terms of the fields of their component vectors. In an effort to provide a more concrete example to illustrate the above, and to provide a reference for database accessor and modifier functions, we describe the database format below. This description starts with the fields of the individual record vectors, and drills down through the vectors used by some of the fields. Record Vectors .............. Name Type Accessor and Modifier Description First String `bbdb-record-firstname' Entity's first name name `bbdb-record-set-firstname' Last name String `bbdb-record-lastname' Entity's last name `bbdb-record-set-lastname' AKAs List of `bbdb-record-aka' Alternate names for Strings `bbdb-record-set-aka' entity Company String `bbdb-record-company' Company with which `bbdb-record-set-company' entity is associated Phones List of `bbdb-record-phones' List of phone number Vectors `bbdb-record-set-phones' vectors Addresses List of `bbdb-record-addresses' List of address vectors Vectors `bbdb-record-set-addresses' Net List of `bbdb-record-net' List of network address Strings `bbdb-record-set-net' addresses Notes String or `bbdb-record-raw-notes' String or Association Alist `bbdb-record-set-raw-notes'list of note fields (strings) Cache Vector `bbdb-record-cache' Record cache. `bbdb-record-set-cache' Internal version only. The phone, address and cache vector fields are described below. Please note that, as indicated in the table above, the cache is present only in the internal version of the database - it is not written out as part of the `.bbdb' file. In addition, the accessor and modifier functions for the notes alist are described. Phone Vectors ............. To access the fields in the below table, you must first get the list of phone vectors using the `bbdb-record-phones' function. Note that if you alter the phones field with the `bbdb-record-set-phones' function, you are altering the entire phones list for the given record. Use the modifier functions below for modifications to individual phone vectors. Name Type Accessor and Modifier Description Location String `bbdb-phone-location' Phone number identifier `bbdb-phone-set-location' Area Integer `bbdb-phone-area' Area code for phone `bbdb-phone-set-area' number Exchange Integer `bbdb-phone-exchange' Exchange (aka prefix) `bbdb-phone-set-exchange' for phone number Suffix Integer `bbdb-phone-suffix' Suffix for phone number `bbdb-phone-set-suffix' Extension Integer `bbdb-phone-extension' Phone number extension `bbdb-phone-set-extension' (`0' if none) Address Vectors ............... To access the fields in the below table, you must first get the list of address vectors using the `bbdb-record-addresses' function. Note that if you alter the addresses field with the `bbdb-record-set-addresses' function, you are altering the entire addresses list for the given record. Use the modifier functions below for modifications to individual address vectors. Name Type Accessor and Modifier Description Location String `bbdb-address-location' Address identifier `bbdb-address-set-location' Streets List `bbdb-address-streets' List of street address `bbdb-address-set-streets' lines. `nil' if none. Street3 String `bbdb-address-street3' Third line of street `bbdb-address-set-street3' address. "" if none. City String `bbdb-address-city' City name `bbdb-address-set-city' State String `bbdb-address-state' State abbreviation `bbdb-address-set-state' Zip Integer `bbdb-address-zip' Zip code (american) `bbdb-address-set-zip' List (non-american) Country String `bbdb-address-country' Country `bbdb-address-set-country' Cache Vector ............ This vector is present only in the internal database representation. It is not written out to the database file because it contains information aggregated from the rest of the record that is reconstructed when the database is read. To write the cache information to the database file would increase the risk of database inconsistency, and would violate the principles of normalization. To access the cache fields using the functions listed below that begin with `bbdb-cache-', you must first get the cache vector using the `bbdb-record-cache' function. The functions that begin with `bbdb-record-' get the cache vector internally. Note that if you alter the cache field in the high-level record with the `bbdb-record-set-cache' function, you are altering the entire cache vector for the given record. Use the modifier functions below for modifications to individual cache fields. Name Type Accessor and Modifier Description Name Cache String `bbdb-cache-namecache' Preconcatenated name `bbdb-cache-set-namecache' of entity Sort Key String `bbdb-cache-sortkey' Preconcatenated sort `bbdb-cache-set-sortkey' key for record Marker Marker `bbdb-cache-marker' Marker in `.bbdb' for `bbdb-record-marker' start of record `bbdb-cache-set-marker' `bbdb-record-set-marker' Deleted Boolean `bbdb-cache-deleted-p' Set to `t' if record `bbdb-record-deleted-p' has been deleted, `bbdb-cache-set-deleted-p' `nil' if not `bbdb-record-set-deleted-p' The functions listed above will return `nil' if their respective cache fields are not set. The functions listed below will return the value of their cache fields if set, but will also build (and set) the correct field values if the fields are unset: `bbdb-record-name' Return the name in the Name Cache field of the cache (if set). If the name has not been built yet (if the field is `nil'), the name is built, stored in the Name Cache field, and returned. `bbdb-record-sortkey' Return the name it the Sort Key field of the cache (if set). If the Sort Key field has not yet been set (if the field is `nil'), the Sort Key is built, stored in the Sort Key field, and returned. Notes String or Alist ..................... If there is only a single note for a given record, the notes field for that record will be a string. If there is more than one note, the notes field will be an association list (alist) with elements of the form ( NAME . VALUE ) where NAME is the symbol for the name of the note, and VALUE is the value of the note. Example BBDB record ................... automatically generated by info2www version 1.2.2.9 |